@edspencer/paddock 0.60.0 → 0.61.1

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

@@ -0,0 +1,192 @@
+import type { PaddockConfig } from "./config.js";
+/**
+ * Entries of a Claude home that are USER-LEVEL configuration rather than
+ * per-instance state, symlinked from the user's home into paddock's own when
+ * paddock's does not already have its own.
+ *
+ * Without this, relocating the home silently changes agent behaviour: the user's
+ * `~/.claude/CLAUDE.md` is auto-loaded into every session, `settings.json`
+ * carries permissions and hooks, and `agents/` `commands/` `plugins/` are
+ * capability. Dropping them is not "a clean home", it is a behaviour regression
+ * nobody asked for.
+ *
+ * `.credentials.json` is the one that matters most: on Linux (and in the Docker
+ * image) it is where `claude login` puts the OAuth token, so without the bridge
+ * every file-authenticated install would come back logged out. Symlinked rather
+ * than copied — a copy would duplicate a live secret onto disk AND diverge the
+ * moment Claude Code refreshed the token.
+ *
+ * Deliberately NOT bridged: `projects/` (that's the whole point), and everything
+ * that is per-instance runtime state — `todos/`, `shell-snapshots/`, `statsig/`,
+ * `sessions/`. Those are exactly what should now be per-instance.
+ */
+export declare const BRIDGED_ENTRIES: readonly [".credentials.json", "settings.json", "CLAUDE.md", "agents", "commands", "plugins"];
+/**
+ * What a Keychain probe concluded.
+ *
+ * `unknown` is the important one and the default: not darwin, no `security`
+ * binary, the lookup errored, or we simply did not find an entry under a name we
+ * guessed. It must never be reported to the user as "you have no login".
+ */
+export type KeychainFinding = "found" | "unknown";
+/** Probe for a macOS login paddock's own home cannot see. Injectable for tests. */
+export type KeychainProbe = () => Promise<KeychainFinding>;
+/**
+ * Ask the macOS Keychain whether a plain-name Claude Code login exists (#683).
+ *
+ * The whole value of this is turning "you appear to have no credentials" into
+ * "you ARE logged in; paddock cannot see it, and here is the one-liner" — a
+ * distinction paddock currently cannot make, and the difference between a
+ * message that describes a problem and one that fixes it.
+ *
+ * ## The asymmetry, which is deliberate
+ *
+ * A positive result is trustworthy: an entry under that service name is a login.
+ * A negative result is NOT — the service name is Claude Code's internal detail
+ * and can change, and `security` can fail for a dozen reasons that have nothing
+ * to do with the user. So a miss returns `unknown`, and the caller falls back to
+ * the existing, correct, generic warning. Guessing the name wrong therefore
+ * costs nothing beyond the improvement not happening.
+ *
+ * Never prompts and never reads a secret: `find-generic-password` WITHOUT `-w`
+ * reports existence only (attributes, which are discarded), so nothing sensitive
+ * reaches a log, a transcript, or this process's memory.
+ */
+export declare function probeMacosKeychainLogin(platform?: string): Promise<KeychainFinding>;
+/** A message for the operator, at the level it should be logged at. */
+export interface ClaudeHomeNotice {
+    level: "info" | "warn";
+    message: string;
+}
+export interface ClaudeHomeReport {
+    /** Entries symlinked in from the user's home this boot. */
+    bridged: string[];
+    /** Messages for `app.ts` to log — config resolution has no logger of its own. */
+    notices: ClaudeHomeNotice[];
+}
+/**
+ * Create paddock's Claude home and bridge the user-level config into it.
+ *
+ * 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 declare function ensureClaudeHome(cfg: Pick<PaddockConfig, "claudeHome" | "legacyClaudeHome" | "ownsClaudeHome">, env?: NodeJS.ProcessEnv, probeKeychain?: KeychainProbe): Promise<ClaudeHomeReport>;
+/** One of the user's transcript folders, made readable through paddock's home. */
+export interface LegacyMirror {
+    /** Folder name inside `<claudeHome>/projects/` — `encodePathForCli(engineCwd)`. */
+    name: string;
+    /**
+     * The working directory the ENGINE must be handed to read this folder.
+     *
+     * Not the real cwd the transcripts were recorded in — see
+     * {@link mirrorLegacyTranscriptFolders} for why it cannot be.
+     */
+    engineCwd: string;
+    /** The user's real folder in `<legacyHome>/projects/`, which we only read. */
+    legacyDir: string;
+}
+/**
+ * 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 declare function legacySourcePath(legacyHome: string, folderName: string): string;
+/**
+ * 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 declare function mirrorLegacyTranscriptFolders(claudeHome: string, legacyHome: string): Promise<LegacyMirror[]>;
+/**
+ * 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 declare function countLegacyTranscriptLinks(legacyHome: string, dataDir: string): Promise<number>;
+/** A `~/.claude/projects/<enc>` symlink pointing at some `.chats/` store. */
+export interface PlantedChatsLink {
+    /** The link itself, inside the user's home — the path to tell the user about. */
+    link: string;
+    /** What it points at, resolved. Always a `.chats` directory by construction. */
+    target: string;
+    /** Does the target still exist? A dangling link is the one that breaks tooling. */
+    dangling: boolean;
+}
+/**
+ * Find transcript symlinks planted in the user's home that point at a `.chats/`
+ * store OUTSIDE `dataDir` (#682).
+ *
+ * The instance's own leftovers — links into this data dir — are already reported
+ * by {@link countLegacyTranscriptLinks} as harmless pre-#620 residue, and they
+ * are: they were planted for a project whose transcripts paddock does own.
+ *
+ * The ones this finds are the poisoned kind. Under `--here` the workspace's
+ * `.chats/` sits at `<dir>/.chats` while the data dir is `<dir>/.paddock`, so a
+ * link planted by an affected build points somewhere no `dataDir` prefix match
+ * will ever catch. While it exists, every `claude` session the user starts in
+ * that directory writes into paddock's store instead of their own history, and
+ * anything that expects `~/.claude/projects/<enc>` to be a real directory
+ * (`unzip -d ~/.claude` being the observed one) fails with an error impossible
+ * to trace back here.
+ *
+ * Reported, never removed. Paddock not writing to `~/.claude` is the entire
+ * point of #620, and that has to include cleaning up after itself — a boot that
+ * silently deleted something under there would be the same class of surprise in
+ * the opposite direction. Naming the exact path is enough: `rm` is one command
+ * and the user can see what they are removing first.
+ *
+ * Never throws; an unreadable home just yields no findings.
+ */
+export declare function findPlantedChatsLinks(legacyHome: string, dataDir: string): Promise<PlantedChatsLink[]>;

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

