@edspencer/paddock 0.71.1 → 0.72.0

package/package.json

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

package/packages/server/dist/app.js

@@ -238,6 +238,33 @@ export async function buildApp(opts = {}) {
     catch (err) {
         app.log.error({ err }, "FleetManager init/start failed — chat will be unavailable");
     }
+    // #708: this instance ran `claude.transcripts: host` and now runs `own`, so
+    // `init` just removed the `.chats` symlinks that period left behind. Until it
+    // did, `own` was not isolating (new chats were landing in the user's real
+    // Claude home) and a chat delete unlinked the user's own history.
+    //
+    // Warned rather than silent, because there IS a visible consequence: the chats
+    // written while `host` was on are still on disk but no longer in paddock's
+    // list. The recovery is deliberately split, and stated that way because it was
+    // MEASURED on a real flipped instance rather than assumed — `Import chats`
+    // offers a terminal session, but `listAdoptableSessions` excludes anything a
+    // run record is attributed to, which is every chat paddock itself drove during
+    // the `host` period. Promising a one-click recovery for those would be a lie;
+    // moving them is the migration #882 is designing.
+    if (herdctl.unplantedChatsLinks.length > 0) {
+        app.log.warn(`${herdctl.unplantedChatsLinks.length} project store(s) still pointed at another ` +
+            `transcript folder from a previous \`claude.transcripts: host\` setting (#708). ` +
+            `While that link existed, \`own\` was not isolating and deleting a chat removed the ` +
+            `file it pointed at. Paddock has replaced each link with a real directory and has ` +
+            `neither read nor moved anything at the other end. The chats written during that ` +
+            `period are still in the folder on the right, and are no longer in paddock's list: ` +
+            `ones you started in a terminal can be brought back with "Import chats"; ones ` +
+            `paddock itself ran are attributed to this instance and are not offered for import ` +
+            `(moving those is #882).\n` +
+            herdctl.unplantedChatsLinks
+                .map((l) => `  ${l.chatsDir} -> ${l.target}`)
+                .join("\n"));
+    }
     // --- post-turn curation sweep (overview + changelog) -------------------
     const sweep = new SweepService({
         herdctl,

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

@@ -31,22 +31,76 @@ export interface CliOptions {
     verbose: boolean;
     help: boolean;
     version: boolean;
+    /**
+     * `config show`: print every effective value with its provenance, rather than
+     * just the decisions someone actually made.
+     *
+     * The three `config` flags below are OPTIONAL rather than defaulted booleans,
+     * unlike the four above. That is not tidiness — `parseArgs([])` is compared
+     * structurally in several tests and is the documented shape of "no flags", so
+     * adding always-present keys to it would change the meaning of an invocation
+     * that has nothing to do with `config`. Absent-when-unset is also what the
+     * value flags (`port`, `host`, `dataDir`) already do.
+     */
+    resolved?: boolean;
+    /** `config show`: emit the whole report as JSON instead of a table. */
+    json?: boolean;
+    /** `config show`: print the values of fields marked sensitive. */
+    showSensitive?: boolean;
+    /**
+     * `config eject`: actually write the file. Without it the command prints the
+     * plan and changes nothing.
+     *
+     * Preview-by-default is the deliberate shape, and it is not timidity about
+     * writing a file: ejecting is the one config operation that changes what the
+     * file MEANS rather than what it says. Afterwards the instance stops inheriting
+     * improved defaults, and the cost is spread across forty keys where no single
+     * one looks like a decision. `--write` is the moment the operator agrees to
+     * that, having just read the specific list.
+     *
+     * A flag rather than an interactive confirm because a prompt cannot be answered
+     * by the CI job, container build or Ansible task that is the likeliest caller.
+     */
+    write?: boolean;
+    /**
+     * `config eject`: also materialise values an environment variable currently
+     * supplies. Off by default — see the argument in config.ts.
+     */
+    includeEnv?: boolean;
 }
 /** A usage error. Thrown rather than exiting, so parsing stays testable. */
 export declare class CliError extends Error {
 }
 export declare const MIN_NODE_MAJOR = 22;
-/** What `paddock service` can be asked to do. */
-export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status"];
+/**
+ * What `paddock service` can be asked to do.
+ *
+ * `start`/`stop`/`restart` join the original three in #873. Note that `start`
+ * is also a top-level VERB — `paddock start` runs a server in this terminal,
+ * `paddock service start` asks the supervisor to run one. The overlap is safe
+ * 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 type ServiceAction = (typeof SERVICE_ACTIONS)[number];
+/**
+ * What `paddock config` can be asked to do (#878).
+ *
+ * `show` reads the resolution; `eject` freezes it into the config file. The two
+ * are the halves of #878's "thin by default, explicit on demand" — and they are
+ * one verb rather than two because the honest way to present `eject` is next to
+ * the command that makes it unnecessary.
+ */
+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"];
+export declare const VERBS: readonly ["start", "service", "config"];
 /**
  * A parsed invocation: which verb, plus the flags that followed it.
  *
- * `action` is optional on `service` for exactly one reason — `paddock service
- * --help`, where there is no action to name and printing usage is the whole
- * request. It is `undefined` only when `opts.help` is true.
+ * `action` is optional on `service` and `config` for exactly one reason —
+ * `paddock service --help`, where there is no action to name and printing usage
+ * is the whole request. It is `undefined` only when `opts.help` is true.
  */
 export type Command = {
     verb: "start";
@@ -55,6 +109,10 @@ export type Command = {
     verb: "service";
     action: ServiceAction | undefined;
     opts: CliOptions;
+} | {
+    verb: "config";
+    action: ConfigAction | undefined;
+    opts: CliOptions;
 };
 /**
  * Split a leading verb off the argv, then parse the rest as flags.
@@ -99,5 +157,6 @@ 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\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\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:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\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/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\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\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";
+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";
+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

@@ -27,12 +27,59 @@
 export class CliError extends Error {
 }
 export const MIN_NODE_MAJOR = 22;
-/** What `paddock service` can be asked to do. */
-export const SERVICE_ACTIONS = ["install", "uninstall", "status"];
+/**
+ * What `paddock service` can be asked to do.
+ *
+ * `start`/`stop`/`restart` join the original three in #873. Note that `start`
+ * is also a top-level VERB — `paddock start` runs a server in this terminal,
+ * `paddock service start` asks the supervisor to run one. The overlap is safe
+ * because `parseCommand` dispatches on `argv[0]` alone and only then reads an
+ * action, so the two never compete for the same token.
+ */
+export const SERVICE_ACTIONS = [
+    "install",
+    "uninstall",
+    "status",
+    "start",
+    "stop",
+    "restart",
+];
+/**
+ * What `paddock config` can be asked to do (#878).
+ *
+ * `show` reads the resolution; `eject` freezes it into the config file. The two
+ * are the halves of #878's "thin by default, explicit on demand" — and they are
+ * one verb rather than two because the honest way to present `eject` is next to
+ * 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"];
-function isServiceAction(token) {
-    return SERVICE_ACTIONS.includes(token);
+export const VERBS = ["start", "service", "config"];
+/**
+ * Split an action off a verb's argv, then parse what follows as flags.
+ *
+ * Shared by `service` and `config` so the two cannot drift: a misspelled action
+ * is caught HERE rather than reaching the flag loop, which would call it an
+ * "unknown option" and send the reader looking for a flag that does not exist.
+ */
+function parseAction(verb, actions, rest) {
+    const head = rest[0];
+    let action;
+    if (head !== undefined && !head.startsWith("-")) {
+        if (!actions.includes(head)) {
+            throw new CliError(`unknown ${verb} action: ${head}\n` +
+                `Expected one of: ${actions.join(", ")}.\n` +
+                `Run \`paddock ${verb} --help\` for usage.`);
+        }
+        action = head;
+    }
+    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` +
+            `Run \`paddock ${verb} --help\` for usage.`);
+    }
+    return { action, opts };
 }
 /**
  * Split a leading verb off the argv, then parse the rest as flags.
@@ -63,25 +110,10 @@ function isServiceAction(token) {
 export function parseCommand(argv) {
     const [first, ...rest] = argv;
     if (first === "service") {
-        const head = rest[0];
-        let action;
-        if (head !== undefined && !head.startsWith("-")) {
-            // Catch a misspelled action here rather than letting the flag loop call
-            // it an "unknown option", which sends the reader looking for a flag.
-            if (!isServiceAction(head)) {
-                throw new CliError(`unknown service action: ${head}\n` +
-                    `Expected one of: ${SERVICE_ACTIONS.join(", ")}.\n` +
-                    "Run `paddock service --help` for usage.");
-            }
-            action = head;
-        }
-        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 service\` needs an action: ${SERVICE_ACTIONS.join(", ")}.\n` +
-                "Run `paddock service --help` for usage.");
-        }
-        return { verb: "service", action, opts };
+        return { verb: "service", ...parseAction("service", SERVICE_ACTIONS, rest) };
+    }
+    if (first === "config") {
+        return { verb: "config", ...parseAction("config", CONFIG_ACTIONS, rest) };
     }
     if (first === "start")
         return { verb: "start", opts: parseArgs(rest) };
@@ -135,6 +167,24 @@ export function parseArgs(argv) {
             case "--verbose":
                 opts.verbose = true;
                 break;
+            // `config` flags. Accepted in every position for the reason
+            // `parseCommand` documents — one flag grammar everywhere — which is also
+            // why `service install --open` has always been silently harmless.
+            case "--resolved":
+                opts.resolved = true;
+                break;
+            case "--json":
+                opts.json = true;
+                break;
+            case "--show-sensitive":
+                opts.showSensitive = true;
+                break;
+            case "--write":
+                opts.write = true;
+                break;
+            case "--include-env":
+                opts.includeEnv = true;
+                break;
             case "-h":
             case "--help":
                 opts.help = true;
@@ -190,6 +240,11 @@ Usage
   paddock service <install|uninstall|status>
                                           run it in the background from login
                                           (\`paddock service --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
+                                          paddock.config.yaml
+                                          (\`paddock config --help\`)
 
 Options
   -p, --port <port>       HTTP/WS port (default 7233, or $PORT)
@@ -223,18 +278,44 @@ Credentials
   login at all anywhere, run \`claude setup-token\`. Paddock says at startup when
   it can find none.
 
+Posture profiles
+  One key picks how much Paddock shares and how much its agents may do:
+
+    profile: balanced     # paranoid | balanced | yolo   (PADDOCK_PROFILE)
+
+  paranoid shares nothing but the login and turns every capability off — the
+  behaviour Paddock had before profiles existed. balanced (the default)
+  inherits the CAPABILITIES your CLI already has — instructions, MCP servers,
+  plugins — and adds the read-only self-management tools, while keeping your
+  chat history Paddock's own. yolo turns the rest on: your transcripts, host
+  hooks, the write and project tools, schedule mutation, deeper spawning, the
+  browser.
+
+  A profile only sets defaults — any single key still overrides it, and an
+  individual key in the config file beats PADDOCK_PROFILE in the environment.
+  Profiles never touch your port, bind address, auth or model list: yolo does
+  NOT open the bind or relax auth, which stay a separate, explicit decision.
+
+  What host actually reaches depends on the machine — a workstation has a real
+  ~/.claude, a container usually has none. The profile sets the levers, the
+  environment sets the blast radius.
+
+  To see what your profile actually expanded to on THIS machine, with the layer
+  each value came from:  paddock config show --resolved
+
 Sharing your Claude Code state
   Apart from that login, Paddock writes nothing outside its data dir by
   default: transcripts go to each project's .chats/, and your ~/.claude is read
   for config only. Each thing it can share is one key in
-  <data-dir>/paddock.config.yaml:
+  <data-dir>/paddock.config.yaml, and each defaults to whatever your profile
+  says (see Posture profiles below):
 
     claude:
-      transcripts: host   # own | host, default own
-      credentials: host   # own | host, default host
-      instructions: host  # own | host, default own
-      hooks: host         # own | host, default own
-      mcpServers: host    # own | host, default own
+      transcripts: host   # own | host   host on yolo only
+      credentials: host   # own | host   host on every profile
+      instructions: host  # own | host   own on paranoid, else host
+      hooks: host         # own | host   host on yolo only
+      mcpServers: host    # own | host   own on paranoid, else host
 
   transcripts: host makes a chat and a \`claude --resume\` in the same directory
   the same file, live in both directions; deleting such a chat in Paddock
@@ -242,9 +323,9 @@ Sharing your Claude Code state
   Paddock's copy. credentials: own is the opt-out from sharing the login above.
 
   instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and
-  plugins/. Off by default, which is a change: your curated CLAUDE.md does not
-  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always
-  does.
+  plugins/. On from balanced up, so your curated CLAUDE.md does reach Paddock's
+  agents; profile: paranoid or instructions: own keeps it out. Each project's
+  own CLAUDE.md applies either way.
 
   hooks: host runs the shell commands your ~/.claude/settings.json binds to
   tool use. Off by default — inheriting someone's hooks is not something to
@@ -278,6 +359,9 @@ 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 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
 
 Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
@@ -328,3 +412,99 @@ A note on access
   you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.
 
 Docs: https://github.com/edspencer/paddock`;
+export const CONFIG_USAGE = `paddock config — what this instance's configuration actually resolved to
+
+Usage
+  paddock config show                 the decisions: your profile, the keys your
+                                      config file sets, the variables your
+                                      environment sets
+  paddock config show --resolved      EVERY effective value, and which layer it
+                                      came from
+  paddock config show --json          the same report as JSON, long values in
+                                      full (sensitive ones still hidden)
+  paddock config eject                what freezing that resolution into
+                                      paddock.config.yaml would write — a
+                                      preview; writes nothing
+  paddock config eject --write        actually write it
+
+Options
+  -d, --data-dir <path>   Which instance to inspect (default ~/.paddock, or
+                          $PADDOCK_DATA_DIR) — the same rule \`paddock start\`
+                          uses, so the two always read the same instance
+      --resolved          show: every field, not just the ones someone set
+      --json              show: the whole report as JSON (implies --resolved's
+                          scope)
+      --show-sensitive    show: print the values of fields marked sensitive
+      --write             eject: apply the plan. Without it, eject only prints
+      --include-env       eject: also freeze values an environment variable
+                          currently supplies (see below — off by default)
+  -h, --help              Show this help
+
+Where a value can come from
+  Config resolves in four layers, and each row of --resolved names the one that
+  won:
+
+    default            Paddock's built-in default.
+    profile (<name>)   Your posture profile. The twelve levers a profile governs
+                       have no code default of their own any more — the profile
+                       IS their default — so this is a distinct answer from
+                       "default", and switching profile would change it.
+    file               A key in paddock.config.yaml.
+    env <NAME>         An environment variable, which beats the file for the
+                       same key.
+
+  One wrinkle worth knowing, and the command shows it plainly: an individual key
+  in the FILE beats PADDOCK_PROFILE in the environment. Specific beats general —
+  PADDOCK_PROFILE speaks for the levers you did not mention.
+
+Why show, and not just write it all into the file
+  \`show\` is computed by the loader the server boots with, so it cannot drift
+  from what the process would actually do. A materialized file can: it stops
+  inheriting improved defaults, says nothing about the variables your container
+  sets on top, and no longer describes the whole surface the day a lever is
+  added. That is why the thin file is the default and \`show\` is the answer to
+  "what am I actually running?".
+
+  \`eject\` is there for when you want it written down anyway — frozen, in the
+  file, reviewable in git. It is a real tradeoff rather than a better \`show\`,
+  so it prints what it would cost you and writes nothing until you pass --write.
+
+What eject writes, and what it leaves alone
+  It writes the posture levers your profile expanded to, plus the behavioural
+  settings the Config screen already round-trips through this file. It does NOT
+  write:
+
+    the bindings     port, host, data dir, projects root, state dir, web dist.
+                     These resolve to absolute paths on THIS machine, and the
+                     data dir resolves to the directory holding the file — so
+                     ejecting them makes the file unportable and unmountable.
+    sensitive keys   transcription.endpoint can carry credentials in its URL.
+                     Bulk-writing a secret-shaped value to disk should not be
+                     one keystroke away; write that key by hand.
+    env-owned keys   by default. An environment variable BEATS the file, so
+                     writing its value in changes nothing today and everything
+                     the day the variable goes away — a deferred, silent change
+                     of provenance. eject names each one it skipped instead.
+                     --include-env writes them, which is the right flag if you
+                     are deliberately migrating from env vars to a file.
+
+  It always writes \`profile:\` as well, even though every key that profile
+  governs is now explicit. That line is what a lever added in a FUTURE release
+  falls back to: without it, a new capability toggle would resolve against the
+  built-in default profile rather than the posture you actually ejected from.
+
+  Your comments and any keys Paddock does not manage survive — the file is
+  round-tripped, not regenerated — and the write is atomic.
+
+Reading nothing, writing nothing
+  \`show\` resolves config and prints it. It starts no server, contacts nothing,
+  and writes no file — including the data dir itself, which it will report as
+  missing rather than create. \`eject\` writes exactly one file, and only with
+  --write.
+
+  Values are printed to a terminal that often ends up pasted into an issue, so
+  fields marked sensitive are shown as (hidden). None of them is a secret —
+  Paddock keeps secrets out of this surface entirely, so there is no API key or
+  JWT signing material here to hide or reveal.
+
+Docs: https://github.com/edspencer/paddock`;

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

@@ -0,0 +1,157 @@
+import type { CliOptions, ConfigAction } from "./args.js";
+import type { ConfigSource, ResolvedConfigReport } from "../instance-config.js";
+/**
+ * The default view: the decisions, not the resolution. Everything named here is
+ * something a human typed somewhere.
+ */
+export declare function formatSummary(report: ResolvedConfigReport): string;
+/** `--resolved`: every field in the settings surface, grouped, with its layer. */
+export declare function formatResolved(report: ResolvedConfigReport, groups: {
+    id: string;
+    label: string;
+}[], showSensitive: boolean): string;
+/** The report as JSON, with `sensitive` values replaced unless asked for. */
+export declare function toJson(report: ResolvedConfigReport, showSensitive: boolean): string;
+/**
+ * `paddock config eject` — freeze the resolution into `paddock.config.yaml`.
+ *
+ * ## Why this exists next to a command that argues against it
+ *
+ * `config show` is the answer to "what am I actually running?", and its whole
+ * case is that a printed resolution cannot drift the way a materialised file
+ * can. `eject` is for the person that argument does not satisfy: someone who
+ * wants the posture pinned in git, reviewable in a diff, identical across a
+ * fleet, and unaffected by what a later release decides a good default is.
+ *
+ * That is a legitimate want and a real tradeoff, so the command's job is not
+ * just to write the file — it is to make the tradeoff visible **at the moment
+ * of use**, where an operator is actually deciding, rather than only in docs
+ * they read once. Hence {@link formatEjectPlan}'s closing section, and hence
+ * preview-by-default.
+ *
+ * ## Preview by default, `--write` to apply
+ *
+ * Ejecting is the one config operation that changes what the file MEANS rather
+ * than what it says, and it spreads that change over ~forty keys, no one of
+ * which looks like a decision. So the default run prints the plan — every key,
+ * its value, the layer it is being frozen out of, and what is deliberately being
+ * left out — and writes nothing. A flag rather than an interactive prompt
+ * because the likeliest caller is a container build or a config-management task
+ * that cannot answer one.
+ *
+ * ## What it refuses to write, and why each refusal is safe
+ *
+ * The key set comes from `ejectable` on the field itself (see
+ * instance-config.ts): posture and editable keys in, machine-specific bindings
+ * and `sensitive` fields out. Two more exclusions are decided here, from
+ * provenance rather than from the field:
+ *
+ * - **A value an environment variable currently supplies is skipped.** This is
+ *   the subtle one. Env beats file, so writing an env-sourced value into the
+ *   file changes *nothing observable today* and changes the instance's behaviour
+ *   on the day that variable stops being set — a deferred, silent transfer of a
+ *   decision from the environment into a file, with no record that it ever was
+ *   an environment decision. It is also how a stray `PADDOCK_*` left over on a
+ *   build box gets baked into a committed config permanently. There is a
+ *   precedent for treating this as an error rather than a courtesy: the Settings
+ *   PUT path (`validatePatch`) already refuses to write a key an env var
+ *   shadows, for the same reason. So eject names each one it skipped and which
+ *   variable owns it; `--include-env` writes them anyway, which is the correct
+ *   behaviour for the one case that genuinely wants it — deliberately migrating
+ *   an instance off a wall of `PADDOCK_*` vars and into a file.
+ *
+ * - **A key whose effective value is `null` is skipped** — an optional nothing
+ *   set, like `sweepMinIntervalMs`. `writeInstanceConfig` reads `null` as
+ *   "delete this key", so there is no value to write; and emitting `key: null`
+ *   would render as a decision in a file whose entire purpose is to record
+ *   decisions.
+ *
+ * Neither exclusion can change what the instance resolves — which is the
+ * property the round-trip test pins, and the one that makes the refusals safe
+ * rather than merely defensible.
+ *
+ * ## `profile:` is written even when the environment set it
+ *
+ * A deliberate exception to the env rule above, and worth the paragraph because
+ * it looks like an inconsistency.
+ *
+ * The env rule exists because writing an env value moves a decision about an
+ * *existing lever* into the file invisibly. After a full eject, `profile:`
+ * governs no existing lever — every key it would have supplied a default for is
+ * now written out explicitly, so the line cannot change any current value. Its
+ * only remaining effect is on levers that do not exist yet: a capability toggle
+ * added in a later release resolves against the profile, and without this line
+ * it would resolve against the built-in default profile rather than the posture
+ * the operator actually froze. Ejecting from `paranoid` and silently acquiring
+ * `balanced`'s answer to a future lever is the exact drift this command is
+ * supposed to protect against.
+ *
+ * So the line goes in, and the plan says out loud that it did.
+ */
+/** One key the plan would write. */
+export interface EjectEntry {
+    key: string;
+    group: string;
+    value: unknown;
+    /** The layer the value is being frozen OUT of. */
+    source: ConfigSource;
+    origin?: string;
+    /** `add` — the file does not name this key. `change` — it does, inertly. */
+    action: "add" | "change";
+    /** What the file says today; only on `change`. */
+    fileValue?: unknown;
+}
+/** Why a field is not in the plan. */
+export type EjectSkipReason = "sensitive" | "binding" | "env" | "unset";
+export interface EjectSkip {
+    key: string;
+    reason: EjectSkipReason;
+    /** The variable name, for `env`. */
+    origin?: string;
+}
+export interface EjectPlan {
+    report: ResolvedConfigReport;
+    entries: EjectEntry[];
+    skipped: EjectSkip[];
+    /** Keys already set in the file AND already in effect — left untouched. */
+    keptFromFile: string[];
+    /** The `profile:` line, and whether the file already names it. */
+    profile: {
+        name: string;
+        write: boolean;
+    };
+    /** Exactly what {@link import("../instance-config.js").writeInstanceConfig} is handed. */
+    pairs: {
+        key: string;
+        value: unknown;
+    }[];
+}
+/**
+ * Decide what ejecting would write. Pure — the caller does the IO — so every
+ * policy decision above is unit-testable against a hand-built report.
+ */
+export declare function buildEjectPlan(report: ResolvedConfigReport, includeEnv?: boolean): EjectPlan;
+/**
+ * Render a plan. `written` switches the tense — the two views are one function
+ * so a preview cannot promise something the write does not do.
+ */
+export declare function formatEjectPlan(plan: EjectPlan, groups: {
+    id: string;
+    label: string;
+}[], written: boolean): string;
+/**
+ * Run a `config` action against the data dir the caller has already resolved
+ * into `PADDOCK_DATA_DIR`.
+ *
+ * The two imports are dynamic for the same reason `paddock.ts` defers
+ * `start.js`: config resolution reads the environment, so nothing that resolves
+ * it may be pulled in before the caller has finished setting it.
+ *
+ * `createDataDir: false` is the one behavioural request this command makes of
+ * the loader, and it holds for `eject` too. Inspecting an instance must not
+ * CREATE one — otherwise `paddock config show` on a machine that has never run
+ * Paddock leaves an empty `~/.paddock` behind, and the first-run welcome that
+ * keys on its absence never prints. `eject --write` does create the directory,
+ * because it has to put a file in it, but only on the path that writes.
+ */
+export declare function runConfig(action: ConfigAction, opts: CliOptions): Promise<void>;