@edspencer/paddock 0.60.0 → 0.61.1

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

@@ -0,0 +1,44 @@
+export interface ClaudeHomeChoiceInput {
+    /** The process environment to read. */
+    env: NodeJS.ProcessEnv;
+    /** The user's own Claude home — `os.homedir()/.claude`. */
+    userClaudeHome: string;
+    /** Does that directory exist? Nothing to be continuous with if it does not. */
+    userHomeExists: boolean;
+    /** Did the user ask for isolation explicitly (`--isolated-claude-home`)? */
+    forceIsolated: boolean;
+}
+export interface ClaudeHomeChoice {
+    /**
+     * The value to put in `CLAUDE_HOME`, or `undefined` to leave the default
+     * (`<dataDir>/claude-home`) alone.
+     */
+    claudeHome?: string;
+    /** Short, user-facing reason — printed when continuity is chosen. */
+    reason: string;
+}
+/**
+ * Decide whether the interactive CLI should run against the user's own Claude
+ * home for credential continuity.
+ *
+ * Pure, so the whole decision table is testable on a platform that has no
+ * Keychain. Continuity is chosen only when all four hold:
+ *
+ *  1. **No explicit home in the environment.** `CLAUDE_HOME` or
+ *     `CLAUDE_CONFIG_DIR` is somebody deciding this already; deferring to them is
+ *     the same rule herdctl#423 follows.
+ *  2. **No token in the environment.** A token authenticates regardless of home,
+ *     so the isolated home works and is strictly better — this is the shape every
+ *     CI, container and server run has.
+ *  3. **`--isolated-claude-home` not passed.** The explicit opt-out.
+ *  4. **`~/.claude` actually exists.** With no user home there is no login to be
+ *     continuous with, and the owned home self-initializes cleanly.
+ *
+ * Note what is NOT a condition: the platform. The isolation/continuity trade is
+ * the same argument on Linux, where it additionally makes the `.credentials.json`
+ * bridge unnecessary rather than merely insufficient. Branching on `darwin` would
+ * mean two behaviours to reason about and one of them untested on most machines.
+ */
+export declare function chooseClaudeHome(input: ClaudeHomeChoiceInput): ClaudeHomeChoice;
+/** `~/.claude`, given a home directory. Kept here so callers do not re-spell it. */
+export declare function userClaudeHomePath(homedir: string): string;

package/packages/server/dist/cli/claude-home-choice.js

