@edspencer/paddock 0.60.0 → 0.61.0

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

@@ -0,0 +1,276 @@
+/**
+ * Paddock's OWN Claude home (#620).
+ *
+ * Paddock already acts as the outer container for everything it owns: the
+ * projects tree, herdctl's entire state dir, the generated `herdctl.yaml`. Claude
+ * Code's transcripts were the one exception — they lived in the user's
+ * `~/.claude` and were reached by planting symlinks into it from outside. That
+ * was never a design choice. Claude Code resolves its home from
+ * `CLAUDE_CONFIG_DIR`, and until herdctl#423 nothing set it, so whatever home
+ * paddock configured the SDK still wrote to `~/.claude`. The symlink was the only
+ * lever there was.
+ *
+ * With `CLAUDE_CONFIG_DIR` now threaded (herdctl#423, `@herdctl/core@5.29.0`),
+ * paddock points Claude Code at `<dataDir>/claude-home` and `~/.claude` becomes a
+ * READ-ONLY source. This module owns everything that follows from that:
+ *
+ *  - **{@link ensureClaudeHome}** — create the home, bridge the user-level config
+ *    that lives in `~/.claude`, and report anything an operator needs to know.
+ *  - **{@link mirrorLegacyTranscriptFolders}** — keep adoption (#588) able to see
+ *    the user's own CLI history, which by definition is in `~/.claude`.
+ *
+ * ## The invariant
+ *
+ * **Paddock never moves, deletes or overwrites anything under `~/.claude`.**
+ *
+ * Stated precisely, because the bridge below does create symlinks POINTING at
+ * files in there, and Claude Code writing through one of those (refreshing an
+ * OAuth token, installing a plugin) does land in the user's home. That is Claude
+ * Code maintaining its own store in the place it has always kept it, which is
+ * what a user wants; it is not paddock relocating their data behind their back.
+ * The thing #620 exists to stop — `ensureProjectChats` copying a user's
+ * transcripts out and then `fs.rm`-ing the originals, unprompted, inside a bare
+ * `catch {}` — is gone, gated on `PaddockConfig.ownsClaudeHome`.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { encodePathForCli } from "@herdctl/core";
+/**
+ * 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.
+ */
+export const BRIDGED_ENTRIES = [
+    ".credentials.json",
+    "settings.json",
+    "CLAUDE.md",
+    "agents",
+    "commands",
+    "plugins",
+];
+/** 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"];
+/** Does `p` exist (following symlinks)? */
+async function exists(p) {
+    return fs
+        .stat(p)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * Create paddock's Claude home and bridge the user-level config into it.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export async function ensureClaudeHome(cfg, env = process.env) {
+    const report = { bridged: [], notices: [] };
+    try {
+        await fs.mkdir(path.join(cfg.claudeHome, "projects"), { recursive: true });
+    }
+    catch (err) {
+        report.notices.push({
+            level: "warn",
+            message: `could not create the Claude home at ${cfg.claudeHome} (${String(err)}) — ` +
+                `Claude Code will fall back to its own default and transcripts will not be ` +
+                `relocated into each project's .chats/`,
+        });
+        return report;
+    }
+    // Running in the user's own home is the pre-#620 layout: nothing to bridge
+    // (the files are already there) and nothing to warn about.
+    if (!cfg.ownsClaudeHome) {
+        report.notices.push({
+            level: "info",
+            message: `Claude home: ${cfg.claudeHome} (the user's own — paddock is not managing it)`,
+        });
+        return report;
+    }
+    for (const entry of BRIDGED_ENTRIES) {
+        const target = path.join(cfg.legacyClaudeHome, entry);
+        const link = path.join(cfg.claudeHome, entry);
+        // lstat, not stat: a bridge symlink planted on a previous boot whose target
+        // has since been removed still occupies the name, and re-linking it would be
+        // a no-op churn at best.
+        const occupied = await fs
+            .lstat(link)
+            .then(() => true)
+            .catch(() => false);
+        if (occupied)
+            continue;
+        if (!(await exists(target)))
+            continue;
+        try {
+            await fs.symlink(target, link);
+            report.bridged.push(entry);
+        }
+        catch {
+            /* a race with another instance, or a read-only home — not fatal */
+        }
+    }
+    report.notices.push({
+        level: "info",
+        message: `Claude home: ${cfg.claudeHome} (paddock-owned; ~/.claude is read-only)` +
+            (report.bridged.length > 0 ? ` — bridged from ~/.claude: ${report.bridged.join(", ")}` : ""),
+    });
+    // The credential question (#620). Claude Code derives its secure-storage
+    // service name from whether `CLAUDE_CONFIG_DIR` is SET AT ALL — unset gets the
+    // plain name, set gets a path-hash suffix. Pointing paddock at its own home
+    // means it is always set, so a login held in the macOS Keychain under the plain
+    // name will not be found. A token in the environment is unaffected, and a
+    // file-based login is bridged above; if neither applies we cannot see the
+    // credential at all, so say so BEFORE the first turn fails with "Not logged in"
+    // rather than leaving the operator to work it out from a chat that never
+    // replies.
+    const hasTokenEnv = TOKEN_ENV_VARS.some((v) => (env[v] ?? "").trim().length > 0);
+    const hasCredentialFile = await exists(path.join(cfg.claudeHome, ".credentials.json"));
+    if (!hasTokenEnv && !hasCredentialFile) {
+        report.notices.push({
+            level: "warn",
+            message: `no Claude credentials found for ${cfg.claudeHome}: no .credentials.json and no ` +
+                `${TOKEN_ENV_VARS.join("/")} in the environment. Claude Code scopes its credential ` +
+                `store to CLAUDE_CONFIG_DIR, so a login stored in the OS keychain against the ` +
+                `default home will NOT be found here. If turns fail with "Not logged in", either ` +
+                `re-run \`claude login\` with CLAUDE_CONFIG_DIR=${cfg.claudeHome}, or set ` +
+                `CLAUDE_HOME=${cfg.legacyClaudeHome} to keep using the previous layout.`,
+        });
+    }
+    return report;
+}
+/**
+ * The synthetic working directory a legacy transcript folder is offered to the
+ * engine under: the folder's own path inside the user's home.
+ *
+ * Any stable, per-folder, collision-free path would do. This one is the obvious
+ * choice because it already exists, is unique by construction, and is honest
+ * about where the transcripts actually are.
+ */
+export function legacySourcePath(legacyHome, folderName) {
+    return path.join(legacyHome, "projects", folderName);
+}
+/**
+ * Make the user's own transcript folders visible through paddock's Claude home,
+ * so adoption (#588) still finds them.
+ *
+ * Adoption's whole premise is "you already have terminal `claude` history for
+ * this directory" — and that history is, by definition, in `~/.claude`. But the
+ * engine resolves every adoption path against the ONE home the FleetManager was
+ * built with, with no per-call override, so once paddock owns its home the
+ * user's folders are out of reach. Without this, #620 would silently gut #588.
+ *
+ * The fix is a read-only view: symlink each of the user's folders into
+ * `<claudeHome>/projects/`. The engine then reads their transcripts through it,
+ * and adoption's default `copy` mode writes the copy into the project's own
+ * folder (itself the symlink to `.chats/`) — originals read, never touched.
+ *
+ * ## Why the mirror is not named after the recorded cwd
+ *
+ * The obvious mirror name — the same encoded name the user's folder has — is
+ * wrong, and wrong in exactly the case adoption exists for. A folder's name is
+ * `encodePathForCli(cwd)`, so the user's history for `/code/thing` and a paddock
+ * project whose working directory IS `/code/thing` want the SAME name in the
+ * same directory. Paddock's `.chats/` symlink is already there and must stay, so
+ * the user's folder loses — and "I pointed a project at a directory I already
+ * have `claude` history for", the headline case, silently offers nothing.
+ *
+ * (Pre-#620 this case worked only because `ensureProjectChats` had already MOVED
+ * those transcripts into `.chats/` and deleted the originals. That destruction is
+ * the thing #620 removes, so the case now needs a real mechanism.)
+ *
+ * So each mirror is named for a SYNTHETIC working directory
+ * ({@link legacySourcePath}) that no agent will ever have, which makes
+ * collisions structurally impossible rather than merely unlikely. The caller
+ * keeps the folder's real recorded cwd for display and hands `engineCwd` to the
+ * engine — see `AdoptableSource.importFrom`.
+ *
+ * Entries in the legacy home that are themselves SYMLINKS are skipped: those are
+ * ones paddock planted under the old layout, pointing back at some `.chats/`, and
+ * mirroring them would re-offer paddock's own chats as "adoptable". That also
+ * makes the leftovers from before this change inert rather than confusing.
+ *
+ * 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.
+ */
+export async function mirrorLegacyTranscriptFolders(claudeHome, legacyHome) {
+    if (path.resolve(claudeHome) === path.resolve(legacyHome))
+        return [];
+    const from = path.join(legacyHome, "projects");
+    const to = path.join(claudeHome, "projects");
+    const mirrors = [];
+    try {
+        const names = await fs.readdir(from).catch(() => []);
+        if (names.length === 0)
+            return [];
+        await fs.mkdir(to, { recursive: true });
+        for (const folderName of names) {
+            const legacyDir = path.join(from, folderName);
+            const st = await fs.lstat(legacyDir).catch(() => null);
+            if (!st?.isDirectory())
+                continue; // skips files AND paddock's old symlinks
+            const engineCwd = legacySourcePath(legacyHome, folderName);
+            // encodePathForCli, not a local encoder: this name must be byte-identical
+            // to what the engine derives from `engineCwd`, including the truncate+hash
+            // branch it takes past 200 chars.
+            const name = encodePathForCli(engineCwd);
+            const link = path.join(to, name);
+            const occupied = await fs
+                .lstat(link)
+                .then(() => true)
+                .catch(() => false);
+            if (!occupied) {
+                const ok = await fs.symlink(legacyDir, link).then(() => true, () => false);
+                if (!ok)
+                    continue;
+            }
+            mirrors.push({ name, engineCwd, legacyDir });
+        }
+    }
+    catch {
+        /* non-fatal: adoption just sees fewer sources */
+    }
+    return mirrors;
+}
+/**
+ * Count the transcript symlinks a paddock instance planted in the user's home
+ * under the pre-#620 layout that point back into THIS data dir.
+ *
+ * Purely informational. They are harmless — they still resolve, and nothing
+ * reads them any more — but they accumulate one per project per instance and go
+ * stale as soon as a data dir is deleted, so an operator is better off being
+ * told they exist than discovering a pile of dangling links months later.
+ * Paddock does not remove them itself: they live in `~/.claude`, and not writing
+ * there is the entire point.
+ */
+export async function countLegacyTranscriptLinks(legacyHome, dataDir) {
+    const root = path.join(legacyHome, "projects");
+    const names = await fs.readdir(root).catch(() => []);
+    const prefix = path.resolve(dataDir) + path.sep;
+    let count = 0;
+    for (const name of names) {
+        const target = await fs.readlink(path.join(root, name)).catch(() => null);
+        if (target !== null && path.resolve(target).startsWith(prefix))
+            count++;
+    }
+    return count;
+}

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

@@ -89,34 +89,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.
  *
@@ -147,7 +119,7 @@ function announceHereConsent(dir, dataDir) {
         "",
         `  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",
+        "    · ~/.claude sessions for this directory are offered for import (nothing is moved)",
         "  Later runs here resume it — no flag needed.",
         "",
     ].join("\n"));
@@ -172,7 +144,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"));
 }
@@ -273,7 +245,13 @@ async function main() {
         if (process.env.HERDCTL_LOG_LEVEL === undefined)
             process.env.HERDCTL_LOG_LEVEL = "warn";
     }
-    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 — `<dataDir>/claude-home` since #620 — after the
+    // bridge has symlinked in any `~/.claude/.credentials.json`, and its remedy
+    // names the `CLAUDE_CONFIG_DIR` keychain scoping that is the real reason a
+    // logged-in user can still land with no credentials. It logs at `warn`, which
+    // survives the quiet default set just above.
     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

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;