@edspencer/paddock 0.60.0 → 0.61.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,8 @@ npx @edspencer/paddock
 
 Then open <http://127.0.0.1:4000>.
 
+Or point it at work you've already done — see [Open your own project](#open-your-own-project).
+
 > **First run downloads ~250 MB.** Paddock drives Claude Code, and the Claude
 > Agent SDK ships a per-platform binary of that size. It cannot be skipped —
 > installing with `--omit=optional` produces a Paddock whose chats all fail.
@@ -24,8 +26,40 @@ 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
+
+```sh
+cd ~/code/some-project        # somewhere you've used Claude Code
+npx @edspencer/paddock --here
+```
+
+`--here` opens **that directory** as Paddock's workspace: Claude works in your files,
+and any Claude Code sessions you already have for the directory are offered for
+import. It's the fastest way to see what Paddock does with real history instead of an
+empty instance. Later runs in the same directory resume it — no flag needed.
+
+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`**
+
+**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.
+
+Without `--here`, Paddock never touches the directory you ran it from.
 
 ## Options
 
@@ -33,11 +67,18 @@ automatically and there is nothing to do.
   -p, --port <port>       HTTP/WS port (default 4000)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock)
+      --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
 ```
 
-Your projects, chats and settings live in `~/.paddock` and persist between runs.
+Your projects, chats and settings persist between runs in `~/.paddock` — or in
+`<dir>/.paddock` when you use `--here`. Either way it's one directory: move it to
+move your instance, delete it to start over.
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.60.0",
+  "version": "0.61.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -53,7 +53,8 @@
     "packages/server/package.json",
     "packages/web/dist",
     "install-notice.mjs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public",

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

