@edspencer/paddock 0.79.1 → 0.81.0

package/packages/server/dist/cli/busy.js

@@ -0,0 +1,150 @@
+// From edspencer/cli-contract reference/busy-client.ts @ SPEC 0.1; local changes: `.ts` import specifiers → `.js`
+// and `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); `EXIT.OK` /
+// `EXIT.BUSY` / `EXIT.NOT_RUNNING` / `EXIT.FAILED` → Paddock's lowercase `EXIT.ok` / `busy` / `notRunning` /
+// `failure` (see `exit-codes.ts`, which wave C4 re-syncs); and `hint` widened from a string to
+// `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is what carries
+// Paddock's keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts are
+// non-zero, so a fixed string could not say it.
+//
+// The CLI's side of the busy check (SPEC §4): find the running instance through `<home>/runtime.json`, ask its
+// `/api/busy`, and map the answer to exit 0 (idle), 75 (busy) or 3 (nothing answers), with §4's messages.
+// Used by `<tool> busy`, and before `service stop`, `service restart` and `update`. Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+import { readLiveRuntimeFile } from "../runtime-file.js";
+/**
+ * Asks the running instance whether it's busy. There's no fallback to a default port: an instance that's running
+ * wrote `runtime.json`, and guessing a port would ask whatever else is listening there.
+ */
+export async function checkBusy(o) {
+    const base = o.url ?? readLiveRuntimeFile(o.home)?.url;
+    if (!base)
+        return { state: "not-running" };
+    const url = new URL("/api/busy", base).toString();
+    const doFetch = o.fetch ?? globalThis.fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            signal: AbortSignal.timeout(o.timeoutMs ?? 3000),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch {
+        // Refused, reset or timed out: nothing is answering, which §4 calls not running.
+        return { state: "not-running" };
+    }
+    if (!res.ok)
+        return { state: "unknown", url, detail: `HTTP ${res.status}` };
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return { state: "unknown", url, detail: "the answer isn't JSON" };
+    }
+    if (!isBusyAnswer(body))
+        return { state: "unknown", url, detail: "the answer has no boolean `busy`" };
+    return { state: body.busy ? "busy" : "idle", url, answer: body };
+}
+function isBusyAnswer(v) {
+    if (typeof v !== "object" || v === null || typeof v.busy !== "boolean")
+        return false;
+    const counts = v.counts;
+    if (counts === undefined)
+        return true;
+    return (typeof counts === "object" &&
+        counts !== null &&
+        Object.values(counts).every((n) => Number.isInteger(n) && n >= 0));
+}
+/** `2 chats and 1 job are running`, from the non-zero counts; '' if there are none. */
+export function describeCounts(counts = {}, nouns = {}) {
+    const parts = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([kind, n]) => {
+        const [one, many] = nouns[kind] ?? [kind, `${kind}s`];
+        return `${n} ${n === 1 ? one : many}`;
+    });
+    if (parts.length === 0)
+        return "";
+    const list = parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+    const total = Object.values(counts).reduce((a, n) => a + (n > 0 ? n : 0), 0);
+    return `${list} ${total === 1 ? "is" : "are"} running`;
+}
+/** The sentence for a person (SPEC §4): `Paddock is busy: 2 chats are running.` */
+export function busyMessage(name, result, nouns = {}) {
+    switch (result.state) {
+        case "not-running":
+            return `${name} isn't running.`;
+        case "idle":
+            return `${name} isn't busy.`;
+        case "busy": {
+            const what = describeCounts(result.answer.counts, nouns);
+            return what ? `${name} is busy: ${what}.` : `${name} is busy.`;
+        }
+        case "unknown":
+            return `Something answered at ${result.url}, but not as ${name}'s busy check (${result.detail}).`;
+    }
+}
+/** 0 idle, 75 busy, 3 nothing answers, 1 an answer that isn't a busy answer. */
+export function busyExitCode(result) {
+    switch (result.state) {
+        case "idle":
+            return EXIT.ok;
+        case "busy":
+            return EXIT.busy;
+        case "not-running":
+            return EXIT.notRunning;
+        case "unknown":
+            return EXIT.failure;
+    }
+}
+/** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
+export function busyJson(result) {
+    if (result.state === "not-running")
+        return { running: false, busy: false };
+    if (result.state === "unknown")
+        return { running: true, busy: false, url: base(result.url), error: result.detail };
+    return {
+        running: true,
+        busy: result.answer.busy,
+        url: base(result.url),
+        ...(result.answer.version !== undefined ? { version: result.answer.version } : {}),
+        counts: result.answer.counts ?? {},
+    };
+}
+const base = (busyUrl) => busyUrl.replace(/\/api\/busy$/, "");
+function resolveHint(hint, result) {
+    return typeof hint === "function" ? hint(result) : hint;
+}
+/** `<tool> busy [--json]`. Returns the exit code; the caller sets `process.exitCode`. */
+export async function runBusyCommand(o) {
+    const result = await checkBusy(o);
+    const message = busyMessage(o.name, result, o.nouns);
+    o.out.result(busyJson(result));
+    if (result.state === "unknown")
+        o.out.error(message);
+    else
+        o.out.say(message);
+    // LOCAL CHANGE: the hint rides along with a busy answer here too, not only on the guard's refusal — someone who
+    // ran `paddock busy` from inside a chat needs the same sentence as someone whose `service stop` was refused.
+    const hint = result.state === "busy" ? resolveHint(o.hint, result) : undefined;
+    if (hint !== undefined)
+        o.out.say(hint);
+    return busyExitCode(result);
+}
+/**
+ * The check before `service stop`, `service restart` and `update` (SPEC §4). Returns null to go ahead, or 75 after
+ * printing the refusal. With `--force` it prints the same message, prefixed `Overriding:`, and goes ahead.
+ * Nothing answering goes ahead: there's nothing to cut short.
+ */
+export async function guardBusy(o) {
+    const result = await checkBusy(o);
+    if (result.state !== "busy")
+        return null;
+    const message = busyMessage(o.name, result, o.nouns);
+    if (o.force) {
+        o.out.warn(`Overriding: ${message}`);
+        return null;
+    }
+    const hint = resolveHint(o.hint, result) ?? "Try again once it has finished, or use --force.";
+    return o.out.error(`${message} ${hint}`, EXIT.busy);
+}

