@edspencer/paddock 0.81.0 → 0.82.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.81.0",
+  "version": "0.82.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

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

@@ -77,10 +77,41 @@ export interface CliOptions {
      *
      * The refusal it skips is the only thing it skips. It does not change what the
      * busy check printed — a forced stop prints the same sentence, prefixed
-     * `Overriding:` — and in wave C2 it will not skip `update`'s health check or
-     * its rollback either.
+     * `Overriding:` — and on `update` it skips the busy check and nothing else:
+     * the health check and the rollback still run (SPEC §1).
      */
     force?: boolean;
+    /**
+     * `update`: report what a new version would be, and change nothing
+     * (SPEC §1, §5 step 4).
+     *
+     * Named `checkOnly` rather than `check` because `check` reads as a verb in a
+     * bag of flags that also carries `write` and `follow`; `update-command.ts`
+     * maps it back to the contract's `--check` at the one seam.
+     */
+    checkOnly?: boolean;
+    /** `update --to <version|tag>`: the only way to move to a LOWER version. */
+    to?: string;
+    /**
+     * `update --yes`: do not ask.
+     *
+     * Required when there is no TTY, where a command that would have asked exits
+     * 2 instead of guessing (SPEC §1, §3). That asymmetry is deliberate: a
+     * scripted update that silently assumed yes would be a restart nobody asked
+     * for, and one that silently assumed no would be a no-op reported as success.
+     */
+    yes?: boolean;
+    /**
+     * `service install --refresh`: re-render the unit, keeping the settings the
+     * EXISTING one carries (SPEC §1, §5 step 11).
+     *
+     * This is the hand-over `update` performs: the NEW version writes the unit,
+     * in its own format, with the port and data dir the OLD one recorded. It
+     * needs an installed unit — with nothing to refresh it exits 4 rather than
+     * quietly performing a first install with defaults, which is how a
+     * `--port 9000` service comes back on 7233.
+     */
+    refresh?: boolean;
 }
 /**
  * A failure with an exit code attached (SPEC §2).
@@ -135,7 +166,7 @@ export type ConfigAction = (typeof CONFIG_ACTIONS)[number];
  * 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 declare const VERBS: readonly ["serve", "start", "service", "config", "busy"];
+export declare const VERBS: readonly ["serve", "start", "service", "config", "busy", "update", "upgrade"];
 /**
  * A parsed invocation: which verb, plus the flags that followed it.
  *
@@ -159,33 +190,17 @@ export type Command = {
  | {
     verb: "busy";
     opts: CliOptions;
-};
+}
 /**
- * Split a leading verb off the argv, then parse the rest as flags.
- *
- * The dispatch is deliberately a check on `argv[0]` alone rather than a scan for
- * the first non-flag token, and it happens BEFORE the flag loop. Two properties
- * fall out of that, both of which matter more than the flexibility given up:
- *
- * - **Bare `paddock` is untouched.** No verb means the whole argv goes to
- *   {@link parseArgs} exactly as before, so the demo path cannot change
- *   behaviour, and an unrecognised leading token still produces `unknown
- *   option:` from the flag loop rather than a new and different error.
- * - **Flags parse after a verb**, so `paddock start --port 7299` and
- *   `paddock service install --port 7299` both work, and the flag grammar is
- *   the same one in every position.
- *
- * A verb is only a verb in first position: `paddock --port start` is an error
- * from `--port`, not a `start` invocation, and `paddock start start` is still
- * `unknown option`.
- *
- * That first half used to claim a *missing-value* error, which was wrong (#823):
- * `next()` only rejects `undefined`, so `start` was happily consumed as the port
- * and became `NaN` in `config.ts`. It is now a **value** error — `--port needs a
- * number between 1 and 65535` — which is the behaviour the claim was reaching
- * 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.
+ * `update` (SPEC §1, §5). `upgrade` is a HIDDEN alias: the spec requires it
+ * be accepted, and deliberately does not list it in the help — one name in
+ * the documentation, two that work, so nobody has to remember which word this
+ * tool chose.
  */