@@ -0,0 +1,387 @@
+/**
+ * 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"];
+/**
+ * Keychain service names Claude Code is known to store its login under.
+ *
+ * Only the unsuffixed form matters here: with `CLAUDE_CONFIG_DIR` set, Claude
+ * Code appends a path hash, and an entry under THAT name is one paddock's own
+ * home can already see. What we are looking for is the login made before paddock
+ * was involved.
+ *
+ * More than one candidate because the name is Claude Code's private detail, not
+ * a contract — see {@link probeMacosKeychainLogin} for why guessing wrong here
+ * is designed to be harmless.
+ */
+const KEYCHAIN_SERVICE_NAMES = ["Claude Code-credentials", "Claude Code"];
+/**
+ * Ask the macOS Keychain whether a plain-name Claude Code login exists (#683).
+ *
+ * The whole value of this is turning "you appear to have no credentials" into
+ * "you ARE logged in; paddock cannot see it, and here is the one-liner" — a
+ * distinction paddock currently cannot make, and the difference between a
+ * message that describes a problem and one that fixes it.
+ *
+ * ## The asymmetry, which is deliberate
+ *
+ * A positive result is trustworthy: an entry under that service name is a login.
+ * A negative result is NOT — the service name is Claude Code's internal detail
+ * and can change, and `security` can fail for a dozen reasons that have nothing
+ * to do with the user. So a miss returns `unknown`, and the caller falls back to
+ * the existing, correct, generic warning. Guessing the name wrong therefore
+ * costs nothing beyond the improvement not happening.
+ *
+ * Never prompts and never reads a secret: `find-generic-password` WITHOUT `-w`
+ * reports existence only (attributes, which are discarded), so nothing sensitive
+ * reaches a log, a transcript, or this process's memory.
+ */
+export async function probeMacosKeychainLogin(platform = process.platform) {
+    if (platform !== "darwin")
+        return "unknown";
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const run = promisify(execFile);
+    for (const service of KEYCHAIN_SERVICE_NAMES) {
+        // No `-w`: existence only. Output is discarded either way.
+        const found = await run("security", ["find-generic-password", "-s", service], {
+            timeout: 5_000,
+        }).then(() => true, () => false);
+        if (found)
+            return "found";
+    }
+    return "unknown";
+}
+/** 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, probeKeychain = probeMacosKeychainLogin) {
+    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) {
+        // #683: "you have no login" and "your login exists but I changed the service
+        // name it is filed under" are the same message today, and only one of them is
+        // the user's problem to solve. On darwin we can tell them apart, and a hit
+        // upgrades a paragraph of explanation into an instruction. A miss is
+        // inconclusive by design (see probeMacosKeychainLogin), so it falls through
+        // to the generic wording rather than asserting anything.
+        const keychain = await probeKeychain();
+        report.notices.push({
+            level: "warn",
+            message: keychain === "found"
+                ? `you ARE logged in to Claude Code, but paddock cannot see it. The login is in the ` +
+                    `macOS Keychain, and Claude Code files it under a service name derived from whether ` +
+                    `CLAUDE_CONFIG_DIR is set — paddock sets it, to ${cfg.claudeHome}, so it looks under ` +
+                    `a different name. A Keychain entry cannot be bridged the way ~/.claude files are. ` +
+                    `Fix it either way: run \`CLAUDE_CONFIG_DIR=${cfg.claudeHome} claude login\` to log ` +
+                    `in for this home too, or set CLAUDE_HOME=${cfg.legacyClaudeHome} (what \`paddock\` ` +
+                    `does by default) to run against your own home and use the login you already have.`
+                : `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;
+}
+/**
+ * Find transcript symlinks planted in the user's home that point at a `.chats/`
+ * store OUTSIDE `dataDir` (#682).
+ *
+ * The instance's own leftovers — links into this data dir — are already reported
+ * by {@link countLegacyTranscriptLinks} as harmless pre-#620 residue, and they
+ * are: they were planted for a project whose transcripts paddock does own.
+ *
+ * The ones this finds are the poisoned kind. Under `--here` the workspace's
+ * `.chats/` sits at `<dir>/.chats` while the data dir is `<dir>/.paddock`, so a
+ * link planted by an affected build points somewhere no `dataDir` prefix match
+ * will ever catch. While it exists, every `claude` session the user starts in
+ * that directory writes into paddock's store instead of their own history, and
+ * anything that expects `~/.claude/projects/<enc>` to be a real directory
+ * (`unzip -d ~/.claude` being the observed one) fails with an error impossible
+ * to trace back here.
+ *
+ * Reported, never removed. Paddock not writing to `~/.claude` is the entire
+ * point of #620, and that has to include cleaning up after itself — a boot that
+ * silently deleted something under there would be the same class of surprise in
+ * the opposite direction. Naming the exact path is enough: `rm` is one command
+ * and the user can see what they are removing first.
+ *
+ * Never throws; an unreadable home just yields no findings.
+ */
+export async function findPlantedChatsLinks(legacyHome, dataDir) {
+    const root = path.join(legacyHome, "projects");
+    const names = await fs.readdir(root).catch(() => []);
+    const ownPrefix = path.resolve(dataDir) + path.sep;
+    const found = [];
+    for (const name of names) {
+        const link = path.join(root, name);
+        const raw = await fs.readlink(link).catch(() => null);
+        if (raw === null)
+            continue;
+        const target = path.resolve(path.dirname(link), raw);
+        // `.chats` is paddock's store name and nothing else's — a precise enough
+        // signature that a link the user made themselves won't be misreported.
+        if (path.basename(target) !== ".chats")
+            continue;
+        if (target.startsWith(ownPrefix))
+            continue; // this instance's own residue
+        found.push({ link, target, dangling: !(await exists(target)) });
+    }
+    return found;
+}

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