package/packages/server/dist/cli/exit-codes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The CLI contract's exit codes (SPEC §2), as constants.
+ *
+ * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied
+ * from `reference/exit-codes.ts` because the reference module did not exist yet
+ * when Paddock aligned; wave C4 re-syncs this file to it and adds the usual
+ * provenance header. The numbers, and what each means, are the contract.
+ *
+ * | 0 | done; running and answering; up to date; not busy
+ * | 1 | failed
+ * | 2 | usage: an unknown command or flag, a bad value
+ * | 3 | not running: installed but not running or not answering
+ * | 4 | not installed: there is no service unit
+ * | 5 | this install cannot update itself          (`update`, not yet built)
+ * | 6 | the update failed and was rolled back      (`update`, not yet built)
+ * | 7 | the update failed and could not be rolled back
+ * | 75 | busy: refused, and why was printed        (`busy`, not yet built)
+ *
+ * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not
+ * running" and "no such service", so a script that already branches on them
+ * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code
+ * that makes Watchtower's pre-update hook skip an update.
+ *
+ * The three `update` codes are declared now and unused until wave C2. They are
+ * here because the contract's whole point is that the numbers mean the same
+ * thing in every tool: adding them later, from a different file, is how two
+ * tools end up disagreeing about what 5 means.
+ */
+export declare const EXIT: {
+    /** Done. Running and answering. Up to date. Not busy. */
+    readonly ok: 0;
+    /** Failed — the catch-all. */
+    readonly failure: 1;
+    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
+    readonly usage: 2;
+    /** Not running: installed, but not running or not answering. */
+    readonly notRunning: 3;
+    /** Not installed: there is no service unit. */
+    readonly notInstalled: 4;
+    /** This install cannot update itself; the right command was printed. */
+    readonly cannotSelfUpdate: 5;
+    /** The update failed and was rolled back; the old version is running again. */
+    readonly rolledBack: 6;
+    /** The update failed and could not be rolled back; a person is needed. */
+    readonly needsHuman: 7;
+    /** Busy: refused, and why was printed. Try later, or use `--force`. */
+    readonly busy: 75;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];

package/packages/server/dist/cli/exit-codes.js

