@edspencer/paddock 0.62.0 → 0.64.0

package/packages/server/dist/herdctl-agent-config.d.ts

@@ -1,6 +1,7 @@
 import type { PaddockConfig } from "./config.js";
 import type { Project } from "./projects.js";
 import { type McpSources } from "./claude-mcp.js";
+import { type HostPluginSource } from "./claude-plugins.js";
 import { type PaddockTrigger } from "./trigger-config.js";
 /**
  * A project's keeper agent config. Inherits the fleet `defaults` (runtime,
@@ -34,8 +35,13 @@ import { type PaddockTrigger } from "./trigger-config.js";
  * which is both the isolated mode and what every existing caller means. The
  * KEEPER is the only agent that gets them: the sweeper is tool-less and each
  * trigger declares its own narrow allowlist, so neither could call one anyway.
+ *
+ * `hostPlugins` is the same story for the host's Claude Code plugins (#700),
+ * resolved once at boot by `claude-plugins.ts` and gated by `claude.instructions`
+ * rather than `claude.mcpServers` — see that module for why. Keeper-only for the
+ * same reasons, and empty unless the lever is on.
  */
-export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string, mcpSources?: McpSources): Record<string, unknown> & {
+export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, modelOverride?: string, mcpSources?: McpSources, hostPlugins?: HostPluginSource): Record<string, unknown> & {
     name: string;
 };
 /**

package/packages/server/dist/herdctl-agent-config.js

@@ -14,6 +14,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { EMPTY_MCP_SOURCES, mcpServersFor, mcpToolPattern, } from "./claude-mcp.js";
+import { EMPTY_HOST_PLUGINS } from "./claude-plugins.js";
 import { DEFAULT_MODEL, SWEEPER_DEFAULT_MODEL, DEFAULT_PERMISSION_MODE, DEFAULT_MAX_TURNS, } from "./models.js";
 import { triggerToAgentToolConfig, triggersToHerdctlSchedules, curatorTriggerOf, } from "./trigger-config.js";
 import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers, FLEET_ALLOWED_TOOLS, DENIED_TOOLS, KEEPER_MAX_CONCURRENT, KEEPER_SESSION_TIMEOUT, } from "./herdctl-agent-names.js";
@@ -49,8 +50,13 @@ import { keeperAgentName, sweeperAgentName, triggerAgentName, browserMcpServers,
  * which is both the isolated mode and what every existing caller means. The
  * KEEPER is the only agent that gets them: the sweeper is tool-less and each
  * trigger declares its own narrow allowlist, so neither could call one anyway.
+ *
+ * `hostPlugins` is the same story for the host's Claude Code plugins (#700),
+ * resolved once at boot by `claude-plugins.ts` and gated by `claude.instructions`
+ * rather than `claude.mcpServers` — see that module for why. Keeper-only for the
+ * same reasons, and empty unless the lever is on.
  */
