@edspencer/paddock 0.71.1 → 0.72.0

package/packages/server/dist/cli/service/index.js

@@ -1,5 +1,6 @@
 /**
- * `paddock service install | uninstall | status` (#796).
+ * `paddock service install | uninstall | status | start | stop | restart`
+ * (#796; the lifecycle three added in #873).
  *
  * Registers Paddock as a **per-user** background service — a launchd
  * LaunchAgent on macOS, a `systemd --user` unit on Linux — so it is up from
@@ -26,7 +27,7 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "../args.js";
 import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, } from "./spec.js";
-import { spawnRunner } from "./backend.js";
+import { spawnRunner, } from "./backend.js";
 import { createLaunchdBackend } from "./launchd.js";
 import { createSystemdBackend } from "./systemd.js";
 import { waitForReady, READY_TIMEOUT_LABEL } from "./ready.js";
@@ -77,6 +78,25 @@ function specFor(opts, ctx) {
 const AT_LOGIN = "  Paddock starts when you LOG IN, not when the machine boots — it runs as\n" +
     "  you, so it can use the Claude login you already have. After a restart\n" +
     "  that nobody logs into, Paddock is not running.";
+/**
+ * What `status` says about a unit installed before #872.
+ *
+ * Upgrading the package leaves the unit file alone, so the people still holding
+ * the broken shape are exactly the people who will never notice — the symptom
+ * is Paddock being absent one morning, with nothing in the logs, because it was
+ * signalled rather than crashed. Naming the fix here is the only path from that
+ * symptom back to a working service.
+ */
+function staleUnitNote(backend) {
+    const key = backend.platform === "darwin"
+        ? "KeepAlive is conditional on a non-zero exit"
+        : "Restart=on-failure";
+    return (`  ⚠ This unit predates a fix (#872): ${key}, so a graceful stop —\n` +
+        "    the kind sleep, logout or a stray `kill` sends — puts Paddock down\n" +
+        "    until you start it again by hand. Re-run to update the unit:\n" +
+        "\n" +
+        "      paddock service install");
+}
 /**
  * Say what is about to happen, before the part that looks like a hang (#861).
  *
@@ -135,6 +155,7 @@ async function install(opts, ctx, backend) {
         ...(linger !== undefined ? ["", linger] : []),
         "",
         "  paddock service status      is it up, and where",
+        "  paddock service restart     bounce it after editing config",
         "  paddock service uninstall   stop it and remove the unit",
         "",
     ].join("\n"));
@@ -194,16 +215,117 @@ function status(opts, ctx, backend) {
         backend.logsHint(spec),
         "",
         AT_LOGIN,
+        ...(state.keepsAlive ? [] : ["", staleUnitNote(backend)]),
         ...(linger !== undefined && !state.running ? ["", linger] : []),
         "",
     ].join("\n"));
 }
+/**
+ * The URL an installed unit is actually serving, or undefined if none is.
+ *
+ * Read out of the unit rather than recomputed from today's flags, for the same
+ * reason `status` does it: the port in the file is the port the server is on.
+ */
+function installedUrl(state) {
+    return `http://${hostFromArgv(state.argv)}:${portFromArgv(state.argv)}`;
+}
+/** "It isn't installed" — the same answer, wherever it is asked. */
+function notInstalled(backend) {
+    return [
+        "",
+        "  Paddock is not installed as a service.",
+        `  Looked for: ${backend.unitPath}`,
+        "",
+        "  paddock service install     register it and start it now",
+        "",
+    ].join("\n");
+}
+/**
+ * `start` / `restart` (#873), which differ only in what they tolerate.
+ *
+ * `start` on something already running is reported and not acted on — asking
+ * launchd to bootstrap a loaded job is an error, and "it is already up" is the
+ * outcome the user wanted anyway. `restart` has no such case: bouncing a
+ * stopped service is a legitimate way to start it, and the sequence each
+ * backend uses handles both states.
+ *
+ * Both then WAIT. Neither supervisor's "started" means the port answers — it
+ * means the fork succeeded — so printing a URL on the strength of it produces a
+ * success message that can sit over a crash-loop (a port clash restarts every
+ * `ThrottleInterval`, and `launchctl print` says `running` for most of that
+ * window). The wait is what makes the last line true.
+ */
+async function startOrRestart(action, ctx, backend) {
+    const before = backend.status();
+    if (!before.registered) {
+        console.log(notInstalled(backend));
+        return;
+    }
+    const url = installedUrl(before);
+    if (action === "start" && before.running) {
+        console.log(`\n  Paddock is already running${pid(before)}.\n\n  URL:  ${url}\n`);
+        return;
+    }
+    console.log(`\n  ${action === "start" ? "Starting" : "Restarting"} Paddock…`);
+    if (action === "start")
+        backend.start();
+    else
+        backend.restart();
+    const readiness = await (ctx.checkReady ?? ((u) => waitForReady({ url: u })))(url);
+    const after = backend.status();
+    console.log([
+        "",
+        readiness === "ready"
+            ? `  ✓ Paddock is running${pid(after)} at ${url}`
+            : `  Paddock was ${action === "start" ? "started" : "restarted"}, but ${url} did not\n` +
+                `  answer within ${READY_TIMEOUT_LABEL}. It may still be coming up — check:`,
+        ...(readiness === "ready" ? [] : ["", "  paddock service status", backend.logsHint(specForLogs(ctx, after))]),
+        "",
+    ].join("\n"));
+}
+/** `stop` (#873): put it down, leave it installed. */
+function stop(backend) {
+    const state = backend.status();
+    if (!state.registered) {
+        console.log(notInstalled(backend));
+        return;
+    }
+    if (!state.running) {
+        console.log(`\n  Paddock is already stopped.\n  Unit: ${backend.unitPath}\n`);
+        return;
+    }
+    backend.stop();
+    console.log([
+        "",
+        "  Paddock is stopped. The unit is still installed.",
+        `  Unit: ${backend.unitPath}`,
+        "",
+        "  It comes back when you log in again, or now with:",
+        "",
+        "    paddock service start",
+        "",
+    ].join("\n"));
+}
+function pid(state) {
+    return state.pid !== undefined ? ` (pid ${state.pid})` : "";
+}
+/** The spec `logsHint` needs, built from the INSTALLED unit's data dir. */
+function specForLogs(ctx, state) {
+    const i = state.argv.indexOf("--data-dir");
+    const dataDir = i >= 0 && state.argv[i + 1] !== undefined ? state.argv[i + 1] : undefined;
+    const { spec } = specFor({ open: false, verbose: false, help: false, version: false }, { ...ctx, ...(dataDir !== undefined ? { envDataDir: dataDir } : {}) });
+    return spec;
+}
 export async function runService(action, opts, ctx) {
     const backend = backendFor(ctx);
     if (action === "install")
         return install(opts, ctx, backend);
     if (action === "uninstall")
         return uninstall(ctx, backend);
+    if (action === "start" || action === "restart")
+        return startOrRestart(action, ctx, backend);
+    if (action === "stop")
+        return stop(backend);
     return status(opts, ctx, backend);
 }
 /** Exported for the entrypoint's context assembly, and for tests. */

