@edspencer/paddock 0.61.0 → 0.61.1

package/README.md

@@ -26,8 +26,11 @@ claude setup-token                  # Claude Max/Pro
 export ANTHROPIC_API_KEY=sk-ant-…   # or API billing
 ```
 
-If you already use Claude Code on this machine, your existing login is picked up
-automatically and there is nothing to do.
+If you already use Claude Code on this machine, there is nothing to do: with no token
+in the environment, Paddock runs against your own `~/.claude` and uses the login
+already there — including one held in the **macOS Keychain**, which cannot be shared
+any other way. Pass `--isolated-claude-home` to give Paddock a Claude home of its own
+instead.
 
 ## Open your own project
 
@@ -45,8 +48,14 @@ The flag is the consent, so here is everything it does:
 
 - creates **`.paddock/`** for the workspace's state and **`.chats/`** for transcripts
 - appends those two entries to **`.gitignore`**
-- **links** `~/.claude/projects/<encoded-dir>` at the workspace — your Claude Code
-  history is linked, never moved or copied
+
+**Nothing is written into your `~/.claude`, ever** — no file, no symlink, in any
+configuration. Sessions found there are *offered* for import: nothing is moved, copied
+or linked until you confirm, and your terminal `claude` keeps working exactly as
+before. What varies is which Claude home Paddock runs against, and it says which on
+startup — with a token in the environment (or `--isolated-claude-home`) it uses its own
+under `.paddock/` and relocates transcripts into `.chats/`; without one it uses your
+`~/.claude`, and transcripts stay there instead.
 
 To undo it: `rm -rf .paddock .chats` and drop the two `.gitignore` lines.
 
@@ -61,6 +70,8 @@ Without `--here`, Paddock never touches the directory you ran it from.
       --here              Open the CURRENT directory as the workspace
   -o, --open              Open the app in your browser once it is listening
       --verbose           Show the server's own logs (quiet by default)
+      --isolated-claude-home
+                          Use Paddock's own Claude home instead of ~/.claude
   -v, --version           Print the version
   -h, --help              Show help
 ```

package/package.json

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

package/packages/server/dist/agent-errors.d.ts

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

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

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

package/packages/server/dist/app.js

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

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

@@ -21,6 +21,38 @@ import type { PaddockConfig } from "./config.js";
  * `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";
@@ -43,7 +75,7 @@ export interface ClaudeHomeReport {
  * — 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): Promise<ClaudeHomeReport>;
+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)`. */
@@ -123,3 +155,38 @@ export declare function mirrorLegacyTranscriptFolders(claudeHome: string, legacy
  * 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

@@ -66,6 +66,56 @@ export const BRIDGED_ENTRIES = [
 ];
 /** 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
@@ -84,7 +134,7 @@ async function exists(p) {
  * — 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) {
+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 });
@@ -146,14 +196,29 @@ export async function ensureClaudeHome(cfg, env = process.env) {
     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: `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.`,
+            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;
@@ -274,3 +339,49 @@ export async function countLegacyTranscriptLinks(legacyHome, dataDir) {
     }
     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.

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;