@@ -32,6 +32,14 @@ export interface CliOptions {
     verbose: boolean;
     help: boolean;
     version: boolean;
+    /**
+     * Keep paddock's own Claude home instead of inheriting the user's (#683).
+     *
+     * The CLI defaults to running against `~/.claude` when there is no token and
+     * no explicit home, because that is the only way a macOS Keychain login is
+     * visible at all. This is the opt-out — see `cli/claude-home-choice.ts`.
+     */
+    isolatedClaudeHome: boolean;
 }
 /** A usage error. Thrown rather than exiting, so parsing stays testable. */
 export declare class CliError extends Error {
@@ -53,4 +61,4 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  * flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 links ~/.claude/projects/<encoded-dir> at this workspace\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials in the\n  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API\n  billing). If you already use Claude Code on this machine, an existing login\n  under ~/.claude is picked up automatically. Otherwise run `claude setup-token`.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n      --isolated-claude-home\n                          Use Paddock's own Claude home instead of ~/.claude\n                          (see Credentials below)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials. With no\n  CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment, it runs\n  against your own ~/.claude and uses the Claude Code login already there \u2014\n  including one held in the macOS Keychain, which cannot be shared any other\n  way. Paddock creates nothing under ~/.claude; your transcripts just stay\n  there rather than being relocated into .chats/, and existing sessions are\n  still offered for import rather than opened for you.\n\n  Pass --isolated-claude-home (or set CLAUDE_HOME) for a Claude home of its\n  own; then a login must be a token in the environment, a ~/.claude\n  .credentials.json, or `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`.\n  With no login at all anywhere, run `claude setup-token`.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";

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

