@edspencer/paddock 0.80.0 → 0.82.0

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

@@ -88,7 +88,7 @@ export const CONFIG_ACTIONS = ["show", "eject"];
  * Paddock and Managers, every existing service unit's `ExecStart` names it, and
  * it is in two years of other people's scripts. They parse to the same command.
  */
-export const VERBS = ["serve", "start", "service", "config"];
+export const VERBS = ["serve", "start", "service", "config", "busy", "update", "upgrade"];
 /**
  * Split an action off a verb's argv, then parse what follows as flags.
  *
@@ -141,7 +141,74 @@ function parseAction(verb, actions, rest) {
  * for. Corrected rather than deleted because the grammar it documents is real
  * and load-bearing; it was only the example's error that was misdescribed.
  */
+/**
+ * Flags that mean something on SOME commands only, and the commands they mean
+ * it on.
+ *
+ * Rejecting a flag the command cannot act on, rather than parsing and dropping
+ * it, is the difference between being told and guessing: the two readings of a
+ * quiet `service uninstall --force` are "it overrode something" and "it did
+ * nothing", and the exit code is 0 either way. The same trap sits under
+ * `service status --refresh` and `serve --check`.
+ *
+ * One table, checked once in {@link parseCommand}, rather than a rule per
+ * command — a second copy of this logic is a second chance for the two to
+ * disagree about where a flag applies. `where` is matched against the
+ * invocation as the user would write it (`service stop`, `update`).
+ */
+const SCOPED_FLAGS = [
+    {
+        flag: "--force",
+        read: (o) => o.force === true,
+        where: ["service stop", "service restart", "update"],
+        why: "It overrides the busy check, and those are the commands that run one.",
+    },
+    {
+        flag: "--check",
+        read: (o) => o.checkOnly === true,
+        where: ["update"],
+        why: "It reports what an update would do, and changes nothing.",
+    },
+    {
+        flag: "--to",
+        read: (o) => o.to !== undefined,
+        where: ["update"],
+        why: "It names the version or dist-tag to move to.",
+    },
+    {
+        flag: "--yes",
+        read: (o) => o.yes === true,
+        where: ["update"],
+        why: "`update` is the only command that asks a question.",
+    },
+    {
+        flag: "--refresh",
+        read: (o) => o.refresh === true,
+        where: ["service install"],
+        why: "It re-renders an existing unit, keeping the settings it carries.",
+    },
+];
 export function parseCommand(argv) {
+    const command = dispatch(argv);
+    // `--help` wins over every rule below, the same way it wins over a missing
+    // action above: asking for the usage is not a usage error.
+    if (command.opts.help)
+        return command;
+    const said = "action" in command && command.action !== undefined
+        ? `${command.verb} ${command.action}`
+        : command.verb;
+    for (const rule of SCOPED_FLAGS) {
+        if (!rule.read(command.opts))
+            continue;
+        if (rule.where.includes(said))
+            continue;
+        const quoted = rule.where.map((w) => `\`${w}\``);
+        const list = quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
+        throw new UsageError(`${rule.flag} applies to ${list} only, not \`${said}\`.\n${rule.why}`);
+    }
+    return command;
+}
+function dispatch(argv) {
     const [first, ...rest] = argv;
     if (first === "service") {
         return { verb: "service", ...parseAction("service", SERVICE_ACTIONS, rest) };
@@ -149,6 +216,14 @@ export function parseCommand(argv) {
     if (first === "config") {
         return { verb: "config", ...parseAction("config", CONFIG_ACTIONS, rest) };
     }
+    // `busy` (SPEC §1, §4). A top-level verb rather than a `service` action
+    // because its whole point is to be askable where there is no service to ask:
+    // a Docker container, a Watchtower pre-update hook, an Ansible task.
+    if (first === "busy")
+        return { verb: "busy", opts: parseArgs(rest) };
+    // `update`, with `upgrade` accepted and undocumented (SPEC §1).
+    if (first === "update" || first === "upgrade")
+        return { verb: "update", opts: parseArgs(rest) };
     // `serve` and `start` are one command: see VERBS.
     if (first === "serve" || first === "start")
         return { verb: "serve", opts: parseArgs(rest) };
@@ -220,6 +295,31 @@ export function parseArgs(argv) {
             case "--include-env":
                 opts.includeEnv = true;
                 break;
+            // `service stop` / `service restart` / `update`: override the busy check
+            // (SPEC §4).
+            case "--force":
+                opts.force = true;
+                break;
+            // `update` flags (SPEC §1).
+            case "--check":
+                opts.checkOnly = true;
+                break;
+            case "--to": {
+                const v = next();
+                if (v === "" || v.startsWith("-")) {
+                    throw new UsageError(`${arg} needs a version or a dist-tag, got: ${JSON.stringify(v)}`);
+                }
+                opts.to = v;
+                break;
+            }
+            case "-y":
+            case "--yes":
+                opts.yes = true;
+                break;
+            // `service install --refresh` (SPEC §5 step 11).
+            case "--refresh":
+                opts.refresh = true;
+                break;
             // `service logs` flags, the names `tail`, `journalctl` and every other
             // log reader uses — this is not the place to be original.
             case "-f":
@@ -293,6 +393,8 @@ export function explainListenError(err, host, port) {
 export const USAGE_SYNOPSIS = `Usage
   paddock [serve] [options]               run the server in this terminal
   paddock service <action> [options]      install|uninstall|status|start|stop|restart|logs
+  paddock busy [--json]                   is the running instance busy?
+  paddock update [--check] [--to <v>]     install a newer Paddock
   paddock config <show|eject> [options]   what this instance's config resolved to
   paddock -v | --version                  print the version and exit
   paddock -h | --help                     the full help`;
@@ -306,10 +408,16 @@ Usage
   paddock service uninstall               stop it and remove the unit
   paddock service status [--json]         installed? running? which version?
   paddock service start                   start an installed service
-  paddock service stop                    stop it, leave it installed
-  paddock service restart                 stop it and start it again
+  paddock service stop [--force]          stop it, leave it installed
+  paddock service restart [--force]       stop it and start it again
   paddock service logs [-f] [-n <lines>]  the service's log
                                           (\`paddock service --help\`)
+  paddock busy [--json]                   is it busy? exit 0 no, 75 yes, 3
+                                          nothing answering
+                                          (\`paddock busy --help\`)
+  paddock update [--check] [--to <v>]     install a newer Paddock and restart
+                                          the service
+                                          (\`paddock update --help\`)
   paddock config show [--resolved]        what this instance's config resolved
                                           to, and where each value came from
   paddock config eject [--write]          freeze that resolution into
@@ -326,11 +434,15 @@ Options
   -h, --help              Show this help
 
 Exit codes
-  0   done; running and answering
+  0   done; running and answering; up to date; not busy
   1   failed
   2   usage: an unknown command or flag, or a bad value
-  3   not running: installed, but not running or not answering
+  3   not running: installed, but not running or not answering; nothing answers
   4   not installed: there is no service unit
+  5   this install cannot update itself; the right command was printed  (update)
+  6   the update failed and was rolled back; the old version is back    (update)
+  7   the update failed and could not be rolled back; a person is needed
+  75  busy: refused, and why was printed. Try later, or use --force
 
 Opening your own directories
   Where you run this from does not matter — the instance is decided by its data
@@ -434,18 +546,44 @@ export const SERVICE_USAGE = `paddock service — keep Paddock running in the ba
 
 Usage
   paddock service install [options]   register it and start it now
+  paddock service install --refresh   re-write the unit, keeping its settings
   paddock service uninstall           stop it and deregister it
   paddock service status [--json]     is it registered, is it running, which
                                       version, where are the logs
   paddock service start               start an installed service that is stopped
-  paddock service stop                stop it, and leave it installed
-  paddock service restart             stop it and start it again, re-reading config
+  paddock service stop [--force]      stop it, and leave it installed
+  paddock service restart [--force]   stop it and start it again, re-reading config
   paddock service logs [-f] [-n <n>]  the service's log (the last 50 lines)
 
 Options (logs)
   -f, --follow            keep printing what gets appended, until Ctrl-C
   -n, --lines <n>         how many lines to print first (default 50)
 
+Options (stop, restart)
+      --force             stop it even though it is busy
+
+Options (install)
+      --refresh           Re-render the unit from the settings the EXISTING one
+                          carries — its port, host, data dir and verbosity —
+                          rather than from this shell's flags and environment.
+                          This is what \`paddock update\` runs, through the new
+                          version's CLI, so the unit is written in the format
+                          that version writes. Exit 4 with nothing installed:
+                          there is no unit to refresh, and doing a first
+                          install with defaults instead is how a --port 9000
+                          service comes back on 7233.
+
+Busy
+  \`stop\` and \`restart\` ask the running instance whether it is busy first, and
+  refuse with exit 75 if it is — a chat turn in flight, a background task, a
+  scheduled job. \`paddock busy\` asks the same question on its own.
+
+  Being refused is the useful case: a restart kills a chat turn mid-sentence,
+  and the turn cannot be resumed from where it was. Wait, or --force.
+
+  \`uninstall\` does not ask. Removing the service is an explicit act, and
+  someone uninstalling it has already decided.
+
 Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
       --host <host>       Bind address (default 127.0.0.1)
@@ -490,6 +628,7 @@ Exit codes
   4   not installed: there is no unit  (status, logs, start, stop, restart)
   1   something failed
   2   usage: an unknown action or flag, or a bad value
+  75  busy, and --force was not given  (stop, restart)
 
 Installed from npx?
   \`service install\` refuses. An npx cache path is hash-keyed and npm may prune
@@ -505,6 +644,66 @@ A note on access
   process that could reach the port could already read the same Claude login as
   you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.
 
+Docs: https://github.com/edspencer/paddock`;
+export const BUSY_USAGE = `paddock busy — is the running instance in the middle of something?
+
+Usage
+  paddock busy                        ask, and say so in a sentence
+  paddock busy --json                 the same answer as one JSON document
+  paddock busy -d <path>              ask a particular instance
+
+Exit codes — this command is FOR its exit code
+  0   not busy. Nothing a restart would cut short.
+  75  busy. What is running was printed.
+  3   nothing answered. No instance is running, so there is nothing to wait for.
+  1   something answered, but not as Paddock's busy check.
+
+Options
+  -d, --data-dir <path>   Which instance to ask (default ~/.paddock, or
+                          \$PADDOCK_DATA_DIR) — the same rule \`paddock serve\`
+                          uses, so the two always mean the same instance
+      --json              One JSON document on stdout: running, busy, url,
+                          version, counts. Prose goes to stderr
+  -h, --help              Show this help
+
+What counts as busy
+  Only work a restart would LOSE or cut short:
+
+    chat         a chat turn running — a human turn, a fired trigger, a cron
+                 fire. A turn is a live claude subprocess writing a transcript,
+                 and it cannot be resumed from where it was interrupted.
+    background   a background task a live session is still holding after its
+                 turn ended: a background shell, a sub-agent, a Monitor.
+    job          a scheduled job herdctl is running.
+
+  Not busy: an idle session (it resumes), an open browser tab (it reconnects),
+  a pending curation sweep (it re-runs from its watermark).
+
+Where to run it from
+  From a terminal. A Paddock chat that runs this is itself one of the chat turns
+  it counts, so it will always see itself as busy — and \`service stop --force\`
+  from inside a chat stops the service that is running the chat, which does not
+  come back with an explanation. That is why the refusal says so.
+
+For scripts, containers and Watchtower
+  \`busy\` is there for callers with no service to ask. 75 is EX_TEMPFAIL, which
+  is the code Watchtower's pre-update hook reads as "skip this one":
+
+    labels:
+      com.centurylinklabs.watchtower.lifecycle.pre-update: paddock busy
+
+  An Ansible task does the same thing with a retry. Nothing here contacts the
+  network or the npm registry, and the question is answered from memory — it is
+  cheap enough to ask in a loop.
+
+How it finds the instance
+  \`<data-dir>/runtime.json\`, written 0600 when the server starts listening and
+  removed when it stops. There is no fallback to a default port: guessing one
+  would ask whatever else happened to be listening there, and get an answer.
+
+  A Paddock from before this feature shipped writes no such file, so it reads as
+  not running (exit 3). Upgrade it and restart it once.
+
 Docs: https://github.com/edspencer/paddock`;
 export const CONFIG_USAGE = `paddock config — what this instance's configuration actually resolved to
 
@@ -602,3 +801,103 @@ Reading nothing, writing nothing
   JWT signing material here to hide or reveal.
 
 Docs: https://github.com/edspencer/paddock`;
+/**
+ * `update`'s own synopsis, printed after a usage error from it (SPEC §2).
+ *
+ * `update` has one usage error of its own — "there is no terminal to ask, so
+ * `--yes` is required" — and the contract says the usage follows the message.
+ * {@link USAGE_SYNOPSIS} is the wrong text there: it lists every command, and
+ * the reader's problem is one flag on the command they already typed.
+ */
+export const UPDATE_SYNOPSIS = `Usage
+  paddock update [--yes]                  install the latest release
+  paddock update --check [--json]         what a new version would be; changes nothing
+  paddock update --to <version|tag>       a particular version, or a dist-tag
+  paddock update --force                  skip the busy check, and nothing else
+  paddock update --help                   the full help`;
+export const UPDATE_USAGE = `paddock update — install a newer Paddock, and put the service back up
+
+Usage
+  paddock update                      update to the latest release, asking first
+  paddock update --check              what a new version would be; changes nothing
+  paddock update --yes                do not ask (required when there is no terminal)
+  paddock update --to 0.79.1          a particular version — the only way to go BACK
+  paddock update --to next            a dist-tag
+  paddock update --json               one JSON document on stdout
+
+Options
+      --check             Ask the registry, report, and change nothing. Exits 0
+                          whether or not there is an update — scripts read
+                          \`updateAvailable\` from --json
+      --to <version|tag>  Install this version or dist-tag instead of latest.
+                          Required to move to a LOWER version: an update never
+                          goes backwards by accident
+      --yes, -y           Skip the question. Required when stdin is not a
+                          terminal, where a command that would have asked exits
+                          2 rather than guessing
+      --force             Skip the busy check, and nothing else — the health
+                          check and the rollback still run
+      --json              One JSON document on stdout; all prose on stderr
+  -h, --help              Show this help
+
+What it does, in order
+  1   takes <data-dir>/update.lock, so two updates cannot interleave
+  2   works out how this copy was installed (see "Installs that cannot update
+      themselves" below)
+  3   asks the registry for the target version and its \`engines.node\`
+  4   compares, and stops here with --check
+  5   checks the global folder is writable, and prints a sudo line if not.
+      It never runs sudo itself
+  6   asks the running instance whether it is BUSY — before anything is stopped
+  7   asks you, unless --yes
+  8   fetches both the new and the current version into the npm cache, while
+      the old version is still serving, so a rollback has its package to hand
+  9   stops the service
+  10  installs with the package manager this copy came from
+  11  hands over to the NEW CLI, which re-writes the service unit
+      (\`service install --refresh\`) and starts it
+  12  waits for /api/health to report the version it just installed
+  13  and if any of 10–12 fails, puts the old version back
+
+Exit codes — this command is FOR its exit code
+  0   updated, or already up to date, or --check reported
+  1   something failed, and nothing had been stopped yet
+  2   usage — including "there is no terminal to ask, so --yes is required"
+  5   this install cannot update itself. The right command was printed
+  6   the new version did not start; the old one is running again
+  7   the new version did not start and the old one could not be restored.
+      The commands to run by hand were printed
+  75  busy: a chat turn, a background task or a scheduled job is running.
+      Wait, or --force
+
+Installs that cannot update themselves (exit 5)
+  Paddock reads where it is running from, and five layouts are not ours to
+  replace. Each prints the command that WOULD work:
+
+    a container image     docker compose pull && docker compose up -d
+    a managed install     whatever PADDOCK_UPDATE_HINT says
+    npx / pnpm dlx        npx @edspencer/paddock@latest already runs the latest
+    a checkout            git pull && npm install && npm run build
+    a project dependency  update it in that project
+    a yarn classic global yarn global add @edspencer/paddock
+
+  A global npm, pnpm, bun or volta install updates in place.
+
+Where it runs from
+  From a terminal, never from inside the service. An updater the service
+  started — a Paddock chat, say — is in the service's own process group, so
+  stopping the service kills the updater half way through step 9. The busy
+  check refuses first and says so; --force from inside a chat would stop the
+  service running that chat, which then never gets to report what happened.
+
+Asking the registry
+  Only \`update\`, \`update --check\` and \`doctor\` ever contact the npm
+  registry, and only when you run them. There is no background check and no
+  check at startup; the server never asks. What the last check found is cached
+  in <data-dir>/update-check.json, which is what \`paddock service status\`
+  repeats — it never asks itself.
+
+  The registry is \`npm_config_registry\`, else \`npm config get registry\`,
+  else https://registry.npmjs.org.
+
+Docs: https://github.com/edspencer/paddock`;

package/packages/server/dist/cli/busy-command.d.ts

@@ -0,0 +1,58 @@
+import { type BusyResult, type Nouns } from "./busy.js";
+/**
+ * How each count in `/api/busy` is said in a sentence (`busy.ts` on the server
+ * decides the keys).
+ *
+ * `background` is spelled out rather than left to the default pluraliser,
+ * because "3 backgrounds are running" is not English — and because "background
+ * task" is the thing a user recognises from the running-work bar in the UI,
+ * where they watched it start.
+ */
+export declare const PADDOCK_NOUNS: Nouns;
+/**
+ * What to do about a busy answer — and for Paddock, the first thing to say is
+ * **where to run the command from**.
+ *
+ * This is the keeper-chat trap, and it is specific to Paddock and Managers
+ * among the six tools: Paddock's agents can drive Paddock. A keeper chat that
+ * runs `paddock service restart` or `paddock update` is itself one of the chat
+ * turns the answer just counted, so it will always see itself as busy — and
+ * `--force` from there does not override a mistaken reading, it kills the chat
+ * that typed it, mid-sentence, along with whatever it had not finished. The
+ * agent then has no way to report what happened, because the thing that would
+ * report it is the thing that died.
+ *
+ * So when `chat` is non-zero the advice is not "wait or use --force": it is
+ * "run this from a terminal". When the busy work is background tasks or
+ * scheduled jobs only, nobody is holding the keyboard inside the service and
+ * the ordinary advice applies.
+ */
+export declare function paddockBusyHint(result: BusyResult): string | undefined;
+/**
+ * `paddock busy [--json]` — exit 0 not busy, 75 busy, 3 nothing answering
+ * (SPEC §1, §2).
+ *
+ * The instance is found through `<data-dir>/runtime.json` and nowhere else, so
+ * this reports on the same instance `paddock serve` and `paddock config show`
+ * resolve — `resolveDataDir` in paddock.ts is the one rule all three use.
+ */
+export declare function runBusy(home: string, json: boolean): Promise<number>;
+/**
+ * The check before `service stop` and `service restart` (SPEC §1): refuse with
+ * 75 unless `--force`, which prints the same message prefixed `Overriding:` and
+ * carries on. Returns null to go ahead.
+ *
+ * `home` is the data dir of the INSTALLED unit, not whatever `--data-dir` this
+ * invocation carries — the same rule `status` and `logs` follow (#824), because
+ * the instance being stopped is the one the unit describes.
+ *
+ * Two deliberate non-refusals. Nothing answering goes ahead: there is nothing
+ * to cut short, which is also the answer for a service that is already stopped.
+ * And an instance running a Paddock from before this release has no
+ * `runtime.json`, so it reads as not running and the stop proceeds exactly as
+ * it did before — an upgrade cannot make a stop start failing.
+ */
+export declare function guardServiceBusy(action: "stop" | "restart", home: string, opts: {
+    force?: boolean;
+    json?: boolean;
+}): Promise<number | null>;

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

@@ -0,0 +1,108 @@
+/**
+ * Paddock's bindings for the copied busy client (`cli/busy.ts`): the nouns its
+ * message uses, the keeper-chat trap, and the two entry points — `paddock busy`
+ * and the check `service stop` / `service restart` run first (CLI contract
+ * SPEC §1, §4).
+ *
+ * Kept separate from `cli/busy.ts` so that file stays a straight copy of
+ * `reference/busy-client.ts`, which is what wave C4 re-syncs. Everything in
+ * here is Paddock-specific by definition: the contract says each tool's kinds of
+ * work are its own.
+ */
+import { EXIT } from "./exit-codes.js";
+import { createOutput } from "./output.js";
+import { guardBusy, runBusyCommand, } from "./busy.js";
+import { PADDOCK_NAME } from "../version.js";
+/**
+ * How each count in `/api/busy` is said in a sentence (`busy.ts` on the server
+ * decides the keys).
+ *
+ * `background` is spelled out rather than left to the default pluraliser,
+ * because "3 backgrounds are running" is not English — and because "background
+ * task" is the thing a user recognises from the running-work bar in the UI,
+ * where they watched it start.
+ */
+export const PADDOCK_NOUNS = {
+    chat: ["chat turn", "chat turns"],
+    background: ["background task", "background tasks"],
+    job: ["scheduled job", "scheduled jobs"],
+};
+/**
+ * What to do about a busy answer — and for Paddock, the first thing to say is
+ * **where to run the command from**.
+ *
+ * This is the keeper-chat trap, and it is specific to Paddock and Managers
+ * among the six tools: Paddock's agents can drive Paddock. A keeper chat that
+ * runs `paddock service restart` or `paddock update` is itself one of the chat
+ * turns the answer just counted, so it will always see itself as busy — and
+ * `--force` from there does not override a mistaken reading, it kills the chat
+ * that typed it, mid-sentence, along with whatever it had not finished. The
+ * agent then has no way to report what happened, because the thing that would
+ * report it is the thing that died.
+ *
+ * So when `chat` is non-zero the advice is not "wait or use --force": it is
+ * "run this from a terminal". When the busy work is background tasks or
+ * scheduled jobs only, nobody is holding the keyboard inside the service and
+ * the ordinary advice applies.
+ */
+export function paddockBusyHint(result) {
+    if (result.state !== "busy")
+        return undefined;
+    const chats = result.answer.counts?.chat ?? 0;
+    if (chats > 0) {
+        // The lead sentence is short because `guardBusy` prints it on the same line
+        // as the message, after `paddock: `. The reasoning goes underneath, indented
+        // like every other continuation this CLI prints.
+        return ("Run it from a terminal, not from inside a Paddock chat.\n" +
+            "    One of the turns counted above may be the chat asking, and --force from there\n" +
+            "    stops the service running that chat — which then never gets to say so.\n" +
+            "    Otherwise: wait for the turns to finish.");
+    }
+    return "Try again once it has finished, or use --force.";
+}
+/** The options both entry points share: name, nouns and hint are fixed for Paddock. */
+function paddockBusyOptions(home, out) {
+    return { home, out, name: PADDOCK_NAME, nouns: PADDOCK_NOUNS, hint: paddockBusyHint };
+}
+/**
+ * `paddock busy [--json]` — exit 0 not busy, 75 busy, 3 nothing answering
+ * (SPEC §1, §2).
+ *
+ * The instance is found through `<data-dir>/runtime.json` and nowhere else, so
+ * this reports on the same instance `paddock serve` and `paddock config show`
+ * resolve — `resolveDataDir` in paddock.ts is the one rule all three use.
+ */
+export async function runBusy(home, json) {
+    const out = createOutput({ tool: "paddock", json });
+    return runBusyCommand(paddockBusyOptions(home, out));
+}
+/**
+ * The check before `service stop` and `service restart` (SPEC §1): refuse with
+ * 75 unless `--force`, which prints the same message prefixed `Overriding:` and
+ * carries on. Returns null to go ahead.
+ *
+ * `home` is the data dir of the INSTALLED unit, not whatever `--data-dir` this
+ * invocation carries — the same rule `status` and `logs` follow (#824), because
+ * the instance being stopped is the one the unit describes.
+ *
+ * Two deliberate non-refusals. Nothing answering goes ahead: there is nothing
+ * to cut short, which is also the answer for a service that is already stopped.
+ * And an instance running a Paddock from before this release has no
+ * `runtime.json`, so it reads as not running and the stop proceeds exactly as
+ * it did before — an upgrade cannot make a stop start failing.
+ */
+export async function guardServiceBusy(action, home, opts) {
+    // No `result()` call on this path, so `--json` only decides which stream the
+    // prose goes to — the one JSON document a `--json` stop may print belongs to
+    // the stop, not to the check it ran first.
+    const out = createOutput({ tool: "paddock", json: opts.json === true });
+    const refusal = await guardBusy({
+        ...paddockBusyOptions(home, out),
+        ...(opts.force === true ? { force: true } : {}),
+    });
+    if (refusal === null)
+        return null;
+    // Spell out the way past it, after the hint about where to run it from.
+    out.warn(`\n    paddock service ${action} --force      ${action} it anyway\n`);
+    return EXIT.busy;
+}

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

@@ -0,0 +1,69 @@
+import type { Output } from "./output.js";
+/** What `/api/busy` answers (SPEC §4). Counts only, until §10's first question is settled. */
+export interface BusyAnswer {
+    busy: boolean;
+    version?: string;
+    counts?: Record<string, number>;
+}
+export type BusyResult = {
+    state: "not-running";
+} | {
+    state: "idle" | "busy";
+    url: string;
+    answer: BusyAnswer;
+}
+/** Something answered, but not with a busy answer: an older version without `/api/busy`, or another program. */
+ | {
+    state: "unknown";
+    url: string;
+    detail: string;
+};
+export interface FindOptions {
+    /** The tool's data home, holding `runtime.json`. */
+    home: string;
+    /** Ask this URL instead of the one in `runtime.json` (`--url`, or a port the user named). */
+    url?: string;
+    /** How long to wait for an answer. §4 asks for well under a second; this allows for a slow machine. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * 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 declare function checkBusy(o: FindOptions): Promise<BusyResult>;
+/** A kind's singular and plural, where adding an "s" is wrong: `{ batch: ['batch', 'batches'] }`. */
+export type Nouns = Record<string, [singular: string, plural: string]>;
+/** `2 chats and 1 job are running`, from the non-zero counts; '' if there are none. */
+export declare function describeCounts(counts?: Record<string, number>, nouns?: Nouns): string;
+/** The sentence for a person (SPEC §4): `Paddock is busy: 2 chats are running.` */
+export declare function busyMessage(name: string, result: BusyResult, nouns?: Nouns): string;
+/** 0 idle, 75 busy, 3 nothing answers, 1 an answer that isn't a busy answer. */
+export declare function busyExitCode(result: BusyResult): number;
+/** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
+export declare function busyJson(result: BusyResult): Record<string, unknown>;
+/**
+ * LOCAL CHANGE (see the header): what to suggest when the answer is busy, as a string or as a function of the
+ * result. {@link resolveHint} is what both the command and the guard call, so the two can never print different
+ * advice about the same answer.
+ */
+export type BusyHint = string | ((result: BusyResult) => string | undefined);
+export interface BusyCommandOptions extends FindOptions {
+    /** The product's name, for messages: `Local Review`. */
+    name: string;
+    out: Output;
+    nouns?: Nouns;
+    /** LOCAL CHANGE: the advice printed after a busy message — Paddock's keeper-chat trap. */
+    hint?: BusyHint;
+}
+/** `<tool> busy [--json]`. Returns the exit code; the caller sets `process.exitCode`. */
+export declare function runBusyCommand(o: BusyCommandOptions): Promise<number>;
+export interface GuardOptions extends BusyCommandOptions {
+    force?: boolean;
+}
+/**
+ * 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 declare function guardBusy(o: GuardOptions): Promise<number | null>;