@edspencer/paddock 0.71.0 → 0.71.2

package/packages/server/dist/cli/service/launchd.js

@@ -51,10 +51,22 @@ function xmlEscape(s) {
 /**
  * Render the plist.
  *
- * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
- * false` means "restart it if it exits nonzero, leave it alone if it exits
- * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
- * make stopping Paddock a wrestling match.
+ * `KeepAlive` is unconditional `<true/>`, and that is a deliberate reversal
+ * (#872). It used to be `{ SuccessfulExit: false }` — "restart it if it exits
+ * nonzero, leave it alone if it exits cleanly" — which reads like the polite
+ * choice and is, for a service, a trap. `start.ts` handles SIGTERM by shutting
+ * down cleanly and exiting `0`, so **every** SIGTERM the OS routinely sends a
+ * LaunchAgent (sleep, logout, a stray `kill`) looked to launchd like "it meant
+ * to stop", and Paddock stayed down until the next login. A hard crash was the
+ * survivable case; the graceful stop was the terminal one.
+ *
+ * The worry that motivated the dict — that `<true/>` fights a deliberate stop —
+ * does not hold for the stop this CLI actually performs. `launchctl bootout`
+ * unloads the job from the domain, and KeepAlive only applies to a job that is
+ * still loaded, so `uninstall` still stops Paddock in one call. What `<true/>`
+ * does fight is `launchctl stop`, which is why nothing here uses it.
+ *
+ * Intent belongs in an explicit command, not in an exit code.
  *
  * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
  * launchd hands a process a stub PATH that a version manager's `node`, and the
@@ -82,10 +94,7 @@ ${strings}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-      <key>SuccessfulExit</key>
-      <false/>
-    </dict>
+    <true/>
     <key>ThrottleInterval</key>
     <integer>10</integer>
     <key>WorkingDirectory</key>
@@ -123,6 +132,19 @@ export function parsePlistArgv(xml) {
         .replace(/&lt;/g, "<")
         .replace(/&amp;/g, "&"));
 }
+/**
+ * Does an installed plist carry the unconditional `KeepAlive` from #872?
+ *
+ * Deliberately narrow: it matches `<key>KeepAlive</key>` followed by `<true/>`
+ * and nothing else. The shape it must NOT accept is the old
+ * `<dict><key>SuccessfulExit</key><false/></dict>`, which is the one that
+ * leaves a service dead after a graceful stop — so a `false` here is the signal
+ * `status` turns into "re-run install", and defaulting to `true` on anything
+ * unrecognised would silence exactly the case this exists to catch.
+ */
+export function plistKeepsAlive(xml) {
+    return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(xml);
+}
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *
@@ -139,6 +161,10 @@ export function parseLaunchctlPrint(out) {
         ...(pid !== null ? { pid: pid[1] } : {}),
     };
 }
+/** One phrasing for "launchctl said no", so every caller reports it the same way. */
+function launchctlFailure(verb, r) {
+    return (`launchctl ${verb} failed (exit ${String(r.status)}).\n` + `${r.stderr || r.stdout}`.trim());
+}
 function target() {
     return `gui/${process.getuid?.() ?? 0}/${LAUNCHD_LABEL}`;
 }
@@ -164,10 +190,8 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
             // they are shims over this one that report success in cases where it
             // reports the actual error.
             const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0) {
-                throw new Error(`launchctl bootstrap failed (exit ${String(boot.status)}).\n` +
-                    `${boot.stderr || boot.stdout}`.trim());
-            }
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
             // `RunAtLoad` should already have started it; `kickstart -k` makes that
             // true rather than probable, and is the same command a later restart uses.
             run("launchctl", ["kickstart", "-k", target()]);
@@ -179,10 +203,59 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 fs.rmSync(file, { force: true });
             return existed;
         },
