@edspencer/paddock 0.71.2 → 0.72.0

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

@@ -0,0 +1,462 @@
+/**
+ * `paddock config show` — what this instance's config actually resolved to (#878).
+ *
+ * ## Why the command exists
+ *
+ * #878 ships a `profile:` key so an operator's config file can stay thin: a
+ * posture name plus the handful of levers they disagree with. The objection to a
+ * thin file is real — "I want it all clearly written down" — and the answer is
+ * not to write it all down. A materialised file is a snapshot that goes stale the
+ * moment a default improves or a lever is added, and it cannot show you the env
+ * vars your container sets on top. Printing the resolution can't drift, because
+ * it is computed by the same loader the server boots with.
+ *
+ * ## Provenance is the deliverable, not the values
+ *
+ * A list of effective values is a thing you can already get by reading the Config
+ * screen. What you cannot get anywhere is the LAYER each one came from — and the
+ * layer is what tells you where to go to change it. So every row names one of
+ * `env` / `file` / `profile` / `default`, and `profile` is kept distinct from
+ * `default` because for the twelve posture keys there is no code default any more
+ * (see `ConfigSource` in instance-config.ts).
+ *
+ * ## What plain `config show` does
+ *
+ * It prints the DECISIONS — the profile, the keys your file sets, the variables
+ * your environment sets — and nothing else. That mirrors the shape #878 argues
+ * for: thin by default, explicit on demand. Two failure modes it avoids: an
+ * argument-less command that errors at you is rude, and one that dumps forty rows
+ * makes `--resolved` pointless. The summary is a reading of the same report
+ * `--resolved` prints in full, so the two can never disagree.
+ *
+ * The formatting functions here are pure and unit-tested; {@link runConfig} is
+ * the only part that touches the filesystem, and it is exercised by running the
+ * built binary.
+ */
+import { CliError } from "./args.js";
+/**
+ * Longest value printed in the table before it is elided. The environment prompt
+ * is ~600 characters of paragraph text and would own the terminal; `--json`
+ * prints every value in full for anyone who needs one.
+ */
+const MAX_VALUE_CHARS = 52;
+/**
+ * Stand-in for a `sensitive` field's value. Provenance is still reported, so the
+ * row still answers "where would I change this?".
+ *
+ * Redaction is uniform on the flag rather than judged per field, and that is the
+ * point. `FIELDS` documents itself as never carrying a secret value — but that is
+ * an intention maintained by hand, not an enforced invariant, and one of the
+ * three fields it already marks is `transcription.endpoint`: a URL an operator
+ * typed, which can perfectly well read `https://user:token@host`. The output of
+ * this command is designed to be pasted into an issue. So the safe reading of the
+ * flag wins by default and `--show-sensitive` is one keystroke away — which also
+ * means a field added with `sensitive: true` in two years is redacted here
+ * without anyone having to remember this file exists.
+ */
+const HIDDEN = "(hidden)";
+/** Render one value as a single line of terminal text. */
+function renderValue(v) {
+    if (v === null || v === undefined)
+        return "(unset)";
+    if (Array.isArray(v))
+        return v.length > 0 ? v.join(", ") : "(empty)";
+    if (typeof v === "string")
+        return v === "" ? '""' : v;
+    return String(v);
+}
+/** Collapse to one line and elide. Returns whether anything was lost. */
+function oneLine(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > MAX_VALUE_CHARS
+        ? { text: `${flat.slice(0, MAX_VALUE_CHARS - 1)}…`, elided: true }
+        : { text: flat, elided: false };
+}
+/** The source column: the layer, and enough of the origin to act on it. */
+function renderSource(f) {
+    switch (f.source) {
+        case "env":
+            return `env ${f.origin}`;
+        case "profile":
+            return `profile (${f.origin})`;
+        case "file":
+            return "file";
+        default:
+            return "default";
+    }
+}
+function pad(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+/** The three header lines both views share. */
+function header(report) {
+    const p = report.profile;
+    const from = p.source === "env"
+        ? `${p.origin}`
+        : p.source === "file"
+            ? "config file"
+            : "built-in default";
+    const lines = [
+        `  Data dir     ${report.dataDir}`,
+        `  Config file  ${report.configPath}${report.configFileExists ? "" : "  (not present)"}`,
+        `  Profile      ${p.name}  (${from})`,
+    ];
+    if (p.unrecognised) {
+        lines.push(`               ${p.origin ?? p.unrecognised.origin} names "${p.unrecognised.value}", which is not a known profile — ` +
+            `fell back to ${p.name}`);
+    }
+    if (report.configFileError)
+        lines.push(`  ⚠ ${report.configFileError}`);
+    return lines;
+}
+/**
+ * File values a higher layer beat. Rendered by both views because the operator
+ * who edited a file and saw nothing change is precisely who runs this command,
+ * and today nothing anywhere tells them why.
+ */
+function shadowedSection(report) {
+    const shadowed = report.fields.filter((f) => f.shadowedFileValue !== undefined);
+    if (shadowed.length === 0)
+        return [];
+    const width = Math.max(...shadowed.map((f) => f.key.length));
+    return [
+        "",
+        "Set in the config file but NOT in effect",
+        ...shadowed.map((f) => {
+            const wrote = renderValue(f.shadowedFileValue);
+            const why = f.source === "env"
+                ? `${f.origin} wins for the same key`
+                : `the resolved value is ${renderValue(f.value)}`;
+            return `  ${pad(f.key, width)}  file says ${wrote} — ${why}`;
+        }),
+    ];
+}
+/**
+ * The default view: the decisions, not the resolution. Everything named here is
+ * something a human typed somewhere.
+ */
+export function formatSummary(report) {
+    const fromFile = report.fields.filter((f) => f.source === "file");
+    const fromEnv = report.fields.filter((f) => f.source === "env");
+    const lines = ["Paddock config", ...header(report), "", "Set in the config file"];
+    if (fromFile.length === 0) {
+        lines.push(report.configFileExists ? "  (nothing this instance reads)" : "  (no config file)");
+    }
+    else {
+        const width = Math.max(...fromFile.map((f) => f.key.length));
+        for (const f of fromFile) {
+            lines.push(`  ${pad(f.key, width)}  ${oneLine(renderValue(f.sensitive ? HIDDEN : f.value)).text}`);
+        }
+    }
+    lines.push("", "Set in the environment");
+    if (fromEnv.length === 0) {
+        lines.push("  (nothing)");
+    }
+    else {
+        const width = Math.max(...fromEnv.map((f) => (f.origin ?? "").length));
+        for (const f of fromEnv) {
+            lines.push(`  ${pad(f.origin ?? "", width)}  ${f.key} = ${oneLine(renderValue(f.sensitive ? HIDDEN : f.value)).text}`);
+        }
+    }
+    lines.push(...shadowedSection(report));
+    lines.push("", `Everything else follows the ${report.profile.name} profile and Paddock's built-in defaults.`, "Run `paddock config show --resolved` to print every effective value and where it came from.");
+    return lines.join("\n");
+}
+/** `--resolved`: every field in the settings surface, grouped, with its layer. */
+export function formatResolved(report, groups, showSensitive) {
+    const keyWidth = Math.max(...report.fields.map((f) => f.key.length));
+    const rendered = report.fields.map((f) => {
+        const hide = f.sensitive && !showSensitive && f.value !== null;
+        return { field: f, ...oneLine(renderValue(hide ? HIDDEN : f.value)), hidden: hide };
+    });
+    const valueWidth = Math.max(...rendered.map((r) => r.text.length));
+    const lines = ["Paddock config — every effective value, and the layer it came from", ...header(report)];
+    for (const g of groups) {
+        const rows = rendered.filter((r) => r.field.group === g.id);
+        if (rows.length === 0)
+            continue;
+        lines.push("", g.label);
+        for (const r of rows) {
+            lines.push(`  ${pad(r.field.key, keyWidth)}  ${pad(r.text, valueWidth)}  ${renderSource(r.field)}`);
+        }
+    }
+    lines.push(...shadowedSection(report));
+    // A legend, listing only the layers actually present — a reader should not
+    // have to learn what `profile (yolo)` means on an instance that has no
+    // profile-sourced values left.
+    const present = new Set(report.fields.map((f) => f.source));
+    const legend = [
+        ["env", "env NAME", "that variable, which beats the config file for the same key"],
+        ["file", "file", report.configPath],
+        [
+            "profile",
+            `profile (${report.profile.name})`,
+            "the profile — these levers have no code default of their own",
+        ],
+        ["default", "default", "Paddock's built-in default"],
+    ];
+    const shown = legend.filter(([source]) => present.has(source));
+    if (shown.length > 0) {
+        const width = Math.max(...shown.map(([, term]) => term.length));
+        lines.push("", "Where the values came from", ...shown.map(([, term, meaning]) => `  ${pad(term, width)}  ${meaning}`));
+    }
+    const notes = [];
+    if (rendered.some((r) => r.hidden)) {
+        notes.push(
+        // NOT "--json prints it": --json redacts too, and pointing at it as an
+        // escape hatch would be a false claim in the one place a reader is
+        // deciding whether their secret just went to a terminal.
+        `${HIDDEN} — a field marked sensitive. Pass --show-sensitive to print it.`);
+    }
+    if (rendered.some((r) => r.elided)) {
+        notes.push(`Values longer than ${MAX_VALUE_CHARS} characters are elided; --json prints them in full.`);
+    }
+    if (notes.length > 0)
+        lines.push("", ...notes.map((n) => n));
+    return lines.join("\n");
+}
+/** The report as JSON, with `sensitive` values replaced unless asked for. */
+export function toJson(report, showSensitive) {
+    return JSON.stringify({
+        ...report,
+        fields: report.fields.map((f) => f.sensitive && !showSensitive && f.value !== null
+            ? { ...f, value: null, redacted: true }
+            : f),
+    }, null, 2);
+}
+/**
+ * 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 function buildEjectPlan(report, includeEnv = false) {
+    const entries = [];
+    const skipped = [];
+    const keptFromFile = [];
+    for (const f of report.fields) {
+        if (!f.ejectable) {
+            // `sensitive` and the machine-specific bindings are the only two ways a
+            // field can be non-ejectable, and `sensitive` is on the field, so the
+            // reason is recoverable without duplicating the policy out of the catalog.
+            skipped.push({ key: f.key, reason: f.sensitive ? "sensitive" : "binding" });
+            continue;
+        }
+        if (f.source === "env" && !includeEnv) {
+            skipped.push({ key: f.key, reason: "env", ...(f.origin ? { origin: f.origin } : {}) });
+            continue;
+        }
+        if (f.value === null) {
+            skipped.push({ key: f.key, reason: "unset" });
+            continue;
+        }
+        // Already in the file and already winning: leave the operator's own line
+        // exactly as they wrote it, comments, quoting and all. The key is present,
+        // which is all an ejected file needs; rewriting it would only churn.
+        if (f.source === "file") {
+            keptFromFile.push(f.key);
+            continue;
+        }
+        entries.push({
+            key: f.key,
+            group: f.group,
+            value: f.value,
+            source: f.source,
+            ...(f.origin ? { origin: f.origin } : {}),
+            // The file naming a key that lost — to an env var, or to another key's
+            // cascade (`selfMcpEnabled: false` collapsing `selfMcpWriteEnabled`) — is
+            // the one case where eject overwrites something an operator typed. It is
+            // also the case where the file currently asserts something untrue, so
+            // replacing it with the effective value is the point rather than a cost.
+            ...(f.shadowedFileValue !== undefined
+                ? { action: "change", fileValue: f.shadowedFileValue }
+                : { action: "add" }),
+        });
+    }
+    const writeProfile = report.profile.source !== "file";
+    const pairs = entries.map(({ key, value }) => ({ key, value }));
+    // Written FIRST so it lands at the top of a fresh document, where a reader
+    // meets the posture before the forty keys expanding it.
+    if (writeProfile)
+        pairs.unshift({ key: "profile", value: report.profile.name });
+    return {
+        report,
+        entries,
+        skipped,
+        keptFromFile,
+        profile: { name: report.profile.name, write: writeProfile },
+        pairs,
+    };
+}
+/** `n item` / `n items`. */
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/**
+ * The cost of ejecting, stated in terms of THIS plan's keys.
+ *
+ * #878 requires the staleness tradeoff to be surfaced where someone can act on
+ * it, not just documented. A generic "you will stop getting improved defaults"
+ * is easy to read past, so the two keys where that bites hardest and most
+ * concretely are named with their actual contents when the plan contains them.
+ */
+function costSection(plan) {
+    const has = (key) => plan.entries.find((e) => e.key === key);
+    const lines = [
+        "",
+        "What you give up",
+        "  Every key below stops following Paddock's defaults and becomes yours to",
+        "  maintain. Upgrades will no longer change any of them.",
+    ];
+    const models = has("models");
+    if (Array.isArray(models?.value)) {
+        lines.push(`    models             pinned to today's ${plural(models.value.length, "model")}. A model added in a`, "                       later release will not be offered until you re-run this.");
+    }
+    if (has("environmentPrompt")) {
+        lines.push("    environmentPrompt  pinned to the current text. Improvements to what agents", "                       are told about running in Paddock stop reaching you.");
+    }
+    lines.push("", "  A lever added in a later release will not be in this file at all, so the", "  file stops being the complete record you ejected it to be. `profile:` keeps", "  such a lever on your posture rather than the built-in default — but keeping", "  the file complete means re-running eject after upgrades.", "", "  None of this is one-way. Delete the keys you would rather inherit again,", "  leave `profile:` in place, and they go back to following it —", "  `paddock config show` will tell you which layer each one is coming from.");
+    return lines;
+}
+/**
+ * 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 function formatEjectPlan(plan, groups, written) {
+    const { report } = plan;
+    const lines = [
+        written ? "Paddock config — ejected" : "Paddock config — eject preview",
+        ...header(report),
+    ];
+    const total = plan.pairs.length;
+    // Re-running eject on an already-ejected instance is the normal way to find
+    // out whether an upgrade added a lever, so it should read as an answer rather
+    // than as a write that did nothing.
+    if (total === 0) {
+        lines.push("", `Nothing to write — every key eject manages is already in ${report.configPath}.`, ...(plan.skipped.length > 0 ? notWrittenSection(plan) : []));
+        return lines.join("\n");
+    }
+    lines.push("", written
+        ? `Wrote ${plural(total, "key")} to ${report.configPath}`
+        : `Would write ${plural(total, "key")} to ${report.configPath}` +
+            (report.configFileExists ? "" : "  (creating it)"));
+    if (plan.profile.write) {
+        lines.push(`  profile: ${plan.profile.name}  — so a lever added in a later release still`, "           follows this posture rather than the built-in default");
+    }
+    const keyWidth = Math.max(8, ...plan.entries.map((e) => e.key.length));
+    const rendered = plan.entries.map((e) => ({ entry: e, ...oneLine(renderValue(e.value)) }));
+    const valueWidth = Math.max(1, ...rendered.map((r) => r.text.length));
+    for (const g of groups) {
+        const rows = rendered.filter((r) => r.entry.group === g.id);
+        if (rows.length === 0)
+            continue;
+        lines.push("", g.label);
+        for (const r of rows) {
+            const from = r.entry.action === "change"
+                ? `replaces ${oneLine(renderValue(r.entry.fileValue)).text}, which is not in effect`
+                : `from ${renderSource({ source: r.entry.source, origin: r.entry.origin })}`;
+            lines.push(`  ${pad(r.entry.key, keyWidth)}  ${pad(r.text, valueWidth)}  ${from}`);
+        }
+    }
+    if (plan.keptFromFile.length > 0) {
+        lines.push("", `Already in the file, left untouched (${plan.keptFromFile.length})`, `  ${plan.keptFromFile.join(", ")}`);
+    }
+    lines.push(...notWrittenSection(plan));
+    lines.push(...costSection(plan));
+    lines.push("", written
+        ? "`paddock config show --resolved` now reports these as `file`."
+        : "Nothing was written. Re-run with --write to apply.");
+    return lines.join("\n");
+}
+/** The deliberate omissions, grouped by reason so the list stays readable. */
+function notWrittenSection(plan) {
+    const by = (r) => plan.skipped.filter((s) => s.reason === r);
+    const env = by("env");
+    const sensitive = by("sensitive");
+    const binding = by("binding");
+    const unset = by("unset");
+    if (plan.skipped.length === 0)
+        return [];
+    const lines = ["", "Not written"];
+    if (env.length > 0) {
+        lines.push(`  ${plural(env.length, "key")} the environment supplies — an environment variable beats the`, "  file, so freezing its value here would change nothing now and change this", "  instance the day the variable goes away. Pass --include-env to write them.", ...(() => {
+            const w = Math.max(...env.map((s) => s.key.length));
+            return env.map((s) => `    ${pad(s.key, w)}  ${s.origin ?? "env"}`);
+        })());
+    }
+    if (sensitive.length > 0) {
+        lines.push(`  ${plural(sensitive.length, "key")} marked sensitive — never bulk-written to disk, because one of`, "  them (transcription.endpoint) can carry a credential in its URL. Set one by", "  hand if you want it in the file.", `    ${sensitive.map((s) => s.key).join(", ")}`);
+    }
+    if (binding.length > 0) {
+        lines.push("  Process and filesystem bindings — absolute paths and a port specific to", "  this machine, which would make the file unportable:", `    ${binding.map((s) => s.key).join(", ")}`);
+    }
+    if (unset.length > 0) {
+        lines.push(`  ${plural(unset.length, "optional key")} nothing has set, so there is no value to freeze:`, `    ${unset.map((s) => s.key).join(", ")}`);
+    }
+    return lines;
+}
+/**
+ * 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 async function runConfig(action, opts) {
+    const { loadPaddockConfig } = await import("../config.js");
+    const { resolveConfigReport, writeInstanceConfig, GROUPS } = await import("../instance-config.js");
+    let cfg;
+    try {
+        cfg = loadPaddockConfig({ createDataDir: false });
+    }
+    catch (err) {
+        // An unparseable file, a `PADDOCK_CONFIG` pointing at nothing, a file from a
+        // newer schema, a Claude home that resolves somewhere refused — the loader
+        // rejects all of these, and rejecting them here is the RIGHT answer: the
+        // honest reply to "what is my config?" when it will not load is "your
+        // instance would not boot". On its own it reads as though the inspection tool
+        // is broken, so say whose problem it is.
+        //
+        // Scoped to the LOAD deliberately, and worded about the configuration rather
+        // than about a file. A failure below this line is a bug in this command, and
+        // claiming `paddock start` would fail too would be a false statement at the
+        // moment someone most needs a true one — while a `CLAUDE_CONFIG_DIR` refusal
+        // is a real boot failure with no config file involved at all.
+        throw new CliError(`${err.message}\nThis is what \`paddock start\` would fail with too.`);
+    }
+    const report = resolveConfigReport(cfg);
+    if (action === "eject") {
+        const plan = buildEjectPlan(report, opts.includeEnv === true);
+        if (opts.write === true) {
+            try {
+                writeInstanceConfig(report.configPath, plan.pairs);
+            }
+            catch (err) {
+                // An unwritable path, a read-only mount, a directory where the file
+                // should be. Raised as a CliError so `paddock.ts` reports it as this
+                // command failing rather than appending its "`paddock start` would fail
+                // on the same file" note, which is true of a malformed config and a
+                // lie about a permissions problem.
+                throw new CliError(`could not write ${report.configPath}: ${err.message}\n` +
+                    `Nothing was changed. Check the path is writable, then re-run.`);
+            }
+        }
+        console.log(formatEjectPlan(plan, GROUPS, opts.write === true));
+        return;
+    }
+    if (action !== "show")
+        throw new Error(`unhandled config action: ${String(action)}`);
+    if (opts.json) {
+        console.log(toJson(report, opts.showSensitive === true));
+        return;
+    }
+    console.log(opts.resolved
+        ? formatResolved(report, GROUPS, opts.showSensitive === true)
+        : formatSummary(report));
+}

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

@@ -23,7 +23,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CliError, USAGE, SERVICE_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
+import { CliError, USAGE, SERVICE_USAGE, CONFIG_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
 import { runService, safeHomeDir } from "./service/index.js";
 /**
  * This module's own file and directory: `<…>/packages/server/dist/cli/`.
@@ -187,6 +187,52 @@ async function service(command) {
         throw err;
     }
 }
+/**
+ * Which instance this invocation is about: an explicit flag, else the
+ * environment, else `~/.paddock`.
+ *
+ * Shared by `start` and `config` deliberately. A `config show` that resolved its
+ * data dir even slightly differently would report on an instance other than the
+ * one `paddock start` runs — and would do it convincingly, since every value it
+ * printed would be real. One function, so the two cannot diverge.
+ */
+function resolveDataDir(opts) {
+    return path.resolve(opts.dataDir ?? process.env.PADDOCK_DATA_DIR ?? path.join(os.homedir(), ".paddock"));
+}
+/**
+ * `paddock config …` — print the resolved configuration (#878).
+ *
+ * Sets `PADDOCK_DATA_DIR` before the dynamic import for the same reason the
+ * start path does: `loadPaddockConfig` reads the environment, so the environment
+ * has to be finished first. Nothing else `main` does on the way to `start()` —
+ * the PATH edit, the first-run notice, the log-level defaults — applies to a
+ * command that only reads.
+ */
+async function config(command) {
+    const { action, opts } = command;
+    // Unreachable: `parseCommand` only omits the action when `--help` was given,
+    // which `main` has already handled. Typed rather than asserted.
+    if (action === undefined) {
+        console.log(CONFIG_USAGE);
+        return;
+    }
+    process.env.PADDOCK_DATA_DIR = resolveDataDir(opts);
+    const { runConfig } = await import("./config.js");
+    try {
+        await runConfig(action, opts);
+    }
+    catch (err) {
+        // A config that will not load reaches here as a CliError already carrying
+        // the "start would fail too" note; anything else is reported as itself,
+        // because it is a bug in this command rather than in the configuration.
+        // Same shape as `service` above.
+        if (err instanceof CliError)
+            fail(err.message);
+        if (err instanceof Error)
+            fail(err.message);
+        throw err;
+    }
+}
 async function main() {
     let command;
     try {
@@ -199,7 +245,7 @@ async function main() {
     }
     const opts = command.opts;
     if (opts.help) {
-        console.log(command.verb === "service" ? SERVICE_USAGE : USAGE);
+        console.log(command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE);
         return;
     }
     if (opts.version) {
@@ -213,6 +259,10 @@ async function main() {
         await service(command);
         return;
     }
+    if (command.verb === "config") {
+        await config(command);
+        return;
+    }
     addBundledBinsToPath();
     // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here`
     // used to make the current directory the workspace by setting
@@ -235,7 +285,7 @@ async function main() {
     // server resolves config inside `buildApp()`, so anything set before the
     // dynamic import below is picked up with no special-casing in config.ts.
     // Precedence is explicit flag > existing env > our default.
-    const dataDir = path.resolve(opts.dataDir ?? process.env.PADDOCK_DATA_DIR ?? path.join(os.homedir(), ".paddock"));
+    const dataDir = resolveDataDir(opts);
     noteFirstRun(dataDir);
     process.env.PADDOCK_DATA_DIR = dataDir;
     if (opts.port)

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).