@@ -0,0 +1,108 @@
+/**
+ * Which Claude home the INTERACTIVE CLI runs against (#683).
+ *
+ * ## The problem this exists for
+ *
+ * Since #620 paddock owns `<dataDir>/claude-home`, and herdctl therefore hands
+ * Claude Code a `CLAUDE_CONFIG_DIR`. Claude Code derives its **secure-storage
+ * service name** from whether that variable is SET AT ALL — unset gets the plain
+ * name, set gets a path-hash suffix — so a macOS login held in the Keychain under
+ * the plain name becomes invisible the moment paddock points at its own home.
+ *
+ * #620 anticipated this and bridges credentials by symlinking
+ * `~/.claude/.credentials.json` in. That is the FILE-based store: it covers Linux
+ * and the Docker image and is structurally incapable of covering macOS, because a
+ * Keychain entry cannot be symlinked. Net effect on a Mac: `npx paddock --here`
+ * boots, the UI loads, and every turn fails with `Not logged in`, two directories
+ * away from a perfectly good login.
+ *
+ * ## Why the fix is a home choice and not a credential copy
+ *
+ * There is exactly one lever. herdctl injects `CLAUDE_CONFIG_DIR` only when the
+ * configured home differs from `~/.claude` — it documents that same service-name
+ * branch as its reason for staying quiet otherwise. So the only way to get the
+ * plain service name, and with it the user's Keychain login, is to run against
+ * `~/.claude` itself.
+ *
+ * The alternative — reading the Keychain secret and writing it to disk as
+ * `.credentials.json` — is deliberately NOT done anywhere in this codebase. It
+ * downgrades OS-protected storage to a plaintext file, and it would diverge the
+ * moment Claude Code refreshed the token.
+ *
+ * ## Why the interactive CLI, and only the interactive CLI
+ *
+ * `--here` means *my* directory, *my* sessions, *my* login; isolation is a server
+ * concern. A daemon, the container image and `node dist/index.js` all keep the
+ * owned home — nothing here runs for them, and `resolveClaudeHome`'s precedence
+ * is untouched. This module only decides what the CLI puts in `CLAUDE_HOME`
+ * before it hands over, which is the same mechanism a user has always had.
+ *
+ * ## What continuity costs
+ *
+ * Running against the user's home means paddock plants no transcript symlink
+ * there (#682, and the reason this was blocked on it), so transcripts stay in
+ * `~/.claude/projects/<encoded-cwd>/` rather than being relocated into the
+ * workspace's `.chats/`. Chats still list, open, resume and rename — paddock and
+ * the engine read the one home — but the workspace directory is no longer
+ * self-contained. The CLI says so out loud when it makes this choice; see
+ * `paddock.ts`.
+ *
+ * What it does NOT change, contrary to the obvious guess: **import consent**.
+ * Reading the home a user's sessions live in does not make them paddock's chats.
+ * Session discovery is attribution-based, so a transcript paddock never ran is
+ * offered by `adoptable-chats` and absent from `chats` — exactly as under an
+ * owned home — and #663's confirmation still gates every import. Checked against
+ * a running instance rather than reasoned about, because the reasoning went the
+ * other way.
+ */
+import path from "node:path";
+/** Env vars that authenticate Claude Code without any on-disk credential. */
+const TOKEN_ENV_VARS = ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+/** Variables that are an explicit choice of home, and are never overridden. */
+const HOME_ENV_VARS = ["CLAUDE_HOME", "CLAUDE_CONFIG_DIR"];
+/**
+ * Decide whether the interactive CLI should run against the user's own Claude
+ * home for credential continuity.
+ *
+ * Pure, so the whole decision table is testable on a platform that has no
+ * Keychain. Continuity is chosen only when all four hold:
+ *
+ *  1. **No explicit home in the environment.** `CLAUDE_HOME` or
+ *     `CLAUDE_CONFIG_DIR` is somebody deciding this already; deferring to them is
+ *     the same rule herdctl#423 follows.
+ *  2. **No token in the environment.** A token authenticates regardless of home,
+ *     so the isolated home works and is strictly better — this is the shape every
+ *     CI, container and server run has.
+ *  3. **`--isolated-claude-home` not passed.** The explicit opt-out.
+ *  4. **`~/.claude` actually exists.** With no user home there is no login to be
+ *     continuous with, and the owned home self-initializes cleanly.
+ *
+ * Note what is NOT a condition: the platform. The isolation/continuity trade is
+ * the same argument on Linux, where it additionally makes the `.credentials.json`
+ * bridge unnecessary rather than merely insufficient. Branching on `darwin` would
+ * mean two behaviours to reason about and one of them untested on most machines.
+ */
+export function chooseClaudeHome(input) {
+    const setHomeVar = HOME_ENV_VARS.find((v) => (input.env[v] ?? "").trim().length > 0);
+    if (setHomeVar !== undefined) {
+        return { reason: `${setHomeVar} is set — honouring it` };
+    }
+    if (input.forceIsolated) {
+        return { reason: "--isolated-claude-home was passed" };
+    }
+    const tokenVar = TOKEN_ENV_VARS.find((v) => (input.env[v] ?? "").trim().length > 0);
+    if (tokenVar !== undefined) {
+        return { reason: `${tokenVar} is set — the isolated home can authenticate on its own` };
+    }
+    if (!input.userHomeExists) {
+        return { reason: `no ${input.userClaudeHome} — nothing to inherit` };
+    }
+    return {
+        claudeHome: input.userClaudeHome,
+        reason: `using your existing Claude Code login and history in ${input.userClaudeHome}`,
+    };
+}
+/** `~/.claude`, given a home directory. Kept here so callers do not re-spell it. */
+export function userClaudeHomePath(homedir) {
+    return path.join(homedir, ".claude");
+}

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

@@ -15,11 +15,13 @@
  *
  * ## Deployment note
  *
