@omega.js/backend 0.1.0

package/dist/cli/commands/deploy.js

@@ -0,0 +1,205 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk').default;
+const powertools = require('node-powertools');
+const attachLogFile = require('../utils/attach-log-file');
+const stageLocalPackages = require('../utils/stage-local-packages');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const { refuseWhenCustom } = require('../utils/project-type');
+const { loadConfig, loadEnv } = require('../../vendor/config/index.js');
+const { resolveLicenseStamp } = require('../../vendor/devkit/license.js');
+
+const DEFAULT_REGION = 'us-central1';
+
+class DeployCommand extends BaseCommand {
+  async execute() {
+    const self = this.main;
+
+    // Custom-server mode has no Cloud Functions to publish (#584) — refuse
+    // before staging, so nothing is written for a deploy that cannot happen.
+    if (refuseWhenCustom(self.firebaseProjectPath, 'deploy')) return;
+
+    const logPath = this.getLogsPath('deploy.log');
+    attachLogFile(logPath);
+    this.log(chalk.gray(`  Logs saving to: ${logPath}\n`));
+
+    // The .env cascade, loaded HERE because nothing else in the CLI boot does:
+    // the license key below is read from this process's environment, and a
+    // licensed brand keeps OMEGA_LICENSE_KEY in the brand root's .env. Named
+    // `production` — the same environment the stage below composes dist/.env
+    // for (#586), so the verdict and the artifact read one overlay.
+    loadEnv(path.join(self.firebaseProjectPath, 'dist'), { environment: 'production' });
+
+    // The license check ([#320](https://github.com/Omega-JS-Stack/omega/issues/320)),
+    // once per deploy and BEFORE the stage: a backend deploy runs straight
+    // from the CLI, so the key comes out of the .env cascade in this process
+    // and never near the artifact. The verdict itself rides the composed
+    // dist/.env as OMEGA_LICENSE_STATUS — a keyless deploy gates the payment
+    // provider libraries at runtime. A key that cannot be answered for throws
+    // here, which stops the deploy rather than shipping the wrong verdict.
+    const licenseStatus = (await resolveLicenseStamp({
+      config: loadConfig(self.firebaseProjectPath, 'backend').config,
+      production: true,
+    })).status;
+    this.log(chalk.gray(`  License: ${licenseStatus}\n`));
+
+    // dist/ is staged output (src/dist pillar): a fresh stage carries the
+    // composed config + public/ hosting boilerplate across the upload boundary.
+    // The upload is composed for PRODUCTION — base .env + `.env.production`,
+    // and no other environment's overlay ever rides along (#586).
+    this.ensureStaged({ environment: 'production', licenseStatus });
+
+    // --only pass-through (e.g. `omega deploy --only hosting` — deploys
+    // hosting on Spark plans where functions would demand Blaze)
+    const only = self.argv?.only ? ` --only ${self.argv.only}` : '';
+
+    // Local file: dependencies (local-first @omega.js packages) can't be
+    // followed by Cloud Build — stage them into the upload as packed tarballs
+    const firebaseJSON = jetpack.read(path.join(self.firebaseProjectPath, 'firebase.json'), 'json') || {};
+    const functionsBlock = Array.isArray(firebaseJSON.functions) ? firebaseJSON.functions[0] : firebaseJSON.functions;
+    const functionsPath = path.join(self.firebaseProjectPath, functionsBlock?.source || 'dist');
+    const deployingFunctions = !self.argv?.only || String(self.argv.only).split(',').some((t) => t.trim().startsWith('functions'));
+
+    // Without an Artifact Registry cleanup policy, firebase deploy EXITS 1
+    // after a successful functions deploy — and the post-steps below (public
+    // invoker) never run. Ensure it up front.
+    if (deployingFunctions) {
+      await this.ensureArtifactCleanupPolicy();
+    }
+
+    const staging = deployingFunctions
+      ? await stageLocalPackages({ functionsPath, log: (message) => this.log(message) })
+      : null;
+
+    try {
+      await powertools.execute(`firebase deploy${only}`, {
+        log: false,
+        config: {
+          cwd: self.firebaseProjectPath,
+          stdio: ['inherit', 'pipe', 'pipe'],
+          env: { ...process.env, FORCE_COLOR: '1' },
+        },
+      }, (child) => {
+        child.stdout.on('data', (data) => process.stdout.write(data));
+        child.stderr.on('data', (data) => process.stderr.write(data));
+      });
+
+      require('../../vendor/devkit/deploy-record.js').recordDeploy({ dir: self.firebaseProjectPath, target: 'backend', detail: { method: 'firebase' } });
+
+      // After successful deploy, ensure HTTP functions are publicly invocable
+      await this.ensurePublicInvoker();
+    } finally {
+      if (staging) {
+        await staging.restore();
+      }
+      await attachLogFile.detach();
+    }
+  }
+
+  /**
+   * Ensure the Artifact Registry cleanup policy exists (old container images
+   * auto-delete). Best-effort: Spark plans, a disabled API, or a first-ever
+   * deploy (no gcf-artifacts repo yet) just skip — deploy proceeds either way.
+   */
+  async ensureArtifactCleanupPolicy() {
+    try {
+      await powertools.execute('firebase functions:artifacts:setpolicy --force', {
+        log: false,
+        config: { cwd: this.main.firebaseProjectPath },
+      });
+      this.log(chalk.gray('  Artifact cleanup policy ensured\n'));
+    } catch (e) {
+      // Non-fatal — the deploy itself doesn't need the policy
+    }
+  }
+
+  /**
+   * Ensure all HTTP-triggered functions have allUsers as cloudfunctions.invoker.
+   *
+   * Firebase CLI used to set this automatically but stopped around the Node 10
+   * runtime transition. Without it, HTTP requests get a 403 at the IAM level
+   * before @omega.js/backend's application-level auth (the omega-admin-key header) can run.
+   *
+   * Dynamically discovers all deployed functions via gcloud and fixes any
+   * HTTP-triggered function missing the allUsers invoker binding.
+   */
+  async ensurePublicInvoker() {
+    const projectId = this.getProjectId();
+
+    if (!projectId) {
+      return;
+    }
+
+    // Discover all deployed HTTP-triggered functions
+    let httpFunctions;
+
+    try {
+      const output = await powertools.execute(
+        `gcloud functions list --project ${projectId} --regions ${DEFAULT_REGION} --format="json(name,httpsTrigger)"`,
+        { log: false },
+      );
+
+      httpFunctions = JSON.parse(output)
+        .filter((fn) => fn.httpsTrigger)
+        .map((fn) => fn.name.split('/').pop());
+    } catch {
+      return;
+    }
+
+    if (!httpFunctions.length) {
+      return;
+    }
+
+    this.log(chalk.gray('\n  Ensuring HTTP functions are publicly invocable...\n'));
+
+    let fixed = 0;
+    let ok = 0;
+
+    for (const fnName of httpFunctions) {
+      try {
+        const policyOutput = await powertools.execute(
+          `gcloud functions get-iam-policy ${fnName} --project ${projectId} --region ${DEFAULT_REGION} --format=json`,
+          { log: false },
+        );
+
+        const policy = JSON.parse(policyOutput);
+        const hasAllUsers = (policy.bindings || []).some(
+          (b) => b.role === 'roles/cloudfunctions.invoker'
+            && (b.members || []).includes('allUsers'),
+        );
+
+        if (hasAllUsers) {
+          ok++;
+          continue;
+        }
+
+        await powertools.execute(
+          `gcloud functions add-iam-policy-binding ${fnName} --project ${projectId} --region ${DEFAULT_REGION} --member="allUsers" --role="roles/cloudfunctions.invoker"`,
+          { log: false },
+        );
+
+        this.log(`  ${chalk.green('✓')} Set public invoker on ${chalk.cyan(fnName)}`);
+        fixed++;
+      } catch {
+        // Skip silently — function may be in a transient state
+      }
+    }
+
+    if (fixed > 0) {
+      this.log(`  ${chalk.green('✓')} Public invoker: ${ok + fixed} functions accessible (${fixed} just fixed)\n`);
+    } else if (ok > 0) {
+      this.log(`  ${chalk.green('✓')} Public invoker: ${ok} functions accessible\n`);
+    }
+  }
+
+  getProjectId() {
+    try {
+      const firebaserc = jetpack.read(path.join(this.main.firebaseProjectPath, '.firebaserc'), 'json');
+      return firebaserc?.projects?.default;
+    } catch {
+      return null;
+    }
+  }
+}
+
+module.exports = DeployCommand;

