@edspencer/paddock 0.70.1 → 0.71.1

package/packages/server/dist/discover.js

@@ -61,6 +61,18 @@
  *
  * Surviving directories are ranked by non-noise session count, then by recency.
  *
+ * ## Paddock's own folders never enter the scan at all (#865)
+ *
+ * {@link withoutOwnTranscriptFolders} runs BEFORE any of this, and it is not one
+ * more exclusion rule: a folder it drops is not counted in `scanned` either.
+ * That distinction is the whole point. Paddock plants a symlink into its Claude
+ * home for each workspace's `.chats` at boot, so a machine that has never run
+ * Claude Code reported `scanned: 2, excluded: {"no-recorded-cwd": 2}` — and
+ * `scanned === 0`, the one signal that separates "no history here" from "all of
+ * it was filtered out", was therefore unreachable in the case it was written
+ * for. The UI then told a first-time user their history was "already a project,
+ * or was filtered out", on a machine with no history at all.
+ *
  * ## Why counts are reported rather than dropped
  *
  * `DiscoverResult.excluded` carries how many directories each rule ate. Without it a
@@ -96,6 +108,45 @@ const TEMP_PATH_ROOTS = [
 export function defaultTempRoots() {
     return [...TEMP_PATH_ROOTS, os.tmpdir()];
 }
+/**
+ * Drop the transcript folders paddock planted itself, BEFORE anything is counted
+ * (issue #865).
+ *
+ * Paddock bridges each workspace's `.chats` into its Claude home as a symlink at
+ * boot — the root workspace's and the sweeper's exist on an instance nobody has
+ * touched yet. They are transcript folders by every structural test, so the scan
+ * saw two of them, excluded both as `no-recorded-cwd` (they are empty), and
+ * reported `scanned: 2`. Reporting them as *scanned* is the bug: `scanned === 0`
+ * is what the UI keys "no Claude Code history on this machine" off, and paddock's
+ * own bookkeeping is not the user's history.
+ *
+ * ## The test, and why it is this one
+ *
+ * A folder is paddock's own when it resolves INTO paddock's own storage
+ * (`ownRoots`: the projects root and the data dir) while resolving OUTSIDE every
+ * Claude home. Both halves are load-bearing:
+ *
+ *  - the second half alone would drop everything — a real folder physically
+ *    lives in `<claudeHome>/projects/`, which is itself inside the data dir;
+ *  - the first half alone would drop the user's OWN mirrored folders (#620),
+ *    which resolve into `~/.claude` — inside `legacyClaudeHome`, and exactly the
+ *    history this feature exists to offer.
+ *
+ * So: resolves into a claude home ⇒ the user's, keep. Resolves into paddock's
+ * storage but no claude home ⇒ a `.chats` bridge paddock made, drop.
+ *
+ * Note this is deliberately NOT another {@link DiscoverExclusion}. An exclusion
+ * is a directory the user has that we are declining to offer, and it is counted
+ * and shown as such; these are folders that were never theirs to begin with.
+ */
+export function withoutOwnTranscriptFolders(folders, roots) {
+    return folders.filter((folder) => {
+        const real = folder.realPath;
+        if (roots.claudeHomes.some((home) => isPathInside(real, home)))
+            return true;
+        return !roots.ownRoots.some((root) => isPathInside(real, root));
+    });
+}
 /**
  * Is this an ephemeral scratch directory?
  *

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

@@ -53,6 +53,7 @@ import { type PaddockTrigger } from "./trigger-config.js";
 import { type McpSources } from "./claude-mcp.js";
 import { type HostPluginSource } from "./claude-plugins.js";
 import { type AdoptableSummary, type FilterReason, type TranscriptFolder } from "./adoptable.js";
+import { type SessionWithActivity } from "./last-activity.js";
 /**
  * One session an import did NOT bring in, with a reason a UI can show verbatim.
  *
@@ -79,6 +80,26 @@ export interface ChatDeletion {
     /** The transcript was deliberately left on disk because it is not paddock's. */
     retained: boolean;
 }
