@edspencer/paddock 0.71.0 → 0.71.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.71.0",
+  "version": "0.71.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/chat-dto.d.ts

@@ -6,6 +6,7 @@
  * and the run-history page-size constants + `clampRunsLimit`.
  */
 import type { DiscoveredSession } from "@herdctl/core";
+import type { SessionWithActivity } from "./last-activity.js";
 import type { Project } from "./projects.js";
 import { type SessionTokenUsage } from "./usage.js";
 import type { RunProvenance } from "./run-provenance.js";
@@ -138,7 +139,7 @@ export type ChatUsageScope = (typeof CHAT_USAGE_SCOPES)[number];
  * each class separately (see {@link estimateCostUsd}).
  */
 export declare function toChatUsage(u: SessionTokenUsage, model: string): ChatUsage | null;
-export declare function toChatDto(s: DiscoveredSession, previewOverride?: string, usage?: ChatUsage | null, archived?: boolean, lastTurnCompletedAt?: string, lastSeen?: number, provenance?: RunProvenance | null, trigger?: ChatTriggerInfo | null, starred?: boolean, unread?: boolean, parent?: ChatParentRef | null): {
+export declare function toChatDto(s: SessionWithActivity, previewOverride?: string, usage?: ChatUsage | null, archived?: boolean, lastTurnCompletedAt?: string, lastSeen?: number, provenance?: RunProvenance | null, trigger?: ChatTriggerInfo | null, starred?: boolean, unread?: boolean, parent?: ChatParentRef | null): {
     trigger?: ChatTriggerInfo | undefined;
     parent?: ChatParentRef | undefined;
     provenance?: RunProvenance | undefined;
@@ -170,7 +171,7 @@ export declare function toChatDto(s: DiscoveredSession, previewOverride?: string
  * name reflects the user's actual request. Only preload chats trigger the extra
  * (head-of-file) read; everything else maps straight through.
  */
-export declare function buildProjectChats(projectDir: string, sessions: DiscoveredSession[], usageOf?: (s: DiscoveredSession) => Promise<ChatUsage | null>, archivedOf?: (s: DiscoveredSession) => Promise<boolean>, lastTurnAt?: ReadonlyMap<string, string>, lastSeenOf?: (s: DiscoveredSession) => Promise<number>, provenanceOf?: (s: DiscoveredSession) => Promise<RunProvenance | undefined>, triggerOf?: (s: DiscoveredSession) => Promise<ChatTriggerInfo | undefined>, starredOf?: (s: DiscoveredSession) => Promise<boolean>, unreadOf?: (s: DiscoveredSession) => Promise<boolean>, parentOf?: (s: DiscoveredSession) => Promise<ChatParentRef | null>): Promise<{
+export declare function buildProjectChats(projectDir: string, sessions: SessionWithActivity[], usageOf?: (s: DiscoveredSession) => Promise<ChatUsage | null>, archivedOf?: (s: DiscoveredSession) => Promise<boolean>, lastTurnAt?: ReadonlyMap<string, string>, lastSeenOf?: (s: DiscoveredSession) => Promise<number>, provenanceOf?: (s: DiscoveredSession) => Promise<RunProvenance | undefined>, triggerOf?: (s: DiscoveredSession) => Promise<ChatTriggerInfo | undefined>, starredOf?: (s: DiscoveredSession) => Promise<boolean>, unreadOf?: (s: DiscoveredSession) => Promise<boolean>, parentOf?: (s: DiscoveredSession) => Promise<ChatParentRef | null>): Promise<{
     trigger?: ChatTriggerInfo | undefined;
     parent?: ChatParentRef | undefined;
     provenance?: RunProvenance | undefined;

package/packages/server/dist/chat-dto.js

@@ -185,7 +185,15 @@ export function toChatDto(s, previewOverride, usage, archived = false, lastTurnC
         sessionId: s.sessionId,
         workingDirectory: s.workingDirectory,
         name: s.customName ?? s.autoName ?? preview ?? s.sessionId.slice(0, 8),
-        updatedAt: s.mtime,
+        // The last real MESSAGE in the transcript, not the file's mtime (#863).
+        // Paddock touches transcripts for reasons that are not conversation — a
+        // discovery re-stat, a resume appending a mode record — and every one of
+        // those used to restamp an idle chat as "updated a few minutes ago" and
+        // float it to the top of a list sorted by recency. mtime survives as the
+        // fallback for a transcript with no datable record, and only as that: it is
+        // still the cache key for auto-name, preview and usage, so it is read here
+        // rather than overwritten upstream.
+        updatedAt: s.lastMessageAt ?? s.mtime,
         resumable: s.resumable,
         preview,
         // Whether this chat is filed away in the Archived section (#95). Always

package/packages/server/dist/cli/paddock.js

@@ -155,7 +155,7 @@ function openBrowser(url) {
  * for npx's cache, because a unit file pointing into a prunable hash-keyed
  * directory rots at some future login with nobody watching.
  */
-function service(command) {
+async function service(command) {
     const { action, opts } = command;
     // Unreachable: `parseCommand` only omits the action when `--help` was given,
     // which `main` has already handled. Typed rather than asserted.
@@ -164,7 +164,7 @@ function service(command) {
         return;
     }
     try {
-        runService(action, opts, {
+        await runService(action, opts, {
             platform: process.platform,
             nodePath: process.execPath,
             scriptPath: entryScript,
@@ -210,7 +210,7 @@ async function main() {
     if (problem !== undefined)
         fail(problem);
     if (command.verb === "service") {
-        service(command);
+        await service(command);
         return;
     }
     addBundledBinsToPath();

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

@@ -1,6 +1,7 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
 import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
 import { type Runner } from "./backend.js";
+import { type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
     platform: NodeJS.Platform;
@@ -17,8 +18,16 @@ export interface ServiceContext {
     xdgConfigHome?: string;
     pathEnv?: string;
     run?: Runner;
+    /**
+     * "Did the URL answer?", injected for the same reason `run` is.
+     *
+     * Without a seam here every install test would really poll 127.0.0.1 for the
+     * full timeout and then assert on the disappointed message — twenty seconds
+     * per case, and green for the wrong reason.
+     */
+    checkReady?: (url: string) => Promise<Readiness>;
 }
-export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): void;
+export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<void>;
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 export type { ServiceSpec };

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

@@ -29,6 +29,7 @@ import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFr
 import { spawnRunner } from "./backend.js";
 import { createLaunchdBackend } from "./launchd.js";
 import { createSystemdBackend } from "./systemd.js";
+import { waitForReady, READY_TIMEOUT_LABEL } from "./ready.js";
 /**
  * Pick a backend, or explain why there isn't one.
  *
@@ -76,19 +77,56 @@ function specFor(opts, ctx) {
 const AT_LOGIN = "  Paddock starts when you LOG IN, not when the machine boots — it runs as\n" +
     "  you, so it can use the Claude login you already have. After a restart\n" +
     "  that nobody logs into, Paddock is not running.";
-function install(opts, ctx, backend) {
+/**
+ * Say what is about to happen, before the part that looks like a hang (#861).
+ *
+ * `backend.install` runs `launchctl bootout` / `bootstrap` / `kickstart` — or
+ * the systemd equivalents — through `spawnSync`, and on macOS the bootstrap is
+ * followed by Background-Task-Management registering the new LaunchAgent as a
+ * login item (the "… can run in the background" notification fires in this
+ * window). Three to five seconds, and every one of them silent.
+ *
+ * **There is no spinner here, and that is not laziness.** Those subprocess calls
+ * are synchronous: they block the event loop, so a `setInterval` ticker would
+ * sit frozen for exactly the span it was added to animate — worse than no
+ * spinner, because a stopped spinner reads as a crashed process. Animating it
+ * would mean making the whole `Runner` seam async, which is a much larger change
+ * than this issue is asking for. The defect reported was the SILENCE, and text
+ * on the screen fixes the silence.
+ */
+function installProgress(backend) {
+    const kind = backend.platform === "darwin" ? "the LaunchAgent" : "the user service";
+    return backend.platform === "darwin"
+        ? `\n  Installing ${kind} and starting Paddock…\n` +
+            "  macOS may take a few seconds to approve the background item."
+        : `\n  Installing ${kind} and starting Paddock…`;
+}
+async function install(opts, ctx, backend) {
     if (isNpxPath(ctx.packageRoot))
         throw new CliError(NPX_REFUSAL);
     const { spec, dataDir } = specFor(opts, ctx);
-    backend.install(spec);
     const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`;
+    console.log(installProgress(backend));
+    backend.install(spec);
+    // The unit is written and the supervisor has accepted it. That is NOT the
+    // same as "Paddock is running", which is what this block used to assert
+    // before anything had been checked — so the success message could sit over a
+    // crash-loop (a port clash restarts every RestartSec/ThrottleInterval, and
+    // both supervisors report `running` for most of that window) and still print
+    // a URL and a tick. Waiting is what makes the headline true.
+    console.log(`  Waiting for ${url} to answer…`);
+    const readiness = await (ctx.checkReady ?? ((u) => waitForReady({ url: u })))(url);
     const kind = backend.platform === "darwin" ? "a launchd LaunchAgent" : "a systemd --user service";
     const linger = backend.lingerNote();
     console.log([
         "",
-        `  Paddock is installed as ${kind}, and running now.`,
+        readiness === "ready"
+            ? `  ✓ Paddock is installed as ${kind}, and running at ${url}`
+            : `  Paddock is installed as ${kind}, but ${url} did not answer\n` +
+                `  within ${READY_TIMEOUT_LABEL}. The unit is in place; it may still be\n` +
+                "  coming up, or it may be failing to start — the logs below say which.",
         "",
-        `  URL:  ${url}`,
+        ...(readiness === "ready" ? [] : [`  URL:  ${url}`]),
         `  Data: ${dataDir}`,
         `  Unit: ${backend.unitPath}`,
         backend.logsHint(spec),
@@ -160,7 +198,7 @@ function status(opts, ctx, backend) {
         "",
     ].join("\n"));
 }
-export function runService(action, opts, ctx) {
+export async function runService(action, opts, ctx) {
     const backend = backendFor(ctx);
     if (action === "install")
         return install(opts, ctx, backend);

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