+ | {
+    verb: "update";
+    opts: CliOptions;
+};
 export declare function parseCommand(argv: string[]): Command;
 export declare function parseArgs(argv: string[]): CliOptions;
 /**
@@ -211,8 +226,18 @@ export declare function explainListenError(err: unknown, host: string, port: str
  * bury the one line explaining what went wrong. The full text is one
  * `--help` away, and the last line here says so.
  */
-export declare const USAGE_SYNOPSIS = "Usage\n  paddock [serve] [options]               run the server in this terminal\n  paddock service <action> [options]      install|uninstall|status|start|stop|restart|logs\n  paddock busy [--json]                   is the running instance busy?\n  paddock config <show|eject> [options]   what this instance's config resolved to\n  paddock -v | --version                  print the version and exit\n  paddock -h | --help                     the full help";
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        run the server (the default)\n  paddock serve [options]                 the same thing, said out loud\n                                          (`paddock start` is a permanent alias)\n  paddock service install [options]       run it in the background from login\n  paddock service uninstall               stop it and remove the unit\n  paddock service status [--json]         installed? running? which version?\n  paddock service start                   start an installed service\n  paddock service stop [--force]          stop it, leave it installed\n  paddock service restart [--force]       stop it and start it again\n  paddock service logs [-f] [-n <lines>]  the service's log\n                                          (`paddock service --help`)\n  paddock busy [--json]                   is it busy? exit 0 no, 75 yes, 3\n                                          nothing answering\n                                          (`paddock busy --help`)\n  paddock config show [--resolved]        what this instance's config resolved\n                                          to, and where each value came from\n  paddock config eject [--write]          freeze that resolution into\n                                          paddock.config.yaml\n                                          (`paddock config --help`)\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nExit codes\n  0   done; running and answering; not busy\n  1   failed\n  2   usage: an unknown command or flag, or a bad value\n  3   not running: installed, but not running or not answering; nothing answers\n  4   not installed: there is no service unit\n  75  busy: refused, and why was printed. Try later, or use --force\n\nOpening your own directories\n  Where you run this from does not matter \u2014 the instance is decided by its data\n  dir alone. Directories are added inside the app, on the Discover screen: it\n  reads your Claude Code history, lists the directories you have worked in, and\n  links the ones you tick as projects. A new instance opens on it.\n\n  Importing a directory does not write into it. No .paddock/, no .chats/, no\n  .gitignore edits, no CLAUDE.md \u2014 the project record and the copied transcripts\n  both live in the data dir, and the project just points at the path. Your own\n  ~/.claude transcripts are copied, never moved or deleted, so your terminal\n  `claude` keeps working exactly as before.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nPosture profiles\n  One key picks how much Paddock shares and how much its agents may do:\n\n    profile: balanced     # paranoid | balanced | yolo   (PADDOCK_PROFILE)\n\n  paranoid shares nothing but the login and turns every capability off \u2014 the\n  behaviour Paddock had before profiles existed. balanced (the default)\n  inherits the CAPABILITIES your CLI already has \u2014 instructions, MCP servers,\n  plugins \u2014 and adds the read-only self-management tools, while keeping your\n  chat history Paddock's own. yolo turns the rest on: your transcripts, host\n  hooks, the write and project tools, schedule mutation, deeper spawning, the\n  browser.\n\n  A profile only sets defaults \u2014 any single key still overrides it, and an\n  individual key in the config file beats PADDOCK_PROFILE in the environment.\n  Profiles never touch your port, bind address, auth or model list: yolo does\n  NOT open the bind or relax auth, which stay a separate, explicit decision.\n\n  What host actually reaches depends on the machine \u2014 a workstation has a real\n  ~/.claude, a container usually has none. The profile sets the levers, the\n  environment sets the blast radius.\n\n  To see what your profile actually expanded to on THIS machine, with the layer\n  each value came from:  paddock config show --resolved\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml, and each defaults to whatever your profile\n  says (see Posture profiles below):\n\n    claude:\n      transcripts: host   # own | host   host on yolo only\n      credentials: host   # own | host   host on every profile\n      instructions: host  # own | host   own on paranoid, else host\n      hooks: host         # own | host   host on yolo only\n      mcpServers: host    # own | host   own on paranoid, else host\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. On from balanced up, so your curated CLAUDE.md does reach Paddock's\n  agents; profile: paranoid or instructions: own keeps it out. Each project's\n  own CLAUDE.md applies either way.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
-export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status [--json]     is it registered, is it running, which\n                                      version, where are the logs\n  paddock service start               start an installed service that is stopped\n  paddock service stop [--force]      stop it, and leave it installed\n  paddock service restart [--force]   stop it and start it again, re-reading config\n  paddock service logs [-f] [-n <n>]  the service's log (the last 50 lines)\n\nOptions (logs)\n  -f, --follow            keep printing what gets appended, until Ctrl-C\n  -n, --lines <n>         how many lines to print first (default 50)\n\nOptions (stop, restart)\n      --force             stop it even though it is busy\n\nBusy\n  `stop` and `restart` ask the running instance whether it is busy first, and\n  refuse with exit 75 if it is \u2014 a chat turn in flight, a background task, a\n  scheduled job. `paddock busy` asks the same question on its own.\n\n  Being refused is the useful case: a restart kills a chat turn mid-sentence,\n  and the turn cannot be resumed from where it was. Wait, or --force.\n\n  `uninstall` does not ask. Removing the service is an explicit act, and\n  someone uninstalling it has already decided.\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Left out of the unit when you omit it\n                          AND `PADDOCK_DATA_DIR` is unset in this shell, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways. If\n                          `PADDOCK_DATA_DIR` IS set here, that path is recorded\n                          in the unit \u2014 the service would otherwise point\n                          somewhere your terminal does not.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n  Linux   ~/.config/systemd/user/paddock.service\n\n  Both write stdout and stderr to ONE file, <data-dir>/logs/service.log, which\n  is what `paddock service logs` reads. Not the journal on Linux: a volatile\n  journal has nothing in it after the reboot you are asking about, and one file\n  means one answer to \"where are the logs\" on every OS. Paddock rotates it\n  itself at 8 MB, keeping three older generations beside it.\n\nExit codes\n  0   it is installed, running and answering\n  3   installed, but not running or not answering\n  4   not installed: there is no unit  (status, logs, start, stop, restart)\n  1   something failed\n  2   usage: an unknown action or flag, or a bad value\n  75  busy, and --force was not given  (stop, restart)\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE_SYNOPSIS = "Usage\n  paddock [serve] [options]               run the server in this terminal\n  paddock service <action> [options]      install|uninstall|status|start|stop|restart|logs\n  paddock busy [--json]                   is the running instance busy?\n  paddock update [--check] [--to <v>]     install a newer Paddock\n  paddock config <show|eject> [options]   what this instance's config resolved to\n  paddock -v | --version                  print the version and exit\n  paddock -h | --help                     the full help";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        run the server (the default)\n  paddock serve [options]                 the same thing, said out loud\n                                          (`paddock start` is a permanent alias)\n  paddock service install [options]       run it in the background from login\n  paddock service uninstall               stop it and remove the unit\n  paddock service status [--json]         installed? running? which version?\n  paddock service start                   start an installed service\n  paddock service stop [--force]          stop it, leave it installed\n  paddock service restart [--force]       stop it and start it again\n  paddock service logs [-f] [-n <lines>]  the service's log\n                                          (`paddock service --help`)\n  paddock busy [--json]                   is it busy? exit 0 no, 75 yes, 3\n                                          nothing answering\n                                          (`paddock busy --help`)\n  paddock update [--check] [--to <v>]     install a newer Paddock and restart\n                                          the service\n                                          (`paddock update --help`)\n  paddock config show [--resolved]        what this instance's config resolved\n                                          to, and where each value came from\n  paddock config eject [--write]          freeze that resolution into\n                                          paddock.config.yaml\n                                          (`paddock config --help`)\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nExit codes\n  0   done; running and answering; up to date; not busy\n  1   failed\n  2   usage: an unknown command or flag, or a bad value\n  3   not running: installed, but not running or not answering; nothing answers\n  4   not installed: there is no service unit\n  5   this install cannot update itself; the right command was printed  (update)\n  6   the update failed and was rolled back; the old version is back    (update)\n  7   the update failed and could not be rolled back; a person is needed\n  75  busy: refused, and why was printed. Try later, or use --force\n\nOpening your own directories\n  Where you run this from does not matter \u2014 the instance is decided by its data\n  dir alone. Directories are added inside the app, on the Discover screen: it\n  reads your Claude Code history, lists the directories you have worked in, and\n  links the ones you tick as projects. A new instance opens on it.\n\n  Importing a directory does not write into it. No .paddock/, no .chats/, no\n  .gitignore edits, no CLAUDE.md \u2014 the project record and the copied transcripts\n  both live in the data dir, and the project just points at the path. Your own\n  ~/.claude transcripts are copied, never moved or deleted, so your terminal\n  `claude` keeps working exactly as before.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nPosture profiles\n  One key picks how much Paddock shares and how much its agents may do:\n\n    profile: balanced     # paranoid | balanced | yolo   (PADDOCK_PROFILE)\n\n  paranoid shares nothing but the login and turns every capability off \u2014 the\n  behaviour Paddock had before profiles existed. balanced (the default)\n  inherits the CAPABILITIES your CLI already has \u2014 instructions, MCP servers,\n  plugins \u2014 and adds the read-only self-management tools, while keeping your\n  chat history Paddock's own. yolo turns the rest on: your transcripts, host\n  hooks, the write and project tools, schedule mutation, deeper spawning, the\n  browser.\n\n  A profile only sets defaults \u2014 any single key still overrides it, and an\n  individual key in the config file beats PADDOCK_PROFILE in the environment.\n  Profiles never touch your port, bind address, auth or model list: yolo does\n  NOT open the bind or relax auth, which stay a separate, explicit decision.\n\n  What host actually reaches depends on the machine \u2014 a workstation has a real\n  ~/.claude, a container usually has none. The profile sets the levers, the\n  environment sets the blast radius.\n\n  To see what your profile actually expanded to on THIS machine, with the layer\n  each value came from:  paddock config show --resolved\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml, and each defaults to whatever your profile\n  says (see Posture profiles below):\n\n    claude:\n      transcripts: host   # own | host   host on yolo only\n      credentials: host   # own | host   host on every profile\n      instructions: host  # own | host   own on paranoid, else host\n      hooks: host         # own | host   host on yolo only\n      mcpServers: host    # own | host   own on paranoid, else host\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. On from balanced up, so your curated CLAUDE.md does reach Paddock's\n  agents; profile: paranoid or instructions: own keeps it out. Each project's\n  own CLAUDE.md applies either way.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service install --refresh   re-write the unit, keeping its settings\n  paddock service uninstall           stop it and deregister it\n  paddock service status [--json]     is it registered, is it running, which\n                                      version, where are the logs\n  paddock service start               start an installed service that is stopped\n  paddock service stop [--force]      stop it, and leave it installed\n  paddock service restart [--force]   stop it and start it again, re-reading config\n  paddock service logs [-f] [-n <n>]  the service's log (the last 50 lines)\n\nOptions (logs)\n  -f, --follow            keep printing what gets appended, until Ctrl-C\n  -n, --lines <n>         how many lines to print first (default 50)\n\nOptions (stop, restart)\n      --force             stop it even though it is busy\n\nOptions (install)\n      --refresh           Re-render the unit from the settings the EXISTING one\n                          carries \u2014 its port, host, data dir and verbosity \u2014\n                          rather than from this shell's flags and environment.\n                          This is what `paddock update` runs, through the new\n                          version's CLI, so the unit is written in the format\n                          that version writes. Exit 4 with nothing installed:\n                          there is no unit to refresh, and doing a first\n                          install with defaults instead is how a --port 9000\n                          service comes back on 7233.\n\nBusy\n  `stop` and `restart` ask the running instance whether it is busy first, and\n  refuse with exit 75 if it is \u2014 a chat turn in flight, a background task, a\n  scheduled job. `paddock busy` asks the same question on its own.\n\n  Being refused is the useful case: a restart kills a chat turn mid-sentence,\n  and the turn cannot be resumed from where it was. Wait, or --force.\n\n  `uninstall` does not ask. Removing the service is an explicit act, and\n  someone uninstalling it has already decided.\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Left out of the unit when you omit it\n                          AND `PADDOCK_DATA_DIR` is unset in this shell, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways. If\n                          `PADDOCK_DATA_DIR` IS set here, that path is recorded\n                          in the unit \u2014 the service would otherwise point\n                          somewhere your terminal does not.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n  Linux   ~/.config/systemd/user/paddock.service\n\n  Both write stdout and stderr to ONE file, <data-dir>/logs/service.log, which\n  is what `paddock service logs` reads. Not the journal on Linux: a volatile\n  journal has nothing in it after the reboot you are asking about, and one file\n  means one answer to \"where are the logs\" on every OS. Paddock rotates it\n  itself at 8 MB, keeping three older generations beside it.\n\nExit codes\n  0   it is installed, running and answering\n  3   installed, but not running or not answering\n  4   not installed: there is no unit  (status, logs, start, stop, restart)\n  1   something failed\n  2   usage: an unknown action or flag, or a bad value\n  75  busy, and --force was not given  (stop, restart)\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";
 export declare const BUSY_USAGE = "paddock busy \u2014 is the running instance in the middle of something?\n\nUsage\n  paddock busy                        ask, and say so in a sentence\n  paddock busy --json                 the same answer as one JSON document\n  paddock busy -d <path>              ask a particular instance\n\nExit codes \u2014 this command is FOR its exit code\n  0   not busy. Nothing a restart would cut short.\n  75  busy. What is running was printed.\n  3   nothing answered. No instance is running, so there is nothing to wait for.\n  1   something answered, but not as Paddock's busy check.\n\nOptions\n  -d, --data-dir <path>   Which instance to ask (default ~/.paddock, or\n                          $PADDOCK_DATA_DIR) \u2014 the same rule `paddock serve`\n                          uses, so the two always mean the same instance\n      --json              One JSON document on stdout: running, busy, url,\n                          version, counts. Prose goes to stderr\n  -h, --help              Show this help\n\nWhat counts as busy\n  Only work a restart would LOSE or cut short:\n\n    chat         a chat turn running \u2014 a human turn, a fired trigger, a cron\n                 fire. A turn is a live claude subprocess writing a transcript,\n                 and it cannot be resumed from where it was interrupted.\n    background   a background task a live session is still holding after its\n                 turn ended: a background shell, a sub-agent, a Monitor.\n    job          a scheduled job herdctl is running.\n\n  Not busy: an idle session (it resumes), an open browser tab (it reconnects),\n  a pending curation sweep (it re-runs from its watermark).\n\nWhere to run it from\n  From a terminal. A Paddock chat that runs this is itself one of the chat turns\n  it counts, so it will always see itself as busy \u2014 and `service stop --force`\n  from inside a chat stops the service that is running the chat, which does not\n  come back with an explanation. That is why the refusal says so.\n\nFor scripts, containers and Watchtower\n  `busy` is there for callers with no service to ask. 75 is EX_TEMPFAIL, which\n  is the code Watchtower's pre-update hook reads as \"skip this one\":\n\n    labels:\n      com.centurylinklabs.watchtower.lifecycle.pre-update: paddock busy\n\n  An Ansible task does the same thing with a retry. Nothing here contacts the\n  network or the npm registry, and the question is answered from memory \u2014 it is\n  cheap enough to ask in a loop.\n\nHow it finds the instance\n  `<data-dir>/runtime.json`, written 0600 when the server starts listening and\n  removed when it stops. There is no fallback to a default port: guessing one\n  would ask whatever else happened to be listening there, and get an answer.\n\n  A Paddock from before this feature shipped writes no such file, so it reads as\n  not running (exit 3). Upgrade it and restart it once.\n\nDocs: https://github.com/edspencer/paddock";
 export declare const CONFIG_USAGE = "paddock config \u2014 what this instance's configuration actually resolved to\n\nUsage\n  paddock config show                 the decisions: your profile, the keys your\n                                      config file sets, the variables your\n                                      environment sets\n  paddock config show --resolved      EVERY effective value, and which layer it\n                                      came from\n  paddock config show --json          the same report as JSON, long values in\n                                      full (sensitive ones still hidden)\n  paddock config eject                what freezing that resolution into\n                                      paddock.config.yaml would write \u2014 a\n                                      preview; writes nothing\n  paddock config eject --write        actually write it\n\nOptions\n  -d, --data-dir <path>   Which instance to inspect (default ~/.paddock, or\n                          $PADDOCK_DATA_DIR) \u2014 the same rule `paddock start`\n                          uses, so the two always read the same instance\n      --resolved          show: every field, not just the ones someone set\n      --json              show: the whole report as JSON (implies --resolved's\n                          scope)\n      --show-sensitive    show: print the values of fields marked sensitive\n      --write             eject: apply the plan. Without it, eject only prints\n      --include-env       eject: also freeze values an environment variable\n                          currently supplies (see below \u2014 off by default)\n  -h, --help              Show this help\n\nWhere a value can come from\n  Config resolves in four layers, and each row of --resolved names the one that\n  won:\n\n    default            Paddock's built-in default.\n    profile (<name>)   Your posture profile. The twelve levers a profile governs\n                       have no code default of their own any more \u2014 the profile\n                       IS their default \u2014 so this is a distinct answer from\n                       \"default\", and switching profile would change it.\n    file               A key in paddock.config.yaml.\n    env <NAME>         An environment variable, which beats the file for the\n                       same key.\n\n  One wrinkle worth knowing, and the command shows it plainly: an individual key\n  in the FILE beats PADDOCK_PROFILE in the environment. Specific beats general \u2014\n  PADDOCK_PROFILE speaks for the levers you did not mention.\n\nWhy show, and not just write it all into the file\n  `show` is computed by the loader the server boots with, so it cannot drift\n  from what the process would actually do. A materialized file can: it stops\n  inheriting improved defaults, says nothing about the variables your container\n  sets on top, and no longer describes the whole surface the day a lever is\n  added. That is why the thin file is the default and `show` is the answer to\n  \"what am I actually running?\".\n\n  `eject` is there for when you want it written down anyway \u2014 frozen, in the\n  file, reviewable in git. It is a real tradeoff rather than a better `show`,\n  so it prints what it would cost you and writes nothing until you pass --write.\n\nWhat eject writes, and what it leaves alone\n  It writes the posture levers your profile expanded to, plus the behavioural\n  settings the Config screen already round-trips through this file. It does NOT\n  write:\n\n    the bindings     port, host, data dir, projects root, state dir, web dist.\n                     These resolve to absolute paths on THIS machine, and the\n                     data dir resolves to the directory holding the file \u2014 so\n                     ejecting them makes the file unportable and unmountable.\n    sensitive keys   transcription.endpoint can carry credentials in its URL.\n                     Bulk-writing a secret-shaped value to disk should not be\n                     one keystroke away; write that key by hand.\n    env-owned keys   by default. An environment variable BEATS the file, so\n                     writing its value in changes nothing today and everything\n                     the day the variable goes away \u2014 a deferred, silent change\n                     of provenance. eject names each one it skipped instead.\n                     --include-env writes them, which is the right flag if you\n                     are deliberately migrating from env vars to a file.\n\n  It always writes `profile:` as well, even though every key that profile\n  governs is now explicit. That line is what a lever added in a FUTURE release\n  falls back to: without it, a new capability toggle would resolve against the\n  built-in default profile rather than the posture you actually ejected from.\n\n  Your comments and any keys Paddock does not manage survive \u2014 the file is\n  round-tripped, not regenerated \u2014 and the write is atomic.\n\nReading nothing, writing nothing\n  `show` resolves config and prints it. It starts no server, contacts nothing,\n  and writes no file \u2014 including the data dir itself, which it will report as\n  missing rather than create. `eject` writes exactly one file, and only with\n  --write.\n\n  Values are printed to a terminal that often ends up pasted into an issue, so\n  fields marked sensitive are shown as (hidden). None of them is a secret \u2014\n  Paddock keeps secrets out of this surface entirely, so there is no API key or\n  JWT signing material here to hide or reveal.\n\nDocs: 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 declare const UPDATE_SYNOPSIS = "Usage\n  paddock update [--yes]                  install the latest release\n  paddock update --check [--json]         what a new version would be; changes nothing\n  paddock update --to <version|tag>       a particular version, or a dist-tag\n  paddock update --force                  skip the busy check, and nothing else\n  paddock update --help                   the full help";