@@ -0,0 +1,48 @@
+/**
+ * The CLI contract's exit codes (SPEC §2), as constants.
+ *
+ * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied
+ * from `reference/exit-codes.ts` because the reference module did not exist yet
+ * when Paddock aligned; wave C4 re-syncs this file to it and adds the usual
+ * provenance header. The numbers, and what each means, are the contract.
+ *
+ * | 0 | done; running and answering; up to date; not busy
+ * | 1 | failed
+ * | 2 | usage: an unknown command or flag, a bad value
+ * | 3 | not running: installed but not running or not answering
+ * | 4 | not installed: there is no service unit
+ * | 5 | this install cannot update itself          (`update`, not yet built)
+ * | 6 | the update failed and was rolled back      (`update`, not yet built)
+ * | 7 | the update failed and could not be rolled back
+ * | 75 | busy: refused, and why was printed        (`busy`, not yet built)
+ *
+ * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not
+ * running" and "no such service", so a script that already branches on them
+ * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code
+ * that makes Watchtower's pre-update hook skip an update.
+ *
+ * The three `update` codes are declared now and unused until wave C2. They are
+ * here because the contract's whole point is that the numbers mean the same
+ * thing in every tool: adding them later, from a different file, is how two
+ * tools end up disagreeing about what 5 means.
+ */
+export const EXIT = {
+    /** Done. Running and answering. Up to date. Not busy. */
+    ok: 0,
+    /** Failed — the catch-all. */
+    failure: 1,
+    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
+    usage: 2,
+    /** Not running: installed, but not running or not answering. */
+    notRunning: 3,
+    /** Not installed: there is no service unit. */
+    notInstalled: 4,
+    /** This install cannot update itself; the right command was printed. */
+    cannotSelfUpdate: 5,
+    /** The update failed and was rolled back; the old version is running again. */
+    rolledBack: 6,
+    /** The update failed and could not be rolled back; a person is needed. */
+    needsHuman: 7,
+    /** Busy: refused, and why was printed. Try later, or use `--force`. */
+    busy: 75,
+};

package/packages/server/dist/cli/output.d.ts