@@ -34,6 +34,7 @@ export function parseArgs(argv) {
         verbose: false,
         help: false,
         version: false,
+        isolatedClaudeHome: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -65,6 +66,9 @@ export function parseArgs(argv) {
             case "--verbose":
                 opts.verbose = true;
                 break;
+            case "--isolated-claude-home":
+                opts.isolatedClaudeHome = true;
+                break;
             case "-h":
             case "--help":
                 opts.help = true;
@@ -124,6 +128,9 @@ Options
       --here              Open the CURRENT directory as the workspace (see below)
   -o, --open              Open the app in your browser once it is listening
       --verbose           Show the server's own logs (quiet by default)
+      --isolated-claude-home
+                          Use Paddock's own Claude home instead of ~/.claude
+                          (see Credentials below)
   -v, --version           Print the Paddock version and exit
   -h, --help              Show this help
 
@@ -134,16 +141,25 @@ Opening a directory (--here)
 
     · creates .paddock/ in the directory for this workspace's own state
     · creates .chats/ for transcripts, and adds both to .gitignore
-    · links ~/.claude/projects/<encoded-dir> at this workspace
+    · offers your ~/.claude sessions for this directory for import — nothing
+      there is moved, copied or linked until you confirm
 
   Once done, later runs in the same directory resume it — no flag needed.
   Without --here, Paddock never touches the directory you ran it from.
 
 Credentials
-  Paddock drives Claude Code, so it needs Claude credentials in the
-  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
-  billing). If you already use Claude Code on this machine, an existing login
-  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
+  Paddock drives Claude Code, so it needs Claude credentials. With no
+  CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment, it runs
+  against your own ~/.claude and uses the Claude Code login already there —
+  including one held in the macOS Keychain, which cannot be shared any other
+  way. Paddock creates nothing under ~/.claude; your transcripts just stay
+  there rather than being relocated into .chats/, and existing sessions are
+  still offered for import rather than opened for you.
+
+  Pass --isolated-claude-home (or set CLAUDE_HOME) for a Claude home of its
+  own; then a login must be a token in the environment, a ~/.claude
+  .credentials.json, or \`CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login\`.
+  With no login at all anywhere, run \`claude setup-token\`.
 
 Your data
   Everything lives in one directory — ~/.paddock unless you pass --data-dir.