package/packages/server/dist/cli/service/launchd.d.ts

@@ -5,10 +5,22 @@ export declare function plistPath(homeDir?: string): string;
 /**
  * Render the plist.
  *
- * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
- * false` means "restart it if it exits nonzero, leave it alone if it exits
- * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
- * make stopping Paddock a wrestling match.
+ * `KeepAlive` is unconditional `<true/>`, and that is a deliberate reversal
+ * (#872). It used to be `{ SuccessfulExit: false }` — "restart it if it exits
+ * nonzero, leave it alone if it exits cleanly" — which reads like the polite
+ * choice and is, for a service, a trap. `start.ts` handles SIGTERM by shutting
+ * down cleanly and exiting `0`, so **every** SIGTERM the OS routinely sends a
+ * LaunchAgent (sleep, logout, a stray `kill`) looked to launchd like "it meant
+ * to stop", and Paddock stayed down until the next login. A hard crash was the
+ * survivable case; the graceful stop was the terminal one.
+ *
+ * The worry that motivated the dict — that `<true/>` fights a deliberate stop —
+ * does not hold for the stop this CLI actually performs. `launchctl bootout`
+ * unloads the job from the domain, and KeepAlive only applies to a job that is
+ * still loaded, so `uninstall` still stops Paddock in one call. What `<true/>`
+ * does fight is `launchctl stop`, which is why nothing here uses it.
+ *
+ * Intent belongs in an explicit command, not in an exit code.
  *
  * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
  * launchd hands a process a stub PATH that a version manager's `node`, and the
@@ -32,6 +44,17 @@ export declare function renderPlist(spec: ServiceSpec): string;
  * would be the larger risk.
  */
 export declare function parsePlistArgv(xml: string): string[];