@@ -21,8 +21,22 @@ export interface AdoptableCandidate {
 }
 /** One working directory that has adoptable sessions, and which ones. */
 export interface AdoptableSource {
-    /** The working directory whose transcript folder holds these sessions. */
+    /**
+     * The working directory whose transcript folder holds these sessions — the
+     * DISPLAY identity, and the value a client round-trips back to import one
+     * source. Always a directory the user would recognise.
+     */
     sourceCwd: string;
+    /**
+     * The path the ENGINE must be handed to read this source, when that differs
+     * from {@link sourceCwd} (#620).
+     *
+     * It differs for the user's own `~/.claude` history, which paddock reaches
+     * through a mirror named for a synthetic path — see
+     * `mirrorLegacyTranscriptFolders`. Server-internal: absent means "same as
+     * sourceCwd", and clients neither send it nor need to know it exists.
+     */
+    importFrom?: string;
     /**
      * Adoptable session ids, newest transcript first.
      *
@@ -142,6 +156,16 @@ export interface AdoptableFleet {
 export declare class AdoptableIndex {
     private readonly claudeHomePath;
     private readonly stateDir;
+    /**
+     * The user's own `~/.claude` (#620). Now that paddock owns its Claude home,
+     * the user's CLI history — the entire point of adoption — is no longer under
+     * `claudeHomePath`, and the engine resolves every adoption path against the
+     * one home the FleetManager was built with, with no per-call override.
+     * {@link scanFolders} therefore mirrors the legacy folders in first,
+     * read-only. Defaults to `claudeHomePath` (i.e. no mirroring at all) for
+     * callers still running in the user's own home.
+     */
+    private readonly legacyClaudeHomePath;
     /** folder name → last-seen entry, reused while its `key` is unchanged. */
     private readonly folders;
     /**
@@ -153,7 +177,17 @@ export declare class AdoptableIndex {
     private readonly remotes;
     /** project key → cached summary + the composite key it was computed under. */
     private readonly summaries;
-    constructor(claudeHomePath: string, stateDir: string);
+    constructor(claudeHomePath: string, stateDir: string, 
+    /**
+     * The user's own `~/.claude` (#620). Now that paddock owns its Claude home,
+     * the user's CLI history — the entire point of adoption — is no longer under
+     * `claudeHomePath`, and the engine resolves every adoption path against the
+     * one home the FleetManager was built with, with no per-call override.
+     * {@link scanFolders} therefore mirrors the legacy folders in first,
+     * read-only. Defaults to `claudeHomePath` (i.e. no mirroring at all) for
+     * callers still running in the user's own home.
+     */
+    legacyClaudeHomePath?: string);
     /**
      * Drop a project's cached summary (or every project's, with no argument).
      * Called after an import, which changes the adoptable set in a way the caller

package/packages/server/dist/adoptable.js

@@ -73,6 +73,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { encodePathForCli, readSessionCwd } from "@herdctl/core";
 import { repoCheckoutName } from "./project-paths.js";
+import { mirrorLegacyTranscriptFolders } from "./claude-home.js";
 /**
  * Minimum transcript size to be worth offering, in bytes.
  *
@@ -290,6 +291,7 @@ async function dirKey(dir) {
 export class AdoptableIndex {
     claudeHomePath;
     stateDir;
+    legacyClaudeHomePath;
     /** folder name → last-seen entry, reused while its `key` is unchanged. */
     folders = new Map();
     /**
@@ -301,9 +303,20 @@ export class AdoptableIndex {
     remotes = new Map();
     /** project key → cached summary + the composite key it was computed under. */
     summaries = new Map();
-    constructor(claudeHomePath, stateDir) {
+    constructor(claudeHomePath, stateDir, 
+    /**
+     * The user's own `~/.claude` (#620). Now that paddock owns its Claude home,
+     * the user's CLI history — the entire point of adoption — is no longer under
+     * `claudeHomePath`, and the engine resolves every adoption path against the
+     * one home the FleetManager was built with, with no per-call override.
+     * {@link scanFolders} therefore mirrors the legacy folders in first,
+     * read-only. Defaults to `claudeHomePath` (i.e. no mirroring at all) for
+     * callers still running in the user's own home.
+     */
+    legacyClaudeHomePath = claudeHomePath) {
         this.claudeHomePath = claudeHomePath;
         this.stateDir = stateDir;
+        this.legacyClaudeHomePath = legacyClaudeHomePath;
     }
     /**
      * Drop a project's cached summary (or every project's, with no argument).
@@ -325,6 +338,12 @@ export class AdoptableIndex {
      * folders whose file set changed since last time.
      */
     async scanFolders() {
+        // Bring the user's own transcript folders into view first (#620). Idempotent,
+        // and it must happen BEFORE the readdir below rather than once at boot: a
+        // directory the user `claude`s in for the first time today should become
+        // adoptable without restarting paddock.
+        const mirrors = await mirrorLegacyTranscriptFolders(this.claudeHomePath, this.legacyClaudeHomePath);
+        const mirrorCwds = new Map(mirrors.map((m) => [m.name, m.engineCwd]));
         const root = path.join(this.claudeHomePath, "projects");
         const names = await fs.readdir(root).catch(() => []);
         const out = [];
@@ -339,11 +358,16 @@ export class AdoptableIndex {
                 out.push(cached);
                 continue;
             }
+            const cwd = await recordedCwd(dir);
             const entry = {
                 name,
                 realPath: await fs.realpath(dir).catch(() => dir),
                 key,
-                cwd: await recordedCwd(dir),
+                cwd,
+                // A mirror is reachable ONLY under its synthetic path: its folder name is
+                // not `encodePathForCli(cwd)`, so handing the engine the recorded cwd
+                // would send it to the project's own folder instead (#620).
+                engineCwd: mirrorCwds.get(name) ?? cwd,
             };
             this.folders.set(name, entry);
             out.push(entry);
@@ -405,7 +429,7 @@ export class AdoptableIndex {
         const seen = new Set([ownReal]);
         const sources = [];
         for (const folder of folders) {
-            if (folder.cwd === null || !nameMatches(folder.cwd))
+            if (folder.cwd === null || folder.engineCwd === null || !nameMatches(folder.cwd))
                 continue;
             if (seen.has(folder.realPath))
                 continue;
@@ -418,13 +442,19 @@ export class AdoptableIndex {
                     continue;
             }
             seen.add(folder.realPath);
-            sources.push(folder.cwd);
+            // Display the cwd the user recognises; hand the engine whatever actually
+            // reaches this folder (#620). For everything but a legacy mirror the two
+            // are the same string.
+            sources.push({ display: folder.cwd, engine: folder.engineCwd });
         }
         // The project's own working directory goes LAST so that a session offered by
         // both it and an external checkout is attributed to the external one — the
         // origin, where the transcript actually lives, so a copy has something to
-        // copy (#588 gotcha 2).
-        sources.push(own);
+        // copy (#588 gotcha 2). Post-#620 that ordering earns its keep again: the
+        // user's `~/.claude` folder for this very cwd and the project's own `.chats/`
+        // are now two DIFFERENT directories that both display as `own`, and the
+        // user's is the one a copy can be taken from.
+        sources.push({ display: own, engine: own });
         return sources;
     }
     /**
@@ -442,8 +472,9 @@ export class AdoptableIndex {
         // so an empty cwd is a value that genuinely occurs here. Written as the
         // escape, never a raw NUL byte: a raw NUL makes ripgrep classify the whole
         // file as binary and skip it, so the file vanishes from code search (#570).
+        const matchedEngineCwds = new Set(sources.map((s) => s.engine));
         const matchedKeys = folders
-            .filter((f) => sources.includes(f.cwd ?? "\u0000"))
+            .filter((f) => matchedEngineCwds.has(f.engineCwd ?? "\u0000"))
             .map((f) => `${f.name}=${f.key}`)
             .sort();
         const key = [
@@ -459,10 +490,15 @@ export class AdoptableIndex {
         const out = [];
         const filtered = [];
         let count = 0;
-        for (const sourceCwd of sources) {
+        for (const source of sources) {
+            const sourceCwd = source.display;
             // Fault-isolated per source: an unreadable folder costs its own sessions,
             // not the whole count.
-            const sessions = await fleet.listAdoptableSessions(agentName, sourceCwd).catch(() => []);
+            // Read through `source.engine`, NOT `sourceCwd`: a legacy mirror is only
+            // reachable under its synthetic path (#620).
+            const sessions = await fleet
+                .listAdoptableSessions(agentName, source.engine)
+                .catch(() => []);
             const candidates = [];
             for (const session of sessions) {
                 // De-dup by session id. Two candidate cwds can collide onto one folder
@@ -485,10 +521,14 @@ export class AdoptableIndex {
                 });
             }
             if (candidates.length > 0) {
-                // Both projections built HERE, from one array, so `sessionIds` can never
-                // disagree with `sessions`.
+                // `importFrom` is carried only when it actually differs, so an ordinary
+                // source's DTO is byte-identical to what it was before #620.
+                //
+                // Both id/detail projections are built HERE, from one array, so
+                // `sessionIds` can never disagree with `sessions`.
                 out.push({
                     sourceCwd,
+                    ...(source.engine === sourceCwd ? {} : { importFrom: source.engine }),
                     sessionIds: candidates.map((c) => c.sessionId),
                     sessions: candidates,
                 });

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,6 +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, 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";
@@ -73,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 },
     });
@@ -150,6 +157,35 @@ export async function buildApp(opts = {}) {
     // root workspace itself is never in it. It always exists — the instance's own
     // directory — so resolve it explicitly and register its keeper alongside every
     // child's. The root keeper is an ordinary keeper in every respect.
+    // Paddock's own Claude home (#620) — created and bridged BEFORE the fleet
+    // starts, because `herdctl.init` immediately plants every project's transcript
+    // symlink inside it and hands the same path to the FleetManager.
+    for (const notice of (await ensureClaudeHome(cfg)).notices) {
+        app.log[notice.level](notice.message);
+    }
+    if (cfg.ownsClaudeHome) {
+        const stale = await countLegacyTranscriptLinks(cfg.legacyClaudeHome, cfg.dataDir);
+        if (stale > 0) {
+            app.log.info(`${stale} transcript symlink(s) from a previous layout still point into ${cfg.dataDir} ` +
+                `from ${path.join(cfg.legacyClaudeHome, "projects")}. Nothing reads them any more; ` +
+                `paddock leaves them alone because it does not write to ~/.claude. Safe to delete.`);
+        }
+    }
+    // #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 {