@edspencer/paddock 0.60.0 → 0.61.0

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.
@@ -27,17 +29,45 @@ 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.
 
+## 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`**
+- **links** `~/.claude/projects/<encoded-dir>` at the workspace — your Claude Code
+  history is linked, never moved or copied
+
+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
 
 ```
   -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)
   -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.0",
   "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/app.js

@@ -19,6 +19,7 @@ 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 { ProjectStore, ROOT_KEY } from "./projects.js";
 import { AttachmentStore } from "./attachments.js";
 import { HerdctlService } from "./herdctl.js";
@@ -150,6 +151,20 @@ 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.`);
+        }
+    }
     const rootWorkspace = await projects.get(ROOT_KEY);
     const initialProjects = [...(await projects.list()), rootWorkspace];
     try {

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

@@ -0,0 +1,125 @@
+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"];
+/** 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): 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>;