@edspencer/paddock 0.61.1 → 0.62.0

package/README.md

@@ -26,11 +26,34 @@ claude setup-token                  # Claude Max/Pro
 export ANTHROPIC_API_KEY=sk-ant-…   # or API billing
 ```
 
-If you already use Claude Code on this machine, there is nothing to do: with no token
-in the environment, Paddock runs against your own `~/.claude` and uses the login
-already there — including one held in the **macOS Keychain**, which cannot be shared
-any other way. Pass `--isolated-claude-home` to give Paddock a Claude home of its own
-instead.
+**If you already use Claude Code on this machine, there is nothing to do.** Paddock
+keeps a Claude home of its own under the data dir, but not a login of its own: it uses
+the one you already have — the macOS Keychain entry on a Mac, your
+`~/.claude/.credentials.json` elsewhere (symlinked in, never copied). Reading a login
+writes nothing, and nothing else is shared with it.
+
+To give Paddock its own instead, set `claude: { credentials: own }` in
+`<data-dir>/paddock.config.yaml`; a login is then a token in the environment as above,
+or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. Either way,
+Paddock says at startup if it can find no credentials at all.
+
+## What else Paddock does and does not take from your `~/.claude`
+
+Apart from that login: **nothing, by default.** Your `CLAUDE.md`, `agents/`,
+`commands/` and `plugins/` are not loaded, and the hooks your `settings.json` binds to
+tool use do not run. Both are one key in `<data-dir>/paddock.config.yaml`:
+
+```yaml
+claude:
+  instructions: host   # own | host, default own — CLAUDE.md, agents, commands, plugins
+  hooks: host          # own | host, default own — shell commands settings.json binds
+```
+
+`instructions: own` is worth knowing about if you have curated a `~/.claude/CLAUDE.md`:
+your Paddock agents will not see it until you set `host`. Each project's own `CLAUDE.md`
+always applies. `hooks` is off by default because inheriting someone's shell commands is
+not a thing to discover after the fact; the rest of your `settings.json` — permissions,
+model, statusline — applies either way.
 
 ## Open your own project
 
@@ -49,13 +72,13 @@ The flag is the consent, so here is everything it does:
 - creates **`.paddock/`** for the workspace's state and **`.chats/`** for transcripts
 - appends those two entries to **`.gitignore`**
 
-**Nothing is written into your `~/.claude`, ever** — no file, no symlink, in any
-configuration. Sessions found there are *offered* for import: nothing is moved, copied
-or linked until you confirm, and your terminal `claude` keeps working exactly as
-before. What varies is which Claude home Paddock runs against, and it says which on
-startup — with a token in the environment (or `--isolated-claude-home`) it uses its own
-under `.paddock/` and relocates transcripts into `.chats/`; without one it uses your
-`~/.claude`, and transcripts stay there instead.
+**Nothing is written into your `~/.claude`** — no file, no symlink. Paddock uses a
+Claude home of its own under `.paddock/` and relocates transcripts into `.chats/`.
+Sessions found in `~/.claude` are *offered* for import: nothing is moved, copied or
+linked until you confirm, and your terminal `claude` keeps working exactly as before.
+To share one set of transcripts between Paddock and your terminal instead, set
+`claude: { transcripts: host }` in `<data-dir>/paddock.config.yaml`. (Your *login* is
+already shared, which is why there is nothing to log into — see Credentials above.)
 
 To undo it: `rm -rf .paddock .chats` and drop the two `.gitignore` lines.
 
@@ -70,8 +93,6 @@ Without `--here`, Paddock never touches the directory you ran it from.
       --here              Open the CURRENT directory as the workspace
   -o, --open              Open the app in your browser once it is listening
       --verbose           Show the server's own logs (quiet by default)
-      --isolated-claude-home
-                          Use Paddock's own Claude home instead of ~/.claude
   -v, --version           Print the version
   -h, --help              Show help
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/app.js

@@ -20,6 +20,8 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { loadPaddockConfig } from "./config.js";
 import { ensureClaudeHome, countLegacyTranscriptLinks, findPlantedChatsLinks, } from "./claude-home.js";
+import { loadHostMcpSource } from "./claude-mcp.js";
+import { declaredMcpNotices } from "./mcp-servers.js";
 import { installHerdctlLogBridge } from "./agent-errors.js";
 import { ProjectStore, ROOT_KEY } from "./projects.js";
 import { AttachmentStore } from "./attachments.js";
@@ -108,7 +110,32 @@ export async function buildApp(opts = {}) {
     // --- project layer + herdctl ------------------------------------------
     const projects = new ProjectStore(cfg.projectsRoot);
     await projects.init();
-    const herdctl = new HerdctlService(cfg);
+    // The user's own MCP servers, under `claude.mcpServers: host` (#691 step 5).
+    // Read BEFORE the service is constructed because every keeper's agent config
+    // carries them, and read exactly once — a `.claude.json` that grows a server
+    // mid-run is picked up at the next restart, which is what the notice says.
+    // Under `own` (the default) the file is not opened at all.
+    const hostMcp = await loadHostMcpSource(cfg);
+    for (const notice of hostMcp.notices)
+        app.log[notice.level](notice.message);
+    // …and the servers this instance declares for ITSELF, from the top-level
+    // `mcpServers:` block (#691 step 6). Resolved during config load (it needs
+    // `process.env` for the `env:VAR` references), logged here because that is
+    // where the logger is. Nothing below carries a value out of the block: the
+    // diagnostics name keys and variable names only, and every server mentioned in
+    // a notice is rendered by `describeServer`.
+    for (const message of cfg.mcpServersDiagnostics.errors)
+        app.log.error(message);
+    for (const message of cfg.mcpServersDiagnostics.warnings)
+        app.log.warn(message);
+    for (const notice of declaredMcpNotices({
+        servers: cfg.mcpServers,
+        hostNames: Object.keys(hostMcp.source.user),
+        browserMcp: cfg.browserMcp,
+    })) {
+        app.log[notice.level](notice.message);
+    }
+    const herdctl = new HerdctlService(cfg, { ...hostMcp.source, declared: cfg.mcpServers });
     const git = new GitService(cfg.projectsRoot, cfg.gitAuthor);
     const githubAuth = new GithubAuth(path.join(cfg.dataDir, "github-auth.json"), cfg.githubClientId);
     const archive = new ArchiveStore(cfg.dataDir);
@@ -163,13 +190,13 @@ export async function buildApp(opts = {}) {
     for (const notice of (await ensureClaudeHome(cfg)).notices) {
         app.log[notice.level](notice.message);
     }
-    if (cfg.ownsClaudeHome) {
-        const stale = await countLegacyTranscriptLinks(cfg.legacyClaudeHome, cfg.dataDir);
-        if (stale > 0) {
-            app.log.info(`${stale} transcript symlink(s) from a previous layout still point into ${cfg.dataDir} ` +
-                `from ${path.join(cfg.legacyClaudeHome, "projects")}. Nothing reads them any more; ` +
-                `paddock leaves them alone because it does not write to ~/.claude. Safe to delete.`);
-        }
+    // Unconditional since #691 — paddock always owns its home, so there is no
+    // longer a layout in which these links are the live ones.
+    const stale = await countLegacyTranscriptLinks(cfg.legacyClaudeHome, cfg.dataDir);
+    if (stale > 0) {
+        app.log.info(`${stale} transcript symlink(s) from a previous layout still point into ${cfg.dataDir} ` +
+            `from ${path.join(cfg.legacyClaudeHome, "projects")}. Nothing reads them any more; ` +
+            `paddock leaves them alone because it does not write to ~/.claude. Safe to delete.`);
     }
     // #682: links an affected build planted at a path the user had not used yet.
     // Unlike the residue above these are still LIVE — they redirect the user's own

package/packages/server/dist/claude-credentials.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The `claude.credentials` lever (#691): whose Claude Code LOGIN this instance
+ * uses.
+ *
+ * Paddock always owns its Claude home (`<dataDir>/claude-home`, #691), and that
+ * is what made a macOS login invisible (#683). Claude Code files its secure
+ * storage entry under a service name derived from the config dir, so the moment
+ * paddock points `CLAUDE_CONFIG_DIR` at its own home, `claude /login`'s Keychain
+ * entry is under a name paddock's agents never look up. On a Mac with no token in
+ * the environment that is an instance which boots cleanly and fails every single
+ * turn with "Not logged in".
+ *
+ * ## The mechanism
+ *
+ * Read out of the SDK bundle (`@anthropic-ai/claude-agent-sdk/sdk.mjs`), which
+ * derives the service name like this:
+ *
+ * ```js
+ * var _z = "-credentials";
+ * function yz(e = "") {
+ *   let t = process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR,
+ *       r = t !== undefined ? !t : !process.env.CLAUDE_CONFIG_DIR,
+ *       n = t !== undefined ? t.normalize("NFC") : Yt(),
+ *       o = r ? "" : `-${sha256(n).digest("hex").substring(0, 8)}`;
+ *   return `Claude Code${OAUTH_FILE_SUFFIX}${e}${o}`;
+ * }
+ * ```
+ *
+ * `OAUTH_FILE_SUFFIX` is `""` in production and the only caller passes `_z`, so a
+ * plain `claude /login` files under exactly **`Claude Code-credentials`** — which
+ * is the name `probeMacosKeychainLogin` looks for, now confirmed rather than
+ * guessed.
+ *
+ * The load-bearing line is `r`. **`CLAUDE_SECURESTORAGE_CONFIG_DIR`, when
+ * DEFINED, overrides `CLAUDE_CONFIG_DIR` for secure storage only.** Define it as
+ * the EMPTY STRING and `!t` is true, so the hash suffix is dropped and the
+ * plain-name entry — the user's real login — is the one read, while
+ * `CLAUDE_CONFIG_DIR` still points at paddock's own home. That decoupling is the
+ * whole lever: one variable, no home moved, nothing else shared.
+ *
+ * The empty string is a value, not a mistake. Anywhere it looks like a bug to
+ * "clean up", it is the signal.
+ *
+ * ## Why this defaults to `host`, against the pattern
+ *
+ * Every other key in the `claude:` block defaults to `own`, and this one does
+ * not. **Isolation is about writes.** Reading a Keychain entry (or a symlinked
+ * `~/.claude/.credentials.json`) puts no file of the user's at risk: nothing is
+ * created, moved or deleted, and the user's own `claude` is unaffected. What
+ * defaulting to `own` WOULD do is recreate #683 — a first run that boots fine,
+ * says everything is ready, and fails every turn — which is the worst first
+ * impression paddock can make and the one it just made.
+ *
+ * So the guarantee `own` everywhere buys ("nothing outside the data dir is
+ * written") survives this default intact, and the deliberate exception is stated
+ * here rather than left to be inferred from a table.
+ */
+/**
+ * Whose Claude Code login this instance uses — the `claude.credentials` key.
+ *
+ * `own` = only what is inside paddock's own Claude home: a token in the
+ * environment, or a `.credentials.json` an operator put there / logged in with.
+ * `host` = this machine's Claude Code login as well — the macOS Keychain entry on
+ * darwin, and the user's `~/.claude/.credentials.json` (bridged by symlink) on
+ * everything else.
+ */
+export type CredentialsMode = "own" | "host";
+/** Sharing a login writes nothing. See the module doc for why this is not `own`. */
+export declare const DEFAULT_CREDENTIALS_MODE: CredentialsMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownCredentialsMode(value: string): value is CredentialsMode;
+/**
+ * The variable Claude Code resolves its SECURE-STORAGE scope from, independently
+ * of `CLAUDE_CONFIG_DIR`. Not exported by the SDK; read from its bundle.
+ */
+export declare const SECURE_STORAGE_DIR_VAR = "CLAUDE_SECURESTORAGE_CONFIG_DIR";
+/**
+ * The value that means "use the unsuffixed service name" — i.e. the entry a
+ * plain `claude /login` wrote. Empty on purpose; see the module doc.
+ */
+export declare const HOST_SECURE_STORAGE_DIR = "";
+/** What {@link applyCredentialsMode} did, for the boot notice. */
+export type CredentialsDecision = 
+/** `host`: the variable was set to `""`, so the plain-name login is used. */
+{
+    action: "shared";
+}
+/** `own`: the variable is unset, so the login is scoped to paddock's home. */
+ | {
+    action: "isolated";
+}
+/** An operator set the variable to something of their own; left alone. */
+ | {
+    action: "deferred";
+    value: string;
+};
+/**
+ * Put this instance's credentials mode into the environment Claude Code runs in.
+ *
+ * **Mutates `env`, and by default that is `process.env` — deliberately.** There
+ * is no per-invocation seam to use instead: herdctl builds the SDK's `options.env`
+ * itself (`withClaudeConfigDir`, which spreads `process.env`) and the CLI runtime
+ * lets execa merge over the inherited environment, and neither takes an env
+ * contribution from paddock. Unlike the Claude home — which herdctl warns must be
+ * per-invocation because one process hosts many agents with potentially different
+ * homes — the credentials mode is a property of the INSTANCE: every agent in it
+ * has the same answer, so a process-wide value cannot leak one agent's setting
+ * into another's. Called once, at boot, before the fleet starts.
+ *
+ * An operator who set the variable to a non-empty value themselves is honoured
+ * rather than clobbered, the same courtesy `CLAUDE_CONFIG_DIR` gets (herdctl#423):
+ * they have named a third secure-storage scope that neither mode can express. An
+ * EMPTY value is not treated that way — it is exactly what `host` writes, so it is
+ * ours by construction and `own` clears it.
+ */
+export declare function applyCredentialsMode(mode: CredentialsMode, env?: NodeJS.ProcessEnv): CredentialsDecision;

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

@@ -0,0 +1,103 @@
+/**
+ * The `claude.credentials` lever (#691): whose Claude Code LOGIN this instance
+ * uses.
+ *
+ * Paddock always owns its Claude home (`<dataDir>/claude-home`, #691), and that
+ * is what made a macOS login invisible (#683). Claude Code files its secure
+ * storage entry under a service name derived from the config dir, so the moment
+ * paddock points `CLAUDE_CONFIG_DIR` at its own home, `claude /login`'s Keychain
+ * entry is under a name paddock's agents never look up. On a Mac with no token in
+ * the environment that is an instance which boots cleanly and fails every single
+ * turn with "Not logged in".
+ *
+ * ## The mechanism
+ *
+ * Read out of the SDK bundle (`@anthropic-ai/claude-agent-sdk/sdk.mjs`), which
+ * derives the service name like this:
+ *
+ * ```js
+ * var _z = "-credentials";
+ * function yz(e = "") {
+ *   let t = process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR,
+ *       r = t !== undefined ? !t : !process.env.CLAUDE_CONFIG_DIR,
+ *       n = t !== undefined ? t.normalize("NFC") : Yt(),
+ *       o = r ? "" : `-${sha256(n).digest("hex").substring(0, 8)}`;
+ *   return `Claude Code${OAUTH_FILE_SUFFIX}${e}${o}`;
+ * }
+ * ```
+ *
+ * `OAUTH_FILE_SUFFIX` is `""` in production and the only caller passes `_z`, so a
+ * plain `claude /login` files under exactly **`Claude Code-credentials`** — which
+ * is the name `probeMacosKeychainLogin` looks for, now confirmed rather than
+ * guessed.
+ *
+ * The load-bearing line is `r`. **`CLAUDE_SECURESTORAGE_CONFIG_DIR`, when
+ * DEFINED, overrides `CLAUDE_CONFIG_DIR` for secure storage only.** Define it as
+ * the EMPTY STRING and `!t` is true, so the hash suffix is dropped and the
+ * plain-name entry — the user's real login — is the one read, while
+ * `CLAUDE_CONFIG_DIR` still points at paddock's own home. That decoupling is the
+ * whole lever: one variable, no home moved, nothing else shared.
+ *
+ * The empty string is a value, not a mistake. Anywhere it looks like a bug to
+ * "clean up", it is the signal.
+ *
+ * ## Why this defaults to `host`, against the pattern
+ *
+ * Every other key in the `claude:` block defaults to `own`, and this one does
+ * not. **Isolation is about writes.** Reading a Keychain entry (or a symlinked
+ * `~/.claude/.credentials.json`) puts no file of the user's at risk: nothing is
+ * created, moved or deleted, and the user's own `claude` is unaffected. What
+ * defaulting to `own` WOULD do is recreate #683 — a first run that boots fine,
+ * says everything is ready, and fails every turn — which is the worst first
+ * impression paddock can make and the one it just made.
+ *
+ * So the guarantee `own` everywhere buys ("nothing outside the data dir is
+ * written") survives this default intact, and the deliberate exception is stated
+ * here rather than left to be inferred from a table.
+ */
+/** Sharing a login writes nothing. See the module doc for why this is not `own`. */
+export const DEFAULT_CREDENTIALS_MODE = "host";
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export function isKnownCredentialsMode(value) {
+    return value === "own" || value === "host";
+}
+/**
+ * The variable Claude Code resolves its SECURE-STORAGE scope from, independently
+ * of `CLAUDE_CONFIG_DIR`. Not exported by the SDK; read from its bundle.
+ */
+export const SECURE_STORAGE_DIR_VAR = "CLAUDE_SECURESTORAGE_CONFIG_DIR";
+/**
+ * The value that means "use the unsuffixed service name" — i.e. the entry a
+ * plain `claude /login` wrote. Empty on purpose; see the module doc.
+ */
+export const HOST_SECURE_STORAGE_DIR = "";
+/**
+ * Put this instance's credentials mode into the environment Claude Code runs in.
+ *
+ * **Mutates `env`, and by default that is `process.env` — deliberately.** There
+ * is no per-invocation seam to use instead: herdctl builds the SDK's `options.env`
+ * itself (`withClaudeConfigDir`, which spreads `process.env`) and the CLI runtime
+ * lets execa merge over the inherited environment, and neither takes an env
+ * contribution from paddock. Unlike the Claude home — which herdctl warns must be
+ * per-invocation because one process hosts many agents with potentially different
+ * homes — the credentials mode is a property of the INSTANCE: every agent in it
+ * has the same answer, so a process-wide value cannot leak one agent's setting
+ * into another's. Called once, at boot, before the fleet starts.
+ *
+ * An operator who set the variable to a non-empty value themselves is honoured
+ * rather than clobbered, the same courtesy `CLAUDE_CONFIG_DIR` gets (herdctl#423):
+ * they have named a third secure-storage scope that neither mode can express. An
+ * EMPTY value is not treated that way — it is exactly what `host` writes, so it is
+ * ours by construction and `own` clears it.
+ */
+export function applyCredentialsMode(mode, env = process.env) {
+    const operator = env[SECURE_STORAGE_DIR_VAR];
+    if (operator !== undefined && operator !== "")
+        return { action: "deferred", value: operator };
+    if (mode === "host") {
+        env[SECURE_STORAGE_DIR_VAR] = HOST_SECURE_STORAGE_DIR;
+        return { action: "shared" };
+    }
+    delete env[SECURE_STORAGE_DIR_VAR];
+    return { action: "isolated" };
+}

package/packages/server/dist/claude-home.d.ts

@@ -1,26 +1,54 @@
 import type { PaddockConfig } from "./config.js";
 /**
- * Entries of a Claude home that are USER-LEVEL configuration rather than
- * per-instance state, symlinked from the user's home into paddock's own when
- * paddock's does not already have its own.
- *
- * Without this, relocating the home silently changes agent behaviour: the user's
- * `~/.claude/CLAUDE.md` is auto-loaded into every session, `settings.json`
- * carries permissions and hooks, and `agents/` `commands/` `plugins/` are
- * capability. Dropping them is not "a clean home", it is a behaviour regression
- * nobody asked for.
- *
- * `.credentials.json` is the one that matters most: on Linux (and in the Docker
- * image) it is where `claude login` puts the OAuth token, so without the bridge
- * every file-authenticated install would come back logged out. Symlinked rather
- * than copied — a copy would duplicate a live secret onto disk AND diverge the
- * moment Claude Code refreshed the token.
- *
- * Deliberately NOT bridged: `projects/` (that's the whole point), and everything
- * that is per-instance runtime state — `todos/`, `shell-snapshots/`, `statsig/`,
- * `sessions/`. Those are exactly what should now be per-instance.
+ * The user's file-based Claude Code login, bridged in only under
+ * `claude.credentials: host` (#691).
+ *
+ * This is what the lever means on Linux and in the Docker image, where `claude
+ * login` writes a file rather than using a keychain: on darwin `credentials: host`
+ * is the `CLAUDE_SECURESTORAGE_CONFIG_DIR` empty-string trick, here it is this
+ * symlink, and one config key has to mean the same thing on both.
+ *
+ * Symlinked rather than copied — a copy would duplicate a live secret onto disk
+ * AND diverge the moment Claude Code refreshed the token.
+ *
+ * It was bridged unconditionally before the lever existed, which is why
+ * `credentials` defaulting to `host` keeps every existing install working
+ * unchanged; `own` is the new behaviour, and it has to also REMOVE a link a
+ * previous boot planted, or "isolated" would be a claim that only holds for
+ * instances that were never anything else.
+ */
+export declare const CREDENTIAL_ENTRY = ".credentials.json";
+/**
+ * Entries of the user's Claude home that paddock can bridge into its own — the
+ * complete list, for callers that want to reason about the surface rather than
+ * about one lever.
+ *
+ * There is no longer an "always bridged" set: since #691 step 4, every entry here
+ * belongs to exactly one key of the `claude:` block, and the mapping is the whole
+ * point of the block.
+ *
+ * | Entry | Lever |
+ * |---|---|
+ * | `CLAUDE.md`, `agents/`, `commands/`, `plugins/` | `claude.instructions` |
+ * | `settings.json` (its `hooks` key) | `claude.hooks` |
+ * | `.credentials.json` | `claude.credentials` |
+ *
+ * `settings.json` appears under `hooks` because that is the half of it a lever
+ * governs; its OTHER keys — permissions, model, statusline, `enabledPlugins` —
+ * are inherited in every mode, which is why `hooks: own` writes a filtered file
+ * rather than declining to bridge one. See `claude-settings.ts`.
+ *
+ * Deliberately NOT bridged in any mode: `projects/` (that's the whole point), and
+ * everything that is per-instance runtime state — `todos/`, `shell-snapshots/`,
+ * `statsig/`, `sessions/`. Those are exactly what should be per-instance.
+ *
+ * The fifth lever, `claude.mcpServers`, has NO row here on purpose: MCP servers
+ * are declared in `~/.claude.json`, which is a sibling of the home rather than an
+ * entry inside it, so it is not bridgeable at all — paddock reads it and passes
+ * the servers programmatically (`claude-mcp.ts`). That asymmetry is the reason
+ * MCP inheritance broke separately from everything in this table.
  */
-export declare const BRIDGED_ENTRIES: readonly [".credentials.json", "settings.json", "CLAUDE.md", "agents", "commands", "plugins"];
+export declare const BRIDGEABLE_ENTRIES: readonly string[];
 /**
  * What a Keychain probe concluded.
  *
@@ -42,15 +70,24 @@ export type KeychainProbe = () => Promise<KeychainFinding>;
  * ## The asymmetry, which is deliberate
  *
  * A positive result is trustworthy: an entry under that service name is a login.
- * A negative result is NOT — the service name is Claude Code's internal detail
- * and can change, and `security` can fail for a dozen reasons that have nothing
- * to do with the user. So a miss returns `unknown`, and the caller falls back to
- * the existing, correct, generic warning. Guessing the name wrong therefore
- * costs nothing beyond the improvement not happening.
+ * A negative result is NOT — `security` can fail for a dozen reasons that have
+ * nothing to do with the user, and the service name, though now read straight out
+ * of the SDK bundle rather than guessed, is still Claude Code's internal detail
+ * and can change. So a miss returns `unknown`, and the caller falls back to the
+ * existing, correct, generic warning. Being wrong about the name therefore costs
+ * nothing beyond the improvement not happening.
  *
  * Never prompts and never reads a secret: `find-generic-password` WITHOUT `-w`
  * reports existence only (attributes, which are discarded), so nothing sensitive
  * reaches a log, a transcript, or this process's memory.
+ *
+ * One known imprecision, left in on purpose: Claude Code's own lookup also passes
+ * `-a` (`process.env.USER`, falling back to the OS username), and this does not.
+ * So an entry filed under a DIFFERENT account still reads as `found` here while
+ * Claude Code would miss it — a service running under a different `USER` than the
+ * terminal that logged in. Matching that exactly would trade a rare false
+ * positive for a rarer false negative, and a false negative is the one that costs
+ * something: it downgrades a specific instruction back to the generic warning.
  */
 export declare function probeMacosKeychainLogin(platform?: string): Promise<KeychainFinding>;
 /** A message for the operator, at the level it should be logged at. */
@@ -61,21 +98,48 @@ export interface ClaudeHomeNotice {
 export interface ClaudeHomeReport {
     /** Entries symlinked in from the user's home this boot. */
     bridged: string[];
+    /**
+     * Entries whose bridge symlink was REMOVED this boot because the lever that
+     * governs them now says `own` (#691).
+     *
+     * The bridge is non-clobbering, so without this an instance that was ever
+     * `host` would keep reading the user's file forever after being reconfigured —
+     * "isolated" would be a claim that only holds for instances that were never
+     * anything else.
+     */
+    withdrawn: string[];
+    /**
+     * Entries paddock WROTE into its own home this boot rather than symlinking,
+     * because a lever needs part of a file and not the whole of it. Only
+     * `settings.json` today — see `claude-settings.ts`.
+     */
+    generated: string[];
     /** Messages for `app.ts` to log — config resolution has no logger of its own. */
     notices: ClaudeHomeNotice[];
 }
 /**
- * Create paddock's Claude home and bridge the user-level config into it.
+ * Create paddock's Claude home and put the user-level config into it that this
+ * instance's `claude:` levers say it should have (#691).
  *
- * Idempotent and non-clobbering: an entry paddock's home already has (whether a
- * real file the user put there or a symlink from a previous boot) is left
- * completely alone, so this is safe to run on every start.
+ * Idempotent and non-clobbering: a real file the user put in paddock's home is
+ * left completely alone, so this is safe to run on every start. What it DOES
+ * maintain is what paddock itself planted — bridge symlinks, withdrawn when a
+ * lever flips to `own`, and the generated `settings.json`, regenerated from the
+ * user's current one. Ownership of a generated file is decided by hash
+ * ({@link classifyOwnEntry}), never by "it is at a name we use".
  *
  * Never throws. A home that cannot be created is not a reason to refuse to boot
  * — Claude Code falls back to its own default and chat still works, which is the
  * same failure mode `ensureProjectChats` has always had.
+ *
+ * **Mutates `env`** (`process.env` by default) to carry `claude.credentials` into
+ * the environment Claude Code runs in — see {@link applyCredentialsMode} for why
+ * that is the only seam available and why it is safe process-wide. Done here
+ * because this is already the one call that runs before the fleet starts, and
+ * because the credential warning below has to describe the environment it just
+ * set rather than the one it found.
  */
-export declare function ensureClaudeHome(cfg: Pick<PaddockConfig, "claudeHome" | "legacyClaudeHome" | "ownsClaudeHome">, env?: NodeJS.ProcessEnv, probeKeychain?: KeychainProbe): Promise<ClaudeHomeReport>;
+export declare function ensureClaudeHome(cfg: Pick<PaddockConfig, "claudeHome" | "legacyClaudeHome" | "claude">, env?: NodeJS.ProcessEnv, probeKeychain?: KeychainProbe): Promise<ClaudeHomeReport>;
 /** One of the user's transcript folders, made readable through paddock's home. */
 export interface LegacyMirror {
     /** Folder name inside `<claudeHome>/projects/` — `encodePathForCli(engineCwd)`. */
@@ -139,6 +203,14 @@ export declare function legacySourcePath(legacyHome: string, folderName: string)
  * mirroring them would re-offer paddock's own chats as "adoptable". That also
  * makes the leftovers from before this change inert rather than confusing.
  *
+ * A folder paddock's own home ALREADY links to directly is skipped for the same
+ * reason. That is the `claude.transcripts: host` case (#691): there the folder in
+ * the user's home is a real directory that paddock itself writes through, so
+ * mirroring it would offer every project's own live chats back as importable —
+ * the #658 mistake with the arrow reversed. (Adoption de-duplicates sources by
+ * resolved real path, so this was noise rather than breakage; it is skipped here
+ * because a link paddock plants and then mirrors is confusing to find on disk.)
+ *
  * Idempotent and never throws. Returns every mirror it maintains, not only the
  * ones planted this call, so a caller can rely on the mapping after any call.
  */