+/**
+ * What happened to a request to stop one background task (#848).
+ *
+ * Three cases, kept apart on purpose — see
+ * {@link HerdctlService.stopBackgroundTask} for why only `error` is a failure.
+ */
+export type StopTaskOutcome = 
+/** Accepted. The SDK's own terminal notification is what removes the row. */
+{
+    outcome: "stopping";
+}
+/** No live session — the work died with it. The caller drops the row. */
+ | {
+    outcome: "gone";
+}
+/** The stop did not happen and the task is still running. */
+ | {
+    outcome: "error";
+    message: string;
+};
 /** Options passed through to a streamed trigger. */
 export interface ChatTurnOptions {
     prompt: string;
@@ -768,6 +789,35 @@ export declare class HerdctlService {
      * failure, so a broken Stop looked like a no-op).
      */
     cancel(jobId: string): Promise<boolean>;
+    /**
+     * Stop ONE background task, by session id and SDK task id (issue #848).
+     *
+     * Deliberately keyed on the SESSION, not on {@link liveSessions}. That map is
+     * emptied in a `finally` the moment the primary turn's result lands, while the
+     * background tasks it launched keep running — so a `liveSessions`-keyed stop
+     * would go inert during exactly the phase the running-work bar exists for.
+     * `stopTaskInSession` is herdctl's answer to that gap: the reaper holds the
+     * session across it.
+     *
+     * There is deliberately NO liveness pre-check. A reap landing between render
+     * and click is a routine race, and `false` already describes it precisely.
+     *
+     * The three outcomes are kept DISTINCT all the way to the UI, because they
+     * mean genuinely different things and only one of them is a failure:
+     *
+     *  - `stopping` — the request was accepted. Nothing is evicted here: the SDK
+     *    emits the terminal `task_notification{status:"stopped"}` on the session's
+     *    own stream and {@link BackgroundRegistry} already evicts on it. This is
+     *    also the idempotent case — the CLI answers `not_found` / `not_running`
+     *    with a success, so a click racing a natural completion lands here.
+     *  - `gone` — no live session with that id. NOT a failure: the tasks died with
+     *    the session, so the user's intent is already satisfied. The caller drops
+     *    the row itself, because there is no stream left to notify on.
+     *  - `error` — the stop did NOT happen and the task is still running. Notably
+     *    a `monitor_mcp` task, which the CLI has no kill strategy for and rejects
+     *    with `unsupported_type`. Surfaced rather than reported as success.
+     */
+    stopBackgroundTask(sessionId: string, taskId: string): Promise<StopTaskOutcome>;
     /**
      * End a managed chat SESSION outright, by session id (issue #731). Where
      * {@link cancel} ends the model turn — and on the session runtime deliberately
@@ -820,7 +870,7 @@ export declare class HerdctlService {
      * zero added cost unless the project actually declares hooks. The extra per-hook
      * scans only kick in for a project that has hook chats to show.
      */
-    listSessions(project: Project): Promise<DiscoveredSession[]>;
+    listSessions(project: Project): Promise<SessionWithActivity[]>;
     /**
      * The on-disk job-record reads (run history + the unread badge) live in
      * `./herdctl-jobs.js` as pure functions over `<stateDir>/jobs` (issue #403);

package/packages/server/dist/herdctl.js

@@ -62,6 +62,7 @@ import * as jobs from "./herdctl-jobs.js";
 import { JobsDirIndex } from "./herdctl-jobs-index.js";
 import { AdoptableIndex, } from "./adoptable.js";
 import { ROOT_KEY } from "./project-paths.js";
+import { withLastActivity } from "./last-activity.js";
 /**
  * The name/visibility helpers + tool/model constants are pure (they only read
  * their arguments, no fleet/cfg/session state), so they live in a sibling module
@@ -1397,6 +1398,48 @@ export class HerdctlService {
             return false;
         }
     }
+    /**
+     * Stop ONE background task, by session id and SDK task id (issue #848).
+     *
+     * Deliberately keyed on the SESSION, not on {@link liveSessions}. That map is
+     * emptied in a `finally` the moment the primary turn's result lands, while the
+     * background tasks it launched keep running — so a `liveSessions`-keyed stop
+     * would go inert during exactly the phase the running-work bar exists for.
+     * `stopTaskInSession` is herdctl's answer to that gap: the reaper holds the
+     * session across it.
+     *
+     * There is deliberately NO liveness pre-check. A reap landing between render
+     * and click is a routine race, and `false` already describes it precisely.
+     *
+     * The three outcomes are kept DISTINCT all the way to the UI, because they
+     * mean genuinely different things and only one of them is a failure:
+     *
+     *  - `stopping` — the request was accepted. Nothing is evicted here: the SDK
+     *    emits the terminal `task_notification{status:"stopped"}` on the session's
+     *    own stream and {@link BackgroundRegistry} already evicts on it. This is
+     *    also the idempotent case — the CLI answers `not_found` / `not_running`
+     *    with a success, so a click racing a natural completion lands here.
+     *  - `gone` — no live session with that id. NOT a failure: the tasks died with
+     *    the session, so the user's intent is already satisfied. The caller drops
+     *    the row itself, because there is no stream left to notify on.
+     *  - `error` — the stop did NOT happen and the task is still running. Notably
+     *    a `monitor_mcp` task, which the CLI has no kill strategy for and rejects
+     *    with `unsupported_type`. Surfaced rather than reported as success.
+     */
+    async stopBackgroundTask(sessionId, taskId) {
+        const fleet = this.fleet;
+        if (!fleet)
+            return { outcome: "gone" };
+        try {
+            const stopped = await fleet.stopTaskInSession(sessionId, taskId);
+            return stopped ? { outcome: "stopping" } : { outcome: "gone" };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[herdctl] stopTaskInSession failed for ${sessionId}/${taskId}:`, err);
+            return { outcome: "error", message };
+        }
+    }
     /**
      * End a managed chat SESSION outright, by session id (issue #731). Where
      * {@link cancel} ends the model turn — and on the session runtime deliberately
@@ -1477,9 +1520,9 @@ export class HerdctlService {
      */
     async listSessions(project) {
         const agentNames = visibleProjectAgentNames(project);
-        if (agentNames.length === 1)
-            return this.manager.getAgentSessions(agentNames[0]);
-        const perAgent = await Promise.all(agentNames.map((name) => this.manager.getAgentSessions(name).catch(() => [])));
+        const perAgent = agentNames.length === 1
+            ? [await this.manager.getAgentSessions(agentNames[0])]
+            : await Promise.all(agentNames.map((name) => this.manager.getAgentSessions(name).catch(() => [])));
         const seen = new Set();
         const merged = [];
         for (const list of perAgent) {
@@ -1490,9 +1533,13 @@ export class HerdctlService {
                 merged.push(s);
             }
         }
-        // ISO-8601 mtimes sort lexicographically in chronological order → descending.
-        merged.sort((a, b) => (a.mtime < b.mtime ? 1 : a.mtime > b.mtime ? -1 : 0));
-        return merged;
+        // Recency, from the last real MESSAGE in each transcript rather than from
+        // its file mtime (#863) — and this is also where the single-agent fast path
+        // stopped being free. It used to return herdctl's own mtime-descending
+        // order untouched; that order is the bug, so the common case has to be
+        // re-sorted too. What it costs is a memoised tail read per chat, which is
+        // why `lastMessageAt` seeks to the end rather than parsing.
+        return withLastActivity(project.dir, merged);
     }
     /**
      * The on-disk job-record reads (run history + the unread badge) live in

package/packages/server/dist/last-activity.d.ts

@@ -0,0 +1,34 @@
+import type { DiscoveredSession } from "@herdctl/core";
+/**
+ * A session plus the timestamp of its last real message.
+ *
+ * A widening rather than a replacement, because `mtime` still has a job:
+ * it is the cache key for auto-name, preview, sidechain detection and usage
+ * throughout this package and inside herdctl. Overwriting it with the corrected
+ * value would fix the display and silently break every one of those caches —
+ * they would stop noticing that a file had changed.
+ */
+export interface SessionWithActivity extends DiscoveredSession {
+    /** ISO 8601 timestamp of the last real message; absent if none was datable. */
+    lastMessageAt?: string;
+}
+/**
+ * Timestamp of the last real message in a project chat's transcript.
+ *
+ * `undefined` — a missing file, an unreadable one, a transcript of nothing but
+ * control records — is a legitimate answer meaning "nothing better than the
+ * mtime", and every caller treats it that way.
+ */
+export declare function lastMessageAt(projectDir: string, sessionId: string): Promise<string | undefined>;
+/**
+ * Attach `lastMessageAt` to each session and order them newest-first.
+ *
+ * The sort lives here rather than in the client because the client is not the
+ * only reader: the MCP `list_chats` tool and the project-detail payload both
+ * take the server's order as given. The comparison falls back to `mtime`
+ * per-session rather than for the list as a whole, so a chat with no datable
+ * record still sorts sensibly against ones that have.
+ */
+export declare function withLastActivity(projectDir: string, sessions: readonly DiscoveredSession[]): Promise<SessionWithActivity[]>;
+/** Epoch ms a session should be ordered by: its last message, else its mtime. */
+export declare function activityMs(s: SessionWithActivity): number;

package/packages/server/dist/last-activity.js

@@ -0,0 +1,178 @@
+/**
+ * When a chat was last *actually* used, as opposed to when its file was last
+ * touched (#863).
+ *
+ * ## The bug this exists to remove
+ *
+ * The chat list's "updated X ago" — and the order the list is in — came from
+ * the transcript `.jsonl`'s filesystem **mtime**. That is a property of the
+ * file, not of the conversation, and Paddock touches transcripts for reasons
+ * that have nothing to do with anyone talking: discovery re-stats, attribution,
+ * a resume appending a mode record, a relocation. Every one of those bumps the
+ * mtime with no new message in the file. The visible result was days-old chats
+ * announcing themselves as "updated a few minutes ago" — in *batches*,
+ * phase-locked to a periodic task, because that is what actually moved them —
+ * and jumping to the top of a list sorted by recency. Nothing was lost; the
+ * ordering was simply not about what it claimed to be about.
+ *
+ * So: read the timestamp of the last real message **inside** the transcript,
+ * and fall back to mtime only when there is no datable record to read.
+ *
+ * ## Why a tail read rather than a parse
+ *
+ * The value wanted is on the last qualifying line, so this seeks to the end and
+ * walks backwards, stopping at the first line that qualifies. A transcript is
+ * append-only, so that is a couple of pages of IO regardless of whether the
+ * chat holds ten messages or ten thousand. `@herdctl/core` does compute this
+ * during `extractSessionMetadata`, but as part of a whole-file parse the
+ * listing path deliberately does not do — reusing it would have traded a
+ * cosmetic bug for a real one.
+ *
+ * Results are memoised against mtime (the same LRU the subagent and usage
+ * readers use). Note the irony, and that it is fine: a spurious touch — the
+ * very thing this module exists to ignore — still invalidates the cache and
+ * costs one tail read. It buys correctness in the other direction, where a
+ * touch accompanies a genuine append, and a tail read is cheap enough that
+ * paying it on a false alarm is not worth a subtler key.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { projectChatsDir } from "./transcripts.js";
+import { mtimeCacheGet, mtimeCacheSet, statMtimeMs } from "./subagents.js";
+/** How much of the file's end to look at before widening the window. */
+const TAIL_BYTES = 128 * 1024;
+/** The second and last attempt — enough to clear a single enormous tool result. */
+const WIDE_TAIL_BYTES = 4 * 1024 * 1024;
+const cache = new Map();
+/**
+ * Does this record represent a human or the agent actually saying something?
+ *
+ * The exclusions are the point of the whole issue, not defensive noise. A
+ * resume, a permission-mode change or a background agent finishing all append
+ * records to a transcript **without any turn having happened**, and counting
+ * those as activity reintroduces the same bug one layer up: a chat nobody has
+ * touched in a week, freshly stamped, back at the top of the list.
+ */
+function isConversation(rec) {
+    // Drops `summary` title entries and every `type: "system"` control line
+    // (local-command records, permission-mode changes, hook output).
+    if (rec.type !== "user" && rec.type !== "assistant")
+        return false;
+    // Harness-injected synthetic user lines: skill bodies, slash-command
+    // expansions, hook output. Nobody typed them.
+    if (rec.isMeta === true)
+        return false;
+    // A spawned agent's stop/complete block. Real work, but not a turn in THIS
+    // chat, and it lands without the user or the agent here saying anything.
+    if (rec.origin?.kind === "task-notification")
+        return false;
+    return true;
+}
+/** The last `bytes` of `file`, plus whether that covered the whole thing. */
+async function readTail(file, size, bytes) {
+    const take = Math.min(bytes, size);
+    const start = size - take;
+    const handle = await fs.open(file, "r");
+    try {
+        const buf = Buffer.alloc(take);
+        await handle.read(buf, 0, take, start);
+        // A byte offset can land mid-character; only the first line can be affected
+        // and the caller discards it whenever `whole` is false.
+        return { text: buf.toString("utf8"), whole: start === 0 };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Walk a window backwards for the newest qualifying record's timestamp. */
+function scanBackwards(text, whole) {
+    const lines = text.split("\n");
+    // Seeking to a byte offset almost certainly landed inside a line. Dropping it
+    // costs nothing (it is the OLDEST line in the window) and keeps a fragment
+    // from being mistaken for a malformed record.
+    if (!whole)
+        lines.shift();
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isConversation(rec))
+            continue;
+        const ts = rec.timestamp;
+        if (typeof ts === "string" && !Number.isNaN(Date.parse(ts)))
+            return ts;
+    }
+    return undefined;
+}
+/**
+ * Timestamp of the last real message in a project chat's transcript.
+ *
+ * `undefined` — a missing file, an unreadable one, a transcript of nothing but
+ * control records — is a legitimate answer meaning "nothing better than the
+ * mtime", and every caller treats it that way.
+ */
+export async function lastMessageAt(projectDir, sessionId) {
+    // Same guard as `readFirstUserText`: keep a session id from walking out of
+    // `.chats/`.
+    if (!/^[A-Za-z0-9._-]+$/.test(sessionId))
+        return undefined;
+    const file = path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`);
+    const mtimeMs = await statMtimeMs(file);
+    if (mtimeMs === undefined)
+        return undefined;
+    const cached = mtimeCacheGet(cache, file, mtimeMs);
+    if (cached.hit)
+        return cached.value;
+    let found;
+    try {
+        const { size } = await fs.stat(file);
+        if (size > 0) {
+            const near = await readTail(file, size, TAIL_BYTES);
+            found = scanBackwards(near.text, near.whole);
+            // Nothing qualified, and there is more file to look at: one transcript
+            // record can be megabytes (a large tool result), so the window can hold a
+            // single unterminated line. One wider retry, then give up to the mtime.
+            if (found === undefined && !near.whole) {
+                const far = await readTail(file, size, WIDE_TAIL_BYTES);
+                found = scanBackwards(far.text, far.whole);
+            }
+        }
+    }
+    catch {
+        found = undefined;
+    }
+    mtimeCacheSet(cache, file, mtimeMs, found);
+    return found;
+}
+/**
+ * Attach `lastMessageAt` to each session and order them newest-first.
+ *
+ * The sort lives here rather than in the client because the client is not the
+ * only reader: the MCP `list_chats` tool and the project-detail payload both
+ * take the server's order as given. The comparison falls back to `mtime`
+ * per-session rather than for the list as a whole, so a chat with no datable
+ * record still sorts sensibly against ones that have.
+ */
+export async function withLastActivity(projectDir, sessions) {
+    const enriched = await Promise.all(sessions.map(async (s) => {
+        const at = await lastMessageAt(projectDir, s.sessionId).catch(() => undefined);
+        return at === undefined ? { ...s } : { ...s, lastMessageAt: at };
+    }));
+    // ISO-8601 sorts lexicographically in chronological order, but only against
+    // another ISO-8601 string in the same shape — `Date.parse` rather than `<`,
+    // because `lastMessageAt` comes out of a transcript written by Claude Code
+    // and `mtime` out of `toISOString()`, and mixing offsets would otherwise
+    // compare as text.
+    return enriched.sort((a, b) => activityMs(b) - activityMs(a));
+}
+/** Epoch ms a session should be ordered by: its last message, else its mtime. */
+export function activityMs(s) {
+    return Date.parse(s.lastMessageAt ?? s.mtime) || 0;
+}

package/packages/server/dist/management-ops.js

@@ -113,7 +113,11 @@ export function buildManagementOps(ctx, params) {
                         project: p.slug,
                         sessionId: s.sessionId,
                         name: s.customName ?? s.autoName ?? s.sessionId.slice(0, 8),
-                        updatedAt: s.mtime,
+                        // Last real message, else the file mtime (#863) — the same rule
+                        // `chat-dto.ts` applies, because the MCP list and the web list
+                        // disagreeing about when a chat was last used is how a background
+                        // agent picks the wrong chat to follow up on.
+                        updatedAt: s.lastMessageAt ?? s.mtime,
                         running: hub.isRunning(s.sessionId),
                         // #489: the archived flag the web UI has always had (`chat-dto.ts`) but
                         // the MCP surface never reported — so the two disagreed about what "the

package/packages/server/dist/routes/chats.js

@@ -1436,8 +1436,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.get("/adoptable-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Count the native Claude Code chats this project could import",
-            description: "Returns the terminal `claude` sessions that could be imported into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name for a repo-backed project, by exact path for a notebook project). Sidechains, already-imported sessions and sessions belonging to a real Paddock run are excluded by the engine; empty transcripts, slash-command-only transcripts and Paddock's own sweeper curation runs (`too-small` / `slash-command-only` / `sweeper-run`) are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an import rather than remembering a dismissal.",
+            summary: "Count the native Claude Code chats this project could adopt",
+            description: "Returns the terminal `claude` sessions that could be adopted into this project but are not yet visible in it: the project's own working directory, plus any Claude transcript folder whose recorded working directory matches the project (by checkout name when the project has a `repo:` key, by exact path otherwise). Sidechains, already-adopted sessions and sessions belonging to a real Paddock run are excluded by the engine; empty transcripts, slash-command-only transcripts and Paddock's own sweeper curation runs (`too-small` / `slash-command-only` / `sweeper-run`) are additionally withheld as noise and reported under `filtered`, so a count lower than the raw total always has an explanation. Response: `{ count, sources: [{ sourceCwd, sessionIds }], filtered: [{ sessionId, sourceCwd, reason }] }`. The count is LIVE — re-read it after an adoption rather than remembering a dismissal.",
             params: {
                 type: "object",
                 properties: {
@@ -1474,8 +1474,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.post("/adopt-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Import native Claude Code chats into this project",
-            description: "Imports the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is imported; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. `sessionIds` narrows the import to a chosen SUBSET of what is on offer (what the confirmation dialog sends); ids that are not on offer are simply not imported, and anything the engine adopts as a side effect of taking a whole source is released again. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
+            summary: "Adopt native Claude Code chats into this project",
+            description: "Adopts the terminal `claude` sessions reported by GET …/adoptable-chats. With no body (or no `sourceCwd`) every detected source is adopted; with `sourceCwd` only that source is, and it must be one this project actually offers — an unrecognised path is a 400 rather than an invitation to scan arbitrary directories. `sessionIds` narrows the adoption to a chosen SUBSET of what is on offer (what the confirmation dialog sends); ids that are not on offer are simply not imported, and anything the engine adopts as a side effect of taking a whole source is released again. Transcripts are COPIED, never moved: the user's own `~/.claude` history is left intact and the copies keep their original mtimes, so imported chats sort by when they really happened. Afterwards the session, run-record and detection caches are dropped, so the chats appear on the very next list request with no restart. Response: `{ adopted, skipped }` — `skipped` carries the engine's reason per session (`sidechain`, `already-adopted`, `destination-exists`, `attributed-to-run`, `unreadable`, `placement-failed`, `record-failed`).",
             params: {
                 type: "object",
                 properties: {
@@ -1500,7 +1500,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object `{ adopted, skipped }` describing what was imported.",
+                    description: "Object `{ adopted, skipped }` describing what was adopted.",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -1549,8 +1549,8 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     app.post("/unadopt-chats", {
         schema: {
             tags: ["Chats"],
-            summary: "Undo the most recent native-chat import into this project",
-            description: "Reverses the import this server most recently performed into the workspace: each adoption is released and the copies that import placed are deleted, leaving the user's own `~/.claude` history untouched. `sessionIds` undoes part of that import; omit it to undo all of it. Deliberately scoped to the LAST import and remembered in memory — undo may delete files, so the paths it can touch come from what this process actually did rather than from the request body, and a restart forgets the offer rather than acting on a stale one. Response: `{ released }`, the session ids actually released; an empty array means there was nothing to undo (nothing imported, already undone, or the server restarted since).",
+            summary: "Undo the most recent native-chat adoption into this project",
+            description: "Reverses the adoption this server most recently performed into the workspace: each adoption is released and the copies that adoption placed are deleted, leaving the user's own `~/.claude` history untouched. `sessionIds` undoes part of that adoption; omit it to undo all of it. Deliberately scoped to the LAST adoption and remembered in memory — undo may delete files, so the paths it can touch come from what this process actually did rather than from the request body, and a restart forgets the offer rather than acting on a stale one. Response: `{ released }`, the session ids actually released; an empty array means there was nothing to undo (nothing imported, already undone, or the server restarted since).",
             params: {
                 type: "object",
                 properties: {

package/packages/server/dist/routes/discover.js

@@ -37,7 +37,7 @@
  * here; on a shared authenticated instance it is worth knowing about.
  */
 import path from "node:path";
-import { defaultTempRoots, discoverCandidates, discoverSessions, DiscoverPathError, } from "../discover.js";
+import { defaultTempRoots, discoverCandidates, discoverSessions, DiscoverPathError, withoutOwnTranscriptFolders, } from "../discover.js";
 import { ROOT_KEY } from "../project-paths.js";
 /** A `?flag=` that is present and not explicitly falsy. */
 function flag(value) {
@@ -54,7 +54,14 @@ export function registerDiscoverRoutes(app, ctx) {
     async function context() {
         const existing = [...(await projects.list()), await projects.get(ROOT_KEY)];
         return {
-            folders: await herdctl.transcriptFolders(),
+            // Paddock's own `.chats` bridges are removed BEFORE the scan sees them, so
+            // they are not counted in `scanned` either (#865). A pristine instance has
+            // two of them and nothing else, and counting those was what made
+            // `scanned === 0` — "no history on this machine" — unreachable.
+            folders: withoutOwnTranscriptFolders(await herdctl.transcriptFolders(), {
+                ownRoots: [cfg.projectsRoot, cfg.dataDir],
+                claudeHomes: [cfg.claudeHome, cfg.legacyClaudeHome],
+            }),
             claudeHome: cfg.claudeHome,
             // The user's own home, taken from the one place config already resolves it
             // (`legacyClaudeHome` is `os.homedir()/.claude`, with no override) so this
@@ -73,7 +80,7 @@ export function registerDiscoverRoutes(app, ctx) {
         schema: {
             tags: ["System"],
             summary: "Directories on this machine that could become projects",
-            description: "Scans `<claudeHome>/projects/*` for directories with existing Claude Code history and returns the ones worth importing, ranked by how many non-noise sessions each holds. Never walks the filesystem: the only directories it can name are ones a transcript already records, and each is put through the same path floor a linked project must clear (no system directories, no temp roots, nothing inside Paddock's own data dir, nothing overlapping an existing project). Two rules are relaxable: `includeNonGit=1` offers directories that are not git checkouts, `includeOutsideHome=1` offers directories outside `$HOME`. `excluded` reports how many folders each rule ate — a container whose Claude home is empty reports `scanned: 0`, which is what distinguishes 'no history' from 'all of it was filtered'. Response: `{ claudeHome, homeDir, scanned, candidates, excluded }`.",
+            description: "Scans `<claudeHome>/projects/*` for directories with existing Claude Code history and returns the ones worth importing, ranked by how many non-noise sessions each holds. Never walks the filesystem: the only directories it can name are ones a transcript already records, and each is put through the same path floor a linked project must clear (no system directories, no temp roots, nothing inside Paddock's own data dir, nothing overlapping an existing project). Two rules are relaxable: `includeNonGit=1` offers directories that are not git checkouts, `includeOutsideHome=1` offers directories outside `$HOME`. Note the two counts are in DIFFERENT units and do not reconcile by subtraction: `scanned` counts transcript FOLDERS, while `excluded` reports how many DIRECTORIES each rule ate — one directory routinely has two transcript folders (the user's own and Paddock's copy), so a rule that ate one directory may account for two scanned folders. The single exception is `no-recorded-cwd`, which is necessarily per-folder: a folder with no recorded cwd has no directory to be counted under. A machine with no Claude Code history reports `scanned: 0`, which is what distinguishes 'no history' from 'all of it was filtered'. Paddock's own `.chats` bridge folders are excluded before that count is taken — they exist on an instance nobody has used yet, and counting them made `scanned: 0` unreachable. Response: `{ claudeHome, homeDir, scanned, candidates, excluded }`.",
             querystring: {
                 type: "object",
                 properties: {

package/packages/server/dist/self-mcp-types.d.ts

@@ -68,7 +68,10 @@ export interface SelfMcpChat {
     sessionId: string;
     /** Display name (custom name, else auto-name, else a short id). */
     name: string;
-    /** ISO timestamp of the last transcript write (mtime). */
+    /**
+     * ISO timestamp of the last real message in the transcript (#863) — the file's
+     * mtime only when no message in it carries a usable date.
+     */
     updatedAt: string;
     /** Whether a turn is currently in flight for this chat. */
     running: boolean;

package/packages/server/dist/transcripts.js

@@ -179,9 +179,11 @@ export async function ensureProjectChats(workingDir, chatsHostDir, home) {
                 // cp+rm is robust across filesystems (rename would EXDEV across mounts).
                 // `preserveTimestamps` is load-bearing, not cosmetic (#588): fs.cp
                 // defaults to stamping the copy with NOW, and a transcript's mtime is
-                // both the chat-list sort key and the cache key for auto-name / preview /
-                // sidechain detection — so without it, relocating a months-old archive
-                // collapses every one of those chats to "today".
+                // the cache key for auto-name / preview / sidechain detection — so
+                // without it, relocating a months-old archive re-derives every one of
+                // those. It is no longer the chat-list sort key (#863, that now comes
+                // from the last message INSIDE the transcript), which narrows the blast
+                // radius of getting this wrong but does not remove it.
                 await fs.cp(from, to, { recursive: true, preserveTimestamps: true });
                 await fs.rm(from, { recursive: true, force: true });
             }