allaboard 0.0.0-stage → 0.4.0

package/dist/host/npm.js

@@ -0,0 +1,134 @@
+/**
+ * What allaboard asks of the owner's npm to update itself: the newest published version, whether a
+ * version is published, whether the running copy is the one `npm install -g` replaces, and the
+ * install. It goes through `npm`, never over HTTP of its own, so the owner's registry, proxy and
+ * credentials apply (issue #361). npm runs through `RunAsync`: an install takes 30 to 60 seconds.
+ *
+ * The shapes of npm's failures were measured on npm 11.17.0 (2026-10-17): an unreachable registry
+ * prints `npm error code ECONNREFUSED` and ends with status 1; a `lib/node_modules` that is not
+ * writable prints `npm error code EACCES`, `npm error path <folder>` and ends with 243; a killed
+ * npm ends with 137 and says nothing. An unknown version under `--json` prints `npm error code
+ * E404` and ends with 1.
+ */
+import { lstatSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { getLogger } from "../log.js";
+import { isVersion } from "../semver.js";
+import { packageVersion } from "../version.js";
+import { copyOf } from "./program.js";
+export const logger = getLogger("allaboard.host.npm");
+export { isNewer, isVersion } from "../semver.js";
+const NETWORK_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "ECONNRESET",
+    "ENETUNREACH",
+]);
+/** The failure that `result`, of a command that did not end well, tells. */
+export function classifyFailure(result) {
+    const code = /^npm error code (\S+)\s*$/m.exec(result.stderr)?.[1];
+    if (code !== undefined && NETWORK_CODES.has(code))
+        return { kind: "network" };
+    if (code === "EACCES" || code === "EPERM") {
+        const path = /^npm error path (\/.+?)\s*$/m.exec(result.stderr)?.[1];
+        return { kind: "permission", path: path ?? null };
+    }
+    return { kind: "other", status: result.status };
+}
+/** The version `npm view` printed for `args`, or why there is none. */
+async function viewed(run, args, signal) {
+    const result = await run("npm", ["view", ...args, "version", "--json"], signal);
+    if (result.status !== 0)
+        return { failure: classifyFailure(result), result };
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (typeof parsed === "string" && isVersion(parsed))
+            return { version: parsed };
+    }
+    catch { }
+    return { failure: { kind: "other", status: 0 }, result };
+}
+/**
+ * The newest version published on npm (`dist-tags.latest`), or the failure that hid it. Every
+ * function below that runs npm takes the `signal` that ends it (SIGTERM, see `RunAsync`).
+ */
+export async function latestVersion(run, signal) {
+    const found = await viewed(run, ["allaboard"], signal);
+    return "failure" in found ? { failure: found.failure } : { version: found.version };
+}
+/**
+ * Whether npm publishes `version` of allaboard. An unknown version is `false`; npm that cannot
+ * answer is the failure. A string that is no version is not asked about.
+ */
+export async function publishedVersion(run, version, signal) {
+    if (!isVersion(version))
+        return { published: false };
+    const found = await viewed(run, [`allaboard@${version}`], signal);
+    if ("version" in found)
+        return { published: found.version === version };
+    // The code of npm's refusal, not an exit status: an unknown version and a package that does
+    // not exist both print E404.
+    return /^npm error code E404\s*$/m.test(found.result.stderr)
+        ? { published: false }
+        : { failure: found.failure };
+}
+/** The real path of `path`, or `path` itself when it cannot be resolved. */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Whether the copy that runs from `main` (the real path of its `dist/main.js`) at `version` is
+ * the one `npm install -g allaboard` replaces: `<npm root -g>/allaboard` by real path, not a link,
+ * its version published. Returns its package folder, else the refusal. `version` is the one the
+ * process read at its start: after an install the copy's `package.json` holds the next one.
+ */
+export async function updatableCopy(run, main, version, signal) {
+    const rooted = await run("npm", ["root", "-g"], signal);
+    if (rooted.status !== 0)
+        return { refusal: { kind: "npm", failure: classifyFailure(rooted) } };
+    const root = real(rooted.stdout.trim());
+    const copy = join(root, "allaboard");
+    const own = real(main);
+    const running = copyOf(own);
+    try {
+        // `npm link` makes the global folder a link to the checkout; the process then runs from the
+        // checkout, which is where the link points.
+        if (lstatSync(copy).isSymbolicLink() && real(copy) === running) {
+            return { refusal: { kind: "link" } };
+        }
+    }
+    catch { }
+    if (own !== join(copy, "dist", "main.js")) {
+        return { refusal: { kind: "not-global", folder: running } };
+    }
+    const published = await publishedVersion(run, version, signal);
+    if ("failure" in published)
+        return { refusal: { kind: "npm", failure: published.failure } };
+    return published.published ? { copy } : { refusal: { kind: "unpublished", version } };
+}
+/**
+ * Runs `npm install -g allaboard@<version>` over the copy in `copy` and reads that copy's
+ * `package.json` again. Throws a RangeError, with nothing run, for a `version` that is not an
+ * exact version. npm's own words go to the log; the result carries only what they classify. An
+ * install that `signal` ended is npm's own rollback (measured 2026-10-17: it finishes its current
+ * step, puts the old folder back and ends with 1): a failure, the copy as it was.
+ */
+export async function installVersion(run, copy, version, signal) {
+    if (!isVersion(version))
+        throw new RangeError(`not a version to install: ${JSON.stringify(version)}`);
+    const result = await run("npm", ["install", "-g", `allaboard@${version}`], signal);
+    if (result.status !== 0) {
+        const failure = classifyFailure(result);
+        logger.error(`npm install allaboard@${version} failed with status ${result.status}: ${result.stderr.trim().slice(0, 4000)}`);
+        return { kind: "failed", failure };
+    }
+    const found = packageVersion(join(copy, "package.json"));
+    return found === version ? { kind: "installed", version } : { kind: "mismatch", found };
+}

