@aloud/runner 0.2.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@aloud/runner",
+  "version": "0.2.0",
+  "description": "Run Aloud usability studies in a real browser on your own machine, so a study can reach localhost and anything else behind your network.",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dfala/user-testing-ai.git",
+    "directory": "packages/runner"
+  },
+  "homepage": "https://usealoud.com",
+  "keywords": ["usability", "testing", "playwright", "aloud"],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "bin": { "aloud": "./dist/cli.js" },
+  "files": ["dist/cli.js", "src", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:playwright --external:sharp --outfile=dist/cli.js",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "playwright": "^1.62.1",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@aloud/core": "*",
+    "@aloud/engine": "*",
+    "@aloud/eval": "*",
+    "esbuild": "^0.28.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * `aloud` - the local runner.
+ *
+ * The browsers run on this machine, which is what makes testing localhost and anything behind a
+ * firewall possible. The connection is outbound only: nothing here listens on a port, and the
+ * server holds no address for this machine.
+ */
+import { createInterface } from "node:readline/promises";
+import { readFileSync, unlinkSync } from "node:fs";
+import { hostname } from "node:os";
+import { normaliseHosts } from "@aloud/core";
+import {
+  CredentialsError,
+  clearCredentials,
+  credentialsFromEnv,
+  credentialsPath,
+  readCredentials,
+  writeCredentials,
+  type Credentials,
+} from "./config/credentials";
+import { policyFrom, type LocalPolicy } from "./config/policy";
+import { clearRunning, readRunning, runningPath, writeRunning } from "./config/running";
+import { RunnerClient } from "./protocol/client";
+import { installChromium, preflight } from "./preflight";
+import { TerminalReporter } from "./ui/output";
+import { runLoop } from "./loop";
+
+/** Where a runner reaches the hosted control plane. Overridable for self-hosting and for tests. */
+const DEFAULT_SERVER = process.env.ALOUD_SERVER?.replace(/\/+$/, "") || "https://usealoud.com";
+
+export async function main(argv: readonly string[] = process.argv.slice(2)): Promise<number> {
+  const [command = "help", ...rest] = argv;
+
+  switch (command) {
+    case "login":
+      return login(rest);
+    case "logout":
+      return logout();
+    case "start":
+      return start(rest);
+    case "status":
+      return status();
+    case "allow":
+      return allow(rest);
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return 0;
+    default:
+      // Refuse rather than guess. An unrecognised command that might spend money is not a thing to
+      // be forgiving about.
+      process.stderr.write(`I do not know the command "${command}".\n\n`);
+      printHelp();
+      return 1;
+  }
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      "",
+      "aloud - run usability studies on this machine",
+      "",
+      "  aloud login [--token <token>]   Connect this machine to your workspace",
+      "  aloud start [--once] [--quiet]  Wait for studies and run them here",
+      "  aloud status                    What is set up, and whether it is running",
+      "  aloud allow <host>              Let studies open this host from this machine",
+      "  aloud logout                    Forget the token on this machine",
+      "",
+      `Server: ${DEFAULT_SERVER}  (override with ALOUD_SERVER)`,
+      "",
+    ].join("\n"),
+  );
+}
+
+async function loadCredentials(): Promise<Credentials | null> {
+  return credentialsFromEnv() ?? (await readCredentials());
+}
+
+function policyOf(credentials: Credentials, argv: readonly string[]): LocalPolicy {
+  const concurrency = numberOption(argv, "--concurrency");
+  return policyFrom({
+    allowedHosts: credentials.allowedHosts,
+    allowPrivateNetwork: credentials.allowPrivateNetwork,
+    ...(concurrency !== null ? { maxConcurrentSessions: concurrency } : {}),
+  });
+}
+
+/* --------------------------------- login --------------------------------- */
+
+async function login(argv: readonly string[]): Promise<number> {
+  const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
+  let token = stringOption(argv, "--token");
+
+  if (!token) {
+    process.stdout.write(`\nOpen ${server}/app/settings/runners and create a runner.\n`);
+    process.stdout.write("It shows you a token once. Paste it here.\n\n");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      token = (await rl.question("Token: ")).trim();
+    } finally {
+      rl.close();
+    }
+  }
+
+  if (!token?.startsWith("utar_")) {
+    process.stderr.write("That does not look like a runner token. They start with utar_.\n");
+    return 1;
+  }
+
+  interface Profile {
+    runnerId?: string;
+    runnerName?: string;
+    workspaceId?: string;
+    allowedHosts?: string[];
+  }
+
+  const client = new RunnerClient({ server, token });
+  let profile: Profile;
+  try {
+    const response = await client.request<Profile>("api/runner/me", { retry: false });
+    profile = response.body ?? {};
+  } catch (error) {
+    process.stderr.write(`That token did not work: ${(error as Error).message}\n`);
+    return 1;
+  }
+
+  const credentials: Credentials = {
+    server,
+    token,
+    runnerId: profile.runnerId ?? "",
+    runnerName: profile.runnerName || hostname(),
+    workspaceId: profile.workspaceId ?? "",
+    // Written from what the server says this runner was registered for, once, at login. Nothing
+    // the server sends afterwards edits this file.
+    allowedHosts: normaliseHosts(profile.allowedHosts ?? ["localhost"]),
+    allowPrivateNetwork: true,
+  };
+  await writeCredentials(credentials);
+
+  const reporter = new TerminalReporter(process.stdout, token);
+  process.stdout.write(`\nConnected as ${credentials.runnerName}.\n`);
+  process.stdout.write(`Allowed here: ${credentials.allowedHosts.join(", ")}\n`);
+  reporter.privacyNote();
+  process.stdout.write("Run `aloud start` and leave it running.\n\n");
+  return 0;
+}
+
+async function logout(): Promise<number> {
+  const removed = await clearCredentials();
+  process.stdout.write(removed ? `Forgot the token at ${credentialsPath()}.\n` : "There was nothing to forget.\n");
+  return 0;
+}
+
+/* --------------------------------- status --------------------------------- */
+
+async function status(): Promise<number> {
+  const credentials = await loadCredentials().catch((error: Error) => {
+    process.stderr.write(error.message + "\n");
+    return null;
+  });
+  const checks = await preflight();
+  const running = await readRunning();
+
+  process.stdout.write("\n");
+  if (!credentials) {
+    process.stdout.write("Signed in       no. Run `aloud login`.\n");
+  } else {
+    process.stdout.write(`Signed in       ${credentials.runnerName}\n`);
+    process.stdout.write(`Server          ${credentials.server}\n`);
+    process.stdout.write(`Allowed here    ${credentials.allowedHosts.join(", ") || "nothing yet"}\n`);
+  }
+  process.stdout.write(
+    `Chromium        ${checks.chromiumInstalled ? `ready (${checks.chromiumPath})` : "not installed yet"}\n`,
+  );
+  process.stdout.write(
+    `Running         ${running ? `yes, since ${when(running.startedAt)} (pid ${running.pid})` : "no. Run `aloud start`."}\n`,
+  );
+  process.stdout.write("\n");
+
+  // Zero means "a study started now would run here", which is the only question worth asking of
+  // this command. Signed in and installed but stopped is not ready, and used to exit 0 anyway.
+  return credentials && checks.chromiumInstalled && running ? 0 : 1;
+}
+
+/* --------------------------------- allow --------------------------------- */
+
+async function allow(argv: readonly string[]): Promise<number> {
+  const host = argv.find((arg) => !arg.startsWith("-"));
+  if (!host) {
+    process.stderr.write("Which host? For example: aloud allow staging.acme.com\n");
+    return 1;
+  }
+
+  const credentials = await readCredentials();
+  if (!credentials) {
+    process.stderr.write("Not signed in. Run `aloud login` first.\n");
+    return 1;
+  }
+
+  const next = normaliseHosts([...credentials.allowedHosts, host]);
+  await writeCredentials({ ...credentials, allowedHosts: next });
+  process.stdout.write(`\nStudies on this machine may now open: ${next.join(", ")}\n`);
+  process.stdout.write("Nothing the server sends can change that list. Only this command can.\n\n");
+  return 0;
+}
+
+/* --------------------------------- start --------------------------------- */
+
+async function start(argv: readonly string[]): Promise<number> {
+  const credentials = await loadCredentials().catch((error: Error) => {
+    process.stderr.write(error.message + "\n");
+    return null;
+  });
+  if (!credentials) {
+    process.stderr.write("Not signed in. Run `aloud login` first.\n");
+    return 1;
+  }
+
+  const reporter = new TerminalReporter(process.stdout, credentials.token, !argv.includes("--quiet"));
+
+  // Preflight runs before the first claim, deliberately. A missing Chromium makes
+  // `chromium.launch()` throw outside the session's own error handling, which takes the whole run
+  // down with a generic failure. That must not be anybody's first experience of the product.
+  const checks = await preflight();
+  if (!checks.chromiumInstalled) {
+    const installed = await installChromium((line) => process.stdout.write(line + "\n"));
+    if (!installed) {
+      process.stderr.write("\nCannot run studies without Chromium. Nothing was claimed.\n");
+      return 1;
+    }
+  }
+
+  const local = policyOf(credentials, argv);
+  if (local.allowedHosts.length === 0) {
+    process.stderr.write("This machine is not allowed to open anything. Try `aloud allow localhost`.\n");
+    return 1;
+  }
+
+  const client = new RunnerClient({
+    server: credentials.server,
+    token: credentials.token,
+    onConnectionChange: (state, detail) => reporter.connection(state, detail),
+  });
+
+  reporter.header({
+    runnerName: credentials.runnerName,
+    workspace: credentials.workspaceId || "your workspace",
+    server: credentials.server,
+    allowedHosts: local.allowedHosts,
+    chromium: true,
+  });
+
+  const controller = new AbortController();
+  installSignalHandlers(controller, reporter);
+
+  await writeRunning({ pid: process.pid, startedAt: new Date().toISOString(), server: credentials.server });
+  // The `finally` below covers every ordinary ending. This covers the second Ctrl-C, which calls
+  // `process.exit` and unwinds nothing. Synchronous, because an exit handler cannot await.
+  process.on("exit", () => clearRunningSync());
+
+  try {
+    await runLoop({
+      client,
+      local,
+      ui: reporter,
+      webUrl: `${credentials.server}/app`,
+      once: argv.includes("--once"),
+      signal: controller.signal,
+    });
+    return 0;
+  } catch (error) {
+    process.stderr.write(`\n${(error as Error).message}\n`);
+    return 1;
+  } finally {
+    await clearRunning();
+  }
+}
+
+/** The exit-handler twin of `clearRunning`, which cannot await anything. */
+function clearRunningSync(): void {
+  try {
+    const path = runningPath();
+    const state = JSON.parse(readFileSync(path, "utf8")) as { pid?: number };
+    if (state.pid === process.pid) unlinkSync(path);
+  } catch {
+    // Nothing to clean up, or nothing we are allowed to clean up. Either way `status` checks the
+    // pid rather than trusting the file, so a leftover record is not a wrong answer.
+  }
+}
+
+/**
+ * Ctrl-C, twice.
+ *
+ * The first asks the run to stop, so the lease is released and nobody is left waiting ninety
+ * seconds for a runner that is already gone. The second gives up on being polite. Playwright's own
+ * SIGINT handler is disabled at launch precisely so this one gets a chance to run at all.
+ */
+function installSignalHandlers(controller: AbortController, reporter: TerminalReporter): void {
+  let asked = false;
+  const onSignal = () => {
+    if (asked) {
+      reporter.note("Stopping now. Some browser windows may need closing by hand.");
+      process.exit(130);
+    }
+    asked = true;
+    reporter.note("Stopping. Closing browsers and telling the server this study did not finish.");
+    controller.abort();
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+}
+
+/** A start time someone can compare against their own clock, not an ISO string. */
+function when(iso: string): string {
+  const at = new Date(iso);
+  return Number.isNaN(at.getTime()) ? "an unknown time" : at.toLocaleTimeString();
+}
+
+function stringOption(argv: readonly string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  return value && !value.startsWith("-") ? value : undefined;
+}
+
+function numberOption(argv: readonly string[], name: string): number | null {
+  const raw = stringOption(argv, name);
+  if (raw === undefined) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+export { CredentialsError };
+
+// Only when run directly, so importing this module from a test does not start a runner.
+const entry = process.argv[1] ?? "";
+if (entry.endsWith("cli.ts") || entry.endsWith("cli.js") || entry.endsWith("/aloud")) {
+  main().then(
+    (code) => process.exit(code),
+    (error: Error) => {
+      process.stderr.write("\n" + error.message + "\n");
+      process.exit(1);
+    },
+  );
+}

package/src/config/credentials.ts

@@ -0,0 +1,146 @@
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The runner's credentials, at ~/.aloud/credentials.json, mode 0600.
+ *
+ * One path on all three platforms rather than XDG on Linux, Application Support on macOS, and
+ * %APPDATA% on Windows. It is easier to explain, easier to tell someone to delete, and it is what
+ * most developer CLIs already do.
+ */
+export interface Credentials {
+  /** Pinned. The token is never sent anywhere else, whatever a redirect suggests. */
+  server: string;
+  token: string;
+  runnerId: string;
+  runnerName: string;
+  workspaceId: string;
+  /** The local allowlist. Written at login from what the person chose; the server cannot edit it. */
+  allowedHosts: string[];
+  allowPrivateNetwork: boolean;
+}
+
+export class CredentialsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialsError";
+  }
+}
+
+export function credentialsPath(home = homedir()): string {
+  return join(home, ".aloud", "credentials.json");
+}
+
+/**
+ * Reads the credentials, or returns null if there are none.
+ *
+ * Refuses a file other users can read. A token that grants a stranger the ability to run browsers
+ * on this machine should not be sitting at 0644 because an editor rewrote it.
+ */
+export async function readCredentials(path = credentialsPath()): Promise<Credentials | null> {
+  let raw: string;
+  try {
+    const info = await stat(path);
+    // eslint-disable-next-line no-bitwise
+    if ((info.mode & 0o077) !== 0) {
+      throw new CredentialsError(
+        `${path} can be read by other users on this machine. Fix it with:\n  chmod 600 ${path}`,
+      );
+    }
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof CredentialsError) throw error;
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+
+  let parsed: Partial<Credentials>;
+  try {
+    parsed = JSON.parse(raw) as Partial<Credentials>;
+  } catch {
+    throw new CredentialsError(`${path} is not valid JSON. Delete it and run \`aloud login\` again.`);
+  }
+
+  if (!parsed.token || !parsed.server || !parsed.workspaceId) {
+    throw new CredentialsError(`${path} is missing fields. Delete it and run \`aloud login\` again.`);
+  }
+
+  return {
+    server: stripTrailingSlash(parsed.server),
+    token: parsed.token,
+    runnerId: parsed.runnerId ?? "",
+    runnerName: parsed.runnerName ?? "this machine",
+    workspaceId: parsed.workspaceId,
+    allowedHosts: parsed.allowedHosts ?? [],
+    allowPrivateNetwork: parsed.allowPrivateNetwork ?? true,
+  };
+}
+
+/**
+ * Writes the credentials at 0600.
+ *
+ * `mode` on writeFile applies only when the file is *created*, so an existing 0644 file would stay
+ * 0644 and the mode argument would be silently ignored. The chmod afterwards is the part that
+ * actually holds.
+ */
+export async function writeCredentials(credentials: Credentials, path = credentialsPath()): Promise<void> {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function clearCredentials(path = credentialsPath()): Promise<boolean> {
+  try {
+    await writeFile(path, "", { mode: 0o600, flag: constants.O_WRONLY | constants.O_TRUNC });
+    const { unlink } = await import("node:fs/promises");
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/**
+ * Credentials from the environment, for CI, where writing a token to disk is the wrong shape.
+ *
+ * Requires the server too: a token with no pinned origin is a token that will go wherever it is
+ * pointed.
+ */
+export function credentialsFromEnv(env: NodeJS.ProcessEnv = process.env): Credentials | null {
+  const token = env.ALOUD_RUNNER_TOKEN?.trim();
+  if (!token) return null;
+  const server = env.ALOUD_SERVER?.trim();
+  if (!server) {
+    throw new CredentialsError("ALOUD_RUNNER_TOKEN is set but ALOUD_SERVER is not. Set both, or neither.");
+  }
+  return {
+    server: stripTrailingSlash(server),
+    token,
+    runnerId: "",
+    runnerName: env.ALOUD_RUNNER_NAME?.trim() || "ci",
+    workspaceId: env.ALOUD_WORKSPACE_ID?.trim() || "",
+    allowedHosts: (env.ALOUD_ALLOWED_HOSTS ?? "").split(",").map((h) => h.trim()).filter(Boolean),
+    allowPrivateNetwork: env.ALOUD_ALLOW_PRIVATE_NETWORK !== "false",
+  };
+}
+
+/**
+ * SPEC 20.4, extended to the runner's own credential.
+ *
+ * Everything the runner prints or logs goes through here, so a token cannot reach a terminal
+ * transcript that someone pastes into a bug report.
+ */
+export function scrubToken(text: string, token?: string | null): string {
+  let out = token && token.length >= 8 ? text.split(token).join("[redacted]") : text;
+  // Also catches a token from some other session that happens to be in the text.
+  out = out.replace(/utar_[A-Za-z0-9_-]{8,}/g, "[redacted]");
+  return out;
+}
+
+function stripTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, "");
+}

package/src/config/policy.ts

@@ -0,0 +1,49 @@
+import { normaliseHosts } from "@aloud/core";
+
+/**
+ * The allowlist that lives on this machine, and that the server cannot change.
+ *
+ * This is the thing that makes the Phase 5 exit criterion true rather than merely intended. The
+ * control plane already intersects the study's hosts with the runner's registered hosts before
+ * issuing a lease, which is a good invariant against a *confused* server. It is no defence against
+ * a *compromised* one: a compromised server simply returns a lease saying `allowedHosts:
+ * ["192.168.1.1"]` and asserts it did the intersection.
+ *
+ * So the runner keeps its own copy on disk and intersects again locally. Nothing the server sends
+ * ever edits this file.
+ */
+export interface LocalPolicy {
+  /** Hosts this machine will open. Written at login, changed only by `aloud allow`. */
+  allowedHosts: string[];
+  /**
+   * Whether private and loopback addresses may be opened at all.
+   *
+   * Testing localhost is the entire point of running here, so this defaults to true. It is a
+   * separate switch from the allowlist because turning it off should be one decision, not a
+   * per-host audit.
+   */
+  allowPrivateNetwork: boolean;
+  /** The server does not know how much memory this machine has. This is a local decision. */
+  maxConcurrentSessions: number;
+}
+
+export const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
+
+export function policyFrom(input: {
+  allowedHosts?: readonly string[];
+  allowPrivateNetwork?: boolean;
+  maxConcurrentSessions?: number;
+}): LocalPolicy {
+  return {
+    allowedHosts: normaliseHosts(input.allowedHosts ?? []),
+    allowPrivateNetwork: input.allowPrivateNetwork ?? true,
+    // Clamped rather than trusted: three browsers is already a lot on a laptop, and a typo of 300
+    // should not take the machine down.
+    maxConcurrentSessions: clamp(input.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS, 1, 8),
+  };
+}
+
+function clamp(value: number, low: number, high: number): number {
+  if (!Number.isFinite(value)) return low;
+  return Math.min(high, Math.max(low, Math.floor(value)));
+}

package/src/config/running.ts

@@ -0,0 +1,95 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Whether a runner is running on this machine, recorded where `aloud status` can read it.
+ *
+ * `status` used to end with a flat "Not running." on every invocation, because it never looked:
+ * it checked the credentials file and the Chromium binary, both of which say what is *installed*,
+ * and then guessed at the one thing it was actually asked. That line had to be explained away
+ * everywhere status was recommended, which is the tell that the command was wrong rather than the
+ * documentation.
+ *
+ * A file next to the credentials is enough. The runner is a foreground process on the same machine
+ * as the person asking, so there is nothing to discover over a network: `start` writes its pid here
+ * and removes it on the way out, and `status` asks the operating system whether that pid is still
+ * alive.
+ */
+export interface RunningState {
+  pid: number;
+  startedAt: string;
+  server: string;
+}
+
+export function runningPath(home = homedir()): string {
+  return join(home, ".aloud", "running.json");
+}
+
+export async function writeRunning(state: RunningState, path = runningPath()): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+}
+
+/**
+ * What is running here, or null.
+ *
+ * A crash leaves the file behind, so the file alone is not the answer: the pid is checked with
+ * signal 0, which tests for the process without touching it. A stale record is deleted on the way
+ * past, so this heals rather than accumulating.
+ *
+ * The one thing this cannot rule out is the operating system having reused that pid for something
+ * unrelated, which would read as a runner that is not there. It is a narrow window on a number that
+ * counts to 99998 before it wraps, and the cost of being wrong is a status line, so it is not worth
+ * platform-specific process inspection to close.
+ */
+export async function readRunning(path = runningPath()): Promise<RunningState | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+
+  let state: Partial<RunningState>;
+  try {
+    state = JSON.parse(raw) as Partial<RunningState>;
+  } catch {
+    await unlink(path).catch(() => {});
+    return null;
+  }
+
+  if (typeof state.pid !== "number" || !alive(state.pid)) {
+    await unlink(path).catch(() => {});
+    return null;
+  }
+
+  return {
+    pid: state.pid,
+    startedAt: state.startedAt ?? "",
+    server: state.server ?? "",
+  };
+}
+
+/** Removes the record, but only if it is ours. A second runner's pid is not ours to forget. */
+export async function clearRunning(pid = process.pid, path = runningPath()): Promise<void> {
+  try {
+    const raw = await readFile(path, "utf8");
+    const state = JSON.parse(raw) as Partial<RunningState>;
+    if (state.pid !== pid) return;
+  } catch {
+    return;
+  }
+  await unlink(path).catch(() => {});
+}
+
+function alive(pid: number): boolean {
+  try {
+    // Signal 0 performs the permission and existence checks without delivering anything.
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means it exists and belongs to someone else, which still counts as alive.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}