+        /**
+         * Load the job back into the GUI domain and make sure it is running (#873).
+         *
+         * `bootstrap`, not `launchctl start`: `stop` below BOOTS OUT, so a stopped
+         * Paddock is not merely idle, it is absent from the domain — and `start` on
+         * a label launchd has never heard of fails. Bootstrapping is also what a
+         * login does, so `service start` and the next login take the same path.
+         */
+        start() {
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", target()]);
+        },
+        /**
+         * `bootout`, not `launchctl stop`.
+         *
+         * With #872's unconditional `KeepAlive`, `stop` is a request launchd
+         * immediately overrules — it stops the process and then relaunches it,
+         * which is exactly the wrestling match the old conditional KeepAlive was
+         * meant to avoid. `bootout` unloads the job, so KeepAlive no longer applies
+         * and it stays down. The plist is untouched, so `status` still reports it
+         * registered, `start` puts it back, and the next LOGIN starts it again via
+         * `RunAtLoad` — a stop is for this session, not forever. Uninstall is the
+         * one that is forever.
+         */
+        stop() {
+            const out = run("launchctl", ["bootout", target()]);
+            // Exit 3 / "No such process" is launchd for "it was not loaded", which is
+            // the state the caller asked for. Anything else is worth surfacing.
+            if (out.status !== 0 && !/no such process/i.test(`${out.stderr}${out.stdout}`)) {
+                throw new Error(launchctlFailure("bootout", out));
+            }
+        },
+        /**
+         * Boot out, bootstrap, kick. Not `kickstart -k` alone, which needs the job
+         * to be loaded and so fails on the case `restart` most needs to handle: a
+         * service that is stopped. This sequence is identical to `install`'s minus
+         * writing the plist, which also gives `restart` the property the issue asks
+         * for — the unit is re-read on the way up, so an edited plist takes effect.
+         */
+        restart() {
+            run("launchctl", ["bootout", target()]);
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", "-k", target()]);
+        },
         status() {
             if (!fs.existsSync(file))
-                return { registered: false, running: false, argv: [] };
-            const argv = parsePlistArgv(fs.readFileSync(file, "utf8"));
+                return { registered: false, running: false, argv: [], keepsAlive: true };
+            const xml = fs.readFileSync(file, "utf8");
+            const argv = parsePlistArgv(xml);
             const printed = run("launchctl", ["print", target()]);
             const parsed = printed.status === 0
                 ? parseLaunchctlPrint(printed.stdout)
@@ -194,6 +267,7 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 // Strip the interpreter and script: what a reader wants from `status`
                 // is the Paddock invocation, not the absolute path to node twice.
                 argv: argv.slice(2),
+                keepsAlive: plistKeepsAlive(xml),
             };
         },
         logsHint(spec) {

package/packages/server/dist/cli/service/ready.d.ts

@@ -0,0 +1,61 @@
+/**
+ * "Is it actually up?" — the bounded readiness poll the service CLI uses before
+ * it claims success (#873, #861).
+ *
+ * Every service command that starts something has the same failure mode without
+ * this: the supervisor accepts the request and returns, so the CLI prints a URL
+ * and a cheerful past tense while the server is still binding — or is already
+ * crash-looping on a port clash, which `launchctl` and `systemctl` will both
+ * happily report as "running" for the ten seconds between restarts. A message
+ * that can sit over a crash-loop and still say "running at <url>" is not a
+ * status line, it is a guess.
+ *
+ * So the check is deliberately end-to-end: an HTTP request to the URL a human
+ * would open, not a pid lookup. `/api/health` is the probe because it is in
+ * `ALWAYS_PUBLIC_PATHS` (`auth.ts`) — it answers whatever `PADDOCK_AUTH_MODE`
+ * the installed unit runs with, so this does not quietly stop working for the
+ * people who configured a credential.
+ *
+ * The result is a tri-state on purpose. "I could not confirm it" is a real and
+ * common answer — an unusual bind host, a slow first boot — and it is not the
+ * same claim as "it failed". Callers print it as a caveat, not an error, and
+ * point at the logs.
+ */
+/** Where the poll got to when it stopped. */
+export type Readiness = "ready" | "timeout";
+export interface ReadyOptions {
+    /** Base URL of the server, e.g. `http://127.0.0.1:7233` — no trailing slash. */
+    url: string;
+    /** Give up after this long. */
+    timeoutMs?: number;
+    /** Gap between attempts. */
+    intervalMs?: number;
+    /** Injected for tests; defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests, so a timeout can be proven without waiting for one. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long to wait before saying "could not confirm".
+ *
+ * Generous rather than snappy: this budget is only ever spent on the unhappy
+ * path (a ready server answers in well under a second), and the cost of being
+ * too short is a false "did not answer" on a cold boot — the single most
+ * alarming thing this output could say about a service that is in fact fine.
+ */
+export declare const READY_TIMEOUT_MS = 20000;
+/** The same budget as prose, so a message and the clock cannot drift apart. */
+export declare const READY_TIMEOUT_LABEL = "20 seconds";
+/**
+ * Poll `<url>/api/health` until it answers, or until `timeoutMs` elapses.
+ *
+ * Connection errors are the expected case rather than the exceptional one — a
+ * server that has not finished binding refuses the connection — so they are
+ * swallowed and retried. Only the clock ends the loop.
+ *
+ * Each request carries its own abort so a hung socket cannot outlive the budget
+ * it was given; without it a single connection that opens and never replies
+ * would park here well past `timeoutMs`.
+ */
+export declare function waitForReady(opts: ReadyOptions): Promise<Readiness>;

package/packages/server/dist/cli/service/ready.js

@@ -0,0 +1,71 @@
+/**
+ * "Is it actually up?" — the bounded readiness poll the service CLI uses before
+ * it claims success (#873, #861).
+ *
+ * Every service command that starts something has the same failure mode without
+ * this: the supervisor accepts the request and returns, so the CLI prints a URL
+ * and a cheerful past tense while the server is still binding — or is already
+ * crash-looping on a port clash, which `launchctl` and `systemctl` will both
+ * happily report as "running" for the ten seconds between restarts. A message
+ * that can sit over a crash-loop and still say "running at <url>" is not a
+ * status line, it is a guess.
+ *
+ * So the check is deliberately end-to-end: an HTTP request to the URL a human
+ * would open, not a pid lookup. `/api/health` is the probe because it is in
+ * `ALWAYS_PUBLIC_PATHS` (`auth.ts`) — it answers whatever `PADDOCK_AUTH_MODE`
+ * the installed unit runs with, so this does not quietly stop working for the
+ * people who configured a credential.
+ *
+ * The result is a tri-state on purpose. "I could not confirm it" is a real and
+ * common answer — an unusual bind host, a slow first boot — and it is not the
+ * same claim as "it failed". Callers print it as a caveat, not an error, and
+ * point at the logs.
+ */
+/**
+ * How long to wait before saying "could not confirm".
+ *
+ * Generous rather than snappy: this budget is only ever spent on the unhappy
+ * path (a ready server answers in well under a second), and the cost of being
+ * too short is a false "did not answer" on a cold boot — the single most
+ * alarming thing this output could say about a service that is in fact fine.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+/** The same budget as prose, so a message and the clock cannot drift apart. */
+export const READY_TIMEOUT_LABEL = `${READY_TIMEOUT_MS / 1000} seconds`;
+const DEFAULT_INTERVAL_MS = 250;
+/**
+ * Poll `<url>/api/health` until it answers, or until `timeoutMs` elapses.
+ *
+ * Connection errors are the expected case rather than the exceptional one — a
+ * server that has not finished binding refuses the connection — so they are
+ * swallowed and retried. Only the clock ends the loop.
+ *
+ * Each request carries its own abort so a hung socket cannot outlive the budget
+ * it was given; without it a single connection that opens and never replies
+ * would park here well past `timeoutMs`.
+ */
+export async function waitForReady(opts) {
+    const { url, timeoutMs = READY_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS, fetchImpl = fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), } = opts;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return "timeout";
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), Math.min(remaining, timeoutMs));
+        try {
+            const res = await fetchImpl(`${url}/api/health`, { signal: abort.signal });
+            if (res.ok)
+                return "ready";
+        }
+        catch {
+            // Refused, reset, aborted — all "not yet", all retried until the clock says stop.
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (deadline - now() <= 0)
+            return "timeout";
+        await sleep(intervalMs);
+    }
+}

