@edspencer/paddock 0.79.0 → 0.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.79.0",
+  "version": "0.80.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.34.0",
+    "@herdctl/core": "5.34.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",

package/packages/server/dist/app.js

@@ -15,7 +15,6 @@ import fastifyStatic from "@fastify/static";
 import fastifyMultipart from "@fastify/multipart";
 import fastifySwagger from "@fastify/swagger";
 import fastifySwaggerUi from "@fastify/swagger-ui";
-import { createRequire } from "node:module";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { loadPaddockConfig } from "./config.js";
@@ -50,17 +49,9 @@ import { TriggerSessionStore } from "./trigger-session.js";
 import { PaddockEventBus } from "./event-bus.js";
 import { TriggerService } from "./triggers.js";
 import { buildSwaggerOptions, buildSwaggerUiOptions } from "./openapi.js";
-// Resolve the package version at runtime (dist/app.js → ../package.json) so the
-// generated OpenAPI document's info.version tracks the release without a build step.
-const pkgVersion = (() => {
-    try {
-        const require = createRequire(import.meta.url);
-        return require("../package.json").version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-})();
+// One source of truth for "which Paddock is this?" — the OpenAPI document,
+// /api/health and the management MCP handshake all read it (version.ts).
+import { PADDOCK_VERSION } from "./version.js";
 /**
  * True when the (query-stripped) path's last segment carries a file extension —
  * e.g. `/assets/index-ABC.js`, `/favicon.ico`, `/sw.js`. Used by the SPA
@@ -85,7 +76,20 @@ export async function buildApp(opts = {}) {
     // out here. `PADDOCK_QUIET` is set by `cli/paddock.ts` unless `--verbose`.
     installHerdctlLogBridge({ quiet: (process.env.PADDOCK_QUIET ?? "") !== "" });
     const app = Fastify({
-        logger: { level: cfg.logLevel },
+        // **Logs go to stderr, not stdout**, and that is load-bearing rather than
+        // tidy. SPEC §3 of the CLI contract requires `serve`'s FIRST stdout line to
+        // be `Paddock <version>: <url>` — the line a script reads to find the URL —
+        // and boot logging is emitted before the server can know it has bound. With
+        // pino on stdout, a machine with no Claude login (every CI runner, every
+        // fresh install) put `{"level":40,…,"msg":"no Claude credentials found…"}`
+        // there first, so the first line was a JSON log record. The conformance
+        // runner caught it; nothing else would have.
+        //
+        // Nothing loses the logs: Docker and Kubernetes collect both streams, and
+        // the service units send stdout and stderr to the same file (SPEC §7). A log
+        // shipper configured for stdout ALONE is the one thing that changes, which
+        // is why the changeset says so.
+        logger: { level: cfg.logLevel, stream: process.stderr },
     });
     // --- safe-by-default bind guard (#435) --------------------------------
     // Fail closed if the resolved bind host is non-loopback AND auth is `none`:
@@ -313,7 +317,7 @@ export async function buildApp(opts = {}) {
             readImage(path.join("icons", "icon-192.png"), "image/png"),
             readImage(path.join("icons", "favicon-32.png"), "image/png"),
         ]);
-        await app.register(fastifySwagger, buildSwaggerOptions(pkgVersion, cfg.auth));
+        await app.register(fastifySwagger, buildSwaggerOptions(PADDOCK_VERSION, cfg.auth));
         await app.register(fastifySwaggerUi, buildSwaggerUiOptions({
             routePrefix: cfg.openapi.path,
             logo: swaggerLogo,

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

@@ -67,9 +67,33 @@ export interface CliOptions {
      * supplies. Off by default — see the argument in config.ts.
      */
     includeEnv?: boolean;
+    /** `service logs`: keep printing what gets appended (`-f`). */
+    follow?: boolean;
+    /** `service logs`: how many lines to print first (`-n`, default 50). */
+    lines?: number;
 }
-/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+/**
+ * A failure with an exit code attached (SPEC §2).
+ *
+ * Thrown rather than exiting, so parsing stays testable. The code travels with
+ * the error because the thing that KNOWS which code applies is whatever threw —
+ * `main` cannot tell an unsupported platform (a failure, 1) from a misspelled
+ * flag (usage, 2) by looking at a string.
+ */
 export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/**
+ * An unknown command, an unknown flag, or a bad value: exit 2 (SPEC §2).
+ *
+ * **This is a behaviour change, and a deliberate one.** Every one of these used
+ * to exit 1, which is also what a genuine failure exits — so a script could not
+ * tell "you typed it wrong" from "it tried and could not". The contract splits
+ * them, and a script that tested `$? -eq 1` for a typo now needs `-eq 2`.
+ */
+export declare class UsageError extends CliError {
+    constructor(message: string);
 }
 export declare const MIN_NODE_MAJOR = 22;
 /**
@@ -81,7 +105,7 @@ export declare const MIN_NODE_MAJOR = 22;
  * because `parseCommand` dispatches on `argv[0]` alone and only then reads an
  * action, so the two never compete for the same token.
  */
