@edspencer/paddock 0.59.0 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.29.1",
+    "@herdctl/core": "5.31.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",

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

@@ -1,11 +1,38 @@
 import { type AdoptableSession } from "@herdctl/core";
 import type { Project } from "./projects.js";
+/**
+ * One session on offer, with enough about it to decide (#660).
+ *
+ * The import used to be a single unconfirmed click, so an id was all the count
+ * needed. A confirmation dialog has to show the user WHAT it is about to import —
+ * and on the instance that prompted this, three quarters of the offer was things
+ * the user would have declined on sight. Every field here is already computed by
+ * the engine's scan; none of it costs an extra transcript parse.
+ */
+export interface AdoptableCandidate {
+    sessionId: string;
+    /** ISO 8601 last-modified time of the transcript (also the sort order). */
+    mtime: string;
+    /** First user message, truncated by the engine at 100 chars. */
+    preview?: string;
+    /** Auto-generated session name, when the transcript carries a summary. */
+    autoName?: string;
+    sizeBytes: number;
+}
 /** One working directory that has adoptable sessions, and which ones. */
 export interface AdoptableSource {
     /** The working directory whose transcript folder holds these sessions. */
     sourceCwd: string;
-    /** Adoptable session ids, newest transcript first. */
+    /**
+     * Adoptable session ids, newest transcript first.
+     *
+     * Exactly the ids of {@link sessions}, both built from one array at one site
+     * below so they cannot drift. Kept because it is the documented response shape
+     * and the narrower thing most callers want.
+     */
     sessionIds: string[];
+    /** The same sessions, with what a confirmation dialog needs to describe them. */
+    sessions: AdoptableCandidate[];
 }
 /** A candidate that detection deliberately did NOT offer, and why. */
 export interface FilteredSession {
@@ -14,11 +41,11 @@ export interface FilteredSession {
     reason: FilterReason;
 }
 /**
- * Why a candidate was withheld. Both values are OURS (paddock-side noise
+ * Why a candidate was withheld. All three values are OURS (paddock-side noise
  * filtering); the engine's own exclusions (sidechain / already-adopted /
  * attributed-to-run) never reach us as candidates at all.
  */
-export type FilterReason = "too-small" | "slash-command-only";
+export type FilterReason = "too-small" | "slash-command-only" | "sweeper-run";
 /** What a project could import right now. */
 export interface AdoptableSummary {
     /** Total adoptable sessions across every source, after de-dup and filtering. */
@@ -55,6 +82,33 @@ export declare const MIN_TRANSCRIPT_BYTES = 256;
  * more than a command plus its output, comfortably less than a conversation.
  */
 export declare const SLASH_COMMAND_MAX_BYTES = 4096;
+/**
+ * Does this transcript preview look like paddock's own sweeper run (#658)?
+ *
+ * Exported so `sweeper-prompt-contract.test.ts` can assert it against the prompt
+ * `SweepService` REALLY builds. The wording has drifted once already; a copy of
+ * it pasted into a test here would go stale silently and take the filter with it.
+ */
+export declare function isSweeperPrompt(preview: string): boolean;
+/**
+ * Reduce a git remote URL to a comparable `host/path` identity (#659).
+ *
+ * The same repo is written many ways, and a project's `repo` field and a clone's
+ * configured remote routinely disagree on form while naming the same thing:
+ *
+ *   https://github.com/edspencer/hushpod.git   ┐
+ *   git@github.com:edspencer/hushpod           ├─ all → github.com/edspencer/hushpod
+ *   ssh://git@github.com/edspencer/hushpod/    ┘
+ *
+ * So: drop any scheme, drop `user@`, turn the scp-style `host:path` colon into a
+ * slash, drop a trailing `.git` and any trailing slashes, and lowercase. A local
+ * path remote (`/srv/git/foo.git`) normalises to `/srv/git/foo` and still
+ * compares correctly against itself.
+ *
+ * Returns `""` for anything that reduces to nothing, which never compares equal
+ * to a real remote — the caller does not have to special-case it.
+ */
+export declare function normalizeRemote(url: string): string;
 /** The engine surface this module needs — narrowed so tests can fake it. */
 export interface AdoptableFleet {
     listAdoptableSessions(agentName: string, fromWorkingDir?: string): Promise<AdoptableSession[]>;
@@ -90,6 +144,13 @@ export declare class AdoptableIndex {
     private readonly stateDir;
     /** folder name → last-seen entry, reused while its `key` is unchanged. */
     private readonly folders;
+    /**
+     * checkout dir → its normalised remotes, memoised on the git config's own
+     * mtime+size (#659). Keyed on the config rather than the transcript folder
+     * because that is the file whose CHANGE would change the answer: adding or
+     * re-pointing a remote must be picked up, and it does not touch `~/.claude`.
+     */
+    private readonly remotes;
     /** project key → cached summary + the composite key it was computed under. */
     private readonly summaries;
     constructor(claudeHomePath: string, stateDir: string);
@@ -108,6 +169,14 @@ export declare class AdoptableIndex {
      * folders whose file set changed since last time.
      */
     private scanFolders;
+    /**
+     * A checkout's normalised git remotes, memoised on its config's mtime+size.
+     *
+     * The memo is keyed by directory and re-validated on every call, so a remote
+     * added or re-pointed after the last scan is picked up without waiting for
+     * anything in `~/.claude` to change.
+     */
+    private remotesFor;
     /**
      * The candidate source working directories for a project, de-duplicated by the
      * transcript folder they resolve to.

package/packages/server/dist/adoptable.js

@@ -15,8 +15,9 @@
  *
  *  1. **Assemble candidate sources** — the project's own `workingDir`, plus any
  *     `<claudeHome>/projects/*` folder whose RECORDED cwd matches the project.
- *  2. **Filter low-value noise** — a zero-byte transcript or a session that is
- *     nothing but a `/mcp` slash command is not a chat anyone wants imported.
+ *  2. **Filter low-value noise** — a zero-byte transcript, a session that is
+ *     nothing but a `/mcp` slash command, or one of paddock's OWN sweeper runs
+ *     (#658) is not a chat anyone wants imported.
  *  3. **Cache** — the scan is O(all transcript folders on the machine), so it is
  *     keyed on directory mtimes and only redone when something could have moved.
  *
@@ -35,16 +36,35 @@
  *
  * ## The matching heuristic, and what it cannot do
  *
- * For a REPO-BACKED project a folder matches when its recorded cwd's BASENAME
- * equals the project's checkout name (`repoCheckoutName(repo)`) — i.e. "the user
- * has their own clone of this repo elsewhere". This is deliberately simple and
- * is NOT identity-precise: two unrelated checkouts that happen to share a
- * basename (`~/work/api` and `~/oss/api`) both match, and a clone the user
- * renamed on disk does not match at all. Verifying the checkout's git remote
- * would be exact; it also means running git in every candidate directory, which
- * is the wrong cost for a count shown in a header. Noted as a known limit
- * (#588 gotcha 6) rather than pretended away — the import is per-source, so a
- * user who sees a source they don't recognise can decline it.
+ * For a REPO-BACKED project a folder matches when BOTH hold: its recorded cwd's
+ * BASENAME equals the project's checkout name (`repoCheckoutName(repo)`), AND
+ * that directory is a git checkout with a remote pointing at the project's repo
+ * — i.e. "the user really does have their own clone of this repo elsewhere".
+ *
+ * The basename test alone used to be the whole rule, documented as deliberately
+ * loose. It is unbounded across the filesystem, and on the dogfooding instance it
+ * was reaching into a THROWAWAY QA instance's data directory: the `hushpod`
+ * project offered 15 chats out of `/data/scratch/paddock-video/data/projects/
+ * hushpod`, which belong to a different Paddock instance entirely (#659). "Two
+ * unrelated checkouts that share a basename" turns out not to be a corner case on
+ * a machine that hosts scratch copies, backups and QA clones.
+ *
+ * The original objection to checking the remote was cost — "running git in every
+ * candidate directory is the wrong cost for a count shown in a header". That
+ * objection is answered by not running git: the remote is READ out of
+ * `<cwd>/.git/config`, one small file, and only for the handful of directories
+ * that already passed the basename test. Results are memoised on the config
+ * file's own mtime+size.
+ *
+ * A candidate with no readable git config, or whose remotes all point somewhere
+ * else, is not offered. That is stricter than before by design — a directory that
+ * is not a clone of this repo has no claim to be imported into it. The project's
+ * OWN working directory is exempt: it is appended unconditionally below, so a
+ * project whose checkout has an unusual remote still offers its own history.
+ *
+ * Still NOT identity-precise, and deliberately so: a clone the user renamed on
+ * disk does not match (the basename test runs first), and a fork with a different
+ * remote does not match. Both fail CLOSED — nothing is offered that shouldn't be.
  *
  * For a NOTEBOOK project the match is exact cwd equality: its working directory
  * IS the project directory, and nothing else is plausibly "the same project".
@@ -91,10 +111,55 @@ export const SLASH_COMMAND_MAX_BYTES = 4096;
  * `/review the auth refactor` all do.
  */
 const SLASH_COMMAND_ONLY_RE = /^\s*(?:<command-name>\s*)?\/[a-z][a-z0-9:_-]*(?![^\s<])/i;
+/**
+ * A preview that opens with paddock's OWN sweeper prompt (#658).
+ *
+ * The sweeper is a one-shot `claude -p` subprocess (`sweep.ts` `runSweeper`), so
+ * it writes a perfectly ordinary transcript into the project's own chat folder.
+ * When no run record binds that session — the sweeper's own history on the
+ * dogfooding instance has ten such transcripts with no `session_id` in any
+ * `job-*.yaml` — attribution cannot tell it from a session the user typed in a
+ * terminal, and paddock ends up offering the user its own curation output as a
+ * chat to "import".
+ *
+ * Matched on the prompt's two stable opening features: the `Project: <name>
+ * (slug: <slug>)` header `buildPrompt` always emits first, and the `You are
+ * curating` sentence that follows it. Both are required. The header alone is too
+ * weak (a user could plausibly open a chat that way), and the sentence alone
+ * would match someone quoting the sweeper prompt to talk ABOUT it.
+ *
+ * Whitespace between the two is `\s+` rather than `\n`: the header is followed by
+ * an optional `Summary:` line and a blank line, and the engine's preview
+ * normalises runs of whitespace. The wording of the sentence has already drifted
+ * once ("curating two files in this project directory" → "curating this
+ * project's three context files"), so only the stable `You are curating` stem is
+ * matched.
+ *
+ * The engine truncates a preview at 100 characters, so a project whose name is
+ * long enough to push `You are curating` past that boundary will not match and
+ * its sweeper chats stay on offer. That is the deliberate direction to fail in:
+ * a sweeper chat wrongly offered is noise the user can decline, while a real chat
+ * wrongly withheld is history they cannot get at. Withheld candidates are
+ * reported under `filtered` for the same reason.
+ */
+const SWEEPER_PROMPT_RE = /^Project: .*\(slug: [^)]*\)\s+(?:Summary:.*\s+)?You are curating\b/;
+/**
+ * Does this transcript preview look like paddock's own sweeper run (#658)?
+ *
+ * Exported so `sweeper-prompt-contract.test.ts` can assert it against the prompt
+ * `SweepService` REALLY builds. The wording has drifted once already; a copy of
+ * it pasted into a test here would go stale silently and take the filter with it.
+ */
+export function isSweeperPrompt(preview) {
+    return SWEEPER_PROMPT_RE.test(preview);
+}
 /** Classify a candidate as noise, or `null` to keep it. */
 function filterReasonFor(session) {
     if (session.sizeBytes < MIN_TRANSCRIPT_BYTES)
         return "too-small";
+    if (session.preview !== undefined && isSweeperPrompt(session.preview)) {
+        return "sweeper-run";
+    }
     if (session.sizeBytes < SLASH_COMMAND_MAX_BYTES &&
         session.preview !== undefined &&
         SLASH_COMMAND_ONLY_RE.test(session.preview)) {
@@ -102,7 +167,96 @@ function filterReasonFor(session) {
     }
     return null;
 }
-/** A directory's cache identity: its mtime + size, or `null` when absent. */
+/**
+ * Reduce a git remote URL to a comparable `host/path` identity (#659).
+ *
+ * The same repo is written many ways, and a project's `repo` field and a clone's
+ * configured remote routinely disagree on form while naming the same thing:
+ *
+ *   https://github.com/edspencer/hushpod.git   ┐
+ *   git@github.com:edspencer/hushpod           ├─ all → github.com/edspencer/hushpod
+ *   ssh://git@github.com/edspencer/hushpod/    ┘
+ *
+ * So: drop any scheme, drop `user@`, turn the scp-style `host:path` colon into a
+ * slash, drop a trailing `.git` and any trailing slashes, and lowercase. A local
+ * path remote (`/srv/git/foo.git`) normalises to `/srv/git/foo` and still
+ * compares correctly against itself.
+ *
+ * Returns `""` for anything that reduces to nothing, which never compares equal
+ * to a real remote — the caller does not have to special-case it.
+ */
+export function normalizeRemote(url) {
+    let s = url.trim();
+    if (s === "")
+        return "";
+    s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, ""); // https://, ssh://, git://
+    s = s.replace(/^[^/@]+@/, ""); // git@
+    // scp-style `host:owner/repo` — but not a port (`host:22/owner/repo`) and not
+    // an absolute local path, neither of which has this shape.
+    s = s.replace(/^([^/:]+):(?!\/)/, "$1/");
+    s = s.replace(/\.git$/i, "");
+    s = s.replace(/\/+$/, "");
+    return s.toLowerCase();
+}
+/**
+ * Every remote URL configured in a git checkout, normalised.
+ *
+ * Reads `.git/config` directly rather than shelling out to git: this runs for
+ * candidate directories behind a count rendered in a header, and a subprocess per
+ * candidate is exactly the cost that made checking the remote look unaffordable
+ * in the first place.
+ *
+ * Handles a linked WORKTREE, where `.git` is a FILE holding `gitdir: <path>` and
+ * the config lives in the MAIN repository's git dir — found by resolving the
+ * `commondir` pointer. This repo is developed with worktrees, so a contributor's
+ * `wt-*` checkout is a real case, not a hypothetical.
+ *
+ * Returns `[]` for anything unreadable or not a checkout at all. An INI parse is
+ * enough here — `url = …` inside a `[remote "…"]` section — because the question
+ * is only "does any remote name this repo", not "what is the exact config".
+ */
+async function gitRemotes(cwd) {
+    const dot = path.join(cwd, ".git");
+    const st = await fs.stat(dot).catch(() => null);
+    if (st === null)
+        return [];
+    let gitDir = dot;
+    if (!st.isDirectory()) {
+        const pointer = await fs.readFile(dot, "utf8").catch(() => "");
+        const m = /^\s*gitdir:\s*(.+?)\s*$/m.exec(pointer);
+        if (m === null)
+            return [];
+        gitDir = path.resolve(cwd, m[1]);
+        // A linked worktree's own git dir has no `config`; `commondir` points at the
+        // main repository's git dir, which does.
+        const common = await fs.readFile(path.join(gitDir, "commondir"), "utf8").catch(() => null);
+        if (common !== null)
+            gitDir = path.resolve(gitDir, common.trim());
+    }
+    const text = await fs.readFile(path.join(gitDir, "config"), "utf8").catch(() => null);
+    if (text === null)
+        return [];
+    const out = [];
+    let inRemote = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("[")) {
+            inRemote = /^\[remote\b/i.test(line);
+            continue;
+        }
+        if (!inRemote)
+            continue;
+        const m = /^url\s*=\s*(.+)$/i.exec(line);
+        if (m === null)
+            continue;
+        const url = normalizeRemote(m[1]);
+        if (url !== "")
+            out.push(url);
+    }
+    return out;
+}
+/** A path's cache identity: its mtime + size, or `"-"` when absent. Used for
+ *  directories (has the file SET changed) and for single files alike. */
 async function dirKey(dir) {
     const st = await fs.stat(dir).catch(() => null);
     return st ? `${st.mtimeMs}:${st.size}` : "-";
@@ -138,6 +292,13 @@ export class AdoptableIndex {
     stateDir;
     /** folder name → last-seen entry, reused while its `key` is unchanged. */
     folders = new Map();
+    /**
+     * checkout dir → its normalised remotes, memoised on the git config's own
+     * mtime+size (#659). Keyed on the config rather than the transcript folder
+     * because that is the file whose CHANGE would change the answer: adding or
+     * re-pointing a remote must be picked up, and it does not touch `~/.claude`.
+     */
+    remotes = new Map();
     /** project key → cached summary + the composite key it was computed under. */
     summaries = new Map();
     constructor(claudeHomePath, stateDir) {
@@ -194,6 +355,29 @@ export class AdoptableIndex {
                 this.folders.delete(name);
         return out;
     }
+    /**
+     * A checkout's normalised git remotes, memoised on its config's mtime+size.
+     *
+     * The memo is keyed by directory and re-validated on every call, so a remote
+     * added or re-pointed after the last scan is picked up without waiting for
+     * anything in `~/.claude` to change.
+     */
+    async remotesFor(cwd) {
+        // Cheap enough to re-key every time: two `stat`s. Both halves are needed —
+        // `.git/config` is the file that answers the question for an ordinary
+        // checkout, and `.git` itself covers a linked worktree, where `.git` is a
+        // FILE and `.git/config` does not exist at all.
+        const key = [
+            await dirKey(path.join(cwd, ".git")),
+            await dirKey(path.join(cwd, ".git", "config")),
+        ].join("|");
+        const cached = this.remotes.get(cwd);
+        if (cached && cached.key === key)
+            return cached.urls;
+        const urls = await gitRemotes(cwd);
+        this.remotes.set(cwd, { key, urls });
+        return urls;
+    }
     /**
      * The candidate source working directories for a project, de-duplicated by the
      * transcript folder they resolve to.
@@ -205,24 +389,34 @@ export class AdoptableIndex {
         const own = project.workingDir;
         const ownFolder = path.join(this.claudeHomePath, "projects", encodePathForCli(own));
         const ownReal = await fs.realpath(ownFolder).catch(() => ownFolder);
-        const matches = (cwd) => {
+        const repo = project.repo !== undefined && project.repo !== "" ? project.repo : null;
+        const wantRemote = repo === null ? "" : normalizeRemote(repo);
+        /** The CHEAP test: worth reading a git config for? */
+        const nameMatches = (cwd) => {
             if (cwd === own)
                 return true;
-            // Repo-backed: "the user's own clone of the same repo", matched by the
-            // checkout basename. Deliberately loose — see the module header.
-            if (project.repo !== undefined && project.repo !== "") {
-                return path.basename(cwd) === repoCheckoutName(project.repo);
-            }
+            // Repo-backed: "the user's own clone of the same repo". A necessary but
+            // NOT sufficient condition — `remoteMatches` below is the other half.
+            if (repo !== null)
+                return path.basename(cwd) === repoCheckoutName(repo);
             // Notebook: exact cwd equality only.
             return false;
         };
         const seen = new Set([ownReal]);
         const sources = [];
         for (const folder of folders) {
-            if (folder.cwd === null || !matches(folder.cwd))
+            if (folder.cwd === null || !nameMatches(folder.cwd))
                 continue;
             if (seen.has(folder.realPath))
                 continue;
+            // A same-named directory has to prove it is a clone of THIS repo (#659).
+            // Only reached for repo-backed projects, and only after the basename test,
+            // so this is a handful of small file reads rather than a filesystem sweep.
+            if (repo !== null && folder.cwd !== own) {
+                const urls = await this.remotesFor(folder.cwd);
+                if (!urls.includes(wantRemote))
+                    continue;
+            }
             seen.add(folder.realPath);
             sources.push(folder.cwd);
         }
@@ -269,7 +463,7 @@ export class AdoptableIndex {
             // Fault-isolated per source: an unreadable folder costs its own sessions,
             // not the whole count.
             const sessions = await fleet.listAdoptableSessions(agentName, sourceCwd).catch(() => []);
-            const ids = [];
+            const candidates = [];
             for (const session of sessions) {
                 // De-dup by session id. Two candidate cwds can collide onto one folder
                 // under the lossy encoding, and a transcript may have been copied; either
@@ -282,11 +476,23 @@ export class AdoptableIndex {
                     filtered.push({ sessionId: session.sessionId, sourceCwd, reason });
                     continue;
                 }
-                ids.push(session.sessionId);
+                candidates.push({
+                    sessionId: session.sessionId,
+                    mtime: session.mtime,
+                    preview: session.preview,
+                    autoName: session.autoName,
+                    sizeBytes: session.sizeBytes,
+                });
             }
-            if (ids.length > 0) {
-                out.push({ sourceCwd, sessionIds: ids });
-                count += ids.length;
+            if (candidates.length > 0) {
+                // Both projections built HERE, from one array, so `sessionIds` can never
+                // disagree with `sessions`.
+                out.push({
+                    sourceCwd,
+                    sessionIds: candidates.map((c) => c.sessionId),
+                    sessions: candidates,
+                });
+                count += candidates.length;
             }
         }
         const summary = { count, sources: out, filtered };

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

@@ -0,0 +1,56 @@
+/**
+ * Pure argument parsing and message formatting for the `paddock` CLI.
+ *
+ * ## Why this is its own module
+ *
+ * These functions want unit tests, and the entrypoint they used to live in
+ * cannot be imported without running. The first attempt kept them in
+ * `paddock.ts` behind a run-directly guard:
+ *
+ * ```ts
+ * if (pathToFileURL(process.argv[1]).href === import.meta.url) main();
+ * ```
+ *
+ * **That guard shipped a silent no-op to npm.** npm installs a `bin` as a
+ * SYMLINK at `node_modules/.bin/paddock`, so `process.argv[1]` is the symlink
+ * path while `import.meta.url` is the module's realpath. They never match, the
+ * condition is always false, and `npx @edspencer/paddock` printed nothing and
+ * exited 0 — in 0.57.0, 0.58.0 and 0.59.0. It went unnoticed because the manual
+ * checks invoked `node <file>` directly, which is the one path where the guard
+ * does hold.
+ *
+ * `realpathSync(argv[1])` would fix that instance. Splitting the module removes
+ * the need for the guard entirely, so there is no condition left to get wrong on
+ * the next shim, platform or package manager. `paddock.ts` now always runs.
+ */
+export interface CliOptions {
+    port?: string;
+    host?: string;
+    dataDir?: string;
+    here: boolean;
+    open: boolean;
+    verbose: boolean;
+    help: boolean;
+    version: boolean;
+}
+/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+export declare class CliError extends Error {
+}
+export declare const MIN_NODE_MAJOR = 22;
+export declare function parseArgs(argv: string[]): CliOptions;
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * `engines` only warns by default, and the failure it eventually produces is an
+ * unexplained syntax error deep inside a dependency.
+ */
+export declare function nodeVersionProblem(nodeVersion: string): string | undefined;
+/**
+ * Translate a listen failure into something a human can act on.
+ *
+ * `EADDRINUSE` on 4000 is the likeliest first-run failure — a popular port and
+ * Paddock's own default — and Node's raw error names neither the port nor the
+ * 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";