package/packages/server/dist/cli/service/systemd.d.ts

@@ -31,8 +31,17 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
 /**
  * Render the unit.
  *
- * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
- * false` — a clean shutdown should stay shut down.
+ * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
+ * `on-failure`, which for a service is the wrong default for the same reason it
+ * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
+ * else that signals the user manager — was read as an intended stop and Paddock
+ * stayed down.
+ *
+ * `always` does not make the unit unstoppable. systemd never restarts a unit it
+ * was itself asked to stop, so `systemctl --user stop` (and therefore
+ * `uninstall`) remains the clean, explicit way to put it down. That is the
+ * difference between an exit code, which has to guess at intent, and a command,
+ * which carries it.
  *
  * `WantedBy=default.target` is what makes `systemctl --user enable` mean
  * "start at login" for a user unit; `multi-user.target` is the system-unit
@@ -43,6 +52,16 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
  * answers to "where are the logs".
  */
 export declare function renderUnit(spec: ServiceSpec): string;
+/**
+ * Does an installed unit carry `Restart=always` (#872)?
+ *
+ * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
+ * value it has to reject is the `on-failure` this file used to write, which
+ * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
+ * Anything unrecognised reads as "not the fixed shape", which at worst tells a
+ * hand-edited unit's owner to re-run install.
+ */
+export declare function unitKeepsAlive(text: string): boolean;
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export declare function parseUnitArgv(text: string): string[];
 export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;

package/packages/server/dist/cli/service/systemd.js