+/**
+ * Does an installed plist carry the unconditional `KeepAlive` from #872?
+ *
+ * Deliberately narrow: it matches `<key>KeepAlive</key>` followed by `<true/>`
+ * and nothing else. The shape it must NOT accept is the old
+ * `<dict><key>SuccessfulExit</key><false/></dict>`, which is the one that
+ * leaves a service dead after a graceful stop — so a `false` here is the signal
+ * `status` turns into "re-run install", and defaulting to `true` on anything
+ * unrecognised would silence exactly the case this exists to catch.
+ */
+export declare function plistKeepsAlive(xml: string): boolean;
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *

package/packages/server/dist/cli/service/launchd.js

@@ -51,10 +51,22 @@ function xmlEscape(s) {
 /**
  * Render the plist.
  *
- * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
- * false` means "restart it if it exits nonzero, leave it alone if it exits
- * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
- * make stopping Paddock a wrestling match.
+ * `KeepAlive` is unconditional `<true/>`, and that is a deliberate reversal
+ * (#872). It used to be `{ SuccessfulExit: false }` — "restart it if it exits
+ * nonzero, leave it alone if it exits cleanly" — which reads like the polite
+ * choice and is, for a service, a trap. `start.ts` handles SIGTERM by shutting
+ * down cleanly and exiting `0`, so **every** SIGTERM the OS routinely sends a
+ * LaunchAgent (sleep, logout, a stray `kill`) looked to launchd like "it meant
+ * to stop", and Paddock stayed down until the next login. A hard crash was the
+ * survivable case; the graceful stop was the terminal one.
+ *
+ * The worry that motivated the dict — that `<true/>` fights a deliberate stop —
+ * does not hold for the stop this CLI actually performs. `launchctl bootout`
+ * unloads the job from the domain, and KeepAlive only applies to a job that is
+ * still loaded, so `uninstall` still stops Paddock in one call. What `<true/>`
+ * does fight is `launchctl stop`, which is why nothing here uses it.
+ *
+ * Intent belongs in an explicit command, not in an exit code.
  *
  * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
  * launchd hands a process a stub PATH that a version manager's `node`, and the
@@ -82,10 +94,7 @@ ${strings}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-      <key>SuccessfulExit</key>
-      <false/>
-    </dict>
+    <true/>
     <key>ThrottleInterval</key>
     <integer>10</integer>
     <key>WorkingDirectory</key>
@@ -123,6 +132,19 @@ export function parsePlistArgv(xml) {
         .replace(/&lt;/g, "<")
         .replace(/&amp;/g, "&"));
 }
+/**
+ * Does an installed plist carry the unconditional `KeepAlive` from #872?
+ *
+ * Deliberately narrow: it matches `<key>KeepAlive</key>` followed by `<true/>`
+ * and nothing else. The shape it must NOT accept is the old
+ * `<dict><key>SuccessfulExit</key><false/></dict>`, which is the one that
+ * leaves a service dead after a graceful stop — so a `false` here is the signal
+ * `status` turns into "re-run install", and defaulting to `true` on anything
+ * unrecognised would silence exactly the case this exists to catch.
+ */
+export function plistKeepsAlive(xml) {
+    return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(xml);
+}
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *
@@ -139,6 +161,10 @@ export function parseLaunchctlPrint(out) {
         ...(pid !== null ? { pid: pid[1] } : {}),
     };
 }