package/dist/cli/commands/emulator-orphans.js

@@ -0,0 +1,440 @@
+/**
+ * The machine-wide orphan reap every emulator boot runs before it claims a port
+ * ([#781](https://github.com/Omega-JS-Stack/omega/issues/781)).
+ *
+ * Emulator processes outlive the run that started them whenever the parent is
+ * killed by pid, force-killed, or torn down with its shell: firebase-tools puts
+ * each emulator in its own process group, so the survivors reparent to PID 1
+ * and hold memory and ports until somebody notices. Found on a real machine:
+ * ~100 `functionsEmulatorRuntime` workers from a node version that machine no
+ * longer runs, plus a hub on a BUMPED port with three java jars, parent gone
+ * for hours.
+ *
+ * The two reapers this file joins could reach none of it. The port-driven one
+ * only ever looked at the ports THIS run wants, and the record-driven one only
+ * at pids a record still names — a hub on 4402 belonging to a legacy run is
+ * outside both by construction.
+ *
+ * **The verdict is parentage AND a strict family match, both required, and no
+ * ownership proof at all.** An orphan of the emulator family is NOBODY's: it is
+ * reaped whatever project it names (Ian 2026-09-03, docs/shared/rulings.md),
+ * which supersedes the [#293](https://github.com/Omega-JS-Stack/omega/issues/293)
+ * line that another brand's orphans stay. The #293 lesson survives as the
+ * FAMILY half: a name matching `/emulator|firebase/i` killed another session's
+ * reload watcher, so nothing here matches on a name, on a port, or on the words
+ * `node`, `java`, `firebase` or `firebase-functions` alone — only on the exact
+ * command shapes below: the hub, the functions runtime worker, the functions
+ * discovery server, an emulator jar out of the firebase cache, and puppeteer's
+ * headless browser.
+ *
+ * Everything the sweep reads or does goes through a seam, so its verdicts are
+ * testable against real `ps` rows without a single live process.
+ */
+
+// Libraries
+const powertools = require('node-powertools');
+const { isPortFree } = require('../../vendor/config/index.js');
+
+// ONE snapshot of every process on the machine, in the four fields the verdict
+// needs. Read once: two `ps` calls describe two moments, and a number that
+// changed hands between them reads as one process that never existed
+// ([#730](https://github.com/Omega-JS-Stack/omega/issues/730)).
+const PROCESS_TABLE_COMMAND = 'ps -A -o pid=,ppid=,uid=,command=';
+
+// A busy machine prints a few hundred KB of table, and a command line can be
+// long; the default 1MB buffer is a limit this must never bump into.
+const PROCESS_TABLE_MAX_BUFFER = 16 * 1024 * 1024;
+const PROCESS_READ_TIMEOUT_MS = 5000;
+
+// The settle windows, as DEFAULTS only: the boot passes its own STOP_GRACE_MS,
+// PORT_RELEASE_TIMEOUT_MS and POLL_INTERVAL_MS in, so emulator.js stays the one
+// home of the numbers. They are restated here because the command requires THIS
+// module, never the other way round, and a sweep run standalone must still
+// settle before it answers.
+const DEFAULT_GRACE_MS = 2000;
+const DEFAULT_PORT_RELEASE_TIMEOUT_MS = 5000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+
+// The hub: `firebase emulators:start` (or `:exec`), reached either through the
+// bin on PATH or through firebase-tools' own entry file. The VERB is what makes
+// it the hub — `firebase deploy` is a live publish and never matches.
+const HUB_BIN = /(^|\/)firebase(\.js)?\s+(emulators:start|emulators:exec)\b/;
+const HUB_TOOLS_ENTRY = /firebase-tools\/lib\/bin\/firebase\.js\b/;
+const HUB_VERB = /\bemulators:(start|exec)\b/;
+
+// The functions worker, by the module path firebase-tools runs it as. No node
+// version and no install prefix is part of it: the pile found on the machine
+// came from a node v22 install beside a v24 one.
+const FUNCTIONS_WORKER = /firebase-tools\/lib\/emulator\/functionsEmulatorRuntime\b/;
+
+// The functions DISCOVERY server: firebase-tools runs the functions source's
+// own `firebase-functions` bin to read the manifest off a random port, then
+// asks it to quit — so a hub that dies inside that window leaves it holding the
+// port forever ([#805](https://github.com/Omega-JS-Stack/omega/issues/805)).
+// A node RUNNING one of its two entry paths is the whole match: the words
+// `firebase-functions` in an argv are somebody reading the package, not it. The
+// path is reached from a space as well as a slash — a hub started inside the
+// functions source spawns it with a bare-relative path and nothing before it.
+const NODE_BIN = /(^|\/)node\s/;
+const FUNCTIONS_DISCOVERY_BIN = /(^|[\s/])node_modules\/\.bin\/firebase-functions(\s|$)/;
+const FUNCTIONS_DISCOVERY_ENTRY = /(^|[\s/])firebase-functions\/lib\/bin\/firebase-functions\.js(\s|$)/;
+
+// An emulator jar, by all four parts together: a java binary, a `-jar`, the
+// firebase emulator cache the jar was downloaded into, and a `.jar`. A jar
+// somewhere else on disk is somebody's application.
+const JAVA_BIN = /(^|\/)java\s/;
+const JAR_FLAG = /\s-jar\s/;
+const JAR_PATH = /-jar\s+(\S*\/firebase\/emulators\/\S*\.jar)\b/;
+
+// Puppeteer's browser, by the temp profile it is launched with. Only puppeteer
+// ever creates a `puppeteer_dev_chrome_profile-` directory, so the flag alone
+// separates a lane's headless Chrome from the one a user opened from Finder.
+const PUPPETEER_PROFILE = /--user-data-dir=\S*puppeteer_dev_chrome_profile-/;
+
+// Which emulator a jar is, decided on the JAR PATH rather than the argv: the
+// firestore jar is launched with `--database-edition standard`, so reading the
+// whole command line calls it the database emulator. First match wins.
+const JAR_NAMES = [
+  { pattern: /firestore/i, label: 'firestore jar' },
+  { pattern: /pubsub/i, label: 'pubsub jar' },
+  { pattern: /database/i, label: 'database jar' },
+  { pattern: /storage/i, label: 'storage jar' },
+];
+
+/**
+ * Which emulator jar a java command line is running, by its jar path.
+ * @param {string} command - Full command line from ps.
+ * @returns {string} The short label; `emulator jar` for one the cache grows later.
+ */
+function describeJar(command) {
+  const jar = JAR_PATH.exec(command);
+  const named = JAR_NAMES.find((entry) => entry.pattern.test(jar ? jar[1] : ''));
+
+  return named ? named.label : 'emulator jar';
+}
+
+/**
+ * Does this command line run the firebase emulator hub?
+ * @param {string} command - Full command line from ps.
+ * @returns {boolean}
+ */
+function isEmulatorHub(command) {
+  return HUB_BIN.test(command) || (HUB_TOOLS_ENTRY.test(command) && HUB_VERB.test(command));
+}
+
+/**
+ * Does this command line run the functions discovery server?
+ * @param {string} command - Full command line from ps.
+ * @returns {boolean}
+ */
+function isFunctionsDiscovery(command) {
+  return NODE_BIN.test(command)
+    && (FUNCTIONS_DISCOVERY_BIN.test(command) || FUNCTIONS_DISCOVERY_ENTRY.test(command));
+}
+
+/**
+ * Does this command line run an emulator jar out of the firebase cache?
+ * @param {string} command - Full command line from ps.
+ * @returns {boolean}
+ */
+function isEmulatorJar(command) {
+  return JAVA_BIN.test(command) && JAR_FLAG.test(command) && JAR_PATH.test(command);
+}
+
+// The WHOLE family, as one table: the shapes and their short names have a
+// single home, so the verdict and the log line can never come to disagree.
+const FAMILY_SHAPES = [
+  { matches: isEmulatorHub, label: () => 'firebase hub' },
+  { matches: (command) => FUNCTIONS_WORKER.test(command), label: () => 'functions worker' },
+  { matches: isFunctionsDiscovery, label: () => 'functions discovery server' },
+  { matches: (command) => PUPPETEER_PROFILE.test(command), label: () => 'puppeteer chrome' },
+  { matches: isEmulatorJar, label: describeJar },
+];
+
+/**
+ * Rows from one `ps -A -o pid=,ppid=,uid=,command=` snapshot.
+ *
+ * A line that does not read as three numbers and a command is dropped rather
+ * than guessed at: a half-parsed row would be a kill order built on nothing.
+ * @param {string} text - The raw ps output.
+ * @returns {Array<{pid: number, ppid: number, uid: number, command: string}>}
+ */
+function parseProcessTable(text) {
+  return String(text || '')
+    .split('\n')
+    .map((line) => /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/.exec(line))
+    .filter((match) => !!match)
+    .map((match) => ({
+      pid: Number(match[1]),
+      ppid: Number(match[2]),
+      uid: Number(match[3]),
+      command: match[4],
+    }));
+}
+
+/**
+ * The short name for a family member's command line, for the boot's one line.
+ * @param {string} command - Full command line from ps.
+ * @returns {string|null} The label, or null when the command is not family.
+ */
+function describeFamilyMember(command) {
+  const text = String(command || '');
+  const shape = FAMILY_SHAPES.find((entry) => entry.matches(text));
+
+  return shape ? shape.label(text) : null;
+}
+
+/**
+ * Is this row an ORPHANED emulator-family process of THIS user?
+ *
+ * Three things, all required, and no ownership proof among them:
+ *
+ *   1. ORPHANED — `ppid === 1`. A live `omega dev`, a hand-run
+ *      `firebase emulators:start`, a second brand's stack and another agent
+ *      session all keep a live parent, so none of them is ever a candidate.
+ *   2. OURS TO SIGNAL — the row's uid is this user's. Missing uid evidence
+ *      proves nothing and reads as "not a candidate".
+ *   3. FAMILY — one of the exact command shapes above. This is the half that
+ *      keeps the reload watcher alive: nodemon runs at PID 1 with a live
+ *      session behind it and names firebase paths in its argv.
+ * @param {{pid: number|string, ppid: number|string, uid: number|string, command: string}} row - One ps row.
+ * @param {number} uid - This user's uid (`process.getuid()`).
+ * @returns {boolean}
+ */
+function isOrphanedEmulatorFamily(row, uid) {
+  const pid = Number(row?.pid);
+  const owner = Number(uid);
+
+  // PID 1 is init, and a non-numeric row is a parse failure — never candidates.
+  if (!Number.isInteger(pid) || pid <= 1) {
+    return false;
+  }
+
+  if (Number(row?.ppid) !== 1) {
+    return false;
+  }
+
+  if (!Number.isInteger(owner) || Number(row?.uid) !== owner) {
+    return false;
+  }
+
+  return describeFamilyMember(row?.command) !== null;
+}
+
+/**
+ * Every port a command line publishes (`--port 9152`, `--port=8085`,
+ * `--websocket_port 9150`).
+ *
+ * A reap is BY PID, so nothing else says which ports the process held — and a
+ * SIGKILLed JVM keeps its listener for a moment after the process is gone,
+ * which is exactly the "probed free, then failed to bind" race the boot's retry
+ * exists to catch ([#778](https://github.com/Omega-JS-Stack/omega/issues/778)).
+ * @param {string} command - Full command line from ps.
+ * @returns {number[]}
+ */
+function publishedPorts(command) {
+  return [...String(command || '').matchAll(/--[\w-]*port[=\s](\d+)/g)].map((match) => Number(match[1]));
+}
+
+/**
+ * One `ps -A` snapshot of the whole machine.
+ *
+ * A failed read answers with NOTHING, never with a partial table: no rows means
+ * no candidates, and a boot that cannot see the machine must not send signals.
+ * @returns {string} The raw ps output, or '' when it could not be read.
+ */
+function readProcessTable() {
+  const { execSync } = require('child_process');
+
+  try {
+    return execSync(PROCESS_TABLE_COMMAND, {
+      encoding: 'utf8',
+      maxBuffer: PROCESS_TABLE_MAX_BUFFER,
+      timeout: PROCESS_READ_TIMEOUT_MS,
+    });
+  } catch (error) {
+    return '';
+  }
+}
+
+/**
+ * One pid's row right now, for the re-read that precedes a SIGKILL.
+ * @param {number|string} pid - The pid to read.
+ * @returns {{pid: number, ppid: number, uid: number, command: string}|null}
+ */
+function readProcessRow(pid) {
+  const { execSync } = require('child_process');
+
+  try {
+    const text = execSync(`ps -o pid=,ppid=,uid=,command= -p ${Number(pid)} 2>/dev/null`, { encoding: 'utf8' });
+
+    return parseProcessTable(text)[0] || null;
+  } catch (error) {
+    // Unreadable is not "gone": the escalation re-proves identity from this
+    // row, and no row is no proof, so the pid is spared either way.
+    return null;
+  }
+}
+
+/**
+ * Poll a pid set until every one is gone or the window closes.
+ *
+ * ONE snapshot per pass, indexed by pid, rather than a `ps` per pid: the pile
+ * this sweep exists for was ~100 processes deep, and a per-pid read would fork
+ * a hundred times every 100ms for the whole grace window.
+ * @param {number[]} pids - The pids to watch.
+ * @param {number} timeoutMs - How long to wait in total.
+ * @param {Function} readTable - The `ps -A` snapshot seam.
+ * @param {number} pollIntervalMs - How often to look.
+ * @returns {Promise<number[]>} The pids still alive when the window closed.
+ */
+async function waitForExit(pids, timeoutMs, readTable, pollIntervalMs) {
+  const deadline = Date.now() + timeoutMs;
+  let alive = pids;
+
+  while (alive.length > 0 && Date.now() < deadline) {
+    await powertools.wait(pollIntervalMs);
+
+    const running = new Set(parseProcessTable(readTable()).map((row) => row.pid));
+
+    alive = alive.filter((pid) => running.has(Number(pid)));
+  }
+
+  return alive;
+}
+
+/**
+ * Poll a port set until nothing is listening or the window closes.
+ * @param {number[]} ports - The ports the reaped processes published.
+ * @param {Function} isFree - The port probe seam.
+ * @param {number} timeoutMs - How long to wait in total.
+ * @param {number} pollIntervalMs - How often to look.
+ * @returns {Promise<number[]>} The ports still held when the window closed.
+ */
+async function waitForPorts(ports, isFree, timeoutMs, pollIntervalMs) {
+  const deadline = Date.now() + timeoutMs;
+  let held = [...new Set(ports)];
+
+  while (held.length > 0 && Date.now() < deadline) {
+    const free = await Promise.all(held.map((port) => isFree(port)));
+    held = held.filter((port, index) => !free[index]);
+
+    if (held.length > 0) {
+      await powertools.wait(pollIntervalMs);
+    }
+  }
+
+  return held;
+}
+
+/**
+ * The boot's one line, when anything went down.
+ * @param {Array<{pid: number, label: string}>} reaped - What went down.
+ * @param {number[]} killed - Which of them needed SIGKILL.
+ * @returns {string}
+ */
+function formatReapLine(reaped, killed) {
+  const plural = reaped.length > 1 ? 'es' : '';
+  const escalated = killed.length > 0 ? ` (${killed.length} needed SIGKILL)` : '';
+  const named = reaped.map((entry) => `${entry.pid} ${entry.label}`).join(', ');
+
+  return `Reaped ${reaped.length} orphaned emulator process${plural} left by earlier runs${escalated}: ${named}.`;
+}
+
+/**
+ * Reap every ORPHANED emulator-family process on the machine.
+ *
+ * SIGTERM to every match, the grace window, then SIGKILL to whatever is still
+ * standing — and the survivor's row is READ AGAIN first, because the window is
+ * long enough for a number to be freed and handed out again, and there is no
+ * apologising to a SIGKILL. Then the ports those rows published are waited on,
+ * so the allocator that probes them moments later is not racing a JVM that is
+ * still unwinding.
+ * @param {object} [options]
+ * @param {number} [options.uid] - This user's uid.
+ * @param {Function} [options.readTable] - The `ps -A` snapshot seam.
+ * @param {Function} [options.readProcess] - The per-pid `ps` seam.
+ * @param {Function} [options.kill] - The signal seam.
+ * @param {Function} [options.isFree] - The port probe seam.
+ * @param {Function} [options.log] - Where the one line goes (silent by default).
+ * @param {number} [options.graceMs] - How long a SIGTERM gets before SIGKILL.
+ * @param {number} [options.portReleaseTimeoutMs] - How long a freed port gets to come back.
+ * @param {number} [options.pollIntervalMs] - How often either wait looks.
+ * @returns {Promise<{reaped: Array<{pid: number, label: string}>, killed: number[]}>}
+ */
+async function reapMachineOrphans({
+  // A host with no `process.getuid` (Windows) hands the verdict no uid, and
+  // "no uid proves nothing" turns the whole sweep into a silent no-op there —
+  // which is the right answer on the one platform these emulators do not
+  // reparent to PID 1 on.
+  uid = typeof process.getuid === 'function' ? process.getuid() : undefined,
+  readTable = readProcessTable,
+  readProcess = readProcessRow,
+  kill = process.kill,
+  isFree = isPortFree,
+  log = () => {},
+  graceMs = DEFAULT_GRACE_MS,
+  portReleaseTimeoutMs = DEFAULT_PORT_RELEASE_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+} = {}) {
+  const targets = parseProcessTable(readTable())
+    .filter((row) => isOrphanedEmulatorFamily(row, uid))
+    // The sweep is the only signaller here with no ownership proof at all, so
+    // the two numbers it must never send a signal to are named outright.
+    .filter((row) => row.pid !== process.pid && row.pid !== process.ppid);
+
+  if (targets.length === 0) {
+    return { reaped: [], killed: [] };
+  }
+
+  for (const target of targets) {
+    try { kill(target.pid, 'SIGTERM'); } catch (e) { /* exited between the read and the signal */ }
+  }
+
+  const survivors = await waitForExit(targets.map((target) => target.pid), graceMs, readTable, pollIntervalMs);
+  const killed = [];
+
+  for (const pid of survivors) {
+    const live = readProcess(pid);
+
+    if (!isOrphanedEmulatorFamily(live, uid)) {
+      continue;
+    }
+
+    try {
+      kill(pid, 'SIGKILL');
+      killed.push(pid);
+    } catch (e) { /* gone in the meantime */ }
+  }
+
+  await waitForExit(killed, graceMs, readTable, pollIntervalMs);
+
+  // Only what actually went down: a target that outlived the grace window and
+  // came back as somebody else's number was spared, and reporting it reaped
+  // would name a pid this sweep never took.
+  const spared = survivors.filter((pid) => !killed.includes(pid));
+  const reaped = targets
+    .filter((target) => !spared.includes(target.pid))
+    .map((target) => ({ pid: target.pid, label: describeFamilyMember(target.command) }));
+
+  if (reaped.length > 0) {
+    log(formatReapLine(reaped, killed));
+
+    const ports = targets
+      .filter((target) => !spared.includes(target.pid))
+      .flatMap((target) => publishedPorts(target.command));
+
+    await waitForPorts(ports, isFree, portReleaseTimeoutMs, pollIntervalMs);
+  }
+
+  return { reaped: reaped, killed: killed };
+}
+
+module.exports = {
+  parseProcessTable: parseProcessTable,
+  isOrphanedEmulatorFamily: isOrphanedEmulatorFamily,
+  describeFamilyMember: describeFamilyMember,
+  reapMachineOrphans: reapMachineOrphans,
+  readProcessTable: readProcessTable,
+  readProcessRow: readProcessRow,
+};