@@ -62,8 +62,17 @@ export function unitPath(homeDir, xdgConfigHome) {
 /**
  * Render the unit.
  *
- * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
- * false` — a clean shutdown should stay shut down.
+ * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
+ * `on-failure`, which for a service is the wrong default for the same reason it
+ * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
+ * else that signals the user manager — was read as an intended stop and Paddock
+ * stayed down.
+ *
+ * `always` does not make the unit unstoppable. systemd never restarts a unit it
+ * was itself asked to stop, so `systemctl --user stop` (and therefore
+ * `uninstall`) remains the clean, explicit way to put it down. That is the
+ * difference between an exit code, which has to guess at intent, and a command,
+ * which carries it.
  *
  * `WantedBy=default.target` is what makes `systemctl --user enable` mean
  * "start at login" for a user unit; `multi-user.target` is the system-unit
@@ -84,13 +93,25 @@ Type=simple
 ExecStart=${exec}
 WorkingDirectory=${spec.workingDirectory}
 Environment=PATH=${spec.pathEnv}
-Restart=on-failure
+Restart=always
 RestartSec=10
 
 [Install]
 WantedBy=default.target
 `;
 }
+/**
+ * Does an installed unit carry `Restart=always` (#872)?
+ *
+ * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
+ * value it has to reject is the `on-failure` this file used to write, which
+ * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
+ * Anything unrecognised reads as "not the fixed shape", which at worst tells a
+ * hand-edited unit's owner to re-run install.
+ */
+export function unitKeepsAlive(text) {
+    return /^Restart=always\s*$/m.test(text);
+}
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export function parseUnitArgv(text) {
     const m = /^ExecStart=(.*)$/m.exec(text);
@@ -98,6 +119,14 @@ export function parseUnitArgv(text) {
         return [];
     return m[1].trim().split(/\s+/).filter(Boolean);
 }
+/** Run a `systemctl` and turn a non-zero exit into the manager's own words. */
+function systemctlOrThrow(run, args) {
+    const r = run("systemctl", args);
+    if (r.status === 0)
+        return;
+    throw new Error(`systemctl ${args.join(" ")} failed (exit ${String(r.status)}).\n` +
+        `${r.stderr || r.stdout}`.trim());
+}
 export function createSystemdBackend(run, homeDir, xdgConfigHome) {
     // Both forwarded, neither defaulted here: `unitPath` owns the precedence, and
     // defaulting `homeDir` to `os.homedir()` at this layer would collapse "the
@@ -129,10 +158,33 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             run("systemctl", ["--user", "daemon-reload"]);
             return existed;
         },
+        /**
+         * The lifecycle three (#873), which on systemd are just the verbs.
+         *
+         * None of them touches `enable`/`disable`: those decide whether Paddock
+         * comes back at your NEXT login, which is a different question from whether
+         * it is running now, and quietly answering both would make `stop` a
+         * surprise the following morning. `uninstall` is where that link is cut.
+         *
+         * `restart` re-reads the unit itself, but a `daemon-reload` first is what
+         * makes an EDITED unit take effect rather than the manager's cached copy —
+         * the same reason `install` reloads before enabling.
+         */
+        start() {
+            systemctlOrThrow(run, ["--user", "start", SYSTEMD_UNIT]);
+        },
+        stop() {
+            systemctlOrThrow(run, ["--user", "stop", SYSTEMD_UNIT]);
+        },
+        restart() {
+            run("systemctl", ["--user", "daemon-reload"]);
+            systemctlOrThrow(run, ["--user", "restart", SYSTEMD_UNIT]);
+        },
         status() {
             if (!fs.existsSync(file))
-                return { registered: false, running: false, argv: [] };
-            const argv = parseUnitArgv(fs.readFileSync(file, "utf8"));
+                return { registered: false, running: false, argv: [], keepsAlive: true };
+            const text = fs.readFileSync(file, "utf8");
+            const argv = parseUnitArgv(text);
             const active = run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
             const pid = run("systemctl", ["--user", "show", "-p", "MainPID", "--value", SYSTEMD_UNIT]);
             const mainPid = pid.stdout.trim();
@@ -141,6 +193,7 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
                 running: active.stdout.trim() === "active",
                 ...(mainPid !== "" && mainPid !== "0" ? { pid: mainPid } : {}),
                 argv: argv.slice(2),
+                keepsAlive: unitKeepsAlive(text),
             };
         },
         logsHint() {

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

@@ -141,6 +141,43 @@ export interface DiscoverContext {
 }
 /** The ephemeral roots on THIS machine — the well-known set plus `$TMPDIR`. */
 export declare function defaultTempRoots(): string[];
+/**
+ * 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 declare function withoutOwnTranscriptFolders(folders: TranscriptFolder[], roots: {
+    /** Paddock's own storage: the projects root and the data dir. */
+    ownRoots: string[];
+    /** Both Claude homes — paddock's and the user's. */
+    claudeHomes: string[];
+}): TranscriptFolder[];
 /**
  * Is this an ephemeral scratch directory?
  *

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.
  *
@@ -869,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
@@ -1519,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) {
@@ -1532,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;