+/** One phrasing for "launchctl said no", so every caller reports it the same way. */
+function launchctlFailure(verb, r) {
+    return (`launchctl ${verb} failed (exit ${String(r.status)}).\n` + `${r.stderr || r.stdout}`.trim());
+}
 function target() {
     return `gui/${process.getuid?.() ?? 0}/${LAUNCHD_LABEL}`;
 }
@@ -164,10 +190,8 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
             // they are shims over this one that report success in cases where it
             // reports the actual error.
             const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0) {
-                throw new Error(`launchctl bootstrap failed (exit ${String(boot.status)}).\n` +
-                    `${boot.stderr || boot.stdout}`.trim());
-            }
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
             // `RunAtLoad` should already have started it; `kickstart -k` makes that
             // true rather than probable, and is the same command a later restart uses.
             run("launchctl", ["kickstart", "-k", target()]);
@@ -179,10 +203,59 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 fs.rmSync(file, { force: true });
             return existed;
         },
+        /**
+         * Load the job back into the GUI domain and make sure it is running (#873).
+         *
+         * `bootstrap`, not `launchctl start`: `stop` below BOOTS OUT, so a stopped
+         * Paddock is not merely idle, it is absent from the domain — and `start` on
+         * a label launchd has never heard of fails. Bootstrapping is also what a
+         * login does, so `service start` and the next login take the same path.
+         */
+        start() {
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", target()]);
+        },
+        /**
+         * `bootout`, not `launchctl stop`.
+         *
+         * With #872's unconditional `KeepAlive`, `stop` is a request launchd
+         * immediately overrules — it stops the process and then relaunches it,
+         * which is exactly the wrestling match the old conditional KeepAlive was
+         * meant to avoid. `bootout` unloads the job, so KeepAlive no longer applies
+         * and it stays down. The plist is untouched, so `status` still reports it
+         * registered, `start` puts it back, and the next LOGIN starts it again via
+         * `RunAtLoad` — a stop is for this session, not forever. Uninstall is the
+         * one that is forever.
+         */
+        stop() {
+            const out = run("launchctl", ["bootout", target()]);
+            // Exit 3 / "No such process" is launchd for "it was not loaded", which is
+            // the state the caller asked for. Anything else is worth surfacing.
+            if (out.status !== 0 && !/no such process/i.test(`${out.stderr}${out.stdout}`)) {
+                throw new Error(launchctlFailure("bootout", out));
+            }
+        },
+        /**
+         * Boot out, bootstrap, kick. Not `kickstart -k` alone, which needs the job
+         * to be loaded and so fails on the case `restart` most needs to handle: a
+         * service that is stopped. This sequence is identical to `install`'s minus
+         * writing the plist, which also gives `restart` the property the issue asks
+         * for — the unit is re-read on the way up, so an edited plist takes effect.
+         */
+        restart() {
+            run("launchctl", ["bootout", target()]);
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", "-k", target()]);
+        },
         status() {
             if (!fs.existsSync(file))
-                return { registered: false, running: false, argv: [] };
-            const argv = parsePlistArgv(fs.readFileSync(file, "utf8"));
+                return { registered: false, running: false, argv: [], keepsAlive: true };
+            const xml = fs.readFileSync(file, "utf8");
+            const argv = parsePlistArgv(xml);
             const printed = run("launchctl", ["print", target()]);
             const parsed = printed.status === 0
                 ? parseLaunchctlPrint(printed.stdout)
@@ -194,6 +267,7 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 // Strip the interpreter and script: what a reader wants from `status`
                 // is the Paddock invocation, not the absolute path to node twice.
                 argv: argv.slice(2),
+                keepsAlive: plistKeepsAlive(xml),
             };
         },
         logsHint(spec) {

package/packages/server/dist/cli/service/systemd.d.ts

@@ -31,8 +31,17 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
 /**
  * Render the unit.
  *
- * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
- * false` — a clean shutdown should stay shut down.
+ * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
+ * `on-failure`, which for a service is the wrong default for the same reason it
+ * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
+ * else that signals the user manager — was read as an intended stop and Paddock
+ * stayed down.
+ *
+ * `always` does not make the unit unstoppable. systemd never restarts a unit it
+ * was itself asked to stop, so `systemctl --user stop` (and therefore
+ * `uninstall`) remains the clean, explicit way to put it down. That is the
+ * difference between an exit code, which has to guess at intent, and a command,
+ * which carries it.
  *
  * `WantedBy=default.target` is what makes `systemctl --user enable` mean
  * "start at login" for a user unit; `multi-user.target` is the system-unit
@@ -43,6 +52,16 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
  * answers to "where are the logs".
  */
 export declare function renderUnit(spec: ServiceSpec): string;
+/**
+ * Does an installed unit carry `Restart=always` (#872)?
+ *
+ * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
+ * value it has to reject is the `on-failure` this file used to write, which
+ * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
+ * Anything unrecognised reads as "not the fixed shape", which at worst tells a
+ * hand-edited unit's owner to re-run install.
+ */
+export declare function unitKeepsAlive(text: string): boolean;
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export declare function parseUnitArgv(text: string): string[];
 export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;

package/packages/server/dist/cli/service/systemd.js

@@ -62,8 +62,17 @@ export function unitPath(homeDir, xdgConfigHome) {
 /**
  * Render the unit.
  *
- * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
- * false` — a clean shutdown should stay shut down.
+ * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
+ * `on-failure`, which for a service is the wrong default for the same reason it
+ * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
+ * else that signals the user manager — was read as an intended stop and Paddock
+ * stayed down.
+ *
+ * `always` does not make the unit unstoppable. systemd never restarts a unit it
+ * was itself asked to stop, so `systemctl --user stop` (and therefore
+ * `uninstall`) remains the clean, explicit way to put it down. That is the
+ * difference between an exit code, which has to guess at intent, and a command,
+ * which carries it.
  *
  * `WantedBy=default.target` is what makes `systemctl --user enable` mean
  * "start at login" for a user unit; `multi-user.target` is the system-unit
@@ -84,13 +93,25 @@ Type=simple
 ExecStart=${exec}
 WorkingDirectory=${spec.workingDirectory}
 Environment=PATH=${spec.pathEnv}
-Restart=on-failure
+Restart=always
 RestartSec=10
 
 [Install]
 WantedBy=default.target
 `;
 }
+/**
+ * Does an installed unit carry `Restart=always` (#872)?
+ *
+ * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
+ * value it has to reject is the `on-failure` this file used to write, which
+ * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
+ * Anything unrecognised reads as "not the fixed shape", which at worst tells a
+ * hand-edited unit's owner to re-run install.
+ */
+export function unitKeepsAlive(text) {
+    return /^Restart=always\s*$/m.test(text);
+}
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export function parseUnitArgv(text) {
     const m = /^ExecStart=(.*)$/m.exec(text);
@@ -98,6 +119,14 @@ export function parseUnitArgv(text) {
         return [];
     return m[1].trim().split(/\s+/).filter(Boolean);
 }
+/** Run a `systemctl` and turn a non-zero exit into the manager's own words. */
+function systemctlOrThrow(run, args) {
+    const r = run("systemctl", args);
+    if (r.status === 0)
+        return;
+    throw new Error(`systemctl ${args.join(" ")} failed (exit ${String(r.status)}).\n` +
+        `${r.stderr || r.stdout}`.trim());
+}
 export function createSystemdBackend(run, homeDir, xdgConfigHome) {
     // Both forwarded, neither defaulted here: `unitPath` owns the precedence, and
     // defaulting `homeDir` to `os.homedir()` at this layer would collapse "the
@@ -129,10 +158,33 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             run("systemctl", ["--user", "daemon-reload"]);
             return existed;
         },
+        /**
+         * The lifecycle three (#873), which on systemd are just the verbs.
+         *
+         * None of them touches `enable`/`disable`: those decide whether Paddock
+         * comes back at your NEXT login, which is a different question from whether
+         * it is running now, and quietly answering both would make `stop` a
+         * surprise the following morning. `uninstall` is where that link is cut.
+         *
+         * `restart` re-reads the unit itself, but a `daemon-reload` first is what
+         * makes an EDITED unit take effect rather than the manager's cached copy —
+         * the same reason `install` reloads before enabling.
+         */
+        start() {
+            systemctlOrThrow(run, ["--user", "start", SYSTEMD_UNIT]);
+        },
+        stop() {
+            systemctlOrThrow(run, ["--user", "stop", SYSTEMD_UNIT]);
+        },
+        restart() {
+            run("systemctl", ["--user", "daemon-reload"]);
+            systemctlOrThrow(run, ["--user", "restart", SYSTEMD_UNIT]);
+        },
         status() {
             if (!fs.existsSync(file))
-                return { registered: false, running: false, argv: [] };
-            const argv = parseUnitArgv(fs.readFileSync(file, "utf8"));
+                return { registered: false, running: false, argv: [], keepsAlive: true };
+            const text = fs.readFileSync(file, "utf8");
+            const argv = parseUnitArgv(text);
             const active = run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
             const pid = run("systemctl", ["--user", "show", "-p", "MainPID", "--value", SYSTEMD_UNIT]);
             const mainPid = pid.stdout.trim();
@@ -141,6 +193,7 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
                 running: active.stdout.trim() === "active",
                 ...(mainPid !== "" && mainPid !== "0" ? { pid: mainPid } : {}),
                 argv: argv.slice(2),
+                keepsAlive: unitKeepsAlive(text),
             };
         },
         logsHint() {

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

@@ -1,4 +1,5 @@
 import { type DriveMode } from "./models.js";
+import { type ProfileName } from "./profiles.js";
 import { type TranscriptsMode } from "./transcripts.js";
 import { type CredentialsMode } from "./claude-credentials.js";
 import { type InstructionsMode } from "./claude-instructions.js";
@@ -145,6 +146,17 @@ export interface OpenApiConfig {
     path: string;
 }
 export interface PaddockConfig {
+    /**
+     * The resolved posture profile (#878) — `paranoid` | `balanced` | `yolo`.
+     *
+     * Reported for display and provenance only; nothing reads it to make a
+     * decision. It has already been expanded into the individual posture fields
+     * below by the time this object exists, and any of those the operator set
+     * explicitly (file key or env var) has overridden the profile's value — so the
+     * profile name tells you where the UNSET levers came from, not what every
+     * lever is. See `profiles.ts` for the precedence chain.
+     */
+    profile: ProfileName;
     /** HTTP/WS port. */
     port: number;
     /** Bind host. Defaults to loopback (`127.0.0.1`) — safe by default (#435). */
@@ -485,6 +497,13 @@ export interface PaddockConfigFile {
      * lenient-parsed. See `schema-version.ts` for when to bump it.
      */
     schemaVersion?: number | string;
+    /**
+     * Posture profile (#878): `paranoid` | `balanced` | `yolo`. Expands to
+     * defaults for the `claude:` modes, `maxSpawnDepth` and the capability
+     * toggles; any of those set explicitly here or in the env still wins.
+     * `PADDOCK_PROFILE` overrides this key. Absent ⇒ `balanced`.
+     */
+    profile?: string;
     port?: number | string;
     host?: string;
     dataDir?: string;
@@ -680,7 +699,23 @@ export declare function loadConfigFile(dataDir: string): PaddockConfigFile;
  * installed under an arbitrary user directory (`npx`, global install).
  */
 export declare function resolveDefaultWebDist(moduleUrl: string): string;
-export declare function loadPaddockConfig(): PaddockConfig;
+/** Options for {@link loadPaddockConfig}. */
+export interface LoadConfigOptions {
+    /**
+     * Create the data root if it is missing. Default `true` — every caller that
+     * goes on to RUN something needs it, and creating it early is what makes the
+     * symlink resolution below consistent.
+     *
+     * `paddock config show` (#878) passes `false`. Inspecting an instance must not
+     * bring one into being: otherwise running it on a machine that has never
+     * started Paddock leaves an empty `~/.paddock` behind, and the first-run
+     * welcome — which keys on that directory's absence — never prints again.
+     * Skipping the mkdir costs nothing else, because `canonical()` already handles
+     * a path whose tail does not exist yet.
+     */
+    createDataDir?: boolean;
+}
+export declare function loadPaddockConfig(opts?: LoadConfigOptions): PaddockConfig;
 /**
  * The USER's own Claude home — `~/.claude`, always. A read-only source for
  * adoption and the user-config bridge, never a destination (#620).