+export declare const UPDATE_USAGE = "paddock update \u2014 install a newer Paddock, and put the service back up\n\nUsage\n  paddock update                      update to the latest release, asking first\n  paddock update --check              what a new version would be; changes nothing\n  paddock update --yes                do not ask (required when there is no terminal)\n  paddock update --to 0.79.1          a particular version \u2014 the only way to go BACK\n  paddock update --to next            a dist-tag\n  paddock update --json               one JSON document on stdout\n\nOptions\n      --check             Ask the registry, report, and change nothing. Exits 0\n                          whether or not there is an update \u2014 scripts read\n                          `updateAvailable` from --json\n      --to <version|tag>  Install this version or dist-tag instead of latest.\n                          Required to move to a LOWER version: an update never\n                          goes backwards by accident\n      --yes, -y           Skip the question. Required when stdin is not a\n                          terminal, where a command that would have asked exits\n                          2 rather than guessing\n      --force             Skip the busy check, and nothing else \u2014 the health\n                          check and the rollback still run\n      --json              One JSON document on stdout; all prose on stderr\n  -h, --help              Show this help\n\nWhat it does, in order\n  1   takes <data-dir>/update.lock, so two updates cannot interleave\n  2   works out how this copy was installed (see \"Installs that cannot update\n      themselves\" below)\n  3   asks the registry for the target version and its `engines.node`\n  4   compares, and stops here with --check\n  5   checks the global folder is writable, and prints a sudo line if not.\n      It never runs sudo itself\n  6   asks the running instance whether it is BUSY \u2014 before anything is stopped\n  7   asks you, unless --yes\n  8   fetches both the new and the current version into the npm cache, while\n      the old version is still serving, so a rollback has its package to hand\n  9   stops the service\n  10  installs with the package manager this copy came from\n  11  hands over to the NEW CLI, which re-writes the service unit\n      (`service install --refresh`) and starts it\n  12  waits for /api/health to report the version it just installed\n  13  and if any of 10\u201312 fails, puts the old version back\n\nExit codes \u2014 this command is FOR its exit code\n  0   updated, or already up to date, or --check reported\n  1   something failed, and nothing had been stopped yet\n  2   usage \u2014 including \"there is no terminal to ask, so --yes is required\"\n  5   this install cannot update itself. The right command was printed\n  6   the new version did not start; the old one is running again\n  7   the new version did not start and the old one could not be restored.\n      The commands to run by hand were printed\n  75  busy: a chat turn, a background task or a scheduled job is running.\n      Wait, or --force\n\nInstalls that cannot update themselves (exit 5)\n  Paddock reads where it is running from, and five layouts are not ours to\n  replace. Each prints the command that WOULD work:\n\n    a container image     docker compose pull && docker compose up -d\n    a managed install     whatever PADDOCK_UPDATE_HINT says\n    npx / pnpm dlx        npx @edspencer/paddock@latest already runs the latest\n    a checkout            git pull && npm install && npm run build\n    a project dependency  update it in that project\n    a yarn classic global yarn global add @edspencer/paddock\n\n  A global npm, pnpm, bun or volta install updates in place.\n\nWhere it runs from\n  From a terminal, never from inside the service. An updater the service\n  started \u2014 a Paddock chat, say \u2014 is in the service's own process group, so\n  stopping the service kills the updater half way through step 9. The busy\n  check refuses first and says so; --force from inside a chat would stop the\n  service running that chat, which then never gets to report what happened.\n\nAsking the registry\n  Only `update`, `update --check` and `doctor` ever contact the npm\n  registry, and only when you run them. There is no background check and no\n  check at startup; the server never asks. What the last check found is cached\n  in <data-dir>/update-check.json, which is what `paddock service status`\n  repeats \u2014 it never asks itself.\n\n  The registry is `npm_config_registry`, else `npm config get registry`,\n  else https://registry.npmjs.org.\n\nDocs: https://github.com/edspencer/paddock";

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

