@edspencer/paddock 0.61.1 → 0.63.0

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

@@ -50,6 +50,8 @@ import { FleetManager, type DiscoveredSession, type ChatMessage, type SDKMessage
 import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
 import { type PaddockTrigger } from "./trigger-config.js";
+import { type McpSources } from "./claude-mcp.js";
+import { type HostPluginSource } from "./claude-plugins.js";
 import { type AdoptableSummary, type FilterReason } from "./adoptable.js";
 /**
  * One session an import did NOT bring in, with a reason a UI can show verbatim.
@@ -63,6 +65,20 @@ export type AdoptSkipped = AdoptSkippedSession | {
     reason: FilterReason;
     detail?: string;
 };
+/**
+ * Outcome of deleting a chat (#689).
+ *
+ * Two fields rather than one boolean because "the transcript is gone" and "the
+ * chat is no longer listed here" stopped being the same thing: in a home paddock
+ * does not own, the file belongs to the user's terminal `claude` and is released
+ * rather than removed. See {@link HerdctlService.deleteSession}.
+ */
+export interface ChatDeletion {
+    /** A transcript file was unlinked. False when none existed, or when retained. */
+    removed: boolean;
+    /** The transcript was deliberately left on disk because it is not paddock's. */
+    retained: boolean;
+}
 /** Options passed through to a streamed trigger. */
 export interface ChatTurnOptions {
     prompt: string;
@@ -105,6 +121,8 @@ export { keeperAgentName, keeperSlugFromAgent, SWEEPER_PREFIX, sweeperAgentName,
 export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endOnCompletedAssistant?: boolean): string | null;
 export declare class HerdctlService {
     private readonly cfg;
+    private readonly mcpSources;
+    private readonly hostPlugins;
     private fleet;
     private started;
     /**
@@ -164,13 +182,31 @@ export declare class HerdctlService {
      */
     private jobsIndexOrNull;
     private get jobsIndex();
-    constructor(cfg: PaddockConfig);
     /**
-     * The Claude home every transcript symlink is planted in, plus whether paddock
-     * owns it (#620). One accessor, so no call site can quietly take a default and
-     * land in a different home than the FleetManager was built with — the bug
-     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
-     * every other agent's went to the configured home.
+     * The external MCP servers every keeper gets: the user's own under
+     * `claude.mcpServers: host` (#691 step 5, read once at boot by
+     * `loadHostMcpSource`) plus the ones this instance declares in its own
+     * `mcpServers:` block (step 6, resolved during config load). Both are merged
+     * into one value by `buildApp` and handed in here.
+     *
+     * A constructor argument rather than something this service reads for itself,
+     * for the same reason `ensureClaudeHome` runs in `buildApp`: the read has
+     * notices an operator needs to see in the boot log, and it must not happen at
+     * all under `mcpServers: own`. Defaults to empty so every existing caller —
+     * including the several tests that construct this with `{} as PaddockConfig` —
+     * keeps meaning "isolated".
+     *
+     * `hostPlugins` is the host's Claude Code plugins (#700), read at boot by
+     * `loadHostPlugins` under `claude.instructions: host`, and handed in for
+     * exactly the same reasons.
+     */
+    constructor(cfg: PaddockConfig, mcpSources?: McpSources, hostPlugins?: HostPluginSource);
+    /**
+     * The Claude home every transcript symlink is planted in, plus where those
+     * symlinks point (#620, #691). One accessor, so no call site can quietly take
+     * a default and land in a different home than the FleetManager was built with
+     * — the bug `ensureSweeperHome` had, which put the sweeper's symlink in
+     * `~/.claude` while every other agent's went to the configured home.
      */
     private get claudeHomeTarget();
     /**
@@ -421,13 +457,39 @@ export declare class HerdctlService {
      */
     removeProjectAgent(slug: string, hookNames?: string[], triggerNames?: string[]): Promise<void>;
     /**
-     * Delete a single chat (session) by agent name + session id. The FleetManager
-     * resolves the agent's working directory, removes the transcript JSONL, and
-     * invalidates the discovery cache so the list reflects it immediately.
-     * Validates the sessionId (rejects path traversal). Returns true if a
-     * transcript file was removed, false if none existed.
-     */
-    deleteSession(agentName: string, sessionId: string): Promise<boolean>;
+     * Delete a single chat (session) by agent name + session id.
+     *
+     * Under `claude.transcripts: own`, this removes the transcript JSONL: the file
+     * lives in paddock's own tree (via the project's `.chats/` symlink), so it is
+     * ours to delete. The FleetManager resolves the agent's working directory,
+     * unlinks the file, validates the sessionId against traversal, and invalidates
+     * the discovery cache so the list reflects it immediately.
+     *
+     * Under `claude.transcripts: host`, it **releases the session instead** (#689).
+     * There is no copy to delete there: the symlink points OUT at
+     * `~/.claude/projects/<encoded-cwd>/`, so the transcript the agent reads and
+     * writes is the user's own — for an adopted chat, literally their terminal
+     * history. `rm`-ing it destroys history paddock never owned, which is the same
+     * class of mistake #682 was, pointed the other way: that one claimed where
+     * future sessions get written, this one deletes the past ones.
+     *
+     * `undoImport` already draws exactly this line ("A session adopted in place has
+     * no copy, and its transcript is the user's own — removing it would destroy
+     * history rather than restore it"); the invariant simply never reached here.
+     *
+     * The discriminator changed with #691 and the meaning did not. It used to be
+     * `ownsClaudeHome` — "is this home ours?" — which is now always true; the
+     * question that survives is "is this transcript ours?", and that is exactly
+     * what `transcripts` says. Deliberately NOT narrowed to "only adopted chats":
+     * under `host` a chat paddock started itself is in the user's tree too, and
+     * distinguishing them well enough to risk an `rm` is not worth the failure mode
+     * of getting it wrong. The cost is a transcript left behind, which the caller
+     * is told about; the alternative cost is somebody's history.
+     *
+     * The chat leaves paddock's list either way — which is what the user asked for
+     * — so `retained` is how a caller tells "gone" from "no longer shown here".
+     */
+    deleteSession(agentName: string, sessionId: string): Promise<ChatDeletion>;
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
      * shared SessionMetadataStore so a subsequent getAgentSessions reflects it

package/packages/server/dist/herdctl.js

@@ -56,6 +56,8 @@ import { DEFAULT_MODEL } from "./models.js";
 import { ensureProjectChats, projectChatsDir } from "./transcripts.js";
 import { triggerRunsOnOwnAgent, isCuratorTrigger, } from "./trigger-config.js";
 import { buildAgentConfig, buildSweeperConfig, sweeperWorkingDir, buildTriggerConfig, ensureConfigFile as writeBootConfigFile, } from "./herdctl-agent-config.js";
+import { EMPTY_MCP_SOURCES } from "./claude-mcp.js";
+import { EMPTY_HOST_PLUGINS } from "./claude-plugins.js";
 import * as jobs from "./herdctl-jobs.js";
 import { JobsDirIndex } from "./herdctl-jobs-index.js";
 import { AdoptableIndex } from "./adoptable.js";
@@ -162,6 +164,8 @@ export function sliceTranscriptAtUuid(raw, cutUuid, endOnCompletedAssistant = fa
 }
 export class HerdctlService {
     cfg;
+    mcpSources;
+    hostPlugins;
     fleet = null;
     started = false;
     /**
@@ -223,18 +227,42 @@ export class HerdctlService {
     get jobsIndex() {
         return (this.jobsIndexOrNull ??= new JobsDirIndex(this.cfg.stateDir));
     }
-    constructor(cfg) {
+    /**
+     * The external MCP servers every keeper gets: the user's own under
+     * `claude.mcpServers: host` (#691 step 5, read once at boot by
+     * `loadHostMcpSource`) plus the ones this instance declares in its own
+     * `mcpServers:` block (step 6, resolved during config load). Both are merged
+     * into one value by `buildApp` and handed in here.
+     *
+     * A constructor argument rather than something this service reads for itself,
+     * for the same reason `ensureClaudeHome` runs in `buildApp`: the read has
+     * notices an operator needs to see in the boot log, and it must not happen at
+     * all under `mcpServers: own`. Defaults to empty so every existing caller —
+     * including the several tests that construct this with `{} as PaddockConfig` —
+     * keeps meaning "isolated".
+     *
+     * `hostPlugins` is the host's Claude Code plugins (#700), read at boot by
+     * `loadHostPlugins` under `claude.instructions: host`, and handed in for
+     * exactly the same reasons.
+     */
+    constructor(cfg, mcpSources = EMPTY_MCP_SOURCES, hostPlugins = EMPTY_HOST_PLUGINS) {
         this.cfg = cfg;
+        this.mcpSources = mcpSources;
+        this.hostPlugins = hostPlugins;
     }
     /**
-     * The Claude home every transcript symlink is planted in, plus whether paddock
-     * owns it (#620). One accessor, so no call site can quietly take a default and
-     * land in a different home than the FleetManager was built with — the bug
-     * `ensureSweeperHome` had, which put the sweeper's symlink in `~/.claude` while
-     * every other agent's went to the configured home.
+     * The Claude home every transcript symlink is planted in, plus where those
+     * symlinks point (#620, #691). One accessor, so no call site can quietly take
+     * a default and land in a different home than the FleetManager was built with
+     * — the bug `ensureSweeperHome` had, which put the sweeper's symlink in
+     * `~/.claude` while every other agent's went to the configured home.
      */
     get claudeHomeTarget() {
-        return { path: this.cfg.claudeHome, owned: this.cfg.ownsClaudeHome };
+        return {
+            path: this.cfg.claudeHome,
+            transcripts: this.cfg.claude.transcripts,
+            userHome: this.cfg.legacyClaudeHome,
+        };
     }
     /**
      * The environment system prompt to append to a keeper turn (issue #635), or
@@ -309,10 +337,10 @@ export class HerdctlService {
             allowScheduleMutation: this.cfg.scheduleMutationEnabled,
             // Hand the engine the SAME Claude home paddock resolved (#588). Omitting
             // it makes the engine fall back to `os.homedir()/.claude` while paddock
-            // honours `CLAUDE_HOME`, so discovery, adoption and paddock's `.chats/`
-            // symlinks would resolve against different directories — sessions list
-            // from one home and open empty from the other. Masked whenever the two
-            // coincide, which is why it must be explicit.
+            // uses its own, so discovery, adoption and paddock's transcript symlinks
+            // would resolve against different directories — sessions list from one
+            // home and open empty from the other. Masked whenever the two coincide,
+            // which is why it must be explicit.
             claudeHomePath: this.cfg.claudeHome,
         });
         await this.fleet.initialize();
@@ -763,14 +791,45 @@ export class HerdctlService {
         }
     }
     /**
-     * Delete a single chat (session) by agent name + session id. The FleetManager
-     * resolves the agent's working directory, removes the transcript JSONL, and
-     * invalidates the discovery cache so the list reflects it immediately.
-     * Validates the sessionId (rejects path traversal). Returns true if a
-     * transcript file was removed, false if none existed.
+     * Delete a single chat (session) by agent name + session id.
+     *
+     * Under `claude.transcripts: own`, this removes the transcript JSONL: the file
+     * lives in paddock's own tree (via the project's `.chats/` symlink), so it is
+     * ours to delete. The FleetManager resolves the agent's working directory,
+     * unlinks the file, validates the sessionId against traversal, and invalidates
+     * the discovery cache so the list reflects it immediately.
+     *
+     * Under `claude.transcripts: host`, it **releases the session instead** (#689).
+     * There is no copy to delete there: the symlink points OUT at
+     * `~/.claude/projects/<encoded-cwd>/`, so the transcript the agent reads and
+     * writes is the user's own — for an adopted chat, literally their terminal
+     * history. `rm`-ing it destroys history paddock never owned, which is the same
+     * class of mistake #682 was, pointed the other way: that one claimed where
+     * future sessions get written, this one deletes the past ones.
+     *
+     * `undoImport` already draws exactly this line ("A session adopted in place has
+     * no copy, and its transcript is the user's own — removing it would destroy
+     * history rather than restore it"); the invariant simply never reached here.
+     *
+     * The discriminator changed with #691 and the meaning did not. It used to be
+     * `ownsClaudeHome` — "is this home ours?" — which is now always true; the
+     * question that survives is "is this transcript ours?", and that is exactly
+     * what `transcripts` says. Deliberately NOT narrowed to "only adopted chats":
+     * under `host` a chat paddock started itself is in the user's tree too, and
+     * distinguishing them well enough to risk an `rm` is not worth the failure mode
+     * of getting it wrong. The cost is a transcript left behind, which the caller
+     * is told about; the alternative cost is somebody's history.
+     *
+     * The chat leaves paddock's list either way — which is what the user asked for
+     * — so `retained` is how a caller tells "gone" from "no longer shown here".
      */
     async deleteSession(agentName, sessionId) {
-        return this.manager.deleteSession(agentName, sessionId);
+        if (this.cfg.claude.transcripts === "own") {
+            return { removed: await this.manager.deleteSession(agentName, sessionId), retained: false };
+        }
+        await this.manager.unadoptSession(agentName, sessionId).catch(() => undefined);
+        this.invalidateSessions(agentName);
+        return { removed: false, retained: true };
     }
     /**
      * Set (or clear) a chat's custom display name. Writes through the fleet's
@@ -1456,7 +1515,7 @@ export class HerdctlService {
     // existing unit-test seams (which reach `sweeperAgentConfig`/`ensureConfigFile`
     // via a cast) and internal callers keep working.
     keeperAgentConfig(project, modelOverride) {
-        return buildAgentConfig(this.cfg, project, modelOverride);
+        return buildAgentConfig(this.cfg, project, modelOverride, this.mcpSources, this.hostPlugins);
     }
     sweeperAgentConfig(project) {
         return buildSweeperConfig(this.cfg, project);

package/packages/server/dist/instance-config.js

@@ -36,6 +36,11 @@ import { DEFAULT_RECOVERY } from "./recovery-config.js";
 import { DEFAULT_ATTACHMENTS, sanitizeAllowedTypes } from "./attachments-config.js";
 import { DEFAULT_CURATION } from "./curation-config.js";
 import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
+import { DEFAULT_TRANSCRIPTS_MODE } from "./transcripts.js";
+import { DEFAULT_CREDENTIALS_MODE } from "./claude-credentials.js";
+import { DEFAULT_INSTRUCTIONS_MODE } from "./claude-instructions.js";
+import { DEFAULT_HOOKS_MODE } from "./claude-settings.js";
+import { DEFAULT_MCP_SERVERS_MODE } from "./claude-mcp.js";
 /** Groups the Settings screen renders, in display order. */
 export const GROUPS = [
     { id: "curation", label: "Curation", description: "Per-file token budgets the post-turn sweeper keeps its curated files under." },
@@ -219,6 +224,37 @@ export const FIELDS = [
     { key: "stateDir", group: "advanced", label: "State dir", type: "string", envVars: ["PADDOCK_STATE_DIR"], default: null, editable: false },
     { key: "herdctlConfigPath", group: "advanced", label: "herdctl config path", type: "string", envVars: ["PADDOCK_HERDCTL_CONFIG"], default: null, editable: false },
     { key: "webDist", group: "advanced", label: "Web dist", type: "string", envVars: ["PADDOCK_WEB_DIST"], default: null, editable: false },
+    // What this instance shares with the host's Claude Code (#691). READ-ONLY on
+    // purpose: `host` means paddock writes to the user's real transcript files,
+    // and the symlinks that implement it are planted at agent-registration time —
+    // a toggle that silently does nothing until the next boot would be worse than
+    // no toggle. It is surfaced because "what is this instance sharing?" should be
+    // answerable without reading a YAML file.
+    { key: "claude.transcripts", group: "advanced", label: "Transcripts", help: "own = Paddock's own, in each project's .chats/; host = your ~/.claude transcripts, shared live.", type: "string", envVars: ["PADDOCK_CLAUDE_TRANSCRIPTS"], default: DEFAULT_TRANSCRIPTS_MODE, editable: false },
+    // Read-only for the same reason, plus one of its own: the secure-storage
+    // variable it sets is read by Claude Code when a turn's process starts, so a
+    // live toggle would apply to some turns and not others.
+    { key: "claude.credentials", group: "advanced", label: "Credentials", help: "host = this machine's Claude Code login (macOS Keychain, or your ~/.claude/.credentials.json); own = only a login of this instance's.", type: "string", envVars: ["PADDOCK_CLAUDE_CREDENTIALS"], default: DEFAULT_CREDENTIALS_MODE, editable: false },
+    // Read-only for the same reasons. `hooks` is the one worth finding here even
+    // though it cannot be changed here: "does this instance run the shell commands
+    // my ~/.claude/settings.json binds to tool use?" is a question with a security
+    // answer, and it should be readable without opening a YAML file.
+    { key: "claude.instructions", group: "advanced", label: "Instructions", help: "own = this instance's own only; host = your ~/.claude CLAUDE.md, agents/, commands/ and plugins/ as well.", type: "string", envVars: ["PADDOCK_CLAUDE_INSTRUCTIONS"], default: DEFAULT_INSTRUCTIONS_MODE, editable: false },
+    { key: "claude.hooks", group: "advanced", label: "Hooks", help: "own = your ~/.claude/settings.json hooks do NOT run here (its other keys still apply); host = they do.", type: "string", envVars: ["PADDOCK_CLAUDE_HOOKS"], default: DEFAULT_HOOKS_MODE, editable: false },
+    // The fifth lever, which step 5 shipped without surfacing here. Read-only like
+    // its four siblings, and worth the row for the same reason `hooks` is: an MCP
+    // server is a process this instance spawns, so "is this instance running my
+    // machine's MCP servers?" should be answerable without opening a YAML file.
+    //
+    // NOTE what is deliberately absent: the top-level `mcpServers:` block (#691
+    // step 6), which declares servers rather than borrowing them. Its values hold
+    // resolved credentials — an MCP server's `env` is where a stdio server's API
+    // token lives — and every field in this table is serialised verbatim into the
+    // GET response, so a row for it would publish tokens to any authenticated UI
+    // user. There is no redacting variant of `FieldSpec`, and inventing one to
+    // display a server list is not worth the leak surface: the boot log already
+    // names every declared server, secret-free, via `describeServer`.
+    { key: "claude.mcpServers", group: "advanced", label: "MCP servers", help: "own = only the servers Paddock provides itself; host = the ones declared in your ~/.claude.json as well.", type: "string", envVars: ["PADDOCK_CLAUDE_MCP_SERVERS"], default: DEFAULT_MCP_SERVERS_MODE, editable: false },
     // Auth: read-only in v1 (misconfig can lock everyone out — issue #385). Only
     // the mode is surfaced; JWT/JWKS internals stay out of the API.
     { key: "auth.mode", group: "advanced", label: "Auth mode", type: "string", envVars: ["PADDOCK_AUTH_MODE"], default: "none", editable: false, sensitive: true },

package/packages/server/dist/mcp-servers.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The top-level `mcpServers:` block of `paddock.config.yaml` (#691 step 6):
+ * MCP servers a user declares **to paddock itself**.
+ *
+ * ## Why this is not another `claude:` key
+ *
+ * The five `claude:` levers all answer one question — *whose X does this instance
+ * use?* — and every one of them has a `host` side that borrows something the
+ * machine already has. `claude.mcpServers: host` therefore only helps a user who
+ * has already run `claude mcp add` on this box. Someone standing up paddock in a
+ * container, who wants Notion inside it, has nothing to borrow; the question they
+ * are asking is *"this instance should have this server"*, which is a declaration
+ * rather than an inheritance. So it is a sibling of `claude:`, not a member.
+ *
+ * ## Everything below the parse is shared with step 5
+ *
+ * `claude-mcp.ts` already built the hard half: the shape herdctl can carry, the
+ * per-working-directory merge, and — the trap — widening the keeper's
+ * `allowed_tools` by one `mcp__<name>__*` pattern per server, without which an
+ * attached server has every call auto-denied with no prompt and no log line. A
+ * declared server needs all of it identically, so this module produces
+ * {@link McpServerDefs} and hands them to {@link McpSources.declared}. The only
+ * thing that is genuinely new here is validation and secrets.
+ *
+ * ## Precedence
+ *
+ * `host` < declared < paddock's own. A name declared here beats the same name
+ * inherited from `~/.claude.json`, because this file is a statement about THIS
+ * instance and the other is ambient machine state. Paddock's own servers
+ * (`send_file`, the self-management tools, the browser server) still win, for the
+ * reason they already won over `host`: their configuration is box-specific and
+ * they are wired up by a different mechanism entirely. A collision with the
+ * browser server is warned about by name at boot rather than being silent; a
+ * collision with an INJECTED server is refused outright, because those are
+ * materialised as an HTTP bridge under the same `mcp__<name>__*` namespace and
+ * two servers claiming one namespace has no defined winner.
+ *
+ * ## Secrets, which is the real work here
+ *
+ * This is the first place in #691 where a user types a credential into paddock's
+ * own config file, and that file is git-tracked (and readable through the
+ * Settings screen's config path). So this module borrows the rule
+ * `management-config.ts` already sets for management tokens: **`env:VAR_NAME` is
+ * a reference, resolved from the environment at boot.** Here it is accepted
+ * anywhere a string is (`command`, each `args` entry, each `env` value, `url`),
+ * so there is one rule to learn rather than a list of blessed fields.
+ *
+ * Unlike a management token, an MCP `env` entry is not necessarily secret
+ * (`NOTION_VERSION: "2022-06-28"` is not), so an inline value is a WARNING and
+ * not an error — but the warning is emitted for any key that looks like a
+ * credential, and nothing in this module ever prints a value. `headers` follows
+ * the same rule and for a stronger reason: `Authorization` is the usual reason a
+ * header is declared at all. Every diagnostic names keys, variable names and
+ * server names only; a `url` is reported with its query string and userinfo
+ * stripped, because that is where an API key rides. {@link describeServer} is the
+ * single place a server is rendered for a human, so there is one function to
+ * audit rather than a scattering of template strings.
+ *
+ * The resolved values do land in the frozen `PaddockConfig` (as management tokens
+ * already do). They must never reach an API response: `instance-config.ts`
+ * publishes only the fields in its own `FIELDS` table, and this block is
+ * deliberately absent from it.
+ *
+ * One exposure the `env:` indirection does NOT close: under `driveMode: batch`
+ * the resolved value reaches a COMMAND LINE. See {@link argvExposure} — and note
+ * that carrying `headers` (#700) widens it, because an `Authorization` bearer is
+ * a likelier long-lived credential than an `env` entry.
+ *
+ * ## Validation is strict, and drops rather than degrades
+ *
+ * Step 5 passes a host server it cannot carry faithfully, with a warning, on the
+ * grounds that a user who declared a server elsewhere should get it plus a
+ * warning rather than nothing plus a warning. That reasoning inverts here,
+ * because the user typed this file: an unusable declaration is a mistake they can
+ * fix. So anything that cannot be carried is an ERROR and that server is not
+ * attached — including an unknown key, which is how a typo (`arg:` for `args:`)
+ * otherwise becomes a server that starts wrong.
+ *
+ * `headers:` and `type: sse` USED to be in that category, because herdctl's
+ * schema had no field for either. herdctl 5.32.0 (#446) carries both verbatim,
+ * so refusing them would now reject a declaration that works — they are accepted,
+ * and `headers` is a first-class secret-bearing field with the same `env:VAR`
+ * resolution and the same never-print rule as `env`.
+ *
+ * Never a boot failure, though: one bad server drops itself and the rest attach,
+ * matching `resolveManagementApiConfig`. A typo in a capability must not take an
+ * instance down.
+ */
+import type { McpServerDefs, McpServerDef } from "./claude-mcp.js";
+import type { DriveMode } from "./models.js";
+/** On-disk shape of one entry of the `mcpServers:` block. Every field optional. */
+export interface McpServerConfigFile {
+    /** Executable for a stdio server. Mutually exclusive with {@link url}. */
+    command?: string;
+    /** Arguments for {@link command}. */
+    args?: string[];
+    /** Environment for the server process. Values may be `env:VAR_NAME`. */
+    env?: Record<string, string>;
+    /** Endpoint for a remote server. Mutually exclusive with {@link command}. */
+    url?: string;
+    /** `stdio` for a {@link command}; `http` or `sse` for a {@link url}. */
+    type?: string;
+    /** Headers for a remote server. Values may be `env:VAR_NAME`. */
+    headers?: Record<string, string>;
+}
+/** On-disk shape of the whole block: a map of server name → declaration. */
+export type McpServersConfigFile = Record<string, McpServerConfigFile | null | undefined>;
+/** Outcome of resolving the block, with everything worth telling the operator. */
+export interface DeclaredMcpResolution {
+    /** The servers that will be attached to every keeper. */
+    servers: McpServerDefs;
+    /** Declarations that could not be carried (logged at error level, server dropped). */
+    errors: string[];
+    /** Advice and fail-closed drops (logged at warn level). */
+    warnings: string[];
+}
+/**
+ * The prefix that makes a string an environment reference rather than a literal.
+ * Same spelling as `managementApi.clients.<id>.auth.ref`, deliberately: an
+ * operator should have to learn it once.
+ */
+export declare const ENV_REF_PREFIX = "env:";
+/**
+ * Server names paddock materialises itself, which a declaration may not take.
+ *
+ * Kept as literals rather than imported from `send-file-mcp.ts`/`self-mcp.ts` so
+ * config resolution stays free of the runtime modules — `mcp-servers-reserved`
+ * in the unit tests asserts the two spellings still agree.
+ */
+export declare const RESERVED_MCP_SERVER_NAMES: readonly string[];
+/**
+ * A URL with everything credential-shaped removed — no query string, no
+ * fragment, no `user:pass@`. Used for every log line that mentions a `url`,
+ * because a remote MCP endpoint's API key is conventionally a query parameter.
+ * An unparseable URL is reported as its scheme only rather than echoed.
+ */
+export declare function redactUrl(raw: string): string;
+/**
+ * A server rendered for a human, carrying no secret. THE chokepoint: every
+ * notice, warning and error about a declared server goes through here, so
+ * auditing "can a token reach a log line?" is auditing one function.
+ *
+ * Args and env values are counted, never printed — an API key is as likely to be
+ * `--token=…` in `args` as it is to be an `env` value. The command is reduced to
+ * its basename for the same reason, which the leak test in
+ * `test/unit/mcp-servers.test.ts` is what forced: a full path is more useful in a
+ * log, but the rule "nothing from the block is echoed" is only worth having if it
+ * has no exceptions to remember. The server's own name is printed alongside and
+ * is what actually identifies it.
+ */
+export declare function describeServer(name: string, def: McpServerDef): string;
+/**
+ * Resolve the whole `mcpServers:` block against `env`.
+ *
+ * Never throws. A declaration paddock cannot carry is reported and dropped so one
+ * typo cannot take an instance down — the same posture as
+ * `resolveManagementApiConfig`, and for the same reason: this is a capability,
+ * and losing a capability is better than losing the instance.
+ */
+export declare function resolveDeclaredMcpServers(file: McpServersConfigFile | undefined, env: Record<string, string | undefined>): DeclaredMcpResolution;
+/** A line for the boot log, at a level (mirrors `HostMcpNotice`). */
+export interface DeclaredMcpNotice {
+    level: "info" | "warn";
+    message: string;
+}
+/**
+ * What to say at boot about the declared servers — the answer to "what does this
+ * instance actually have?", which should be readable off the log rather than
+ * inferred from a YAML file plus an environment.
+ *
+ * Takes the already-resolved servers, so it cannot see a raw declaration and
+ * therefore cannot leak one; every line it produces goes through
+ * {@link describeServer}.
+ */
+export declare function declaredMcpNotices(opts: {
+    servers: McpServerDefs;
+    /** Names inherited from `~/.claude.json`, for the shadowing notice. */
+    hostNames?: readonly string[];
+    /** Whether paddock's own browser server is attached (it wins a name clash). */
+    browserMcp?: boolean;
+    /**
+     * The instance's drive mode, which decides whether a declared `env` value ends
+     * up on a command line. Omitted ⇒ say nothing (the several callers that only
+     * want the inventory line).
+     */
+    driveMode?: DriveMode;
+}): DeclaredMcpNotice[];