- * The import needs READ access to the user's transcripts. In a container that
- * usually means running this on the HOST against the data dir (`--data-dir`),
- * or mounting `~/.claude` in and pointing `CLAUDE_HOME` at the mount. Detection
- * silently finds nothing if the transcripts are not visible — which is why
- * `--dry-run` prints the sources it found rather than only a count.
+ * The import needs READ access to the user's own transcripts, which live in
+ * `~/.claude` — a read-only source paddock reads out of and never writes to
+ * (#620). In a container that usually means running this on the HOST against
+ * the data dir (`--data-dir`), or bind-mounting the user's `~/.claude` in at the
+ * same path. Detection silently finds nothing if the transcripts are not
+ * visible — which is why `--dry-run` prints the sources it found rather than
+ * only a count.
  *
  * ## Usage
  *
@@ -140,8 +142,9 @@ async function main() {
                 : `Nothing to import for "${project.slug || "(root)"}".\n` +
                     `Working directory: ${project.workingDir}\n` +
                     `Claude home:       ${cfg.claudeHome}\n` +
+                    `Importing from:    ${cfg.legacyClaudeHome}\n` +
                     `If you expected chats here, check that this process can READ the transcripts\n` +
-                    `(a container only sees what is mounted) and that CLAUDE_HOME points at them.\n`);
+                    `under that source home (a container only sees what is mounted).\n`);
             return 0;
         }
         const result = await herdctl.adoptChats(project, {

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

@@ -24,6 +24,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { HERE_MARKER, isHereWorkspace, countClaudeSessions, ensureGitignored } from "./here.js";
+import { chooseClaudeHome, userClaudeHomePath } from "./claude-home-choice.js";
 import { CliError, USAGE, parseArgs, nodeVersionProblem, explainListenError, } from "./args.js";
 /** This module's own directory: `<…>/packages/server/dist/cli`. */
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -89,34 +90,6 @@ function addBundledBinsToPath() {
         return;
     process.env.PATH = current ? `${binDir}${sep}${current}` : binDir;
 }
-/**
- * Best-effort credential check — WARNS, never blocks.
- *
- * Claude Code stores credentials differently per platform (a file under
- * ~/.claude on Linux, the Keychain on macOS), so absence of a file does not
- * prove absence of a login. Refusing to start on a false negative would be
- * worse than a chat that fails with the runtime's own error, so this only
- * prints guidance.
- */
-function warnIfNoCredentials(claudeHome) {
-    if (process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY)
-        return;
-    const looksLoggedIn = fs.existsSync(path.join(claudeHome, ".credentials.json")) ||
-        fs.existsSync(path.join(os.homedir(), ".claude.json"));
-    if (looksLoggedIn)
-        return;
-    console.warn([
-        "",
-        "  ⚠ No Claude credentials found.",
-        "",
-        "    Paddock will start, but chats will fail until it has credentials.",
-        "    Fix with either:",
-        "",
-        "      claude setup-token                  # Claude Max/Pro",
-        "      export ANTHROPIC_API_KEY=sk-ant-…   # API billing",
-        "",
-    ].join("\n"));
-}
 /**
  * Report where the data lives, the first time we create it.
  *
@@ -142,12 +115,26 @@ function noteFirstRun(dataDir) {
  * effects are announced rather than asked about. Printed only on the first
  * `--here` in a directory; resuming an already-opened one says nothing.
  */
-function announceHereConsent(dir, dataDir) {
+function announceHereConsent(dir, dataDir, inheritedHome) {
     console.log([
         "",
         `  Opening ${dir} as a Paddock workspace.`,
         `    · ${path.relative(dir, dataDir) || HERE_MARKER}/ and .chats/ created here, and added to .gitignore`,
-        "    · ~/.claude sessions for this directory are linked at the workspace",
+        // Import consent is UNCHANGED by continuity, which is worth stating
+        // because it is not what you would predict: reading the user's home does
+        // not turn their sessions into paddock's chats. Verified against a running
+        // instance — a pre-existing transcript for the directory comes back from
+        // `adoptable-chats` (offered) and NOT from `chats` (listed), because
+        // session discovery is attribution-based, not "whatever is in the folder".
+        // So #663's confirmation still gates every import.
+        //
+        // What continuity DOES change is where transcripts live: with no symlink
+        // planted in a home paddock does not own (#682), Claude Code keeps writing
+        // to `~/.claude/projects/<encoded-cwd>/` and `.chats/` stays empty.
+        inheritedHome === undefined
+            ? "    · ~/.claude sessions for this directory are offered for import (nothing is moved)"
+            : `    · running against your ${inheritedHome}: sessions there are offered for import ` +
+                `(nothing is moved), and new transcripts stay there rather than in .chats/`,
         "  Later runs here resume it — no flag needed.",
         "",
     ].join("\n"));
@@ -172,7 +159,7 @@ function offerHereIfSessionsExist(dir) {
     console.log([
         "",
         `  This directory has ${sessions} Claude Code session${sessions === 1 ? "" : "s"}.`,
-        "  Run `paddock --here` to open it as a workspace and import them.",
+        "  Run `paddock --here` to open it as a workspace, where they can be imported.",
         "",
     ].join("\n"));
 }
@@ -232,6 +219,20 @@ async function main() {
     // is `.git`. A flagless run anywhere else touches nothing.
     const resuming = !opts.here && isHereWorkspace(cwd);
     const hereMode = opts.here || resuming;
+    // Credential continuity (#683). Decided HERE, in the interactive CLI, and
+    // nowhere else: `resolveClaudeHome`'s precedence is untouched, so a server, a
+    // container and `node dist/index.js` all keep the owned home. All this does is
+    // set the same `CLAUDE_HOME` a user could set by hand — the difference is that
+    // on macOS they currently have no way to know they need to.
+    const userHome = userClaudeHomePath(os.homedir());
+    const homeChoice = chooseClaudeHome({
+        env: process.env,
+        userClaudeHome: userHome,
+        userHomeExists: fs.existsSync(userHome),
+        forceIsolated: opts.isolatedClaudeHome,
+    });
+    if (homeChoice.claudeHome !== undefined)
+        process.env.CLAUDE_HOME = homeChoice.claudeHome;
     // Apply CLI defaults as env vars. This is the whole integration surface: the
     // server resolves config inside `buildApp()`, so anything set before the
     // dynamic import below is picked up with no special-casing in config.ts.
@@ -241,7 +242,7 @@ async function main() {
         (hereMode ? path.join(cwd, HERE_MARKER) : path.join(os.homedir(), ".paddock")));
     if (hereMode) {
         if (!resuming)
-            announceHereConsent(cwd, dataDir);
+            announceHereConsent(cwd, dataDir, homeChoice.claudeHome);
         // The root workspace IS `projectsRoot` (its key is ""), so pointing this at
         // the user's directory makes that directory the workspace. No schema change,
         // no new project type — see cli/here.ts.
@@ -267,13 +268,27 @@ async function main() {
     //                      `[fleet-manager] …` lines via console.info — pino's
     //                      level cannot reach those.
     // An explicit value for either is left alone, and `--verbose` skips both.
+    // A LEVEL is not enough, which is what #684 was about. Background job failures
+    // are logged at `error` — level 50, above every threshold either variable can
+    // set — and one of them is a bare `console.error` inside the engine. So quiet
+    // mode is also stated as a fact the server can act on: `agent-errors.ts` reads
+    // this to collapse a recognised, non-fatal failure to its cause instead of
+    // printing a stack trace with 2 KB of system prompt in it. Internal to the
+    // CLI; `--verbose` leaves it unset and nothing is suppressed.
     if (!opts.verbose) {
         if (process.env.LOG_LEVEL === undefined)
             process.env.LOG_LEVEL = "warn";
         if (process.env.HERDCTL_LOG_LEVEL === undefined)
             process.env.HERDCTL_LOG_LEVEL = "warn";
+        process.env.PADDOCK_QUIET = "1";
     }
-    warnIfNoCredentials(process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude"));
+    // No credential preflight here: `ensureClaudeHome` (claude-home.ts) already
+    // warns at boot, and it is the only check that can be right. It tests the home
+    // paddock will ACTUALLY use — after the bridge has symlinked in any
+    // `~/.claude/.credentials.json`, and, on darwin, after probing the Keychain for
+    // the login `CLAUDE_CONFIG_DIR` scoping hides (#683). It logs at `warn`, which
+    // survives the quiet default set just above. Continuity (chosen above) usually
+    // means it has nothing to say, because there is nothing left to bridge.
     const port = process.env.PORT ?? "4000";
     const host = process.env.HOST ?? "127.0.0.1";
     // Imported dynamically, AFTER the env above is set: a static import would
@@ -293,6 +308,12 @@ async function main() {
         "",
         `  Paddock is running at ${url}`,
         `  Workspace: ${hereMode ? cwd : dataDir}${resuming ? "  (resumed)" : ""}`,
+        // Same rule as the workspace line: running against somebody's own Claude
+        // home is a real difference in what this instance reads and writes, so it
+        // is stated every run rather than only on the one that decided it.
+        ...(homeChoice.claudeHome !== undefined
+            ? [`  Claude home: ${homeChoice.claudeHome}  (yours — sessions and login shared)`]
+            : []),
         "  Press Ctrl-C to stop.",
         "",
     ].join("\n"));

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

@@ -94,22 +94,48 @@ export interface PaddockConfig {
     /** Absolute path to the built web SPA (served in production). */
     webDist: string;
     /**
-     * Absolute path to the Claude home (`~/.claude`, unless `CLAUDE_HOME` says
-     * otherwise) — the directory whose `projects/<encoded-cwd>/` folders hold
-     * Claude Code's session transcripts.
+     * Absolute path to the Claude home THIS INSTANCE owns — the directory whose
+     * `projects/<encoded-cwd>/` folders hold Claude Code's session transcripts.
+     * Defaults to `<dataDir>/claude-home` (#620); see {@link resolveClaudeHome}
+     * for the full precedence.
      *
      * Resolved ONCE here (#588) rather than re-read from `process.env` at each call
      * site, because it must be the SAME value everywhere: paddock's transcript
      * relocation (`ensureProjectChats`) symlinks `<claudeHome>/projects/<encoded>`
      * at the project's `.chats/`, and the engine's session discovery / adoption
      * resolves transcripts under `FleetManagerOptions.claudeHomePath`. If paddock
-     * honoured `CLAUDE_HOME` while the engine fell back to `os.homedir()/.claude`,
+     * honoured one home while the engine fell back to `os.homedir()/.claude`,
      * detection would scan one home while reads came from another — chats LIST but
      * open EMPTY (herdctl#423 / #588 gotcha 1). The divergence is invisible
-     * whenever `CLAUDE_HOME` equals `$HOME/.claude`, which is exactly why it is
-     * threaded explicitly instead of being left to a shared default.
+     * whenever the two coincide, which is exactly why it is threaded explicitly
+     * instead of being left to a shared default.
      */
     claudeHome: string;
+    /**
+     * Absolute path to the USER's own Claude home — always `os.homedir()/.claude`,
+     * regardless of what {@link claudeHome} resolved to.
+     *
+     * This is a READ-ONLY source (#620), never a destination. Paddock consults it
+     * for exactly two things: adoption (`~/.claude` is where a user's own Claude
+     * Code CLI history lives, which #588 lets them import), and the user-level
+     * config bridge (see `claude-home.ts`). Nothing in paddock moves or deletes
+     * anything under it.
+     */
+    legacyClaudeHome: string;
+    /**
+     * Does paddock OWN {@link claudeHome} — i.e. is it something other than the
+     * user's `~/.claude`?
+     *
+     * The single gate on every mutating transcript operation (#620). Paddock's
+     * self-healing relocation is allowed to migrate a stray real transcript
+     * directory into `.chats/` inside a home it owns, because that directory is
+     * its own doing. Inside the user's home it is somebody else's data — a
+     * `claude` CLI session run in a directory paddock happens to also manage — and
+     * moving it is the destructive behaviour this flag exists to prevent.
+     *
+     * Derived, not configured: `resolve(claudeHome) !== resolve(legacyClaudeHome)`.
+     */
+    ownsClaudeHome: boolean;
     /** Provider-agnostic user-authentication config (see AUTH.md). */
     auth: AuthConfig;
     /** Voice-dictation (Whisper) capability (per-instance; default off). */
@@ -359,6 +385,8 @@ export interface PaddockConfigFile {
     stateDir?: string;
     herdctlConfigPath?: string;
     webDist?: string;
+    /** Claude home override; beneath `CLAUDE_HOME`/`CLAUDE_CONFIG_DIR` (#620). */
+    claudeHome?: string;
     auth?: {
         mode?: string;
         userHeader?: string;
@@ -525,14 +553,49 @@ export declare function loadConfigFile(dataDir: string): PaddockConfigFile;
 export declare function resolveDefaultWebDist(moduleUrl: string): string;
 export declare function loadPaddockConfig(): PaddockConfig;
 /**
- * Resolve the Claude home from the environment — `CLAUDE_HOME`, else
- * `~/.claude`.
+ * The USER's own Claude home — `~/.claude`, always. A read-only source for
+ * adoption and the user-config bridge, never a destination (#620).
+ *
+ * Stays a function (not a constant) because `os.homedir()` must be read at call
+ * time — tests and processes that mutate `HOME` depend on that.
+ */
+export declare function userClaudeHome(): string;
+/**
+ * Resolve the Claude home paddock runs its agents against.
+ *
+ * Precedence, highest first:
+ *
+ * 1. **`CLAUDE_HOME`** — paddock's own long-standing override. Setting it to
+ *    `$HOME/.claude` restores the pre-#620 behaviour exactly, which is the
+ *    documented escape hatch if the relocation causes trouble.
+ * 2. **`CLAUDE_CONFIG_DIR`** — the variable *Claude Code itself* resolves its
+ *    home from. Honouring it is load-bearing, not a courtesy: herdctl
+ *    deliberately refuses to clobber an operator-set `CLAUDE_CONFIG_DIR`
+ *    (herdctl#423), so if paddock picked a different home the SDK would write
+ *    transcripts to one tree while herdctl read from another — the exact
+ *    split-brain #588 fixed. Deferring to it makes that state unreachable.
+ * 3. A `claudeHome:` key in the instance config file.
+ * 4. **`<dataDir>/claude-home`** — the default since #620.
+ *
+ * On the default, and why it changed: paddock already nests herdctl's whole
+ * state dir, the projects tree and the generated `herdctl.yaml` under its data
+ * dir. Transcripts were the one exception, reached by planting symlinks in the
+ * user's home — not a design choice but a constraint, because until
+ * herdctl#423 nothing set `CLAUDE_CONFIG_DIR` and the SDK wrote to `~/.claude`
+ * no matter what paddock configured. With that gone, owning the home makes the
+ * data dir relocatable as a unit, leaves `~/.claude` alone, and (because there
+ * is no longer a `.claude` path component) unblocks agent memory writes, which
+ * the harness refuses for any path containing `.claude`.
+ *
+ * NOT canonical()-ed: this exact string is what herdctl hands Claude Code as
+ * `CLAUDE_CONFIG_DIR`, and canonicalising would silently diverge from the
+ * literal path the two of them encode into `<home>/projects/<encoded-cwd>`.
  *
  * This is the RESOLVER, not the accessor. It is read once by
  * {@link loadPaddockConfig} into {@link PaddockConfig.claudeHome}; runtime code
  * should thread `cfg.claudeHome` rather than call this again, so paddock and the
- * engine can never end up resolving two different homes (#588). It stays a
- * function (not a constant) because `os.homedir()` must be read at call time —
- * tests and processes that mutate `HOME` depend on that.
+ * engine can never end up resolving two different homes (#588).
  */
-export declare function claudeHome(): string;
+export declare function resolveClaudeHome(dataDir: string, fromFile?: string): string;
+/** Directory name of paddock's own Claude home inside the data dir (#620). */
+export declare const DEFAULT_CLAUDE_HOME_DIRNAME = "claude-home";

package/packages/server/dist/config.js

@@ -264,10 +264,10 @@ export function loadPaddockConfig() {
     const herdctlConfigPath = canonical(envOr("PADDOCK_HERDCTL_CONFIG", fileOr(file.herdctlConfigPath, path.join(dataRoot, "herdctl.yaml"))));
     // The ONE Claude home for this process (#588): paddock's transcript symlinks,
     // the engine's session discovery and session adoption all resolve against this
-    // exact value. NOT canonical()-ed: `claudeHome()` is also what the CLI runtime
-    // and Claude Code itself see, and canonicalising would silently diverge from
-    // the literal path they encode into `<home>/projects/<encoded-cwd>`.
-    const resolvedClaudeHome = claudeHome();
+    // exact value — which herdctl in turn hands Claude Code as `CLAUDE_CONFIG_DIR`.
+    // Defaults to `<dataDir>/claude-home` (#620); see `resolveClaudeHome`.
+    const resolvedClaudeHome = resolveClaudeHome(dataDir, fileOpt(file.claudeHome));
+    const legacyClaudeHome = userClaudeHome();
     const defaultWebDist = resolveDefaultWebDist(import.meta.url);
     return Object.freeze({
         port: Number(envOr("PORT", fileOr(file.port, "4000"))),
@@ -285,6 +285,11 @@ export function loadPaddockConfig() {
         herdctlConfigPath,
         webDist: abs(envOr("PADDOCK_WEB_DIST", fileOr(file.webDist, defaultWebDist))),
         claudeHome: resolvedClaudeHome,
+        legacyClaudeHome,
+        // Paddock owns any home that is not the user's own `~/.claude` (#620) —
+        // including one an operator pointed it at explicitly. The user's home is the
+        // only one whose contents belong to somebody else.
+        ownsClaudeHome: path.resolve(resolvedClaudeHome) !== path.resolve(legacyClaudeHome),
         auth: loadAuthConfig(file.auth),
         transcription: loadTranscriptionConfig(file.transcription),
         brand: loadBrandConfig(file.brand),
@@ -610,16 +615,58 @@ function loadDriveMode(file) {
     return raw && isKnownDriveMode(raw) ? raw : DEFAULT_DRIVE_MODE;
 }
 /**
- * Resolve the Claude home from the environment — `CLAUDE_HOME`, else
- * `~/.claude`.
+ * The USER's own Claude home — `~/.claude`, always. A read-only source for
+ * adoption and the user-config bridge, never a destination (#620).
+ *
+ * Stays a function (not a constant) because `os.homedir()` must be read at call
+ * time — tests and processes that mutate `HOME` depend on that.
+ */
+export function userClaudeHome() {
+    return path.join(os.homedir(), ".claude");
+}
+/**
+ * Resolve the Claude home paddock runs its agents against.
+ *
+ * Precedence, highest first:
+ *
+ * 1. **`CLAUDE_HOME`** — paddock's own long-standing override. Setting it to
+ *    `$HOME/.claude` restores the pre-#620 behaviour exactly, which is the
+ *    documented escape hatch if the relocation causes trouble.
+ * 2. **`CLAUDE_CONFIG_DIR`** — the variable *Claude Code itself* resolves its
+ *    home from. Honouring it is load-bearing, not a courtesy: herdctl
+ *    deliberately refuses to clobber an operator-set `CLAUDE_CONFIG_DIR`
+ *    (herdctl#423), so if paddock picked a different home the SDK would write
+ *    transcripts to one tree while herdctl read from another — the exact
+ *    split-brain #588 fixed. Deferring to it makes that state unreachable.
+ * 3. A `claudeHome:` key in the instance config file.
+ * 4. **`<dataDir>/claude-home`** — the default since #620.
+ *
+ * On the default, and why it changed: paddock already nests herdctl's whole
+ * state dir, the projects tree and the generated `herdctl.yaml` under its data
+ * dir. Transcripts were the one exception, reached by planting symlinks in the
+ * user's home — not a design choice but a constraint, because until
+ * herdctl#423 nothing set `CLAUDE_CONFIG_DIR` and the SDK wrote to `~/.claude`
+ * no matter what paddock configured. With that gone, owning the home makes the
+ * data dir relocatable as a unit, leaves `~/.claude` alone, and (because there
+ * is no longer a `.claude` path component) unblocks agent memory writes, which
+ * the harness refuses for any path containing `.claude`.
+ *
+ * NOT canonical()-ed: this exact string is what herdctl hands Claude Code as
+ * `CLAUDE_CONFIG_DIR`, and canonicalising would silently diverge from the
+ * literal path the two of them encode into `<home>/projects/<encoded-cwd>`.
  *
  * This is the RESOLVER, not the accessor. It is read once by
  * {@link loadPaddockConfig} into {@link PaddockConfig.claudeHome}; runtime code
  * should thread `cfg.claudeHome` rather than call this again, so paddock and the
- * engine can never end up resolving two different homes (#588). It stays a
- * function (not a constant) because `os.homedir()` must be read at call time —
- * tests and processes that mutate `HOME` depend on that.
+ * engine can never end up resolving two different homes (#588).
  */
-export function claudeHome() {
-    return process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+export function resolveClaudeHome(dataDir, fromFile) {
+    const env = envOpt("CLAUDE_HOME") ?? envOpt("CLAUDE_CONFIG_DIR");
+    if (env !== undefined)
+        return abs(env);
+    if (fromFile !== undefined && fromFile !== "")
+        return abs(fromFile);
+    return path.join(dataDir, DEFAULT_CLAUDE_HOME_DIRNAME);
 }
+/** Directory name of paddock's own Claude home inside the data dir (#620). */
+export const DEFAULT_CLAUDE_HOME_DIRNAME = "claude-home";

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

@@ -56,15 +56,22 @@ export declare function buildAgentConfig(cfg: PaddockConfig, project: Project, m
  */
 export declare function sweeperWorkingDir(cfg: PaddockConfig, slug: string): string;
 /**
- * A project's sweeper (curator) agent config. TOOL-LESS: the sweeper has NO
- * tools (`allowed_tools: []`) — it never reads or writes files. Instead it
- * RETURNS the curated content as plain assistant text in marked sections
- * (OVERVIEW / CHANGELOG / optional CLAUDE, issue #177); SweepService parses
- * that text and writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
+ * A project's sweeper (curator) agent config. TOOL-LESS BY DESIGN: it declares
+ * `allowed_tools: []` and never reads or writes files. Instead it RETURNS the
+ * curated content as plain assistant text in marked sections (OVERVIEW /
+ * CHANGELOG / optional CLAUDE, issue #177); SweepService parses that text and
+ * writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
  *
  * This is cheaper and far more predictable than letting a Haiku agent drive
  * file edits: no tool-loop turns, no partial writes, no permission_mode /
- * denied_tools to reason about (all irrelevant with zero tools).
+ * denied_tools to reason about.
+ *
+ * What makes it tool-less is NOT the empty `allowed_tools` — herdctl emits an
+ * allow-list only when it is non-empty, so `[]` restricts nothing (#647). The
+ * actual guarantees are: no injected MCP servers (the sweeper is the one turn
+ * path that does not even get `send_file`), `max_turns: 4`, a system prompt
+ * whose first line is "You DO NOT use any tools", and a non-interactive
+ * `claude -p` run that cannot answer a permission prompt.
  */
 export declare function buildSweeperConfig(cfg: PaddockConfig, project: Project): Record<string, unknown> & {
     name: string;
@@ -77,7 +84,8 @@ export declare function buildSweeperConfig(cfg: PaddockConfig, project: Project)
  * (`allowed_tools`/`permission_mode`/`model`/`max_turns`, projected by
  * {@link triggerToAgentToolConfig} from the trigger's `run`) IS its capability set.
  * Runs in the project's WORKING dir (so a trigger's Bash/Write act on the same tree
- * the keeper does). A tool-less trigger gets `allowed_tools: []` and can only return text.
+ * the keeper does). A trigger that declares no tools gets `allowed_tools: []` — which
+ * herdctl does not enforce as a deny-all; see {@link triggerToAgentToolConfig} (#647).
  */
 export declare function buildTriggerConfig(cfg: PaddockConfig, project: Project, triggerName: string, trigger: PaddockTrigger): Record<string, unknown> & {
     name: string;

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

@@ -141,15 +141,22 @@ export function sweeperWorkingDir(cfg, slug) {
     return path.join(cfg.dataDir, "sweepers", slug === "" ? "_root" : slug);
 }
 /**
- * A project's sweeper (curator) agent config. TOOL-LESS: the sweeper has NO
- * tools (`allowed_tools: []`) — it never reads or writes files. Instead it
- * RETURNS the curated content as plain assistant text in marked sections
- * (OVERVIEW / CHANGELOG / optional CLAUDE, issue #177); SweepService parses
- * that text and writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
+ * A project's sweeper (curator) agent config. TOOL-LESS BY DESIGN: it declares
+ * `allowed_tools: []` and never reads or writes files. Instead it RETURNS the
+ * curated content as plain assistant text in marked sections (OVERVIEW /
+ * CHANGELOG / optional CLAUDE, issue #177); SweepService parses that text and
+ * writes OVERVIEW.md / CHANGELOG.md / CLAUDE.md itself.
  *
  * This is cheaper and far more predictable than letting a Haiku agent drive
  * file edits: no tool-loop turns, no partial writes, no permission_mode /
- * denied_tools to reason about (all irrelevant with zero tools).
+ * denied_tools to reason about.
+ *
+ * What makes it tool-less is NOT the empty `allowed_tools` — herdctl emits an
+ * allow-list only when it is non-empty, so `[]` restricts nothing (#647). The
+ * actual guarantees are: no injected MCP servers (the sweeper is the one turn
+ * path that does not even get `send_file`), `max_turns: 4`, a system prompt
+ * whose first line is "You DO NOT use any tools", and a non-interactive
+ * `claude -p` run that cannot answer a permission prompt.
  */
 export function buildSweeperConfig(cfg, project) {
     // T5: the sweeper IS the default `curate-overview` (event/afterTurn) trigger. When a
@@ -171,9 +178,13 @@ export function buildSweeperConfig(cfg, project) {
         // addAgent does deep-merge the loaded defaults, they just never carry it).
         runtime: "cli",
         model: curatorModel ?? SWEEPER_DEFAULT_MODEL,
-        // Tool-less: a handful of turns is plenty since there are no tool loops.
+        // A handful of turns is plenty since there are no tool loops — and this, not
+        // the empty allow-list below, is one of the things actually bounding the run.
         max_turns: 4,
-        // NO tools. The sweeper returns text only; SweepService does the writing.
+        // Declares NO tools: the sweeper returns text only; SweepService does the
+        // writing. Note herdctl does not emit an empty allow-list at all, so this
+        // restricts nothing on its own (#647) — see the doc comment above for the
+        // properties that do make the sweeper tool-less in practice.
         allowed_tools: [],
         system_prompt: "You are a concise project curator. You DO NOT use any tools — you only " +
             "return text. From the recent activity, the current OVERVIEW.md, the " +
@@ -226,7 +237,8 @@ export function buildSweeperConfig(cfg, project) {
  * (`allowed_tools`/`permission_mode`/`model`/`max_turns`, projected by
  * {@link triggerToAgentToolConfig} from the trigger's `run`) IS its capability set.
  * Runs in the project's WORKING dir (so a trigger's Bash/Write act on the same tree
- * the keeper does). A tool-less trigger gets `allowed_tools: []` and can only return text.
+ * the keeper does). A trigger that declares no tools gets `allowed_tools: []` — which
+ * herdctl does not enforce as a deny-all; see {@link triggerToAgentToolConfig} (#647).
  */
 export function buildTriggerConfig(cfg, project, triggerName, trigger) {
     const config = {