-export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY_MCP_SOURCES) {
+export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY_MCP_SOURCES, hostPlugins = EMPTY_HOST_PLUGINS) {
     const config = {
         name: keeperAgentName(project.slug),
         description: project.summary || `Claude Code agent for project ${project.name}.`,
@@ -142,9 +148,19 @@ export function buildAgentConfig(cfg, project, modelOverride, mcpSources = EMPTY
     // Patterns already on the defaults are filtered out, so nothing is restated
     // for an instance with no external servers (or one whose only server paddock's
     // own overrode above) — that config stays byte-identical to before this lever.
-    const extra = Object.keys(external)
-        .map(mcpToolPattern)
-        .filter((pattern) => !FLEET_ALLOWED_TOOLS.includes(pattern));
+    //
+    // The host's Claude Code PLUGINS ride on the same two mechanisms (#700, and the
+    // `plugins` passthrough herdctl 5.32.0 added for it). They are a separate key
+    // rather than more `mcp_servers` because a plugin is a directory the engine
+    // loads, not a server paddock can describe — but their servers land in the same
+    // tool namespace and need the same allowlist widening, under names paddock has
+    // to derive rather than read (`claude-plugins.ts`).
+    if (hostPlugins.plugins.length > 0)
+        config.plugins = hostPlugins.plugins;
+    const extra = [
+        ...Object.keys(external).map(mcpToolPattern),
+        ...hostPlugins.toolPatterns,
+    ].filter((pattern) => !FLEET_ALLOWED_TOOLS.includes(pattern));
     if (extra.length > 0)
         config.allowed_tools = [...FLEET_ALLOWED_TOOLS, ...extra];
     return config;

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

@@ -51,6 +51,7 @@ 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.
@@ -121,6 +122,7 @@ export declare function sliceTranscriptAtUuid(raw: string, cutUuid: string, endO
 export declare class HerdctlService {
     private readonly cfg;
     private readonly mcpSources;
+    private readonly hostPlugins;
     private fleet;
     private started;
     /**
@@ -193,8 +195,12 @@ export declare class HerdctlService {
      * 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);
+    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

package/packages/server/dist/herdctl.js

@@ -57,6 +57,7 @@ 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";
@@ -164,6 +165,7 @@ export function sliceTranscriptAtUuid(raw, cutUuid, endOnCompletedAssistant = fa
 export class HerdctlService {
     cfg;
     mcpSources;
+    hostPlugins;
     fleet = null;
     started = false;
     /**
@@ -238,10 +240,15 @@ export class HerdctlService {
      * 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) {
+    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 where those
@@ -1508,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, this.mcpSources);
+        return buildAgentConfig(this.cfg, project, modelOverride, this.mcpSources, this.hostPlugins);
     }
     sweeperAgentConfig(project) {
         return buildSweeperConfig(this.cfg, project);

package/packages/server/dist/management-ops.js

@@ -308,8 +308,9 @@ export function buildManagementOps(ctx, params) {
                 name: project.name,
                 dir: project.dir,
                 workingDir: project.workingDir,
-                repoBacked: project.repoBacked === true,
+                managed: project.managed === true,
                 ...(project.repo ? { repo: project.repo } : {}),
+                ...(project.path ? { path: project.path } : {}),
                 agentRegistered,
             };
         },

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

@@ -48,33 +48,46 @@
  * 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. 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.
+ * 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, and a `headers:` block that is silently dropped is an authentication
- * failure that looks like a broken server. 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.
+ * 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}. */
@@ -83,11 +96,11 @@ export interface McpServerConfigFile {
     args?: string[];
     /** Environment for the server process. Values may be `env:VAR_NAME`. */
     env?: Record<string, string>;
-    /** Endpoint for a streamable-HTTP server. Mutually exclusive with {@link command}. */
+    /** Endpoint for a remote server. Mutually exclusive with {@link command}. */
     url?: string;
-    /** Accepted only as `stdio`/`http`, and only when it agrees with the above. */
+    /** `stdio` for a {@link command}; `http` or `sse` for a {@link url}. */
     type?: string;
-    /** Present only in a MISCONFIGURED file: the engine cannot carry headers. */
+    /** 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. */
@@ -165,4 +178,10 @@ export declare function declaredMcpNotices(opts: {
     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[];

package/packages/server/dist/mcp-servers.js

@@ -65,12 +65,15 @@ export function describeServer(name, def) {
     if (def.command)
         parts.push(`stdio: ${def.command.split(/[\\/]/).pop()}`);
     if (def.url)
-        parts.push(`http: ${redactUrl(def.url)}`);
+        parts.push(`${def.type ?? "http"}: ${redactUrl(def.url)}`);
     if (def.args?.length)
         parts.push(`${def.args.length} args`);
     const envCount = Object.keys(def.env ?? {}).length;
     if (envCount > 0)
         parts.push(`${envCount} env ${envCount === 1 ? "entry" : "entries"}`);
+    const headerCount = Object.keys(def.headers ?? {}).length;
+    if (headerCount > 0)
+        parts.push(`${headerCount} ${headerCount === 1 ? "header" : "headers"}`);
     return `${name} (${parts.join(", ")})`;
 }
 /**
@@ -102,18 +105,18 @@ function resolveLeaf(raw, env, where) {
  * Validate + resolve one declaration into the shape herdctl's `McpServerSchema`
  * carries, or explain why it cannot be.
  *
- * The rejections are the interesting part, and each is a thing step 5 discovered
- * the engine strips silently:
+ * The one rejection left that is about the engine rather than about the file is
+ * **an unknown key** — the only defence against `arg:`/`envs:`/`commands:`, which
+ * would otherwise yield a server that starts with the wrong argv.
  *
- * - **`headers`** — there is no field for them, so a bearer-authenticated server
- *   would arrive unauthenticated AND miss its stored OAuth token, which is keyed
- *   on a hash that includes the headers. Step 5 passes such a host server with a
- *   warning; a hand-written declaration gets an error instead, because the user
- *   typed the header and can act on being told it does nothing.
- * - **`type: sse`** — every `url` is mapped to `type: "http"` downstream, so an
- *   sse server is silently downgraded, with the same OAuth-key consequence.
- * - **an unknown key** — the only defence against `arg:`/`envs:`/`commands:`,
- *   which would otherwise yield a server that starts with the wrong argv.
+ * `headers` and `type: sse` were rejections too until herdctl 5.32.0, because
+ * the schema had no field for either: a bearer-authenticated server arrived
+ * unauthenticated and missed its stored OAuth token (keyed on a hash that
+ * includes the headers and the type), and an `sse` url was silently connected to
+ * as HTTP. Both are now carried verbatim, so both are accepted — `headers`
+ * through the same `env:VAR` resolution as `env`, and `type` checked only for
+ * agreeing with the declaration (`stdio` for a `command`, `http`/`sse` for a
+ * `url`).
  */
 function narrowDeclaration(name, raw, env) {
     const where = `mcpServers.${name}`;
@@ -135,16 +138,10 @@ function narrowDeclaration(name, raw, env) {
         return fail(`${where}: is not a mapping`);
     const unknown = Object.keys(raw).filter((k) => !KNOWN_KEYS.has(k));
     if (unknown.length > 0) {
-        return fail(`${where}: unrecognised key(s) ${unknown.join(", ")} (supported: command, args, env, url) ` +
+        return fail(`${where}: unrecognised key(s) ${unknown.join(", ")} ` +
+            `(supported: command, args, env, url, type, headers) ` +
             `— a mistyped key would otherwise be dropped without a trace`);
     }
-    if (raw.headers !== undefined) {
-        const keys = isRecord(raw.headers) ? Object.keys(raw.headers) : [];
-        return fail(`${where}: \`headers\`${keys.length > 0 ? ` (${keys.join(", ")})` : ""} cannot be ` +
-            `carried — the engine's MCP schema has no field for them, so the server would arrive ` +
-            `unauthenticated and its stored OAuth token (keyed on a hash that includes the headers) ` +
-            `would not be found either`);
-    }
     const hasCommand = typeof raw.command === "string" && raw.command.trim().length > 0;
     const hasUrl = typeof raw.url === "string" && raw.url.trim().length > 0;
     if (hasCommand && hasUrl) {
@@ -153,20 +150,21 @@ function narrowDeclaration(name, raw, env) {
     if (!hasCommand && !hasUrl) {
         return fail(`${where}: declares neither a \`command\` nor a \`url\`, so there is nothing to start`);
     }
+    const server = {};
     if (raw.type !== undefined) {
         const type = String(raw.type).trim().toLowerCase();
-        if (type === "sse") {
-            return fail(`${where}: \`type: sse\` cannot be carried — every \`url\` server is connected to as ` +
-                `streamable HTTP downstream, so an sse server would be silently downgraded (and its ` +
-                `stored OAuth token, keyed on a hash that includes the type, not found). Declare it ` +
-                `as \`http\` if the server supports it`);
-        }
-        const expected = hasUrl ? "http" : "stdio";
-        if (type !== expected) {
-            return fail(`${where}: \`type: ${type}\` disagrees with the declaration (expected ${expected})`);
+        // `sse` joined `http` here in herdctl 5.32.0; an explicit type now wins over
+        // the bare-`url` ⇒ `http` inference rather than being stripped on the way
+        // down. It still has to agree with the rest of the declaration, because a
+        // `type` that disagrees is a typo and starting the wrong transport is a
+        // confusing failure rather than a loud one.
+        const expected = hasUrl ? ["http", "sse"] : ["stdio"];
+        if (!expected.includes(type)) {
+            return fail(`${where}: \`type: ${type}\` disagrees with the declaration ` +
+                `(expected ${expected.join(" or ")})`);
         }
+        server.type = type;
     }
-    const server = {};
     if (hasCommand) {
         const res = resolveLeaf(raw.command.trim(), env, `${where}.command`);
         if (!res.ok)
@@ -178,9 +176,9 @@ function narrowDeclaration(name, raw, env) {
         if (!res.ok)
             return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
         server.url = res.value;
-        // A key in the query string is the usual way a remote MCP endpoint is
-        // authenticated now that `headers` cannot be carried, and this file is
-        // git-tracked. Say so once; never echo the query itself.
+        // A key in the query string is one of the two ways a remote MCP endpoint is
+        // authenticated (the other, `headers`, is carryable again since #700), and
+        // this file is git-tracked. Say so once; never echo the query itself.
         if (!raw.url.startsWith(ENV_REF_PREFIX)) {
             let parsed;
             try {
@@ -231,6 +229,34 @@ function narrowDeclaration(name, raw, env) {
         if (Object.keys(resolved).length > 0)
             server.env = resolved;
     }
+    if (raw.headers !== undefined) {
+        if (!hasUrl) {
+            return fail(`${where}.headers: only a \`url\` server can carry headers`);
+        }
+        if (!isRecord(raw.headers)) {
+            return fail(`${where}.headers: must be a mapping of header name to value`);
+        }
+        const resolved = {};
+        for (const [key, value] of Object.entries(raw.headers)) {
+            if (typeof value !== "string") {
+                return fail(`${where}.headers.${key}: must be a string`);
+            }
+            const res = resolveLeaf(value, env, `${where}.headers.${key}`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            resolved[key] = res.value;
+            // Same heuristic as `env`, one rule to learn — and `Authorization` is the
+            // usual reason a header is declared at all, so this fires on the common
+            // case rather than the exotic one.
+            if (!value.startsWith(ENV_REF_PREFIX) && SECRET_ISH_KEY_RE.test(key)) {
+                warnings.push(`${where}.headers.${key}: looks like a credential and is written into the config file ` +
+                    `itself, which is git-tracked — prefer \`${key}: ${ENV_REF_PREFIX}VAR_NAME\` and set ` +
+                    `the value in the environment`);
+            }
+        }
+        if (Object.keys(resolved).length > 0)
+            server.headers = resolved;
+    }
     return { server, errors, warnings };
 }
 /**
@@ -265,6 +291,62 @@ export function resolveDeclaredMcpServers(file, env) {
     }
     return { servers, errors, warnings };
 }
+/**
+ * The one way a declared credential leaves paddock, said out loud.
+ *
+ * Everything else in this module is about keeping a resolved value out of the
+ * places paddock controls — the log, an error, the Settings API. It does that
+ * completely, and it is still not the whole story, because of what herdctl does
+ * with the record afterwards:
+ *
+ * ```js
+ * // @herdctl/core, runner/runtime/cli-runtime.js
+ * const mcpServers = transformMcpServers(options.agent.mcp_servers);
+ * const mcpConfig = JSON.stringify({ mcpServers });
+ * args.push("--mcp-config", mcpConfig);      // ← env values and all
+ * ```
+ *
+ * A process ARGUMENT is not private on Linux: `/proc/<pid>/cmdline` is
+ * world-readable by default (no `hidepid`), and `ps` prints it. So on the CLI
+ * runtime every declared server's `env` — and, since #700 made the field
+ * carryable, its `headers` — is legible to any local user for the lifetime of
+ * each `claude` invocation. Observed, not
+ * inferred: `test/integration/declared-mcp-argv.test.ts` drives a real turn and
+ * reads the token back out of the spawned process's argv.
+ *
+ * The SDK runtime does NOT do this. It hands the same record to the SDK
+ * in-process, and the stdio server it spawns receives the value in its
+ * environment, where `/proc/<pid>/environ` is owner-only — which is exactly what
+ * Claude Code itself does, so it is not a regression to fix here.
+ *
+ * Which runtime runs is `driveMode`: `session` (the default) is the SDK,
+ * `batch` is the CLI. Hence a WARNING on an instance that is on `batch`, and an
+ * informational note otherwise — because a single project can pin `driveMode:
+ * batch` for itself and bring the exposure back with it.
+ *
+ * Paddock cannot close this from here: the fix is upstream (the Claude CLI's
+ * `--mcp-config` also accepts a file path, which is not readable from another
+ * process's argv). Refusing to attach the server instead would break the feature
+ * for the deployments most likely to need it, so what this does is refuse to be
+ * silent — the same posture step 5 takes towards the fields the engine's schema
+ * cannot carry.
+ */
+function argvExposure(names, driveMode) {
+    const batch = driveMode === "batch";
+    return {
+        level: batch ? "warn" : "info",
+        message: `${names.join(", ")} ${names.length === 1 ? "declares" : "declare"} \`env\` values or ` +
+            `\`headers\`, and ` +
+            `under \`driveMode: batch\` the engine passes the whole server definition to \`claude\` ` +
+            `as a \`--mcp-config\` COMMAND-LINE argument — where any local process can read it via ` +
+            `/proc/<pid>/cmdline. ` +
+            (batch
+                ? `This instance is on \`driveMode: batch\`, so that applies to every turn. Prefer ` +
+                    `\`driveMode: session\` (the default) for a server that holds a credential.`
+                : `This instance is on \`driveMode: session\`, which passes them in-process instead — ` +
+                    `but a project that pins \`driveMode: batch\` brings the exposure back.`),
+    };
+}
 /**
  * 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
@@ -294,6 +376,18 @@ export function declaredMcpNotices(opts) {
                 `~/.claude.json (\`claude.mcpServers: host\`); this instance's own declaration wins.`,
         });
     }
+    // `headers` joined `env` here in #700: herdctl 5.32.0 carries them, so an
+    // `Authorization` bearer now rides in the same `--mcp-config` argv element that
+    // #702 found an `env` token in — and a bearer is the likelier long-lived
+    // credential of the two. A server declared with headers and no env would
+    // otherwise be the one case this warning missed.
+    const exposed = names.filter((n) => Object.keys(opts.servers[n].env ?? {}).length > 0 ||
+        Object.keys(opts.servers[n].headers ?? {}).length > 0);
+    if (exposed.length > 0 && opts.driveMode !== undefined) {
+        // The one place a declared credential escapes paddock, and it escapes
+        // downstream of every rule this module enforces — see {@link argvExposure}.
+        notices.push(argvExposure(exposed, opts.driveMode));
+    }
     if (opts.browserMcp && names.includes("playwright")) {
         notices.push({
             level: "warn",

package/packages/server/dist/project-paths.d.ts

@@ -66,11 +66,79 @@ export declare function isValidRepoUrl(url: string): boolean;
  */
 export declare function repoCheckoutName(repo: string): string;
 /**
- * Resolve a project's working directory (keeper cwd) from its metadata dir + repo
- * URL: the nested checkout for a repo-backed project, else the metadata dir
- * itself for a notebook project (issue #187).
+ * Whether `child` is `parent` itself or lives underneath it. Both are resolved
+ * first, so this compares real path strings rather than the caller's spelling
+ * (it does NOT follow symlinks — callers that care resolve them beforehand).
+ *
+ * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
+ * `/data/projects-old` a child of `/data/projects`.
+ */
+export declare function isPathInside(child: string, parent: string): boolean;
+/**
+ * Resolve a project's working directory (keeper cwd) from its metadata dir plus
+ * whichever backing field is set:
+ *
+ *  - **`linkedPath`** (issue #206) — the cwd IS that directory, returned
+ *    verbatim, used in place with no copy. Applies on BOTH sides of the
+ *    managed/unmanaged axis: an unmanaged project links a code checkout you
+ *    already have, a managed one nominates where its notes should live.
+ *  - **`repo`** (issue #187) — the nested checkout Paddock cloned.
+ *  - **neither** — the metadata dir itself.
+ *
+ * `linkedPath` WINS over `repo`, which is why the two are not mutually exclusive:
+ * `repo` alongside a path is an ACQUISITION hint (clone here if the path is
+ * missing) plus a remote-match for adoption (`adoptable.ts`, #659) and a re-clone
+ * hint for disaster recovery. It never moves the cwd off the nominated path.
+ */
+export declare function workingDirFor(dir: string, repo?: string, linkedPath?: string): string;
+/** The subset of `project.yaml` that decides a project's shape. */
+export interface ProjectBacking {
+    managed?: boolean;
+    repo?: string;
+    path?: string;
+}
+/**
+ * Whether Paddock looks after this project's own files — the real axis, and the
+ * one that replaced the overloaded `repoBacked` boolean (issue #206).
+ *
+ * **managed** — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md`
+ * here. This is what "notebook" used to mean.
+ * **unmanaged** — the content is code that you or your agents source-control
+ * OUTSIDE Paddock. Paddock never writes project files into it.
+ *
+ * Whether a git repo sits behind it is an INDEPENDENT question (just which of
+ * `path`/`repo` are set), not a type. See `docs/DESIGN-backing-store.md` §2 goal
+ * 4: the base store is a plain directory and git is an optional layer.
+ *
+ * ## The default is derived, never constant
+ *
+ * `managed ?? !(repo || path)` — an absent key means "whatever this project's
+ * backing implies". That is load-bearing for the upgrade path: every existing
+ * `project.yaml` predates the key, and if absent meant `true`, every existing
+ * repo-backed project would flip to managed on upgrade and the sweeper would
+ * start writing `CLAUDE.md` into somebody's checkout. New projects write the key
+ * explicitly, so the derivation only ever has to serve legacy files.
+ */
+export declare function isManaged(backing: ProjectBacking): boolean;
+/**
+ * Where a project's CURATED CONTENT lives — `OVERVIEW.md`, `CHANGELOG.md` and
+ * `CLAUDE.md`, the three files the sweeper writes.
+ *
+ * Content follows the working directory; application state does not. So:
+ *
+ *  - **managed** ⇒ the working dir. For a classic notebook that IS the metadata
+ *    dir (unchanged). For a managed project with an external `path`, the curated
+ *    files live out there with the content — an accepted consequence being that
+ *    they then do NOT live in the Paddock data dir.
+ *  - **unmanaged** ⇒ the metadata dir, always. The working dir is somebody
+ *    else's tree and Paddock does not write project files into it; `OVERVIEW.md`
+ *    and `CHANGELOG.md` are still curated, just sidecarred (issue #187), and
+ *    `CLAUDE.md` is not curated at all (the checkout owns its own).
+ *
+ * `project.yaml` and `.chats/` are NOT content and never move — see
+ * {@link import("./projects.js").ProjectStore.dirFor}.
  */
-export declare function workingDirFor(dir: string, repo?: string): string;
+export declare function contentDirFor(dir: string, backing: ProjectBacking): string;
 export declare class ProjectError extends Error {
     readonly code: "not_found" | "exists" | "invalid" | "not_directory";
     constructor(message: string, code: "not_found" | "exists" | "invalid" | "not_directory");

package/packages/server/dist/project-paths.js

@@ -74,13 +74,85 @@ export function repoCheckoutName(repo) {
     return safe || "repo";
 }
 /**
- * Resolve a project's working directory (keeper cwd) from its metadata dir + repo
- * URL: the nested checkout for a repo-backed project, else the metadata dir
- * itself for a notebook project (issue #187).
+ * Whether `child` is `parent` itself or lives underneath it. Both are resolved
+ * first, so this compares real path strings rather than the caller's spelling
+ * (it does NOT follow symlinks — callers that care resolve them beforehand).
+ *
+ * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
+ * `/data/projects-old` a child of `/data/projects`.
+ */
+export function isPathInside(child, parent) {
+    const c = path.resolve(child);
+    const p = path.resolve(parent);
+    return c === p || c.startsWith(p + path.sep);
+}
+/**
+ * Resolve a project's working directory (keeper cwd) from its metadata dir plus
+ * whichever backing field is set:
+ *
+ *  - **`linkedPath`** (issue #206) — the cwd IS that directory, returned
+ *    verbatim, used in place with no copy. Applies on BOTH sides of the
+ *    managed/unmanaged axis: an unmanaged project links a code checkout you
+ *    already have, a managed one nominates where its notes should live.
+ *  - **`repo`** (issue #187) — the nested checkout Paddock cloned.
+ *  - **neither** — the metadata dir itself.
+ *
+ * `linkedPath` WINS over `repo`, which is why the two are not mutually exclusive:
+ * `repo` alongside a path is an ACQUISITION hint (clone here if the path is
+ * missing) plus a remote-match for adoption (`adoptable.ts`, #659) and a re-clone
+ * hint for disaster recovery. It never moves the cwd off the nominated path.
  */
-export function workingDirFor(dir, repo) {
+export function workingDirFor(dir, repo, linkedPath) {
+    if (linkedPath)
+        return linkedPath;
     return repo ? path.join(dir, repoCheckoutName(repo)) : dir;
 }
+/**
+ * Whether Paddock looks after this project's own files — the real axis, and the
+ * one that replaced the overloaded `repoBacked` boolean (issue #206).
+ *
+ * **managed** — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md`
+ * here. This is what "notebook" used to mean.
+ * **unmanaged** — the content is code that you or your agents source-control
+ * OUTSIDE Paddock. Paddock never writes project files into it.
+ *
+ * Whether a git repo sits behind it is an INDEPENDENT question (just which of
+ * `path`/`repo` are set), not a type. See `docs/DESIGN-backing-store.md` §2 goal
+ * 4: the base store is a plain directory and git is an optional layer.
+ *
+ * ## The default is derived, never constant
+ *
+ * `managed ?? !(repo || path)` — an absent key means "whatever this project's
+ * backing implies". That is load-bearing for the upgrade path: every existing
+ * `project.yaml` predates the key, and if absent meant `true`, every existing
+ * repo-backed project would flip to managed on upgrade and the sweeper would
+ * start writing `CLAUDE.md` into somebody's checkout. New projects write the key
+ * explicitly, so the derivation only ever has to serve legacy files.
+ */
+export function isManaged(backing) {
+    return backing.managed ?? !(backing.repo || backing.path);
+}
+/**
+ * Where a project's CURATED CONTENT lives — `OVERVIEW.md`, `CHANGELOG.md` and
+ * `CLAUDE.md`, the three files the sweeper writes.
+ *
+ * Content follows the working directory; application state does not. So:
+ *
+ *  - **managed** ⇒ the working dir. For a classic notebook that IS the metadata
+ *    dir (unchanged). For a managed project with an external `path`, the curated
+ *    files live out there with the content — an accepted consequence being that
+ *    they then do NOT live in the Paddock data dir.
+ *  - **unmanaged** ⇒ the metadata dir, always. The working dir is somebody
+ *    else's tree and Paddock does not write project files into it; `OVERVIEW.md`
+ *    and `CHANGELOG.md` are still curated, just sidecarred (issue #187), and
+ *    `CLAUDE.md` is not curated at all (the checkout owns its own).
+ *
+ * `project.yaml` and `.chats/` are NOT content and never move — see
+ * {@link import("./projects.js").ProjectStore.dirFor}.
+ */
+export function contentDirFor(dir, backing) {
+    return isManaged(backing) ? workingDirFor(dir, backing.repo, backing.path) : dir;
+}
 export class ProjectError extends Error {
     code;
     constructor(message, code) {