@edspencer/paddock 0.62.0 → 0.64.0

package/packages/server/dist/claude-plugins.js

@@ -0,0 +1,394 @@
+/**
+ * Host Claude Code **plugins**, handed to each keeper as `agent.plugins` (#700).
+ *
+ * The half of MCP inheritance that `claude-mcp.ts` structurally could not reach.
+ * A plugin bundles commands, agents, skills, hooks and — the reported symptom —
+ * MCP servers, and none of it is declared in `~/.claude.json`, so reading that
+ * file finds nothing however carefully it is read.
+ *
+ * ## Why the symlink was not enough
+ *
+ * `plugins/` IS bridged into paddock's home (under `claude.instructions: host`,
+ * see `claude-home.ts`) and the SDK really does auto-discover plugins under
+ * `join(CLAUDE_CONFIG_DIR, "plugins")` — two facts that together made this look
+ * fixed for months. It is not, because discovery of an *installed* plugin is
+ * driven by the `enabledPlugins` key, and `enabledPlugins` lives in the **user**
+ * settings source, which herdctl does not load: every agent with a working
+ * directory is invoked with `setting_sources: ["project"]`. So the plugin is
+ * found and then never enabled, silently.
+ *
+ * herdctl 5.32.0 (herdctl#446, closing herdctl#444) adds the channel this needs:
+ * an optional `plugins` array on the agent config, translated to the SDK's own
+ * `plugins` option and to `--plugin-dir` on the CLI runtime. A plugin passed that
+ * way is a *session* plugin, and — read out of the CLI bundle rather than
+ * assumed — a session plugin's enablement is
+ * `enabledPlugins[`${name}@inline`] ?? manifest.defaultEnabled !== false`, i.e.
+ * **enabled by default**, with no settings-source grant required. That is why the
+ * passthrough works where the symlink did not, and why herdctl#446 was right to
+ * refuse to widen `setting_sources` instead.
+ *
+ * ## Which lever gates this, which is NOT the one #700 assumes
+ *
+ * #700 (and the brief written from it) scope plugin enumeration to
+ * `claude.mcpServers: host`. That is half right, and shipping it that way would
+ * have punched a hole through a different lever:
+ *
+ * - `plugins/` is bridged by **`claude.instructions`**, alongside `CLAUDE.md`,
+ *   `agents/` and `commands/` — because most of a plugin IS instructions. Under
+ *   `instructions: own` paddock withdraws that symlink and prints a notice saying
+ *   the host's plugins are not loaded. Passing them anyway because a *different*
+ *   key says `host` would contradict a notice paddock itself emits.
+ * - the MCP servers inside a plugin are what `claude.mcpServers` is about.
+ *
+ * So both levers apply, to the two halves of a plugin, and the SDK has exactly
+ * the flag needed to split them: `skipMcpDiscovery` loads a plugin's
+ * skills/hooks/agents/commands but does NOT read its `.mcp.json` or manifest
+ * `mcpServers`. Hence {@link enumerateHostPlugins}:
+ *
+ * | `instructions` | `mcpServers` | result |
+ * |---|---|---|
+ * | `host` | `host` | plugins passed whole |
+ * | `host` | `own`  | plugins passed with `skipMcpDiscovery: true` |
+ * | `own`  | *any*  | no plugins, and a notice saying which key turns them on |
+ *
+ * ## The allowlist, which is where this gets uncomfortable
+ *
+ * Both runtimes auto-deny any tool missing from an explicit `allowed_tools`, with
+ * no prompt and nothing in the logs — the trap `claude-mcp.ts` documents at
+ * length. A plugin-provided MCP server needs the same widening, so paddock has to
+ * know its tool prefix *before* the plugin has ever run.
+ *
+ * It is knowable, from the CLI bundle: a plugin's servers are registered under
+ * `` `plugin:${pluginName}:${serverName}` ``, and a server name is normalised
+ * with `[^a-zA-Z0-9_-] → _` before it becomes a tool prefix. So the pattern is
+ * `mcp__plugin_<plugin>_<server>__*` — matching the SDK's own documented example,
+ * `mcp__plugin_documents_docs__doc_export`. {@link pluginMcpToolPattern} is that
+ * one line, and {@link readPluginServerNames} recovers `<server>` by reading the
+ * two places a plugin declares servers statically: `<dir>/.mcp.json` and an
+ * inline `mcpServers` object in `<dir>/.claude-plugin/plugin.json`.
+ *
+ * What it CANNOT recover is a manifest whose `mcpServers` is a string or an array
+ * of strings — a pointer to another file, or to an MCPB source the CLI downloads.
+ * Resolving a same-directory JSON pointer is easy and is done; anything else is
+ * recorded as a caveat and warned about at boot, naming the plugin, because the
+ * failure it produces otherwise is the silent one: the plugin loads, its server
+ * connects, and every tool call is denied with no log line. Better a warning that
+ * says "add `mcp__plugin_x_y__*` yourself" than a mystery.
+ *
+ * ## What is read, and what is not verified
+ *
+ * Enumeration is from `<pluginRoot>/installed_plugins.json`, the CLI's own
+ * registry of installs (v2: `{plugins: {"<name>@<marketplace>": [{installPath,
+ * scope, …}]}}`; v1 keyed the same ids to a single record, whose path was derived
+ * as `<pluginRoot>/cache/<marketplace>/<name>/<version>`). Both are read. The
+ * host's `settings.json` `enabledPlugins` is consulted only to VETO — an id set
+ * to `false` is skipped — because a session plugin's own default is "enabled",
+ * so honouring the veto is the only thing that can respect a host's `/plugin
+ * disable`.
+ *
+ * None of this was validated against a machine with plugins installed: this box
+ * is Linux with an empty plugin root, and no test here proves a plugin *loads*.
+ * Every path, file name and naming rule above comes from reading the bundled CLI
+ * (`node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude`), and the tests
+ * assert what config paddock produces from a planted directory tree, which is a
+ * strictly weaker claim. A `marketplace`-installed plugin loading via
+ * `type: "local"` remains unverified end-to-end and needs a real host.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** Nothing inherited: `instructions: own`, and where tests start. */
+export const EMPTY_HOST_PLUGINS = Object.freeze({
+    plugins: [],
+    toolPatterns: [],
+    caveats: [],
+});
+/** The plugin root, `join(CLAUDE_CONFIG_DIR, "plugins")` in the CLI's terms. */
+export function hostPluginRoot(legacyClaudeHome) {
+    return path.join(legacyClaudeHome, "plugins");
+}
+/** The CLI's own registry of what is installed, under {@link hostPluginRoot}. */
+export const INSTALLED_PLUGINS_FILE = "installed_plugins.json";
+/** A plugin's manifest, relative to its directory. */
+export const PLUGIN_MANIFEST = path.join(".claude-plugin", "plugin.json");
+/** A plugin's out-of-manifest MCP declaration, relative to its directory. */
+export const PLUGIN_MCP_FILE = ".mcp.json";
+/**
+ * The CLI's server-name normalisation: `[^a-zA-Z0-9_-] → _`, applied to the whole
+ * `plugin:<plugin>:<server>` name before it becomes a `mcp__…__` prefix. Applied
+ * to the joined string, not to the parts, so a `.` in a plugin name normalises
+ * the same way the separators do.
+ */
+function normalizeServerName(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+ * The allowlist pattern for one server of one plugin.
+ *
+ * Deliberately not `mcpToolPattern` from `claude-mcp.ts`: the name a plugin's
+ * server is registered under is not the name it is declared under, and that
+ * derivation is the whole content of this function.
+ */
+export function pluginMcpToolPattern(pluginName, serverName) {
+    return `mcp__${normalizeServerName(`plugin:${pluginName}:${serverName}`)}__*`;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server names one `.mcp.json`-shaped document declares.
+ *
+ * Claude Code accepts both `{mcpServers: {…}}` and a bare map at the top level,
+ * so both are read — the CLI does `parsed.mcpServers || parsed`.
+ */
+function serverNamesOf(doc) {
+    if (!isRecord(doc))
+        return [];
+    const servers = isRecord(doc.mcpServers) ? doc.mcpServers : doc;
+    return Object.keys(servers).filter((k) => isRecord(servers[k]));
+}
+/**
+ * Read one plugin directory's declared MCP server names.
+ *
+ * Mirrors the CLI's own discovery order — `<dir>/.mcp.json` first, then whatever
+ * `manifest.mcpServers` adds — with the one deliberate gap described in the
+ * module doc: a manifest that points at an MCPB source (or at any path outside
+ * its own directory) is recorded in {@link PluginServerNames.unresolved} rather
+ * than fetched. Paddock does not download anything to build an allowlist.
+ */
+export async function readPluginServerNames(dir) {
+    const manifest = await readJson(path.join(dir, PLUGIN_MANIFEST));
+    const pluginName = isRecord(manifest) && typeof manifest.name === "string" && manifest.name.trim() !== ""
+        ? manifest.name.trim()
+        : path.basename(dir);
+    const servers = new Set(serverNamesOf(await readJson(path.join(dir, PLUGIN_MCP_FILE))));
+    const unresolved = [];
+    const declared = isRecord(manifest) ? manifest.mcpServers : undefined;
+    // A string entry is a path relative to the plugin directory (or an MCPB
+    // source, which looks the same and is not resolvable without downloading it).
+    // Resolve it only when it stays inside the directory and parses as JSON;
+    // anything else is a gap paddock reports rather than guesses at.
+    const resolveRef = async (ref) => {
+        const target = path.resolve(dir, ref);
+        if (target !== dir && !target.startsWith(dir + path.sep)) {
+            unresolved.push(ref);
+            return;
+        }
+        const names = serverNamesOf(await readJson(target));
+        if (names.length === 0)
+            unresolved.push(ref);
+        else
+            for (const n of names)
+                servers.add(n);
+    };
+    if (typeof declared === "string")
+        await resolveRef(declared);
+    else if (Array.isArray(declared)) {
+        for (const entry of declared) {
+            if (typeof entry === "string")
+                await resolveRef(entry);
+            else
+                for (const n of serverNamesOf(entry))
+                    servers.add(n);
+        }
+    }
+    else if (isRecord(declared)) {
+        for (const n of serverNamesOf(declared))
+            servers.add(n);
+    }
+    return { pluginName, servers: [...servers], unresolved };
+}
+/**
+ * Parse `installed_plugins.json`, v1 or v2. Pure, so the whole selection is
+ * testable from a string.
+ *
+ * v2 keys each `<name>@<marketplace>` id to an ARRAY of installations (one per
+ * scope), each carrying an explicit `installPath`. v1 keyed it to a single record
+ * with no path, which the CLI derives as
+ * `<root>/cache/<marketplace>/<name>/<version>` with each segment sanitised
+ * `[^a-zA-Z0-9\-_] → -` (and the version segment additionally allowing `.`).
+ *
+ * Fails soft in every direction: this is a file paddock does not own and must
+ * never turn into a boot failure.
+ */
+export function parseInstalledPlugins(raw, root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.plugins))
+        return [];
+    const out = [];
+    for (const [id, entry] of Object.entries(parsed.plugins)) {
+        if (Array.isArray(entry)) {
+            for (const install of entry) {
+                if (isRecord(install) && typeof install.installPath === "string" && install.installPath) {
+                    out.push({ id, installPath: install.installPath });
+                }
+            }
+        }
+        else if (isRecord(entry)) {
+            const derived = legacyInstallPath(root, id, entry.version);
+            if (derived)
+                out.push({ id, installPath: derived });
+        }
+    }
+    return out;
+}
+/** The v1 path derivation, kept beside its only caller. */
+function legacyInstallPath(root, id, version) {
+    if (typeof version !== "string" || version === "")
+        return undefined;
+    const at = id.lastIndexOf("@");
+    const name = at > 0 ? id.slice(0, at) : id;
+    const marketplace = at > 0 ? id.slice(at + 1) : "unknown";
+    const seg = (s) => s.replace(/[^a-zA-Z0-9\-_]/g, "-");
+    let ver = version.replace(/[^a-zA-Z0-9\-_.]/g, "-");
+    if (ver === "." || ver === "..")
+        ver = "-";
+    return path.join(root, "cache", seg(marketplace || "unknown"), seg(name), ver);
+}
+/** Ids the host has explicitly turned off, from its `settings.json`. */
+function disabledIds(settings) {
+    const out = new Set();
+    if (!isRecord(settings) || !isRecord(settings.enabledPlugins))
+        return out;
+    for (const [id, value] of Object.entries(settings.enabledPlugins)) {
+        // Anything that is not an explicit `false` counts as enabled: the key also
+        // takes an extended object form carrying a version constraint, and a version
+        // constraint is not a disable.
+        if (value === false)
+            out.add(id.toLowerCase());
+    }
+    return out;
+}
+/**
+ * Enumerate the host's installed plugin directories. Pure apart from reading the
+ * plugin tree, and takes the two files' contents rather than paths so the whole
+ * selection is testable without a home directory.
+ */
+export async function enumerateHostPlugins(opts) {
+    const caveats = [];
+    if (opts.installed === undefined)
+        return { plugins: [], toolPatterns: [], caveats };
+    const disabled = disabledIds(opts.settings);
+    const plugins = [];
+    const toolPatterns = new Set();
+    // One plugin can be recorded under several scopes, and two ids can in principle
+    // resolve to one directory. `--plugin-dir` the same path twice and the CLI loads
+    // it twice under one name, so collapse them here.
+    const seen = new Set();
+    for (const install of parseInstalledPlugins(opts.installed, opts.root)) {
+        if (disabled.has(install.id.toLowerCase()))
+            continue;
+        if (seen.has(install.installPath))
+            continue;
+        seen.add(install.installPath);
+        // A registry entry whose directory is gone is the normal aftermath of a
+        // hand-deleted plugin. The SDK would log "Plugin path does not exist" and
+        // carry on, but saying it here is what makes an empty `plugins` explicable.
+        try {
+            if (!(await fs.stat(install.installPath)).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            caveats.push({
+                name: install.id,
+                kind: "dropped",
+                reason: `its recorded install directory (${install.installPath}) is missing`,
+            });
+            continue;
+        }
+        plugins.push(opts.mcp
+            ? { type: "local", path: install.installPath }
+            : { type: "local", path: install.installPath, skipMcpDiscovery: true });
+        if (!opts.mcp)
+            continue;
+        const { pluginName, servers, unresolved } = await readPluginServerNames(install.installPath);
+        for (const server of servers)
+            toolPatterns.add(pluginMcpToolPattern(pluginName, server));
+        if (unresolved.length > 0) {
+            caveats.push({
+                name: install.id,
+                kind: "degraded",
+                reason: `its manifest points \`mcpServers\` at ${unresolved.join(", ")} rather than declaring ` +
+                    `them inline, so paddock cannot name its servers — the plugin is attached, but any ` +
+                    `tool it provides will be auto-denied with no prompt until you add the matching ` +
+                    `\`mcp__plugin_${normalizeServerName(pluginName)}_<server>__*\` to the keeper's ` +
+                    `allowed tools`,
+            });
+        }
+    }
+    return { plugins, toolPatterns: [...toolPatterns], caveats };
+}
+/**
+ * Read the host's plugin registry — once, at boot — and say what came of it.
+ *
+ * Under `instructions: own` nothing is opened at all, for the same reason
+ * `loadHostMcpSource` does not open `.claude.json` under `mcpServers: own`: "own
+ * everywhere means nothing outside the data dir is read" is a guarantee that has
+ * to be true in the place someone would check it.
+ */
+export async function loadHostPlugins(cfg) {
+    const notices = [];
+    const mcp = cfg.claude.mcpServers === "host";
+    if (cfg.claude.instructions !== "host") {
+        if (mcp) {
+            // The one combination that silently does less than a user asked for, so it
+            // is the one that gets a line naming the other key.
+            notices.push({
+                level: "info",
+                message: "`claude.mcpServers: host` does not reach MCP servers provided by a Claude Code " +
+                    "plugin: a plugin is mostly commands, agents and skills, so loading one is a " +
+                    "`claude.instructions` decision. Set `claude.instructions: host` (or " +
+                    "PADDOCK_CLAUDE_INSTRUCTIONS=host) as well to inherit your plugins.",
+            });
+        }
+        return { source: EMPTY_HOST_PLUGINS, notices };
+    }
+    const root = hostPluginRoot(cfg.legacyClaudeHome);
+    const file = path.join(root, INSTALLED_PLUGINS_FILE);
+    let installed;
+    try {
+        installed = await fs.readFile(file, "utf8");
+    }
+    catch {
+        // Not a warning: no plugins installed is the overwhelmingly common case, and
+        // this file does not exist until the first `claude plugin install`.
+        return { source: EMPTY_HOST_PLUGINS, notices };
+    }
+    const settings = await readJson(path.join(cfg.legacyClaudeHome, "settings.json"));
+    const source = await enumerateHostPlugins({ root, installed, settings, mcp });
+    if (source.plugins.length > 0) {
+        notices.push({
+            level: "info",
+            message: `Claude plugins: host (\`claude.instructions: host\`) — ${source.plugins.length} ` +
+                `installed plugin${source.plugins.length === 1 ? "" : "s"} attached to every keeper` +
+                (mcp
+                    ? source.toolPatterns.length > 0
+                        ? `, including their MCP servers (${source.toolPatterns.join(", ")})`
+                        : ", including their MCP servers (none declared)"
+                    : ". Their MCP servers are NOT attached (`claude.mcpServers: own`)") +
+                ".",
+        });
+    }
+    for (const caveat of source.caveats) {
+        notices.push({
+            level: "warn",
+            message: caveat.kind === "dropped"
+                ? `Claude plugin "${caveat.name}" was NOT attached: ${caveat.reason}.`
+                : `Claude plugin "${caveat.name}" is attached but incomplete: ${caveat.reason}.`,
+        });
+    }
+    return { source, notices };
+}

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

@@ -53,4 +53,4 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  * flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";

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

@@ -162,6 +162,7 @@ Sharing your Claude Code state
       credentials: host   # own | host, default host
       instructions: host  # own | host, default own
       hooks: host         # own | host, default own
+      mcpServers: host    # own | host, default own
 
   transcripts: host makes a chat and a \`claude --resume\` in the same directory
   the same file, live in both directions; deleting such a chat in Paddock
@@ -179,6 +180,14 @@ Sharing your Claude Code state
   apply either way: under hooks: own Paddock writes its own settings.json
   carrying them with hooks dropped, regenerated at startup.
 
+  mcpServers: host attaches the MCP servers declared in your ~/.claude.json —
+  the top-level ones, plus a project's own when its directory matches. To give
+  this instance a server your machine doesn't have, declare it instead in a
+  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a
+  string goes so tokens stay out of it. That keeps a token out of the file, not
+  out of \`ps\`: leave driveMode on its default (session) for a server holding
+  one, since batch passes the definition to claude as a command-line argument.
+
 Your data
   Everything lives in one directory — ~/.paddock unless you pass --data-dir.
   Projects, chat transcripts and settings all persist there between runs. Move

package/packages/server/dist/cli/import-chats.js

@@ -126,7 +126,7 @@ async function main() {
     if (args.dataDir !== undefined)
         process.env.PADDOCK_DATA_DIR = args.dataDir;
     const cfg = loadPaddockConfig();
-    const projects = new ProjectStore(cfg.projectsRoot);
+    const projects = new ProjectStore(cfg.projectsRoot, cfg.dataDir);
     const herdctl = new HerdctlService(cfg);
     const project = await projects.get(args.project);
     // Register the keepers so the agent this imports INTO exists and its `.chats/`

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

@@ -46,6 +46,8 @@ export declare class GitService {
     private readonly author;
     /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
     private repoFlag;
+    /** Cached per-directory repo detection, keyed by resolved path (#597 / #206). */
+    private readonly repoAt;
     /**
      * @param projectsRoot Absolute path to the projects root the service operates on.
      * @param author Commit identity used when Paddock commits on a project's behalf.
@@ -62,9 +64,36 @@ export declare class GitService {
      * Whether the backing store is a git working tree. Cached after the first
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
+     *
+     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
+     * {@link remote}, {@link push}). The PER-PROJECT surface asks
+     * {@link isRepoAt} about the project's own working directory instead — see
+     * that method for why the two had to be separated.
      */
     isRepo(): Promise<boolean>;
-    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    /**
+     * Whether `dir` is inside a git working tree, cached per directory.
+     *
+     * The per-project git surface used to gate on {@link isRepo} — "is the PROJECTS
+     * ROOT a repo?" — which was right only while every project's tree lived under
+     * that root. It stopped being right twice over (issue #597, issue #206):
+     *
+     *  - a project whose working directory is a linked checkout outside the root
+     *    would report "not a repo" whenever the root itself wasn't one, hiding the
+     *    Changes tab for the exact directory that IS a repo;
+     *  - conversely a non-repo directory inside a repo root would claim to be one.
+     *
+     * Asking about the directory the project actually works in answers both. For
+     * every pre-existing shape it returns what {@link isRepo} did, because a
+     * project dir under a repo root is itself inside that work tree.
+     *
+     * Probing rather than requiring is the house style: nothing here refuses a
+     * directory for not being a repo, it just doesn't light up the git features.
+     */
+    isRepoAt(dir: string): Promise<boolean>;
+    /** One `rev-parse`, false on any failure (missing binary, missing dir, not a repo). */
+    private probeRepo;
+    /** Force the next repo check to re-run (e.g. after `git init` at runtime). */
     resetRepoCache(): void;
     /**
      * Status for one project's subtree. Returns `{ repo: false }` when the store
@@ -120,6 +149,20 @@ export declare class GitService {
      * when the store isn't a repo.
      */
     dirtyCounts(): Promise<Record<string, number>>;
+    /**
+     * Uncommitted-file count for ONE directory's own repository.
+     *
+     * The companion to {@link dirtyCounts} for a project whose working directory
+     * lives outside `projectsRoot` (issue #206). That method answers the whole grid
+     * in a single `git status` over the store, which is why it is cheap — and also
+     * why it structurally cannot see a linked checkout: it buckets paths by their
+     * first segment relative to the store, and a directory outside it has no such
+     * segment. This one costs a subprocess, so callers use it only for the projects
+     * the cheap sweep genuinely cannot cover.
+     *
+     * Returns 0 for a directory that isn't a repo, matching "nothing to report".
+     */
+    dirtyCountAt(dir: string): Promise<number>;
     /** Push the current branch to origin (sets upstream on first push). */
     push(): Promise<{
         pushed: boolean;

package/packages/server/dist/git.js

@@ -52,6 +52,8 @@ export class GitService {
     author;
     /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
     repoFlag = null;
+    /** Cached per-directory repo detection, keyed by resolved path (#597 / #206). */
+    repoAt = new Map();
     /**
      * @param projectsRoot Absolute path to the projects root the service operates on.
      * @param author Commit identity used when Paddock commits on a project's behalf.
@@ -74,25 +76,60 @@ export class GitService {
      * Whether the backing store is a git working tree. Cached after the first
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
+     *
+     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
+     * {@link remote}, {@link push}). The PER-PROJECT surface asks
+     * {@link isRepoAt} about the project's own working directory instead — see
+     * that method for why the two had to be separated.
      */
     async isRepo() {
         if (this.repoFlag !== null)
             return this.repoFlag;
+        this.repoFlag = await this.probeRepo(this.projectsRoot);
+        return this.repoFlag;
+    }
+    /**
+     * Whether `dir` is inside a git working tree, cached per directory.
+     *
+     * The per-project git surface used to gate on {@link isRepo} — "is the PROJECTS
+     * ROOT a repo?" — which was right only while every project's tree lived under
+     * that root. It stopped being right twice over (issue #597, issue #206):
+     *
+     *  - a project whose working directory is a linked checkout outside the root
+     *    would report "not a repo" whenever the root itself wasn't one, hiding the
+     *    Changes tab for the exact directory that IS a repo;
+     *  - conversely a non-repo directory inside a repo root would claim to be one.
+     *
+     * Asking about the directory the project actually works in answers both. For
+     * every pre-existing shape it returns what {@link isRepo} did, because a
+     * project dir under a repo root is itself inside that work tree.
+     *
+     * Probing rather than requiring is the house style: nothing here refuses a
+     * directory for not being a repo, it just doesn't light up the git features.
+     */
+    async isRepoAt(dir) {
+        const key = path.resolve(dir);
+        const cached = this.repoAt.get(key);
+        if (cached !== undefined)
+            return cached;
+        const found = await this.probeRepo(key);
+        this.repoAt.set(key, found);
+        return found;
+    }
+    /** One `rev-parse`, false on any failure (missing binary, missing dir, not a repo). */
+    async probeRepo(dir) {
         try {
-            const out = await this.git(this.projectsRoot, [
-                "rev-parse",
-                "--is-inside-work-tree",
-            ]);
-            this.repoFlag = out.trim() === "true";
+            const out = await this.git(dir, ["rev-parse", "--is-inside-work-tree"]);
+            return out.trim() === "true";
         }
         catch {
-            this.repoFlag = false;
+            return false;
         }
-        return this.repoFlag;
     }
-    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    /** Force the next repo check to re-run (e.g. after `git init` at runtime). */
     resetRepoCache() {
         this.repoFlag = null;
+        this.repoAt.clear();
     }
     /**
      * Status for one project's subtree. Returns `{ repo: false }` when the store
@@ -100,7 +137,9 @@ export class GitService {
      * `projectDir`.
      */
     async projectStatus(projectDir) {
-        if (!(await this.isRepo())) {
+        // Per-DIRECTORY, not store-wide: callers pass the project's workingDir, which
+        // may be a linked checkout outside `projectsRoot` entirely (#597 / #206).
+        if (!(await this.isRepoAt(projectDir))) {
             return { repo: false, files: [], clean: true };
         }
         let branch;
@@ -188,7 +227,7 @@ export class GitService {
      * (they're listed by `projectStatus`). Returns "" when not a repo / no diff.
      */
     async projectDiff(projectDir, file) {
-        if (!(await this.isRepo()))
+        if (!(await this.isRepoAt(projectDir)))
             return "";
         const args = ["diff", "HEAD", "--", file ?? "."];
         try {
@@ -259,7 +298,7 @@ export class GitService {
      * Omitting `paths` keeps the legacy commit-the-whole-subtree behavior.
      */
     async commitProject(projectDir, message, paths) {
-        if (!(await this.isRepo()))
+        if (!(await this.isRepoAt(projectDir)))
             return { committed: false, error: "not a repo" };
         const msg = message.trim() || "Update project";
         let pathspec;
@@ -325,6 +364,35 @@ export class GitService {
             return {};
         }
     }
+    /**
+     * Uncommitted-file count for ONE directory's own repository.
+     *
+     * The companion to {@link dirtyCounts} for a project whose working directory
+     * lives outside `projectsRoot` (issue #206). That method answers the whole grid
+     * in a single `git status` over the store, which is why it is cheap — and also
+     * why it structurally cannot see a linked checkout: it buckets paths by their
+     * first segment relative to the store, and a directory outside it has no such
+     * segment. This one costs a subprocess, so callers use it only for the projects
+     * the cheap sweep genuinely cannot cover.
+     *
+     * Returns 0 for a directory that isn't a repo, matching "nothing to report".
+     */
+    async dirtyCountAt(dir) {
+        if (!(await this.isRepoAt(dir)))
+            return 0;
+        try {
+            const out = await this.git(dir, [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=all",
+            ]);
+            return parsePorcelainZ(out).length;
+        }
+        catch {
+            return 0;
+        }
+    }
     /** Push the current branch to origin (sets upstream on first push). */
     async push() {
         if (!(await this.isRepo()))