@edspencer/paddock 0.59.1 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.59.1",
+  "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/herdctl.d.ts

@@ -134,6 +134,24 @@ export declare class HerdctlService {
      * {@link cancel}). Entries are removed when the turn's stream ends.
      */
     private liveSessions;
+    /**
+     * Background-phase turns keyed by the synthetic job id the sink minted for
+     * them, valued by the chat session they belong to (paddock#528).
+     *
+     * After a turn's primary `result` lands, {@link chatSession} returns and drops
+     * its {@link liveSessions} entry — but the session itself may live on, held
+     * open by the reaper because the turn launched background work, streaming
+     * autonomous re-invocation turns. Those turns are real, running, and shown as
+     * such; until now they were also uncancellable, because nothing registered
+     * them anywhere Stop could reach.
+     *
+     * `interrupt()` would be the wrong tool even if it could: it targets an
+     * in-flight model turn, and the wedge case is a session sitting idle holding
+     * background work that will never finish. So these route to a force-reap
+     * instead — end the session, let the stream end, and let the ordinary unwind
+     * emit `chat:complete`. Entries are removed when the background stream ends.
+     */
+    private backgroundTurns;
     /**
      * Incremental index of `<stateDir>/jobs`, backing the unread-badge reads
      * (`lastTurnCompletedAt*`) — one per service, reused across requests so a warm
@@ -325,12 +343,61 @@ export declare class HerdctlService {
      */
     adoptChats(project: Project, opts?: {
         sourceCwd?: string;
+        /**
+         * Import only these sessions (#660). Anything else the engine adopts along
+         * the way is released again, exactly as a noise-filtered session is — see
+         * the "honouring the noise filter" note above, which this reuses wholesale.
+         * Undefined means "everything on offer", which is what a confirmed
+         * select-all sends and what the CLI has always sent.
+         */
+        sessionIds?: string[];
         mode?: AdoptionPlacementMode;
         dryRun?: boolean;
     }): Promise<{
         adopted: string[];
         skipped: AdoptSkipped[];
     }>;
+    /**
+     * Did an import of `sessionId` from `fromWorkingDir` place a NEW file?
+     *
+     * The same test `releaseWithheld` makes before deleting anything: an in-place
+     * adoption resolves the destination and the origin to one path, so there is no
+     * copy and nothing that may be removed.
+     */
+    private placedACopy;
+    /**
+     * What the LAST import into each workspace did, so it can be undone (#660).
+     *
+     * Keyed by workspace key (which may be `""` — the root). Holds the sessions
+     * that import actually brought in, and of those, the ones where it PLACED a
+     * copy and may therefore delete one again.
+     *
+     * Server-side rather than a token the client hands back: undo deletes files, so
+     * the set of paths it may touch must come from what this process actually did,
+     * not from a request body. A restart forgets it, which is the right failure —
+     * the offer to undo is a transient toast, not a durable feature.
+     *
+     * Only the most recent import per workspace is kept. Undoing an import two
+     * imports ago is not offered and would be a lie to describe as "undo".
+     */
+    private readonly lastImport;
+    /**
+     * Undo the import this process most recently performed into `project` (#660).
+     *
+     * Releases each adoption and deletes the copies that import placed, leaving the
+     * user's own `~/.claude` history exactly as it was. Returns the sessions it
+     * released; an empty array means there was nothing to undo (nothing imported
+     * yet, already undone, or the server restarted since).
+     *
+     * `sessionIds` narrows it to part of that import — the rest stays. Ids that
+     * were not part of it are ignored rather than rejected: undo is a best-effort
+     * safety net, and the alternative is a 400 for a button the user pressed once.
+     */
+    unadoptChats(project: Project, opts?: {
+        sessionIds?: string[];
+    }): Promise<{
+        released: string[];
+    }>;
     /**
      * Undo the adoption of a session detection had withheld, restoring the state
      * that existed before this import. See {@link adoptChats} for why the file
@@ -452,11 +519,24 @@ export declare class HerdctlService {
     }): Promise<{
         sessionId: string | null;
     }>;
+    /**
+     * Register a background-phase turn so Stop can reach it (paddock#528). Called
+     * by the background turn sink once it knows both the synthetic job id it
+     * published and the session that stream belongs to. Re-registering the same
+     * job id with a later session id is fine — the sink refreshes the mapping if
+     * the stream resolves a different session.
+     */
+    registerBackgroundTurn(jobId: string, sessionId: string): void;
+    /** Forget a background-phase turn once its stream has ended. */
+    unregisterBackgroundTurn(jobId: string): void;
     /**
      * Cancel a running turn (Stop button → WS chat:cancel). Handles BOTH drive
      * modes off the single id the client holds as `jobId`:
      *  - **session mode** — the id is a synthetic turn id in {@link liveSessions};
      *    interrupt the live `RuntimeSession` (there is no herdctl job to cancel).
+     *  - **background phase** — the id is a synthetic id in
+     *    {@link backgroundTurns}; there is no model turn to interrupt, so reap the
+     *    session (paddock#528).
      *  - **batch mode** — the id is a real herdctl job id; abort it via `cancelJob`
      *    (which kills the CLI subprocess / aborts the SDK query).
      *