package/dist/host/program.js

@@ -0,0 +1,49 @@
+/**
+ * The program a service manager starts: which Node, which file, and the folders a session's
+ * commands need on their `PATH`. Read from the command being run, so `allaboard service install`
+ * names the copy it was started from.
+ */
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+/** The first executable file called `name` in the folders of `pathVariable`, or null. */
+export function findOnPath(name, pathVariable) {
+    for (const folder of pathVariable.split(delimiter)) {
+        if (folder === "")
+            continue;
+        const candidate = join(folder, name);
+        try {
+            // A folder passes the access check too.
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch { }
+    }
+    return null;
+}
+// npm's folders page (read 2026-10-16): "Global installs on Unix systems go to
+// `{prefix}/lib/node_modules`" and executables "are linked into `{prefix}/bin` on Unix".
+const GLOBAL_ENTRY = /^(.*)\/lib\/node_modules\/allaboard\/dist\/main\.js$/;
+/**
+ * The program of the running command: `entry` is `process.argv[1]` (npm's link in its `bin`
+ * folder, resolved here), `pathVariable` the caller's `PATH`, `execPath` the fallback Node.
+ */
+export function programOf(entry, pathVariable, execPath) {
+    const main = realpathSync(entry);
+    const prefix = GLOBAL_ENTRY.exec(main)?.[1];
+    return {
+        node: findOnPath("node", pathVariable) ?? execPath,
+        main,
+        npmBin: prefix === undefined ? null : join(prefix, "bin"),
+    };
+}
+/** The folders of the service's `PATH`: Node's own first, then npm's, then the system's. */
+export function servicePath(program, system) {
+    const folders = [dirname(program.node), program.npmBin, ...system];
+    return [...new Set(folders.filter((folder) => folder !== null))].join(":");
+}
+/** The package folder of the copy whose entry file is `main`: the folder above `dist/`. */
+export function copyOf(main) {
+    return dirname(dirname(main));
+}

package/dist/host/run.js

@@ -0,0 +1,52 @@
+/** Runs a system command for the host layer, with no shell between, and waits for it. */
+import { spawn, spawnSync } from "node:child_process";
+/** `Run` on the real machine: a command that cannot start reports status null and why. */
+export const runCommand = (command, args) => {
+    const result = spawnSync(command, args, { encoding: "utf8" });
+    if (result.error !== undefined) {
+        return { status: null, stdout: "", stderr: result.error.message };
+    }
+    return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+};
+function abortReason(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason.message : "aborted before the command started";
+}
+/** `RunAsync` on the real machine: same reporting as `runCommand`, the event loop free meanwhile. */
+export const runAsync = (command, args, signal) => new Promise((resolve) => {
+    // A signal that has aborted already starts nothing: there is no command to end.
+    if (signal?.aborted) {
+        resolve({ status: null, stdout: "", stderr: abortReason(signal) });
+        return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        signal?.removeEventListener("abort", terminate);
+        resolve(result);
+    };
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    // Not `spawn`'s own `signal` option: it reports the abort as an 'error' at once, before the
+    // command has ended, and the caller waits for the end.
+    // A child that did not start has no pid, and a kill with none aimed at the caller's whole
+    // process group on Node 26.5.1.
+    function terminate() {
+        if (child.pid !== undefined)
+            child.kill("SIGTERM");
+    }
+    signal?.addEventListener("abort", terminate, { once: true });
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+        stderr += chunk;
+    });
+    // 'error' without 'close': the command could not start (a missing file, no permission).
+    child.on("error", (error) => done({ status: null, stdout: "", stderr: error.message }));
+    // 'close', not 'exit': the streams are drained by then. A signal leaves the status null.
+    child.on("close", (status) => done({ status, stdout, stderr }));
+});