-export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status", "start", "stop", "restart"];
+export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status", "start", "stop", "restart", "logs"];
 export type ServiceAction = (typeof SERVICE_ACTIONS)[number];
 /**
  * What `paddock config` can be asked to do (#878).
@@ -93,8 +117,15 @@ export type ServiceAction = (typeof SERVICE_ACTIONS)[number];
  */
 export declare const CONFIG_ACTIONS: readonly ["show", "eject"];
 export type ConfigAction = (typeof CONFIG_ACTIONS)[number];
-/** The leading words {@link parseCommand} recognises. Anything else is a flag. */
-export declare const VERBS: readonly ["start", "service", "config"];
+/**
+ * The leading words {@link parseCommand} recognises. Anything else is a flag.
+ *
+ * `serve` is the contract's name for running in the foreground (SPEC §1), and
+ * `start` is kept as an alias **for good** — the spec says so explicitly for
+ * 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"];
 /**
  * A parsed invocation: which verb, plus the flags that followed it.
  *
@@ -103,7 +134,7 @@ export declare const VERBS: readonly ["start", "service", "config"];
  * is the whole request. It is `undefined` only when `opts.help` is true.
  */
 export type Command = {
-    verb: "start";
+    verb: "serve";
     opts: CliOptions;
 } | {
     verb: "service";
@@ -157,6 +188,15 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  * names neither the port nor the flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        start the server (the default)\n  paddock start [options]                 the same thing, said out loud\n  paddock service <install|uninstall|status>\n                                          run it in the background from login\n                                          (`paddock service --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\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              is it registered, is it running, where are the logs\n  paddock service start               start an installed service that is stopped\n  paddock service stop                stop it, and leave it installed\n  paddock service restart             stop it and start it again, re-reading config\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          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock.service -f\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";
+/**
+ * The command list, on its own.
+ *
+ * Printed after a usage error, because SPEC §2 says the usage follows the
+ * message — and because {@link USAGE} is a thousand words of guide that would
+ * 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 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                    stop it, leave it installed\n  paddock service restart                 stop it and start it again\n  paddock service logs [-f] [-n <lines>]  the service's log\n                                          (`paddock service --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\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\n  4   not installed: there is no service unit\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                stop it, and leave it installed\n  paddock service restart             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 (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\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 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";

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

@@ -23,8 +23,34 @@
  * the need for the guard entirely, so there is no condition left to get wrong on
  * the next shim, platform or package manager. `paddock.ts` now always runs.
  */
-/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+import { EXIT } from "./exit-codes.js";
+/**
+ * A failure with an exit code attached (SPEC §2).
+ *
+ * Thrown rather than exiting, so parsing stays testable. The code travels with
+ * the error because the thing that KNOWS which code applies is whatever threw —
+ * `main` cannot tell an unsupported platform (a failure, 1) from a misspelled
+ * flag (usage, 2) by looking at a string.
+ */
 export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.failure) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * An unknown command, an unknown flag, or a bad value: exit 2 (SPEC §2).
+ *
+ * **This is a behaviour change, and a deliberate one.** Every one of these used
+ * to exit 1, which is also what a genuine failure exits — so a script could not
+ * tell "you typed it wrong" from "it tried and could not". The contract splits
+ * them, and a script that tested `$? -eq 1` for a typo now needs `-eq 2`.
+ */
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT.usage);
+    }
 }
 export const MIN_NODE_MAJOR = 22;
 /**
@@ -43,6 +69,7 @@ export const SERVICE_ACTIONS = [
     "start",
     "stop",
     "restart",
+    "logs",
 ];
 /**
  * What `paddock config` can be asked to do (#878).
@@ -53,8 +80,15 @@ export const SERVICE_ACTIONS = [
  * the command that makes it unnecessary.
  */
 export const CONFIG_ACTIONS = ["show", "eject"];
