@edspencer/paddock 0.61.0 → 0.62.0

package/README.md

@@ -26,8 +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, your existing login is picked up
-automatically and there is nothing to do.
+**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
 
@@ -45,8 +71,14 @@ 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`**
-- **links** `~/.claude/projects/<encoded-dir>` at the workspace — your Claude Code
-  history is linked, never moved or copied
+
+**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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.61.0",
+  "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/agent-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The one-line, actionable reason this failed, if it is one we recognise.
+ *
+ * `undefined` means "no idea" — and an unknown failure keeps its full detail,
+ * because that is exactly the case where somebody needs it.
+ */
+export declare function classifyAgentError(err: unknown): string | undefined;
+/**
+ * The same error with the reconstructed `claude` argv cut out.
+ *
+ * execa's message quotes the entire command it ran, which for the sweeper is
+ * ~2 KB of system prompt followed by the full `--disallowedTools` list. It is
+ * noise to an end user and it buries the signal; it also means the curator
+ * prompt is copied into any log or paste of the failure. Everything before the
+ * argv (`Command failed with exit code 1`) is kept, because the exit status is
+ * the part that is actually diagnostic.
+ *
+ * Full text is still one env var away — see {@link installHerdctlLogBridge}.
+ */
+export declare function summariseAgentError(message: string): string;
+/**
+ * Route `@herdctl/core`'s logging through a handler that shapes agent failures.
+ *
+ * Two behaviours, and they are separate on purpose:
+ *
+ *  - **Always** summarise the argv. The system prompt in a `claude -p` command
+ *    line is never what somebody is reading the log for, on a laptop or a
+ *    server. `HERDCTL_LOG_LEVEL=debug` turns it back on — at debug you have
+ *    asked for everything, and the argv is genuinely useful there.
+ *  - **In quiet mode** (the CLI's default), collapse a recognised failure to its
+ *    cause. `LOG_LEVEL=warn` was never enough for this: core logs these at
+ *    `error`, which passes every level filter there is, and one of them is a
+ *    bare `console.error`. Quiet-by-default meant "quiet when nothing goes
+ *    wrong", which is the easy half.
+ *
+ * Idempotent; installing again replaces the handler. Call `setLogHandler(null)`
+ * to restore core's own output.
+ */
+export declare function installHerdctlLogBridge(options: {
+    quiet: boolean;
+}): void;

package/packages/server/dist/agent-errors.js

@@ -0,0 +1,127 @@
+/**
+ * Making a failed agent run readable (#684).
+ *
+ * A credential-less `npx @edspencer/paddock --here` — the path the README, the
+ * docs site and the front page all point new users at — greeted them with a
+ * multi-screen stack trace containing the entire sweeper system prompt, four
+ * times over: once in the `ExecaError`, once in the `[fleet-manager]` line, once
+ * in the serialised `err.message` and once inside `err.stack`. The one useful
+ * string, `Not logged in · Please run /login`, was on line 40 of the dump. The
+ * server was fine and still serving; nothing about the output said so.
+ *
+ * Three separate things produce that wall, and only one of them is ours:
+ *
+ *  1. `sweep.ts` logging `{ err }` at pino level 50 — ours, fixed there.
+ *  2. `[CLIRuntime] Process failed: …` — `@herdctl/core`.
+ *  3. `[fleet-manager] Job … error: …` — `@herdctl/core`.
+ *
+ * We cannot edit core from here, but we do not have to: `setLogHandler` is an
+ * exported hook that replaces the `console.*` output of EVERY `createLogger` in
+ * the engine. {@link installHerdctlLogBridge} uses it to shape both of core's
+ * lines on the way past. That is a better fix than patching core anyway — it
+ * keeps the decision about how much noise a paddock instance emits inside
+ * paddock, where the CLI's quiet mode lives.
+ */
+import { setLogHandler, getLogLevel, LOG_LEVEL_ORDER } from "@herdctl/core";
+/**
+ * Failures that are USER STATE, not exceptions — a known cause with a known
+ * remedy, where a stack trace tells the reader nothing they can act on.
+ *
+ * Matched against the whole error text because the signal arrives in the failed
+ * command's own output, not in the message execa constructs.
+ */
+const KNOWN_CAUSES = [
+    {
+        pattern: /Not logged in|Please run \/login|Invalid API key|OAuth token has expired/i,
+        cause: "Claude Code is not logged in — run `claude setup-token`, " +
+            "or set CLAUDE_CODE_OAUTH_TOKEN",
+    },
+    {
+        pattern: /Credit balance is too low|insufficient[_ ]quota/i,
+        cause: "the Claude account is out of credit",
+    },
+    {
+        // Anchored to `claude` specifically. A bare /ENOENT/ would claim a missing
+        // CLI for any file the engine failed to open, which is a confident wrong
+        // answer — worse than the raw error it replaces.
+        pattern: /ENOENT[^\n]{0,40}claude|claude: (command )?not found/i,
+        cause: "the `claude` CLI is not on PATH (needed by the sweeper and triggers)",
+    },
+];
+/**
+ * The one-line, actionable reason this failed, if it is one we recognise.
+ *
+ * `undefined` means "no idea" — and an unknown failure keeps its full detail,
+ * because that is exactly the case where somebody needs it.
+ */
+export function classifyAgentError(err) {
+    const text = agentErrorText(err);
+    return KNOWN_CAUSES.find((k) => k.pattern.test(text))?.cause;
+}
+/** Everything an error carries as text — message, and stdio execa attached. */
+function agentErrorText(err) {
+    if (typeof err === "string")
+        return err;
+    const e = err;
+    return [e?.message, e?.stdout, e?.stderr].filter((v) => typeof v === "string").join("\n");
+}
+/**
+ * The same error with the reconstructed `claude` argv cut out.
+ *
+ * execa's message quotes the entire command it ran, which for the sweeper is
+ * ~2 KB of system prompt followed by the full `--disallowedTools` list. It is
+ * noise to an end user and it buries the signal; it also means the curator
+ * prompt is copied into any log or paste of the failure. Everything before the
+ * argv (`Command failed with exit code 1`) is kept, because the exit status is
+ * the part that is actually diagnostic.
+ *
+ * Full text is still one env var away — see {@link installHerdctlLogBridge}.
+ */
+export function summariseAgentError(message) {
+    return message.replace(
+    // Up to and including "claude", then a flag, then everything after it.
+    /(:\s*)claude(\.exe)?\s+-{1,2}[\s\S]*/, "$1claude … (argv omitted — set HERDCTL_LOG_LEVEL=debug for the full command)");
+}
+/**
+ * Route `@herdctl/core`'s logging through a handler that shapes agent failures.
+ *
+ * Two behaviours, and they are separate on purpose:
+ *
+ *  - **Always** summarise the argv. The system prompt in a `claude -p` command
+ *    line is never what somebody is reading the log for, on a laptop or a
+ *    server. `HERDCTL_LOG_LEVEL=debug` turns it back on — at debug you have
+ *    asked for everything, and the argv is genuinely useful there.
+ *  - **In quiet mode** (the CLI's default), collapse a recognised failure to its
+ *    cause. `LOG_LEVEL=warn` was never enough for this: core logs these at
+ *    `error`, which passes every level filter there is, and one of them is a
+ *    bare `console.error`. Quiet-by-default meant "quiet when nothing goes
+ *    wrong", which is the easy half.
+ *
+ * Idempotent; installing again replaces the handler. Call `setLogHandler(null)`
+ * to restore core's own output.
+ */
+export function installHerdctlLogBridge(options) {
+    const debug = LOG_LEVEL_ORDER[getLogLevel()] <= LOG_LEVEL_ORDER.debug;
+    setLogHandler((level, prefix, message, data) => {
+        if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[getLogLevel()])
+            return;
+        let text = debug ? message : summariseAgentError(message);
+        if (options.quiet && level === "error") {
+            const cause = classifyAgentError(message);
+            // A known cause replaces the message rather than annotating it: the
+            // reader does not need the exit code as well as the reason, and the
+            // failure is non-fatal — the server is still up and still serving.
+            if (cause !== undefined)
+                text = `${cause} — run with --verbose for the full error`;
+        }
+        const line = data === undefined ? `[${prefix}] ${text}` : `[${prefix}] ${text} ${JSON.stringify(data)}`;
+        if (level === "error")
+            console.error(line);
+        else if (level === "warn")
+            console.warn(line);
+        else if (level === "info")
+            console.info(line);
+        else
+            console.debug(line);
+    });
+}

package/packages/server/dist/app.js

@@ -19,7 +19,10 @@ import { createRequire } from "node:module";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { loadPaddockConfig } from "./config.js";
-import { ensureClaudeHome, countLegacyTranscriptLinks } from "./claude-home.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";
 import { HerdctlService } from "./herdctl.js";
@@ -74,6 +77,11 @@ function hasFileExtension(pathname) {
  */
 export async function buildApp(opts = {}) {
     const cfg = opts.config ?? loadPaddockConfig();
+    // Shape the engine's own logging before anything can start a job (#684). Two
+    // of the three sources of the credential-failure stack-trace wall are inside
+    // `@herdctl/core`, and `setLogHandler` is the supported way to reach them from
+    // out here. `PADDOCK_QUIET` is set by `cli/paddock.ts` unless `--verbose`.
+    installHerdctlLogBridge({ quiet: (process.env.PADDOCK_QUIET ?? "") !== "" });
     const app = Fastify({
         logger: { level: cfg.logLevel },
     });
@@ -102,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);
@@ -157,13 +190,28 @@ 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
+    // future `claude` sessions — so they warn, and name every path. Paddock does
+    // not remove them; it does not write to `~/.claude`.
+    const poisoned = await findPlantedChatsLinks(cfg.legacyClaudeHome, cfg.dataDir);
+    if (poisoned.length > 0) {
+        app.log.warn(`${poisoned.length} symlink(s) in ${path.join(cfg.legacyClaudeHome, "projects")} redirect ` +
+            `Claude Code's transcripts into a paddock .chats/ store (#682). While they exist, ` +
+            `\`claude\` sessions you start in those directories are written to paddock's store, and ` +
+            `deleting that store destroys them. Paddock does not remove anything under ~/.claude — ` +
+            `delete them yourself if you did not intend this:\n` +
+            poisoned
+                .map((p) => `  ${p.link} -> ${p.target}${p.dangling ? "  (target is missing)" : ""}`)
+                .join("\n"));
     }
     const rootWorkspace = await projects.get(ROOT_KEY);
     const initialProjects = [...(await projects.list()), rootWorkspace];

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" };
+}