@@ -34,7 +34,7 @@ import { EXIT } from "./exit-codes.js";
  */
 export class CliError extends Error {
     exitCode;
-    constructor(message, exitCode = EXIT.failure) {
+    constructor(message, exitCode = EXIT.FAILED) {
         super(message);
         this.exitCode = exitCode;
     }
@@ -49,7 +49,7 @@ export class CliError extends Error {
  */
 export class UsageError extends CliError {
     constructor(message) {
-        super(message, EXIT.usage);
+        super(message, EXIT.USAGE);
     }
 }
 export const MIN_NODE_MAJOR = 22;
@@ -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", "busy"];
+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,27 +141,70 @@ 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);
-    // `--force` overrides the busy check (SPEC §1, §4) and nothing else, so it
-    // only means anything on the two commands that run one. Rejecting it
-    // everywhere else, 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.
-    //
-    // Checked here, once, rather than in each command: a second copy of this rule
-    // is a second chance for the two to drift apart about what `--force` means.
-    if (command.opts.force === true &&
-        // `--help` wins, the same way it wins over a missing action above: asking
-        // for the usage is not a usage error.
-        !command.opts.help &&
-        !(command.verb === "service" && (command.action === "stop" || command.action === "restart"))) {
-        const what = command.verb === "service" && command.action !== undefined
-            ? `\`service ${command.action}\``
-            : `\`${command.verb}\``;
-        throw new UsageError(`--force applies to \`service stop\` and \`service restart\` only, not ${what}.\n` +
-            "It overrides the busy check, and those are the two commands that run one.");
+    // `--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;
 }
@@ -178,6 +221,9 @@ function dispatch(argv) {
     // 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) };
@@ -249,10 +295,31 @@ export function parseArgs(argv) {
             case "--include-env":
                 opts.includeEnv = true;
                 break;
-            // `service stop` / `service restart`: override the busy check (SPEC §4).
+            // `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":
@@ -327,6 +394,7 @@ 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`;
@@ -347,6 +415,9 @@ Usage
   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
@@ -363,11 +434,14 @@ Options
   -h, --help              Show this help
 
 Exit codes
-  0   done; running and answering; not busy
+  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; 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
@@ -472,6 +546,7 @@ 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
@@ -487,6 +562,17 @@ Options (logs)
 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
@@ -715,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.js

@@ -104,5 +104,5 @@ export async function guardServiceBusy(action, home, opts) {
         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;
+    return EXIT.BUSY;
 }

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

@@ -1,10 +1,8 @@
-// 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.
+// From edspencer/cli-contract reference/busy-client.ts @ 0.2; local changes: `.ts` import specifiers → `.js` and
+// `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); 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.
@@ -88,13 +86,13 @@ export function busyMessage(name, result, nouns = {}) {
 export function busyExitCode(result) {
     switch (result.state) {
         case "idle":
-            return EXIT.ok;
+            return EXIT.OK;
         case "busy":
-            return EXIT.busy;
+            return EXIT.BUSY;
         case "not-running":
-            return EXIT.notRunning;
+            return EXIT.NOT_RUNNING;
         case "unknown":
-            return EXIT.failure;
+            return EXIT.FAILED;
     }
 }
 /** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
@@ -146,5 +144,5 @@ export async function guardBusy(o) {
         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);
+    return o.out.error(`${message} ${hint}`, EXIT.BUSY);
 }