-/** The leading words {@link parseCommand} recognises. Anything else is a flag. */
-export const VERBS = ["start", "service", "config"];
+/**
+ * The leading words {@link parseCommand} recognises. Anything else is a flag.
+ *
+ * `serve` is the contract's name for running in the foreground (SPEC §1), and
+ * `start` is kept as an alias **for good** — the spec says so explicitly for
+ * 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"];
 /**
  * Split an action off a verb's argv, then parse what follows as flags.
  *
@@ -67,7 +101,7 @@ function parseAction(verb, actions, rest) {
     let action;
     if (head !== undefined && !head.startsWith("-")) {
         if (!actions.includes(head)) {
-            throw new CliError(`unknown ${verb} action: ${head}\n` +
+            throw new UsageError(`unknown ${verb} action: ${head}\n` +
                 `Expected one of: ${actions.join(", ")}.\n` +
                 `Run \`paddock ${verb} --help\` for usage.`);
         }
@@ -76,7 +110,7 @@ function parseAction(verb, actions, rest) {
     const opts = parseArgs(action === undefined ? rest : rest.slice(1));
     // `--help` wins over a missing action: asking for usage is not a usage error.
     if (action === undefined && !opts.help) {
-        throw new CliError(`\`paddock ${verb}\` needs an action: ${actions.join(", ")}.\n` +
+        throw new UsageError(`\`paddock ${verb}\` needs an action: ${actions.join(", ")}.\n` +
             `Run \`paddock ${verb} --help\` for usage.`);
     }
     return { action, opts };
@@ -115,9 +149,10 @@ export function parseCommand(argv) {
     if (first === "config") {
         return { verb: "config", ...parseAction("config", CONFIG_ACTIONS, rest) };
     }
-    if (first === "start")
-        return { verb: "start", opts: parseArgs(rest) };
-    return { verb: "start", opts: parseArgs(argv) };
+    // `serve` and `start` are one command: see VERBS.
+    if (first === "serve" || first === "start")
+        return { verb: "serve", opts: parseArgs(rest) };
+    return { verb: "serve", opts: parseArgs(argv) };
 }
 export function parseArgs(argv) {
     const opts = {
@@ -131,7 +166,7 @@ export function parseArgs(argv) {
         const next = () => {
             const v = argv[++i];
             if (v === undefined)
-                throw new CliError(`${arg} needs a value`);
+                throw new UsageError(`${arg} needs a value`);
             return v;
         };
         switch (arg) {
@@ -148,7 +183,7 @@ export function parseArgs(argv) {
                 // into a hard error.
                 const v = next();
                 if (v !== "" && (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535)) {
-                    throw new CliError(`${arg} needs a number between 1 and 65535, got: ${v}`);
+                    throw new UsageError(`${arg} needs a number between 1 and 65535, got: ${v}`);
                 }
                 opts.port = v;
                 break;
@@ -185,6 +220,21 @@ export function parseArgs(argv) {
             case "--include-env":
                 opts.includeEnv = 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":
+            case "--follow":
+                opts.follow = true;
+                break;
+            case "-n":
+            case "--lines": {
+                const v = next();
+                if (!/^\d+$/.test(v) || Number(v) < 1) {
+                    throw new UsageError(`${arg} needs a positive number of lines, got: ${v}`);
+                }
+                opts.lines = Number(v);
+                break;
+            }
             case "-h":
             case "--help":
                 opts.help = true;
@@ -194,7 +244,7 @@ export function parseArgs(argv) {
                 opts.version = true;
                 break;
             default:
-                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+                throw new UsageError(`unknown option: ${arg}`);
         }
     }
     return opts;
@@ -232,13 +282,33 @@ export function explainListenError(err, host, port) {
     }
     return String(err?.message ?? err);
 }
+/**
+ * The command list, on its own.
+ *
+ * Printed after a usage error, because SPEC §2 says the usage follows the
+ * message — and because {@link USAGE} is a thousand words of guide that would
+ * bury the one line explaining what went wrong. The full text is one
+ * `--help` away, and the last line here says so.
+ */
+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 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`;
 export const USAGE = `paddock — run a Paddock instance locally
 
 Usage
-  npx @edspencer/paddock [options]        start the server (the default)
-  paddock start [options]                 the same thing, said out loud
-  paddock service <install|uninstall|status>
-                                          run it in the background from login
+  npx @edspencer/paddock [options]        run the server (the default)
+  paddock serve [options]                 the same thing, said out loud
+                                          (\`paddock start\` is a permanent alias)
+  paddock service install [options]       run it in the background from login
+  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 logs [-f] [-n <lines>]  the service's log
                                           (\`paddock service --help\`)
   paddock config show [--resolved]        what this instance's config resolved
                                           to, and where each value came from
@@ -255,6 +325,13 @@ Options
   -v, --version           Print the Paddock version and exit
   -h, --help              Show this help
 
+Exit codes
+  0   done; running and answering
+  1   failed
+  2   usage: an unknown command or flag, or a bad value
+  3   not running: installed, but not running or not answering
+  4   not installed: there is no service unit
+
 Opening your own directories
   Where you run this from does not matter — the instance is decided by its data
   dir alone. Directories are added inside the app, on the Discover screen: it
@@ -358,10 +435,16 @@ 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 uninstall           stop it and deregister it
-  paddock service status              is it registered, is it running, where are the logs
+  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 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 (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
@@ -393,9 +476,20 @@ At login, not at boot
 
 Where it lives
   macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist
-          logs in <data-dir>/service/
   Linux   ~/.config/systemd/user/paddock.service
-          logs via  journalctl --user -u paddock.service -f
+
+  Both write stdout and stderr to ONE file, <data-dir>/logs/service.log, which
+  is what \`paddock service logs\` reads. Not the journal on Linux: a volatile
+  journal has nothing in it after the reboot you are asking about, and one file
+  means one answer to "where are the logs" on every OS. Paddock rotates it
+  itself at 8 MB, keeping three older generations beside it.
+
+Exit codes
+  0   it is installed, running and answering
+  3   installed, but not running or not answering
+  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
 
 Installed from npx?
   \`service install\` refuses. An npx cache path is hash-keyed and npm may prune

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

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

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

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