@@ -0,0 +1,52 @@
+export interface OutputStream {
+    write(chunk: string): unknown;
+    isTTY?: boolean;
+}
+export interface OutputOptions {
+    /** The bin, for `<tool>: <message>`. */
+    tool: string;
+    /** `--json` was given: stdout carries exactly one JSON document, and prose goes to stderr. */
+    json?: boolean;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export declare function useColor(stream: OutputStream, env?: NodeJS.ProcessEnv): boolean;
+export interface Paint {
+    bold(s: string): string;
+    dim(s: string): string;
+    red(s: string): string;
+    green(s: string): string;
+    yellow(s: string): string;
+}
+/** Colour functions that do nothing when `on` is false. */
+export declare function paint(on: boolean): Paint;
+export interface Output {
+    readonly json: boolean;
+    /** Colour for prose on stdout (never with `--json`, which has no prose on stdout). */
+    readonly color: Paint;
+    /** Colour for stderr. */
+    readonly errColor: Paint;
+    /** Prose for a person: stdout, or stderr under `--json`. */
+    say(line: string): void;
+    /** A warning on stderr, always. */
+    warn(line: string): void;
+    /** `<tool>: <message>` on stderr. Returns `code` (default 1), for `return out.error(…)`. Sets nothing itself. */
+    error(message: string, code?: number): number;
+    /** The one JSON document `--json` promises. Prints nothing without `--json`. */
+    result(doc: unknown): void;
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export declare function createOutput(o: OutputOptions): Output;
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export declare function exitQuietlyOnEpipe(stream?: NodeJS.WriteStream, exit?: (code: number) => void): void;

package/packages/server/dist/cli/output.js

@@ -0,0 +1,84 @@
+// From edspencer/cli-contract reference/output.ts @ SPEC 0.1; local changes: `./exit-codes.ts` → `./exit-codes.js`
+// (Paddock compiles to ESM-with-extensions, not a TS runtime); `EXIT.FAILED`/`EXIT.USAGE` → Paddock's lowercase
+// `EXIT.failure`/`EXIT.usage`, because Paddock's own `exit-codes.ts` predates the reference module and wave C4
+// re-syncs that file; and the reference's `UsageError` / `reportUsageError` are NOT copied, because `cli/args.ts`
+// already has a `UsageError` (a `CliError` subclass carrying its own code) that the entrypoint already reports.
+//
+// A CLI's output, the way SPEC §2 and §3 say: errors as `<tool>: <message>` on stderr, colour only on a TTY (honouring
+// NO_COLOR and FORCE_COLOR), and with `--json`, one JSON document on stdout and every word of prose on stderr.
+// Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export function useColor(stream, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined)
+        return env.FORCE_COLOR !== "0" && env.FORCE_COLOR !== "false";
+    if (env.TERM === "dumb")
+        return false;
+    return stream.isTTY === true;
+}
+const sgr = (open, close) => (s) => `\u001b[${open}m${s}\u001b[${close}m`;
+const plain = (s) => s;
+/** Colour functions that do nothing when `on` is false. */
+export function paint(on) {
+    return on
+        ? {
+            bold: sgr(1, 22),
+            dim: sgr(2, 22),
+            red: sgr(31, 39),
+            green: sgr(32, 39),
+            yellow: sgr(33, 39),
+        }
+        : { bold: plain, dim: plain, red: plain, green: plain, yellow: plain };
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export function createOutput(o) {
+    const stdout = o.stdout ?? process.stdout;
+    const stderr = o.stderr ?? process.stderr;
+    const env = o.env ?? process.env;
+    const json = o.json === true;
+    let printed = false;
+    const line = (s) => (s.endsWith("\n") ? s : `${s}\n`);
+    return {
+        json,
+        color: paint(!json && useColor(stdout, env)),
+        errColor: paint(useColor(stderr, env)),
+        say(s) {
+            (json ? stderr : stdout).write(line(s));
+        },
+        warn(s) {
+            stderr.write(line(s));
+        },
+        error(message, code = EXIT.failure) {
+            stderr.write(line(`${o.tool}: ${message}`));
+            return code;
+        },
+        result(doc) {
+            if (!json)
+                return;
+            if (printed)
+                throw new Error("--json prints one document; result() was called twice");
+            printed = true;
+            stdout.write(`${JSON.stringify(doc, null, 2)}\n`);
+        },
+    };
+}
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export function exitQuietlyOnEpipe(stream = process.stdout, exit = (c) => process.exit(c)) {
+    stream.on("error", (err) => {
+        if (err.code === "EPIPE")
+            exit(typeof process.exitCode === "number" ? process.exitCode : 0);
+        else
+            throw err;
+    });
+}

package/packages/server/dist/cli/paddock.js

@@ -23,8 +23,10 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CliError, USAGE, SERVICE_USAGE, CONFIG_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
-import { runService, safeHomeDir } from "./service/index.js";
+import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
+import { EXIT } from "./exit-codes.js";
+import { runService, safeHomeDir, realpathOr } from "./service/index.js";
+import { PADDOCK_NAME, PADDOCK_VERSION } from "../version.js";
 /**
  * This module's own file and directory: `<…>/packages/server/dist/cli/`.
  *
@@ -62,18 +64,27 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-function fail(message) {
+/**
+ * Report a failure, and hand back the code to exit with (SPEC §2, §3).
+ *
+ * Two things here are the contract rather than style. Errors go to **stderr**
+ * as `paddock: <message>`, so a `--json` document on stdout stays the only
+ * thing on stdout. And the code is RETURNED rather than passed to
+ * `process.exit()`: exiting mid-write truncates piped output, which is how a
+ * `paddock service status | jq` loses the end of its document. `main` assigns
+ * `process.exitCode` and lets the process end on its own.
+ *
+ * A usage error also prints the synopsis after the message, because the spec
+ * says the usage follows the message — the short one, not {@link USAGE}'s
+ * thousand words, which would bury the line that says what was wrong.
+ */
+function fail(message, code = EXIT.failure) {
     console.error(`paddock: ${message}`);
-    process.exit(1);
-}
-function readVersion() {
-    try {
-        const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf8");
-        return JSON.parse(raw).version ?? "unknown";
-    }
-    catch {
-        return "unknown";
+    if (code === EXIT.usage) {
+        console.error("");
+        console.error(USAGE_SYNOPSIS);
     }
+    return code;
 }
 /**
  * Put our bundled `claude` on PATH for child processes.
@@ -121,7 +132,10 @@ function addBundledBinsToPath() {
 function noteFirstRun(dataDir) {
     if (fs.existsSync(dataDir))
         return;
-    console.log([
+    // stderr, because stdout's first line belongs to the banner (SPEC §3). This
+    // block is prose for a person and it only appears on a first run — which is
+    // exactly the run a conformance check or a script reading the URL performs.
+    console.error([
         "",
         `  Welcome to Paddock. Creating a new instance in ${dataDir}`,
         "  Projects, chats and settings persist there between runs.",
@@ -161,12 +175,17 @@ async function service(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(SERVICE_USAGE);
-        return;
+        return EXIT.ok;
     }
     try {
-        await runService(action, opts, {
+        return await runService(action, opts, {
             platform: process.platform,
-            nodePath: process.execPath,
+            // Realpath'd (SPEC §7). `process.execPath` under a version manager is
+            // routinely a symlink into a per-shell directory — fnm's
+            // `fnm_multishells/<pid>_<ts>/bin/node` is deleted when that terminal
+            // exits — so a unit naming the symlink stops working when the tab closes,
+            // at some later login, with nothing in the logs because it never ran.
+            nodePath: realpathOr(process.execPath),
             scriptPath: entryScript,
             packageRoot,
             homeDir: safeHomeDir(),
@@ -180,10 +199,12 @@ async function service(command) {
         });
     }
     catch (err) {
+        // A CliError carries its own code: an unsupported platform or an npx
+        // refusal is a failure (1), a misspelled flag is usage (2).
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         if (err instanceof Error)
-            fail(err.message);
+            return fail(err.message);
         throw err;
     }
 }
@@ -214,12 +235,13 @@ async function config(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(CONFIG_USAGE);
-        return;
+        return EXIT.ok;
     }
     process.env.PADDOCK_DATA_DIR = resolveDataDir(opts);
     const { runConfig } = await import("./config.js");
     try {
         await runConfig(action, opts);
+        return EXIT.ok;
     }
     catch (err) {
         // A config that will not load reaches here as a CliError already carrying
@@ -227,9 +249,9 @@ async function config(command) {
         // because it is a bug in this command rather than in the configuration.
         // Same shape as `service` above.
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         if (err instanceof Error)
-            fail(err.message);
+            return fail(err.message);
         throw err;
     }
 }
@@ -239,29 +261,43 @@ async function main() {
         command = parseCommand(process.argv.slice(2));
     }
     catch (err) {
+        // Parse failures are usage failures: exit 2, not 1 (SPEC §2).
+        if (err instanceof UsageError)
+            return fail(err.message, err.exitCode);
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         throw err;
     }
     const opts = command.opts;
     if (opts.help) {
-        console.log(command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE);
-        return;
+        console.log(command.verb === "service"
+            ? SERVICE_USAGE
+            : command.verb === "config"
+                ? CONFIG_USAGE
+                : command.verb === "busy"
+                    ? BUSY_USAGE
+                    : USAGE);
+        return EXIT.ok;
     }
     if (opts.version) {
-        console.log(readVersion());
-        return;
+        // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this.
+        console.log(PADDOCK_VERSION);
+        return EXIT.ok;
     }
     const problem = nodeVersionProblem(process.versions.node);
     if (problem !== undefined)
-        fail(problem);
-    if (command.verb === "service") {
-        await service(command);
-        return;
-    }
-    if (command.verb === "config") {
-        await config(command);
-        return;
+        return fail(problem);
+    if (command.verb === "service")
+        return service(command);
+    if (command.verb === "config")
+        return config(command);
+    // `busy` (SPEC §1, §4). Nothing is imported from the server for this: the
+    // answer comes off the wire, and `cli/busy.ts` is Node built-ins only — which
+    // is what keeps a question meant for a Watchtower hook from loading Fastify,
+    // herdctl and the project layer to ask it.
+    if (command.verb === "busy") {
+        const { runBusy } = await import("./busy-command.js");
+        return runBusy(resolveDataDir(opts), opts.json === true);
     }
     addBundledBinsToPath();
     // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here`
@@ -330,9 +366,14 @@ async function main() {
         await start();
     }
     catch (err) {
-        fail(explainListenError(err, host, port));
+        return fail(explainListenError(err, host, port));
     }
     const url = `http://${host}:${port}`;
+    // The contract's banner line, FIRST on stdout and in exactly this shape:
+    // `<Name> <version>: <url>` (SPEC §3). It is parsed — by the conformance
+    // runner, and by anything that wants the URL without guessing the port — so
+    // the friendly block below it stays, but below it.
+    console.log(`${PADDOCK_NAME} ${PADDOCK_VERSION}: ${url}`);
     // Still name the data dir, even though it no longer varies with cwd: "which
     // instance am I looking at" is a real question the moment anyone passes
     // `--data-dir`, and the answer should be readable off the two lines the tool
@@ -346,8 +387,28 @@ async function main() {
     ].join("\n"));
     if (opts.open)
         openBrowser(url);
+    // 0, but NOT yet: a foreground serve keeps running because the server holds
+    // the event loop open. `process.exitCode` is set and never acted on until the
+    // listener closes, which is what SIGTERM does (start.ts).
+    return EXIT.ok;
 }
-main().catch((err) => {
+/**
+ * A closed pipe exits quietly (SPEC §2).
+ *
+ * `paddock service logs | head -5` closes the pipe under us, and Node's default
+ * is an unhandled EPIPE with a stack trace — printed to the terminal, after the
+ * output the user asked for, about a thing that is not a problem.
+ */
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+});
+main().then((code) => {
+    // `process.exitCode`, never `process.exit()` (SPEC §2): exiting mid-write
+    // truncates piped output, which is how `paddock config show --json | jq`
+    // loses the end of a large document.
+    process.exitCode = code;
+}, (err) => {
     console.error("fatal:", err);
-    process.exit(1);
+    process.exitCode = EXIT.failure;
 });