@edspencer/paddock 0.59.1 → 0.61.0

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".
@@ -53,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.
  *
@@ -91,10 +112,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 +168,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}` : "-";
@@ -136,13 +291,32 @@ async function dirKey(dir) {
 export class AdoptableIndex {
     claudeHomePath;
     stateDir;
+    legacyClaudeHomePath;
     /** 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) {
+    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).
@@ -164,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 = [];
@@ -178,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);
@@ -194,6 +379,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,32 +413,48 @@ 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 || folder.engineCwd === 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);
+            // 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;
     }
     /**
@@ -248,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 = [
@@ -265,11 +490,16 @@ 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(() => []);
-            const ids = [];
+            // 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
                 // under the lossy encoding, and a transcript may have been copied; either
@@ -282,11 +512,27 @@ 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) {
+                // `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,
+                });
+                count += candidates.length;
             }
         }
         const summary = { count, sources: out, filtered };

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>;