package/dist/host/service/launchd.js

@@ -0,0 +1,385 @@
+/**
+ * The service on macOS: a user LaunchAgent, `local.allaboard`, loaded in the owner's login session,
+ * where Claude Code's credentials are (the Keychain). The plist is the one `docs/setup.md` wrote by
+ * hand before this command existed: same label, keys and log. A named instance has a service of its
+ * own, `local.allaboard.<name>`, started with `--instance <name>`; the default instance's plist is
+ * the one 0.1.x writes, byte for byte, so a copy with instances and a copy without agree on it.
+ * The instance reaches this layer as its name (null for the default): the host layer imports
+ * nothing of the core.
+ *
+ * Whether the job is loaded and its pid come from `launchctl list`, whose three columns (pid or
+ * `-`, last exit status, label) `man launchctl` documents; `launchctl print` would say more, but
+ * its man page calls its output "NOT API in any sense at all".
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { packageVersion } from "../../version.js";
+import { copyOf, servicePath } from "../program.js";
+import { listReport } from "./listing.js";
+const DEFAULT_LABEL = "local.allaboard";
+// The rule of an instance's name (`core/instance.ts`, `parseInstanceName`), kept here because the
+// host layer imports nothing of the core; `test/host/service/launchd.test.ts` holds the two
+// together. `service list` reads plists it did not write, so it checks the name itself.
+const INSTANCE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const RESERVED_NAMES = ["default", "allaboard"];
+/** Whether `name` is a name an instance may have. */
+export function isInstanceName(name) {
+    return INSTANCE_NAME.test(name) && !RESERVED_NAMES.includes(name);
+}
+/** The service's label: `local.allaboard` for the default instance, `local.allaboard.<name>` else. */
+export function labelOf(instance) {
+    return instance === null ? DEFAULT_LABEL : `${DEFAULT_LABEL}.${instance}`;
+}
+// After `ExitTimeOut` seconds launchd kills a job that `bootout` stopped; macOS 27.0 caps it at
+// 60 (measured 2026-09-26, `docs/setup.md`, Restarts and shutdown).
+export const EXIT_TIMEOUT_SECONDS = 60;
+// Folders a session's commands find as a terminal's do, after Node's and npm's (`servicePath`).
+const SYSTEM_PATH = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+function agentsDir(home) {
+    return join(home, "Library", "LaunchAgents");
+}
+/** The plist's path for the instance of the user whose home is `home`. */
+export function plistPath(home, instance) {
+    return join(agentsDir(home), `${labelOf(instance)}.plist`);
+}
+/** The file launchd writes the instance's stdout and stderr to. */
+export function logPath(home, instance) {
+    return join(home, "Library", "Logs", "allaboard", `${instance ?? "allaboard"}.log`);
+}
+function xml(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/**
+ * The plist that starts `program` at login, keeps it alive and writes its output to `log`. The
+ * default instance (`instance` null) passes no argument, as 0.1.x does.
+ */
+export function plistFor(program, log, instance = null) {
+    const argument = instance === null
+        ? ""
+        : `\n    <string>--instance</string>\n    <string>${xml(instance)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${labelOf(instance)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(program.node)}</string>
+    <string>${xml(program.main)}</string>${argument}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xml(servicePath(program, SYSTEM_PATH))}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ExitTimeOut</key>
+  <integer>${EXIT_TIMEOUT_SECONDS}</integer>
+  <key>StandardOutPath</key>
+  <string>${xml(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+/** The jobs `launchctl list` prints, one per row of three columns; the header and noise are skipped. */
+function listedRows(output) {
+    const number = (text) => (/^-?\d+$/.test(text) ? Number(text) : null);
+    return output.split("\n").flatMap((line) => {
+        const columns = line.trim().split(/\s+/);
+        if (columns.length !== 3)
+            return [];
+        return [
+            {
+                label: columns[2],
+                pid: number(columns[0]),
+                lastExit: number(columns[1]),
+            },
+        ];
+    });
+}
+/** The job `label` in the output of `launchctl list`, or null when it is not loaded. */
+export function listedJob(output, label) {
+    const row = listedRows(output).find((job) => job.label === label);
+    return row === undefined ? null : { pid: row.pid, lastExit: row.lastExit };
+}
+/**
+ * The instances of allaboard that `launchctl list` shows loaded: the default instance as null, the
+ * others by name. A label is one when it is `local.allaboard` or `local.allaboard.<name>` with a
+ * name the rule allows, exactly as `listedJob` matches one.
+ */
+function listedInstances(output) {
+    const found = [];
+    for (const { label } of listedRows(output)) {
+        if (label === DEFAULT_LABEL)
+            found.push(null);
+        else if (label.startsWith(`${DEFAULT_LABEL}.`)) {
+            const name = label.slice(DEFAULT_LABEL.length + 1);
+            if (isInstanceName(name))
+                found.push(name);
+        }
+    }
+    return found;
+}
+class LaunchctlError extends Error {
+}
+const ok = (out) => ({ code: 0, out, err: [] });
+const failed = (code, err) => ({ code, out: [], err });
+// The files that may be an allaboard service: `local.allaboard.plist` and `local.allaboard.<...>.plist`.
+// Which instance one is comes from what it says inside (`inspected`), not from this name.
+const OWN_PLIST = /^local\.allaboard(?:\..+)?\.plist$/;
+const NOT_MANAGEABLE = "not an allaboard instance it can manage";
+/** The Label and program arguments of the plist at `file`, or null when `plutil` cannot read them. */
+function plistFacts(run, file) {
+    const result = run("plutil", ["-convert", "json", "-o", "-", file]);
+    if (result.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const args = "ProgramArguments" in parsed ? parsed.ProgramArguments : null;
+        if (!Array.isArray(args) || !args.every((item) => typeof item === "string"))
+            return null;
+        const label = "Label" in parsed && typeof parsed.Label === "string" ? parsed.Label : null;
+        return { label, args };
+    }
+    catch {
+        return null;
+    }
+}
+/** The instance a plist starts and its entry file, or the reason it is not one `file` can manage. */
+function inspected(file, facts) {
+    if (facts === null)
+        return { reason: "its plist cannot be read" };
+    const [, main, ...rest] = facts.args;
+    let instance = null;
+    if (rest.length === 1 && rest[0] === "--instance") {
+        return { reason: "its program arguments end with --instance and no name" };
+    }
+    if (rest.length === 2 && rest[0] === "--instance")
+        instance = rest[1];
+    else if (rest.length !== 0) {
+        return {
+            reason: "its program arguments are the entry file alone, or the entry file and --instance <name>",
+        };
+    }
+    if (instance !== null && !isInstanceName(instance)) {
+        return {
+            reason: `${JSON.stringify(instance)} is not an instance name: 1 to 32 characters of a-z, 0-9 and "-", starting with a letter or a digit, and not "default" or "allaboard"`,
+        };
+    }
+    const expected = labelOf(instance);
+    const named = instance === null ? "the default instance" : `instance ${JSON.stringify(instance)}`;
+    if (facts.label === null)
+        return { reason: "it has no Label" };
+    if (facts.label !== expected) {
+        return {
+            reason: `its Label is ${facts.label}, but its program arguments start ${named} (Label ${expected})`,
+        };
+    }
+    if (file !== `${expected}.plist`) {
+        return {
+            reason: `its file name says another instance than its program arguments, which name ${named} (${expected}.plist)`,
+        };
+    }
+    return { instance, main };
+}
+/** The launchd implementation of `ServiceManager`. */
+export class Launchd {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    get #label() {
+        return labelOf(this.#options.instance);
+    }
+    get #plist() {
+        return plistPath(this.#options.home, this.#options.instance);
+    }
+    get #log() {
+        return logPath(this.#options.home, this.#options.instance);
+    }
+    get #target() {
+        return `gui/${this.#options.uid}/${this.#label}`;
+    }
+    /** A command of this instance as the owner types it: `--instance` is part of it when named. */
+    #command(action) {
+        const { instance } = this.#options;
+        return `\`allaboard service ${action}${instance === null ? "" : ` --instance ${instance}`}\``;
+    }
+    #launchctl(args) {
+        const result = this.#options.run("launchctl", args);
+        if (result.status !== 0) {
+            const said = (result.stderr || result.stdout).trim();
+            throw new LaunchctlError(`launchctl ${args[0]} failed${said === "" ? "" : `: ${said}`}`);
+        }
+        return result.stdout;
+    }
+    #job() {
+        return listedJob(this.#launchctl(["list"]), this.#label);
+    }
+    /** The result of `action`, or the sentence of the failure of launchctl or of a file it touched. */
+    #attempt(action) {
+        try {
+            return { done: action() };
+        }
+        catch (error) {
+            if (error instanceof LaunchctlError)
+                return { failure: error.message };
+            // A file it could not read or write, such as a folder it may not create: Node's message
+            // names the path and the reason.
+            if (error instanceof Error && "code" in error && typeof error.code === "string") {
+                return { failure: error.message };
+            }
+            throw error;
+        }
+    }
+    #guarded(action) {
+        const attempt = this.#attempt(action);
+        return "failure" in attempt ? failed(1, [attempt.failure]) : attempt.done;
+    }
+    install(program) {
+        return this.#guarded(() => {
+            const text = plistFor(program, this.#log, this.#options.instance);
+            const written = existsSync(this.#plist) ? readFileSync(this.#plist, "utf8") : null;
+            if (this.#job() !== null) {
+                if (written === text)
+                    return ok([`${this.#label} is already installed and loaded.`]);
+                return failed(1, [
+                    written === null
+                        ? `${this.#label} is loaded, and its plist ${this.#plist} is gone.`
+                        : `${this.#label} is loaded with another definition (${this.#plist}).`,
+                    `${this.#command("uninstall")} then ${this.#command("install")} replaces it; the uninstall ends turns still running after ${EXIT_TIMEOUT_SECONDS} seconds.`,
+                ]);
+            }
+            mkdirSync(dirname(this.#plist), { recursive: true });
+            mkdirSync(dirname(this.#log), { recursive: true });
+            writeFileSync(this.#plist, text);
+            const lint = this.#options.run("plutil", ["-lint", this.#plist]);
+            if (lint.status !== 0) {
+                return failed(1, [`plutil refused ${this.#plist}: ${(lint.stdout || lint.stderr).trim()}`]);
+            }
+            this.#launchctl(["bootstrap", `gui/${this.#options.uid}`, this.#plist]);
+            const copy = copyOf(program.main);
+            const version = packageVersion(join(copy, "package.json"));
+            return ok([
+                `Wrote ${this.#plist}.`,
+                `Loaded ${this.#label}: allaboard starts now and at every login.`,
+                `Log: ${this.#log}`,
+                version === null
+                    ? `Runs the copy in ${copy}, whose package.json cannot be read.`
+                    : `Runs the copy in ${copy}, version ${version}.`,
+            ]);
+        });
+    }
+    uninstall() {
+        return this.#guarded(() => {
+            const loaded = this.#job() !== null;
+            const present = existsSync(this.#plist);
+            if (!loaded && !present)
+                return ok([`${this.#label} is not installed.`]);
+            const out = [];
+            if (loaded) {
+                // Returns once the daemon has exited: its drain is cut at `ExitTimeOut`.
+                this.#launchctl(["bootout", this.#target]);
+                out.push(`Stopped ${this.#label}.`);
+            }
+            if (present) {
+                rmSync(this.#plist);
+                out.push(`Removed ${this.#plist}.`);
+            }
+            out.push(`Left in place: ${this.#options.configDir} (.env, state.json) and ${dirname(this.#log)}.`);
+            return ok(out);
+        });
+    }
+    status() {
+        return this.#guarded(() => {
+            const job = this.#job();
+            if (job === null) {
+                const line = existsSync(this.#plist)
+                    ? `${this.#label} is installed and not loaded: ${this.#command("install")} loads it.`
+                    : `${this.#label} is not installed.`;
+                return { code: 3, out: [line], err: [] };
+            }
+            if (job.pid !== null) {
+                return ok([`${this.#label} is running, pid ${job.pid}.`, `Log: ${this.#log}`]);
+            }
+            const exit = job.lastExit === null ? "" : `; its last exit status was ${job.lastExit}`;
+            return {
+                code: 3,
+                out: [`${this.#label} is loaded and not running${exit}.`, `Log: ${this.#log}`],
+                err: [],
+            };
+        });
+    }
+    restart() {
+        return this.#guarded(() => {
+            const job = this.#job();
+            if (job === null) {
+                return failed(1, [`${this.#label} is not loaded: ${this.#command("install")} starts it.`]);
+            }
+            if (job.pid === null) {
+                return failed(1, [
+                    `${this.#label} is not running; launchd starts it again on its own. Its log says why it stopped: ${this.#log}`,
+                ]);
+            }
+            // Only sends the signal: the daemon lets running turns finish, exits, and `KeepAlive` starts
+            // it again. `bootout` or `kickstart -k` would kill it after `ExitTimeOut`.
+            this.#launchctl(["kill", "TERM", this.#target]);
+            return ok([
+                `Sent SIGTERM to ${this.#label} (pid ${job.pid}): running turns finish first, then launchd starts it again.`,
+            ]);
+        });
+    }
+    list() {
+        return listReport(this.instances());
+    }
+    runningPid() {
+        const attempt = this.#attempt(() => this.#job()?.pid ?? null);
+        return "failure" in attempt ? null : attempt.done;
+    }
+    instances() {
+        const attempt = this.#attempt(() => {
+            const directory = agentsDir(this.#options.home);
+            const files = existsSync(directory)
+                ? readdirSync(directory)
+                    .filter((name) => OWN_PLIST.test(name))
+                    .sort()
+                : [];
+            const listing = this.#launchctl(["list"]);
+            // A job can outlive its plist (the file removed by hand): launchd keeps it loaded, and only
+            // `launchctl list` knows. A loaded instance whose plist file is not there is listed as such.
+            const gone = listedInstances(listing).filter((instance) => !files.includes(`${labelOf(instance)}.plist`));
+            const found = files.map((file) => ({
+                file,
+                what: inspected(file, plistFacts(this.#options.run, join(directory, file))),
+            }));
+            const instances = [
+                ...found.flatMap(({ what }) => ("reason" in what ? [] : [{ ...what, gone: false }])),
+                ...gone.map((instance) => ({ instance, main: undefined, gone: true })),
+            ]
+                // The default instance first, then the others by name.
+                .sort((a, b) => (a.instance ?? "").localeCompare(b.instance ?? ""));
+            const rows = instances.map(({ instance, main, gone: plistGone }) => {
+                const job = listedJob(listing, labelOf(instance));
+                const base = { instance, loaded: job !== null, pid: job?.pid ?? null };
+                if (plistGone)
+                    return { ...base, entry: "plist-gone" };
+                if (main === undefined)
+                    return { ...base, entry: "unreadable" };
+                const copy = copyOf(main);
+                return { ...base, entry: { copy, version: packageVersion(join(copy, "package.json")) } };
+            });
+            // What no command of an instance could find or remove is named, not listed as one.
+            const refused = found.flatMap(({ file, what }) => "reason" in what ? [`${file}: ${NOT_MANAGEABLE}: ${what.reason}`] : []);
+            return { rows, refused };
+        });
+        return "failure" in attempt ? attempt : attempt.done;
+    }
+}

package/dist/host/service/listing.js

@@ -0,0 +1,42 @@
+/** The columns of `rows` padded to their widest cell, two spaces apart; the last is not padded. */
+function table(rows) {
+    const widths = [0, 1, 2].map((column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows.map((row) => row
+        .map((cell, column) => (column < 3 ? cell.padEnd(widths[column] + 2) : cell))
+        .join(""));
+}
+function cellsOf(row) {
+    const state = !row.loaded
+        ? "not loaded"
+        : row.pid === null
+            ? "loaded, not running"
+            : `running, pid ${row.pid}`;
+    // Not a name to type: `--instance default` is refused.
+    const name = row.instance ?? "(default)";
+    if (row.entry === "plist-gone")
+        return [name, `${state}; its plist is gone`, "-", "-"];
+    if (row.entry === "unreadable")
+        return [name, state, "unreadable plist", "-"];
+    return [name, state, row.entry.copy, row.entry.version ?? "unknown"];
+}
+/** The report of `service list`: the table, then the definitions that are no instance's. */
+export function listReport(listing) {
+    if ("failure" in listing)
+        return { code: 1, out: [], err: [listing.failure] };
+    if (listing.rows.length === 0 && listing.refused.length === 0) {
+        return { code: 0, out: ["No allaboard service is installed."], err: [] };
+    }
+    const header = ["INSTANCE", "STATE", "COPY", "VERSION"];
+    return {
+        code: 0,
+        out: [
+            ...(listing.rows.length === 0 ? [] : table([header, ...listing.rows.map(cellsOf)])),
+            ...listing.refused,
+        ],
+        err: [],
+    };
+}
+/** The loaded instances whose copy is the package folder `copy`: the ones an update restarts. */
+export function loadedOn(rows, copy) {
+    return rows.filter((row) => row.loaded && typeof row.entry === "object" && row.entry.copy === copy);
+}

package/dist/host/service/seam.js

@@ -0,0 +1 @@
+export const SERVICE_ACTIONS = ["install", "uninstall", "status", "restart", "list"];