#2066 · Timeline cache retains obsolete revisions for the same request shape

/**
 * Unit-level repro for get-bb/bb#2066 against the cache in isolation, using the
 * exact key builder the route uses. Two revisions (maxSeq 10 then 11) of one
 * request shape leave two resident entries although only the newest can ever
 * be looked up again (a thread's maxSeq never decreases).
 */
import { describe, expect, it } from "vitest";
import type { ThreadTimelineResponse } from "@bb/server-contract";
import {
  buildThreadTimelineCacheKey,
  createThreadTimelineCache,
  type ThreadTimelineCacheKeyArgs,
} from "../../../src/services/threads/timeline-cache.js";

function makeResponse(rowCount: number): ThreadTimelineResponse {
  return {
    rows: Array.from({ length: rowCount }, (_, index) => ({
      id: `row-${index}`,
      kind: "system",
      threadId: "thr_x",
      turnId: null,
      sourceSeqStart: index,
      sourceSeqEnd: index,
      startedAt: 0,
      createdAt: 0,
      systemKind: "debug",
      title: "t",
      detail: null,
      status: null,
    })),
    activePromptMode: null,
    activeThinking: null,
    activeWorkflows: [],
    activeBackgroundCommands: [],
    pendingTodos: null,
    goal: null,
    modelFallback: null,
    maxSeq: 0,
    timelinePage: {
      kind: "latest",
      segmentLimit: 20,
      returnedSegmentCount: 0,
      hasOlderRows: false,
      olderCursor: null,
    },
  };
}

const shape: ThreadTimelineCacheKeyArgs = {
  threadId: "thr_x",
  maxSeq: 10,
  status: "active",
  environmentId: null,
  page: { kind: "latest", segmentLimit: 20 },
  includeNestedRows: false,
  summaryOnly: false,
  includeProviderUnhandledOperations: false,
};

describe("#2066 unit", () => {
  it("replaces the previous revision of the same request shape", () => {
    const cache = createThreadTimelineCache();
    cache.getOrBuild(buildThreadTimelineCacheKey(shape), () => makeResponse(3));
    cache.getOrBuild(buildThreadTimelineCacheKey({ ...shape, maxSeq: 11 }), () =>
      makeResponse(3),
    );
    // Expected 1 (only maxSeq 11 is reachable). Actual on fcada5a3b: 2.
    expect(cache.size).toBe(1);
  });

  it("is bounded only by the global LRU for a single streaming thread", () => {
    const cache = createThreadTimelineCache();
    for (let maxSeq = 1; maxSeq <= 500; maxSeq++) {
      cache.getOrBuild(buildThreadTimelineCacheKey({ ...shape, maxSeq }), () =>
        makeResponse(3),
      );
    }
    // Expected 1. Actual on fcada5a3b: 128 (DEFAULT_MAX_ENTRIES).
    expect(cache.size).toBe(1);
  });
});

/**
 * The two #2066 unit scenarios (repro-2066-unit.test.ts) rewritten against
 * PR #2067's `getOrBuild({ paramsKey, revisionKey }, build)` signature, so the
 * "pass after" half of the claim can be shown on the PR branch. The base-tree
 * version cannot run against the PR: it passes a string key and throws
 * `TypeError: Cannot read properties of undefined (reading 'value')`.
 *
 * Note: this file also fails on fcada5a3b (2 and 128 instead of 1) because the
 * base cache accepts the object as an opaque Map key, but that is a type error
 * at compile time, not evidence; use repro-2066-unit.test.ts for "fails before".
 */
import { describe, expect, it } from "vitest";
import type { ThreadTimelineResponse } from "@bb/server-contract";
import {
  buildThreadTimelineCacheKey,
  buildThreadTimelineParamsKey,
  createThreadTimelineCache,
  type ThreadTimelineCacheKeyArgs,
} from "../../../src/services/threads/timeline-cache.js";

function makeResponse(rowCount: number): ThreadTimelineResponse {
  return {
    rows: Array.from({ length: rowCount }, (_, index) => ({
      id: `row-${index}`,
      kind: "system",
      threadId: "thr_x",
      turnId: null,
      sourceSeqStart: index,
      sourceSeqEnd: index,
      startedAt: 0,
      createdAt: 0,
      systemKind: "debug",
      title: "t",
      detail: null,
      status: null,
    })),
    activePromptMode: null,
    activeThinking: null,
    activeWorkflows: [],
    activeBackgroundCommands: [],
    pendingTodos: null,
    goal: null,
    modelFallback: null,
    maxSeq: 0,
    timelinePage: {
      kind: "latest",
      segmentLimit: 20,
      returnedSegmentCount: 0,
      hasOlderRows: false,
      olderCursor: null,
    },
  };
}

const shape: ThreadTimelineCacheKeyArgs = {
  threadId: "thr_x",
  maxSeq: 10,
  status: "active",
  environmentId: null,
  page: { kind: "latest", segmentLimit: 20 },
  includeNestedRows: false,
  summaryOnly: false,
  includeProviderUnhandledOperations: false,
};

// Exactly what routes/threads/data.ts does on the PR branch.
const keysFor = (args: ThreadTimelineCacheKeyArgs) => ({
  paramsKey: buildThreadTimelineParamsKey(args),
  revisionKey: buildThreadTimelineCacheKey(args),
});

describe("#2066 unit (PR #2067 signature)", () => {
  it("replaces the previous revision of the same request shape", () => {
    const cache = createThreadTimelineCache();
    cache.getOrBuild(keysFor(shape), () => makeResponse(3));
    cache.getOrBuild(keysFor({ ...shape, maxSeq: 11 }), () => makeResponse(3));
    expect(cache.size).toBe(1);
  });

  it("keeps one entry for a single streaming thread regardless of revision count", () => {
    const cache = createThreadTimelineCache();
    for (let maxSeq = 1; maxSeq <= 500; maxSeq++) {
      cache.getOrBuild(keysFor({ ...shape, maxSeq }), () => makeResponse(3));
    }
    expect(cache.size).toBe(1);
  });
});

/**
 * The two #2066 unit scenarios (repro-2066-unit.test.ts) written against the
 * proposed fix's `getOrBuild({ paramsKey, maxSeq }, build)` signature
 * (proposed-fix-2066.diff). Run on fcada5a3b + proposed-fix-2066.diff.
 * Does not apply to fcada5a3b (string key) or PR #2067 (`revisionKey`).
 */
import { describe, expect, it } from "vitest";
import type { ThreadTimelineResponse } from "@bb/server-contract";
import {
  buildThreadTimelineParamsKey,
  createThreadTimelineCache,
  type ThreadTimelineCacheKeyArgs,
} from "../../../src/services/threads/timeline-cache.js";

function makeResponse(rowCount: number): ThreadTimelineResponse {
  return {
    rows: Array.from({ length: rowCount }, (_, index) => ({
      id: `row-${index}`,
      kind: "system",
      threadId: "thr_x",
      turnId: null,
      sourceSeqStart: index,
      sourceSeqEnd: index,
      startedAt: 0,
      createdAt: 0,
      systemKind: "debug",
      title: "t",
      detail: null,
      status: null,
    })),
    activePromptMode: null,
    activeThinking: null,
    activeWorkflows: [],
    activeBackgroundCommands: [],
    pendingTodos: null,
    goal: null,
    modelFallback: null,
    maxSeq: 0,
    timelinePage: {
      kind: "latest",
      segmentLimit: 20,
      returnedSegmentCount: 0,
      hasOlderRows: false,
      olderCursor: null,
    },
  };
}

const shape: ThreadTimelineCacheKeyArgs = {
  threadId: "thr_x",
  status: "active",
  environmentId: null,
  page: { kind: "latest", segmentLimit: 20 },
  includeNestedRows: false,
  summaryOnly: false,
  includeProviderUnhandledOperations: false,
};
const paramsKey = buildThreadTimelineParamsKey(shape);

describe("#2066 unit (proposed-fix signature)", () => {
  it("replaces the previous revision of the same request shape", () => {
    const cache = createThreadTimelineCache();
    cache.getOrBuild({ paramsKey, maxSeq: 10 }, () => makeResponse(3));
    cache.getOrBuild({ paramsKey, maxSeq: 11 }, () => makeResponse(3));
    expect(cache.size).toBe(1);
  });

  it("keeps one entry for a single streaming thread regardless of revision count", () => {
    const cache = createThreadTimelineCache();
    for (let maxSeq = 1; maxSeq <= 500; maxSeq++) {
      cache.getOrBuild({ paramsKey, maxSeq }, () => makeResponse(3));
    }
    expect(cache.size).toBe(1);
  });
});

 RUN  v4.1.1 /Users/sawyerhood/.bb-machines/bee.getbb.app/checkouts/bb/.claude/worktrees/wf_21e66a79-f02-23/apps/server
 ✓  @bb/server  test/services/threads/repro-2066-unit-pr2067.test.ts > #2066 unit (PR #2067 signature) > replaces the previous revision of the same request shape 1ms
 ✓  @bb/server  test/services/threads/repro-2066-unit-pr2067.test.ts > #2066 unit (PR #2067 signature) > keeps one entry for a single streaming thread regardless of revision count 1ms
 ×  @bb/server  test/services/threads/repro-2066-unit.test.ts > #2066 unit > replaces the previous revision of the same request shape 2ms
   → Cannot read properties of undefined (reading 'value')
 ×  @bb/server  test/services/threads/repro-2066-unit.test.ts > #2066 unit > is bounded only by the global LRU for a single streaming thread 0ms
   → Cannot read properties of undefined (reading 'value')
 ✓  @bb/server  test/services/threads/pr-2067-adversarial.test.ts > PR #2067 adversarial > an oversized newer revision evicts the previous cacheable revision (claimed in PR body, untested there) 1ms
 ✓  @bb/server  test/services/threads/pr-2067-adversarial.test.ts > PR #2067 adversarial > a replacement is most-recently-used for LRU purposes 1ms
 ✓  @bb/server  test/services/threads/pr-2067-adversarial.test.ts > PR #2067 adversarial > a stale revision request never returns the newer cached value 0ms
 ✓  @bb/server  test/services/threads/pr-2067-adversarial.test.ts > PR #2067 adversarial > bounded: N revisions of one shape never exceed one entry 1ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > builds once for the same key and serves cached on repeat 1ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > rebuilds and replaces the prior revision for the same request shape 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > retains separate request shapes independently 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > does not cache responses above the row cap (streaming expanded turns) 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > evicts least-recently-used entries beyond maxEntries 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > buildThreadTimelineCacheKey > differs when any projection input differs 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > buildThreadTimelineCacheKey > distinguishes older-page cursors 0ms
 ✓  @bb/server:isolated  test/public/repro-2066-timeline-cache-retention.test.ts > #2066 timeline cache retains superseded revisions > keeps one resident response per appended event for the same request shape 357ms
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 2 ⎯⎯⎯⎯⎯⎯⎯
 FAIL   @bb/server  test/services/threads/repro-2066-unit.test.ts > #2066 unit > replaces the previous revision of the same request shape
TypeError: Cannot read properties of undefined (reading 'value')
 ❯ Object.getOrBuild src/services/threads/timeline-cache.ts:68:23
     66|         entries.delete(paramsKey);
     67|         entries.set(paramsKey, cached);
     68|         return cached.value;
       |                       ^
     69|       }
     70|
 ❯ test/services/threads/repro-2066-unit.test.ts:63:11
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/2]⎯
 FAIL   @bb/server  test/services/threads/repro-2066-unit.test.ts > #2066 unit > is bounded only by the global LRU for a single streaming thread
TypeError: Cannot read properties of undefined (reading 'value')
 ❯ Object.getOrBuild src/services/threads/timeline-cache.ts:68:23
     66|         entries.delete(paramsKey);
     67|         entries.set(paramsKey, cached);
     68|         return cached.value;
       |                       ^
     69|       }
     70|
 ❯ test/services/threads/repro-2066-unit.test.ts:74:13
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[2/2]⎯
 Test Files  1 failed | 4 passed (5)
      Tests  2 failed | 14 passed (16)
   Start at  09:28:29
   Duration  2.28s (transform 1.25s, setup 0ms, import 1.98s, tests 369ms, environment 0ms)

/**
 * Repro for get-bb/bb#2066: the timeline response cache keys on `maxSeq`, so
 * every appended event leaves the previous revision resident (and unreachable,
 * because a thread's maxSeq is monotonic) until global LRU eviction.
 *
 * Drives the REAL `GET /api/v1/threads/:id/timeline` route against an
 * in-memory SQLite database. The only instrumentation is wrapping the cache
 * factory so the test can read `.size` of the instance the route creates.
 */
import { describe, expect, it, vi } from "vitest";
import { threadScope, turnScope } from "@bb/domain";
import { threadTimelineResponseSchema } from "@bb/server-contract";
import { seedEvent, seedThreadFixture } from "../helpers/seed.js";
import { withTestHarness } from "../helpers/test-app.js";
import type { TestAppHarness } from "../helpers/test-app.js";
import type { createThreadTimelineCache as CreateCache } from "../../src/services/threads/timeline-cache.js";

const createdCaches: ReturnType<typeof CreateCache>[] = [];

vi.mock(
  "../../src/services/threads/timeline-cache.js",
  async (importOriginal) => {
    const mod =
      await importOriginal<
        typeof import("../../src/services/threads/timeline-cache.js")
      >();
    return {
      ...mod,
      createThreadTimelineCache: (
        ...args: Parameters<typeof mod.createThreadTimelineCache>
      ) => {
        const cache = mod.createThreadTimelineCache(...args);
        createdCaches.push(cache);
        return cache;
      },
    };
  },
);

async function fetchTimeline(harness: TestAppHarness, threadId: string) {
  const response = await harness.app.request(
    `/api/v1/threads/${threadId}/timeline`,
  );
  expect(response.status).toBe(200);
  const text = await response.text();
  return {
    bytes: Buffer.byteLength(text),
    body: threadTimelineResponseSchema.parse(JSON.parse(text)),
  };
}

describe("#2066 timeline cache retains superseded revisions", () => {
  it("keeps one resident response per appended event for the same request shape", async () => {
    await withTestHarness(async (harness) => {
      const cache = createdCaches.at(-1);
      if (!cache) {
        throw new Error("route did not create a timeline cache");
      }
      const { environment, thread } = seedThreadFixture(harness);
      const base = {
        threadId: thread.id,
        environmentId: environment.id,
        providerThreadId: "p1",
      } as const;

      // A completed turn with a sizeable assistant message so each cached
      // revision carries real payload weight.
      const bigText = "lorem ipsum ".repeat(2_000); // ~24 KB
      seedEvent(harness.deps, {
        ...base,
        scope: threadScope(),
        sequence: 1,
        type: "system/manager/user_message",
        data: { text: "hello" },
      });
      seedEvent(harness.deps, {
        ...base,
        scope: turnScope("turn-1"),
        sequence: 2,
        type: "turn/started",
        data: {},
      });
      seedEvent(harness.deps, {
        ...base,
        scope: turnScope("turn-1"),
        sequence: 3,
        type: "item/completed",
        data: { item: { type: "agentMessage", id: "a-1", text: bigText } },
      });
      seedEvent(harness.deps, {
        ...base,
        scope: turnScope("turn-1"),
        sequence: 4,
        type: "turn/completed",
        data: { status: "completed" },
      });

      const first = await fetchTimeline(harness, thread.id);
      expect(first.body.maxSeq).toBe(4);
      expect(cache.size).toBe(1);
      // Well under the 200-row cap, so every revision is cacheable.
      expect(first.body.rows.length).toBeLessThan(200);

      // A second, streaming turn: each appended event bumps maxSeq and the
      // client refetches the same window (same request shape).
      seedEvent(harness.deps, {
        ...base,
        scope: turnScope("turn-2"),
        sequence: 5,
        type: "turn/started",
        data: {},
      });
      const rounds = 150;
      let lastRows = 0;
      for (let i = 0; i < rounds; i++) {
        seedEvent(harness.deps, {
          ...base,
          scope: turnScope("turn-2"),
          sequence: 6 + i,
          type: "item/completed",
          data: {
            item: {
              type: "agentMessage",
              id: `a-2-${i}`,
              text: `chunk ${i}`,
            },
          },
        });
        const page = await fetchTimeline(harness, thread.id);
        expect(page.body.maxSeq).toBe(6 + i);
        lastRows = page.body.rows.length;
        // Still cacheable (row count grows slowly; stays <= 200 here).
        expect(lastRows).toBeLessThanOrEqual(200);
      }

      // A thread's maxSeq is monotonic (getLatestThreadSequence = MAX(sequence)),
      // so only the entry keyed by the newest maxSeq can ever be hit again.
      // Every other entry is dead weight. Expected: 1 live revision.
      // Actual on fcada5a3b: the global LRU bound (128) of dead revisions.
      // eslint-disable-next-line no-console
      console.log(
        `[2066] first-response bytes=${first.bytes} rows(last)=${lastRows} rounds=${rounds} cache.size=${cache.size}`,
      );
      expect(cache.size).toBe(1);
    });
  });
});

diff --git a/apps/server/src/routes/threads/data.ts b/apps/server/src/routes/threads/data.ts
index f8a741ade..e3c9a3007 100644
--- a/apps/server/src/routes/threads/data.ts
+++ b/apps/server/src/routes/threads/data.ts
@@ -56,7 +56,6 @@ import type {
 } from "../../services/threads/timeline-pagination.js";
 import { createSlowThreadTimelineBuildLogger } from "../../services/threads/timeline-build-log.js";
 import {
-  buildThreadTimelineCacheKey,
   buildThreadTimelineParamsKey,
   createThreadTimelineCache,
 } from "../../services/threads/timeline-cache.js";
@@ -355,8 +354,9 @@ export function registerThreadDataRoutes(app: Hono, deps: AppDeps): void {
       summaryOnly,
       includeProviderUnhandledOperations,
     };
+    const paramsKey = buildThreadTimelineParamsKey(keyArgs);
     const full = timelineCache.getOrBuild(
-      buildThreadTimelineCacheKey({ ...keyArgs, maxSeq }),
+      { paramsKey, maxSeq },
       () => {
         const { profile, response } = buildThreadTimelineWithProfile(
           deps.db,
@@ -399,7 +399,6 @@ export function registerThreadDataRoutes(app: Hono, deps: AppDeps): void {
       query.afterSequence,
       "afterSequence",
     );
-    const paramsKey = buildThreadTimelineParamsKey(keyArgs);
     const previous =
       afterSequence === undefined
         ? undefined
diff --git a/apps/server/src/services/threads/timeline-cache.ts b/apps/server/src/services/threads/timeline-cache.ts
index f5e1c903a..a8bca92f9 100644
--- a/apps/server/src/services/threads/timeline-cache.ts
+++ b/apps/server/src/services/threads/timeline-cache.ts
@@ -13,9 +13,12 @@ import type { ThreadTimelinePageRequest } from "./timeline-pagination.js";
  * (detail view + side-chat tabs), debounced realtime invalidations that fire
  * after the tail already settled, and re-opening a thread.
  *
- * Keying on the thread high-water `maxSeq` makes invalidation implicit: any
- * appended event bumps `maxSeq`, producing a new key and a cold rebuild. The
- * key MUST also include every other input the projection depends on:
+ * Entries are keyed by request shape (`paramsKey`) and store the thread
+ * high-water `maxSeq` they were built at. A request with a different `maxSeq`
+ * is a miss that *replaces* the slot: `maxSeq` never decreases, so the old
+ * revision could never be looked up again and keeping it until global LRU
+ * eviction only pins a dead response per appended event (#2066). The request
+ * shape MUST include every other input the projection depends on:
  * `thread.status` (interrupt flips earlier rows), `environmentId` (workspace
  * root relativizes file paths), provider display name (labels dynamic-provider
  * diagnostic rows), and the row-shape request flags. Event pruning
@@ -23,10 +26,9 @@ import type { ThreadTimelinePageRequest } from "./timeline-pagination.js";
  * and never lowers `maxSeq`, so it cannot stale a cached entry.
  *
  * Entries with many rows are not cached: an expanded active turn (the streaming
- * case) produces hundreds of rows AND a `maxSeq` that changes on every event,
- * so caching it only thrashes the LRU and pins large objects for no reuse. Idle
- * windows collapse completed turns to a handful of rows regardless of thread
- * size, so the cap excludes exactly the entries that would never be reused.
+ * case) produces hundreds of rows that are rebuilt on every event, so storing
+ * them pins a large object for no reuse. The per-shape slot bounds the *count*
+ * of retained revisions; the row cap bounds their *size*.
  */
 
 const DEFAULT_MAX_ENTRIES = 128;
@@ -40,7 +42,7 @@ interface ThreadTimelineCacheOptions {
 
 interface ThreadTimelineCache {
   getOrBuild(
-    key: string,
+    key: { paramsKey: string; maxSeq: number },
     build: () => ThreadTimelineResponse,
   ): ThreadTimelineResponse;
   /** Number of currently cached entries (for tests/metrics). */
@@ -53,21 +55,27 @@ export function createThreadTimelineCache(
   const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
   const maxCacheableRows =
     options.maxCacheableRows ?? DEFAULT_MAX_CACHEABLE_ROWS;
-  const entries = new Map<string, ThreadTimelineResponse>();
+  const entries = new Map<
+    string,
+    { maxSeq: number; value: ThreadTimelineResponse }
+  >();
 
   return {
-    getOrBuild(key, build) {
-      const cached = entries.get(key);
-      if (cached !== undefined) {
+    getOrBuild({ paramsKey, maxSeq }, build) {
+      const cached = entries.get(paramsKey);
+      if (cached?.maxSeq === maxSeq) {
         // Re-insert to mark most-recently-used.
-        entries.delete(key);
-        entries.set(key, cached);
-        return cached;
+        entries.delete(paramsKey);
+        entries.set(paramsKey, cached);
+        return cached.value;
       }
 
       const value = build();
+      // A newer revision supersedes the stored one even when the new value is
+      // too large to cache: the old one can never hit again.
+      entries.delete(paramsKey);
       if (value.rows.length <= maxCacheableRows) {
-        entries.set(key, value);
+        entries.set(paramsKey, { maxSeq, value });
         while (entries.size > maxEntries) {
           const oldest = entries.keys().next().value;
           if (oldest === undefined) {
@@ -86,8 +94,6 @@ export function createThreadTimelineCache(
 
 export interface ThreadTimelineCacheKeyArgs {
   threadId: string;
-  /** Thread high-water event sequence; bumps on every appended event. */
-  maxSeq: number;
   status: ThreadStatus;
   environmentId: string | null;
   providerDisplayName?: string;
@@ -104,12 +110,12 @@ function pageKeyPart(page: ThreadTimelinePageRequest): string {
 }
 
 /**
- * The cache identity *excluding* `maxSeq` — i.e. everything that selects which
- * window is being requested, but not which revision of it. Used to track the
- * latest-sent rows per request shape for delta computation.
+ * The request shape: everything that selects which window is being requested,
+ * but not which revision (`maxSeq`) of it. Shared by the response cache and the
+ * latest-rows delta cache.
  */
 export function buildThreadTimelineParamsKey(
-  args: Omit<ThreadTimelineCacheKeyArgs, "maxSeq">,
+  args: ThreadTimelineCacheKeyArgs,
 ): string {
   return [
     args.threadId,
@@ -122,9 +128,3 @@ export function buildThreadTimelineParamsKey(
     args.includeProviderUnhandledOperations ? "1" : "0",
   ].join("|");
 }
-
-export function buildThreadTimelineCacheKey(
-  args: ThreadTimelineCacheKeyArgs,
-): string {
-  return `${args.maxSeq}|${buildThreadTimelineParamsKey(args)}`;
-}
diff --git a/apps/server/test/services/threads/timeline-cache.test.ts b/apps/server/test/services/threads/timeline-cache.test.ts
index 141af64fe..7ef779e94 100644
--- a/apps/server/test/services/threads/timeline-cache.test.ts
+++ b/apps/server/test/services/threads/timeline-cache.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import type { ThreadTimelineResponse } from "@bb/server-contract";
 import type { ThreadTimelinePageRequest } from "../../../src/services/threads/timeline-pagination.js";
 import {
-  buildThreadTimelineCacheKey,
+  buildThreadTimelineParamsKey,
   createThreadTimelineCache,
   type ThreadTimelineCacheKeyArgs,
 } from "../../../src/services/threads/timeline-cache.js";
@@ -48,7 +48,6 @@ const latestPage: ThreadTimelinePageRequest = {
 
 const baseKeyArgs: ThreadTimelineCacheKeyArgs = {
   threadId: "thr_x",
-  maxSeq: 10,
   status: "idle",
   environmentId: null,
   page: latestPage,
@@ -57,62 +56,92 @@ const baseKeyArgs: ThreadTimelineCacheKeyArgs = {
   includeProviderUnhandledOperations: false,
 };
 
+const k = (paramsKey: string, maxSeq = 1) => ({ paramsKey, maxSeq });
+
 describe("createThreadTimelineCache", () => {
-  it("builds once for the same key and serves cached on repeat", () => {
+  it("builds once for the same shape and revision and serves cached on repeat", () => {
     const cache = createThreadTimelineCache();
     const build = vi.fn(() => makeResponse(3));
 
-    const first = cache.getOrBuild("k", build);
-    const second = cache.getOrBuild("k", build);
+    const first = cache.getOrBuild(k("k"), build);
+    const second = cache.getOrBuild(k("k"), build);
 
     expect(build).toHaveBeenCalledTimes(1);
     expect(second).toBe(first);
     expect(cache.size).toBe(1);
   });
 
-  it("rebuilds when the key changes (e.g. new maxSeq)", () => {
+  it("rebuilds on a new maxSeq and replaces the prior revision of the same shape", () => {
     const cache = createThreadTimelineCache();
     const build = vi.fn(() => makeResponse(3));
 
-    cache.getOrBuild("k1", build);
-    cache.getOrBuild("k2", build);
+    cache.getOrBuild(k("k", 10), build);
+    cache.getOrBuild(k("k", 11), build);
 
     expect(build).toHaveBeenCalledTimes(2);
+    expect(cache.size).toBe(1);
+  });
+
+  it("never returns a newer revision to a request for an older maxSeq", () => {
+    const cache = createThreadTimelineCache();
+    const newer = makeResponse(2);
+    cache.getOrBuild(k("k", 11), () => newer);
+    const rebuilt = makeResponse(1);
+    const served = cache.getOrBuild(k("k", 10), () => rebuilt);
+    expect(served).toBe(rebuilt);
+  });
+
+  it("retains separate request shapes independently", () => {
+    const cache = createThreadTimelineCache();
+    const build = vi.fn(() => makeResponse(3));
+
+    cache.getOrBuild(k("latest", 10), build);
+    cache.getOrBuild(k("older:5", 10), build);
+
+    expect(cache.size).toBe(2);
   });
 
   it("does not cache responses above the row cap (streaming expanded turns)", () => {
     const cache = createThreadTimelineCache({ maxCacheableRows: 5 });
     const build = vi.fn(() => makeResponse(50));
 
-    cache.getOrBuild("k", build);
-    cache.getOrBuild("k", build);
+    cache.getOrBuild(k("k"), build);
+    cache.getOrBuild(k("k"), build);
 
     expect(build).toHaveBeenCalledTimes(2);
     expect(cache.size).toBe(0);
   });
 
+  it("drops a cached revision when its replacement is above the row cap", () => {
+    const cache = createThreadTimelineCache({ maxCacheableRows: 5 });
+
+    cache.getOrBuild(k("k", 1), () => makeResponse(3));
+    expect(cache.size).toBe(1);
+    cache.getOrBuild(k("k", 2), () => makeResponse(50));
+    expect(cache.size).toBe(0);
+  });
+
   it("evicts least-recently-used entries beyond maxEntries", () => {
     const cache = createThreadTimelineCache({ maxEntries: 2 });
     const build = vi.fn(() => makeResponse(1));
 
-    cache.getOrBuild("a", build); // [a]
-    cache.getOrBuild("b", build); // [a,b]
-    cache.getOrBuild("a", build); // touch a -> [b,a]
-    cache.getOrBuild("c", build); // evict b -> [a,c]
+    cache.getOrBuild(k("a"), build); // [a]
+    cache.getOrBuild(k("b"), build); // [a,b]
+    cache.getOrBuild(k("a"), build); // touch a -> [b,a]
+    cache.getOrBuild(k("c"), build); // evict b -> [a,c]
 
     expect(cache.size).toBe(2);
     const buildAgain = vi.fn(() => makeResponse(1));
-    cache.getOrBuild("a", buildAgain); // still cached
-    cache.getOrBuild("b", buildAgain); // evicted -> rebuild
+    cache.getOrBuild(k("a"), buildAgain); // still cached
+    cache.getOrBuild(k("b"), buildAgain); // evicted -> rebuild
     expect(buildAgain).toHaveBeenCalledTimes(1);
   });
 });
 
-describe("buildThreadTimelineCacheKey", () => {
+describe("buildThreadTimelineParamsKey", () => {
   it("differs when any projection input differs", () => {
-    const base = buildThreadTimelineCacheKey(baseKeyArgs);
+    const base = buildThreadTimelineParamsKey(baseKeyArgs);
     const variants: ThreadTimelineCacheKeyArgs[] = [
-      { ...baseKeyArgs, maxSeq: 11 },
       { ...baseKeyArgs, status: "active" },
       { ...baseKeyArgs, environmentId: "env_1" },
       { ...baseKeyArgs, includeNestedRows: true },
@@ -128,12 +157,12 @@ describe("buildThreadTimelineCacheKey", () => {
       },
     ];
     for (const variant of variants) {
-      expect(buildThreadTimelineCacheKey(variant)).not.toBe(base);
+      expect(buildThreadTimelineParamsKey(variant)).not.toBe(base);
     }
   });
 
   it("distinguishes older-page cursors", () => {
-    const cursorA = buildThreadTimelineCacheKey({
+    const cursorA = buildThreadTimelineParamsKey({
       ...baseKeyArgs,
       page: {
         kind: "older",
@@ -141,7 +170,7 @@ describe("buildThreadTimelineCacheKey", () => {
         beforeCursor: { anchorSeq: 5, anchorId: "a5" },
       },
     });
-    const cursorB = buildThreadTimelineCacheKey({
+    const cursorB = buildThreadTimelineParamsKey({
       ...baseKeyArgs,
       page: {
         kind: "older",

 RUN  v4.1.1 /Users/sawyerhood/.bb-machines/bee.getbb.app/checkouts/bb/.claude/worktrees/wf_21e66a79-f02-23/apps/server
 ✓  @bb/server  test/services/threads/repro-2066-unit-after-fix.test.ts > #2066 unit (proposed-fix signature) > replaces the previous revision of the same request shape 1ms
 ✓  @bb/server  test/services/threads/repro-2066-unit-after-fix.test.ts > #2066 unit (proposed-fix signature) > keeps one entry for a single streaming thread regardless of revision count 0ms
 ✓  @bb/server  test/services/threads/timeline-latest-rows-cache.test.ts > createTimelineLatestRowsCache > keeps a ring of recent revisions per params key and evicts the oldest 1ms
 ✓  @bb/server  test/services/threads/timeline-latest-rows-cache.test.ts > createTimelineLatestRowsCache > a repeated set at the same revision refreshes recency without consuming a ring slot 0ms
 ✓  @bb/server  test/services/threads/timeline-latest-rows-cache.test.ts > createTimelineLatestRowsCache > bounds params keys LRU-style; a lookup counts as use 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > builds once for the same shape and revision and serves cached on repeat 1ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > rebuilds on a new maxSeq and replaces the prior revision of the same shape 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > never returns a newer revision to a request for an older maxSeq 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > retains separate request shapes independently 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > does not cache responses above the row cap (streaming expanded turns) 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > drops a cached revision when its replacement is above the row cap 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > createThreadTimelineCache > evicts least-recently-used entries beyond maxEntries 0ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > buildThreadTimelineParamsKey > differs when any projection input differs 1ms
 ✓  @bb/server  test/services/threads/timeline-cache.test.ts > buildThreadTimelineParamsKey > distinguishes older-page cursors 0ms
 ✓  @bb/server  test/public/public-thread-timeline-output-preview.test.ts > GET /threads/:id/timeline inline output preview > previews the running turn's large outputs and leaves small ones whole 119ms
 ✓  @bb/server  test/public/public-thread-timeline-output-preview.test.ts > GET /threads/:id/timeline inline output preview > nested-row consumers still receive the full inline output 78ms
 ✓  @bb/server  test/public/public-thread-timeline-delta.test.ts > GET /threads/:id/timeline?afterSequence (row-patch delta) > a full fetch carries no delta and echoes maxSeq 115ms
 ✓  @bb/server  test/public/public-thread-timeline-delta.test.ts > GET /threads/:id/timeline?afterSequence (row-patch delta) > delta + merge reproduces a fresh full window when rows are appended 86ms
 ✓  @bb/server  test/public/public-thread-timeline-delta.test.ts > GET /threads/:id/timeline?afterSequence (row-patch delta) > delta + merge reproduces a fresh full window when a turn completes (collapse) 72ms
 ✓  @bb/server  test/public/public-thread-timeline-delta.test.ts > GET /threads/:id/timeline?afterSequence (row-patch delta) > two interleaved clients both receive deltas (snapshot ring per params key) 83ms
 ✓  @bb/server  test/public/public-thread-timeline-output-preview.test.ts > GET /threads/:id/timeline inline output preview > turn-summary-details scoped to the previewed row returns its whole output 70ms
 ✓  @bb/server  test/public/public-thread-timeline-output-preview.test.ts > GET /threads/:id/timeline inline output preview > row-scoped details still resolve after the turn completes (expand/complete race) 74ms
 ✓  @bb/server  test/public/public-thread-timeline-output-preview.test.ts > GET /threads/:id/timeline inline output preview (tool rows) > previews a large tool result and row-scoped details return it whole 71ms
 ✓  @bb/server  test/public/public-thread-timeline-delta.test.ts > GET /threads/:id/timeline?afterSequence (row-patch delta) > a no-op delta (no new events) returns an empty patch and merges to the same rows 69ms
 ✓  @bb/server:isolated  test/public/repro-2066-timeline-cache-retention.test.ts > #2066 timeline cache retains superseded revisions > keeps one resident response per appended event for the same request shape 440ms
 Test Files  6 passed (6)
      Tests  25 passed (25)
   Start at  09:30:04
   Duration  3.19s (transform 5.30s, setup 0ms, import 8.15s, tests 1.29s, environment 0ms)

diff --git a/apps/server/src/routes/threads/data.ts b/apps/server/src/routes/threads/data.ts
index f8a741ade..e8ce0acc8 100644
--- a/apps/server/src/routes/threads/data.ts
+++ b/apps/server/src/routes/threads/data.ts
@@ -355,8 +355,12 @@ export function registerThreadDataRoutes(app: Hono, deps: AppDeps): void {
       summaryOnly,
       includeProviderUnhandledOperations,
     };
+    const paramsKey = buildThreadTimelineParamsKey(keyArgs);
     const full = timelineCache.getOrBuild(
-      buildThreadTimelineCacheKey({ ...keyArgs, maxSeq }),
+      {
+        paramsKey,
+        revisionKey: buildThreadTimelineCacheKey({ ...keyArgs, maxSeq }),
+      },
       () => {
         const { profile, response } = buildThreadTimelineWithProfile(
           deps.db,
@@ -399,7 +403,6 @@ export function registerThreadDataRoutes(app: Hono, deps: AppDeps): void {
       query.afterSequence,
       "afterSequence",
     );
-    const paramsKey = buildThreadTimelineParamsKey(keyArgs);
     const previous =
       afterSequence === undefined
         ? undefined
diff --git a/apps/server/src/services/threads/timeline-cache.ts b/apps/server/src/services/threads/timeline-cache.ts
index f5e1c903a..340a7120c 100644
--- a/apps/server/src/services/threads/timeline-cache.ts
+++ b/apps/server/src/services/threads/timeline-cache.ts
@@ -13,20 +13,20 @@ import type { ThreadTimelinePageRequest } from "./timeline-pagination.js";
  * (detail view + side-chat tabs), debounced realtime invalidations that fire
  * after the tail already settled, and re-opening a thread.
  *
- * Keying on the thread high-water `maxSeq` makes invalidation implicit: any
- * appended event bumps `maxSeq`, producing a new key and a cold rebuild. The
- * key MUST also include every other input the projection depends on:
+ * Keying each revision on the thread high-water `maxSeq` makes invalidation
+ * implicit: any appended event bumps `maxSeq`, producing a cold rebuild. The
+ * cache keeps only the newest revision for each request shape; otherwise an
+ * active thread with compact projected rows can pin one full response per
+ * event until the global LRU fills. The request shape MUST include every other
+ * input the projection depends on:
  * `thread.status` (interrupt flips earlier rows), `environmentId` (workspace
  * root relativizes file paths), provider display name (labels dynamic-provider
  * diagnostic rows), and the row-shape request flags. Event pruning
  * (`pruneResolvedItemDeltas`, background-task progress) is output-preserving
  * and never lowers `maxSeq`, so it cannot stale a cached entry.
  *
- * Entries with many rows are not cached: an expanded active turn (the streaming
- * case) produces hundreds of rows AND a `maxSeq` that changes on every event,
- * so caching it only thrashes the LRU and pins large objects for no reuse. Idle
- * windows collapse completed turns to a handful of rows regardless of thread
- * size, so the cap excludes exactly the entries that would never be reused.
+ * Entries with many rows are not cached: an expanded active turn produces
+ * hundreds of rows, so caching it would pin a large object for little reuse.
  */
 
 const DEFAULT_MAX_ENTRIES = 128;
@@ -40,7 +40,7 @@ interface ThreadTimelineCacheOptions {
 
 interface ThreadTimelineCache {
   getOrBuild(
-    key: string,
+    keys: { paramsKey: string; revisionKey: string },
     build: () => ThreadTimelineResponse,
   ): ThreadTimelineResponse;
   /** Number of currently cached entries (for tests/metrics). */
@@ -53,21 +53,28 @@ export function createThreadTimelineCache(
   const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
   const maxCacheableRows =
     options.maxCacheableRows ?? DEFAULT_MAX_CACHEABLE_ROWS;
-  const entries = new Map<string, ThreadTimelineResponse>();
+  const entries = new Map<
+    string,
+    { revisionKey: string; value: ThreadTimelineResponse }
+  >();
 
   return {
-    getOrBuild(key, build) {
-      const cached = entries.get(key);
-      if (cached !== undefined) {
+    getOrBuild({ paramsKey, revisionKey }, build) {
+      const cached = entries.get(paramsKey);
+      if (cached?.revisionKey === revisionKey) {
         // Re-insert to mark most-recently-used.
-        entries.delete(key);
-        entries.set(key, cached);
-        return cached;
+        entries.delete(paramsKey);
+        entries.set(paramsKey, cached);
+        return cached.value;
       }
 
       const value = build();
+      // A newer revision supersedes the old response even when the new value
+      // is too large to cache. Keeping the stale value cannot produce a hit
+      // and needlessly retains its rows.
+      entries.delete(paramsKey);
       if (value.rows.length <= maxCacheableRows) {
-        entries.set(key, value);
+        entries.set(paramsKey, { revisionKey, value });
         while (entries.size > maxEntries) {
           const oldest = entries.keys().next().value;
           if (oldest === undefined) {
diff --git a/apps/server/test/services/threads/timeline-cache.test.ts b/apps/server/test/services/threads/timeline-cache.test.ts
index 141af64fe..da68e0f7f 100644
--- a/apps/server/test/services/threads/timeline-cache.test.ts
+++ b/apps/server/test/services/threads/timeline-cache.test.ts
@@ -57,35 +57,60 @@ const baseKeyArgs: ThreadTimelineCacheKeyArgs = {
   includeProviderUnhandledOperations: false,
 };
 
+function cacheKeys(revisionKey: string, paramsKey = revisionKey) {
+  return { paramsKey, revisionKey };
+}
+
 describe("createThreadTimelineCache", () => {
   it("builds once for the same key and serves cached on repeat", () => {
     const cache = createThreadTimelineCache();
     const build = vi.fn(() => makeResponse(3));
 
-    const first = cache.getOrBuild("k", build);
-    const second = cache.getOrBuild("k", build);
+    const first = cache.getOrBuild(cacheKeys("k"), build);
+    const second = cache.getOrBuild(cacheKeys("k"), build);
 
     expect(build).toHaveBeenCalledTimes(1);
     expect(second).toBe(first);
     expect(cache.size).toBe(1);
   });
 
-  it("rebuilds when the key changes (e.g. new maxSeq)", () => {
+  it("rebuilds and replaces the prior revision for the same request shape", () => {
     const cache = createThreadTimelineCache();
     const build = vi.fn(() => makeResponse(3));
 
-    cache.getOrBuild("k1", build);
-    cache.getOrBuild("k2", build);
+    cache.getOrBuild(
+      cacheKeys(buildThreadTimelineCacheKey(baseKeyArgs), "latest-shape"),
+      build,
+    );
+    cache.getOrBuild(
+      cacheKeys(
+        buildThreadTimelineCacheKey({ ...baseKeyArgs, maxSeq: 11 }),
+        "latest-shape",
+      ),
+      build,
+    );
 
     expect(build).toHaveBeenCalledTimes(2);
+    expect(cache.size).toBe(1);
+  });
+
+  it("retains separate request shapes independently", () => {
+    const cache = createThreadTimelineCache();
+    const build = vi.fn(() => makeResponse(3));
+
+    cache.getOrBuild(cacheKeys("revision", "latest-page"), build);
+    cache.getOrBuild(cacheKeys("revision", "older-page"), build);
+
+    expect(build).toHaveBeenCalledTimes(2);
+    expect(cache.size).toBe(2);
   });
 
   it("does not cache responses above the row cap (streaming expanded turns)", () => {
     const cache = createThreadTimelineCache({ maxCacheableRows: 5 });
     const build = vi.fn(() => makeResponse(50));
 
-    cache.getOrBuild("k", build);
-    cache.getOrBuild("k", build);
+    cache.getOrBuild(cacheKeys("k"), build);
+    cache.getOrBuild(cacheKeys("k"), build);
 
     expect(build).toHaveBeenCalledTimes(2);
     expect(cache.size).toBe(0);
@@ -95,15 +120,15 @@ describe("createThreadTimelineCache", () => {
     const cache = createThreadTimelineCache({ maxEntries: 2 });
     const build = vi.fn(() => makeResponse(1));
 
-    cache.getOrBuild("a", build); // [a]
-    cache.getOrBuild("b", build); // [a,b]
-    cache.getOrBuild("a", build); // touch a -> [b,a]
-    cache.getOrBuild("c", build); // evict b -> [a,c]
+    cache.getOrBuild(cacheKeys("a"), build); // [a]
+    cache.getOrBuild(cacheKeys("b"), build); // [a,b]
+    cache.getOrBuild(cacheKeys("a"), build); // touch a -> [b,a]
+    cache.getOrBuild(cacheKeys("c"), build); // evict b -> [a,c]
 
     expect(cache.size).toBe(2);
     const buildAgain = vi.fn(() => makeResponse(1));
-    cache.getOrBuild("a", buildAgain); // still cached
-    cache.getOrBuild("b", buildAgain); // evicted -> rebuild
+    cache.getOrBuild(cacheKeys("a"), buildAgain); // still cached
+    cache.getOrBuild(cacheKeys("b"), buildAgain); // evicted -> rebuild
     expect(buildAgain).toHaveBeenCalledTimes(1);
   });
 });

/**
 * Adversarial checks for PR #2067 (one timeline revision per request shape).
 * Exercises paths the PR's own tests do not: an oversized replacement must
 * drop the previous cacheable revision, a replacement must become MRU, and a
 * hit on the newest revision must not be disturbed by a sibling shape.
 */
import { describe, expect, it, vi } from "vitest";
import type { ThreadTimelineResponse } from "@bb/server-contract";
import { createThreadTimelineCache } from "../../../src/services/threads/timeline-cache.js";

function makeResponse(rowCount: number): ThreadTimelineResponse {
  return {
    rows: Array.from({ length: rowCount }, (_, index) => ({
      id: `row-${index}`,
      kind: "system",
      threadId: "thr_x",
      turnId: null,
      sourceSeqStart: index,
      sourceSeqEnd: index,
      startedAt: 0,
      createdAt: 0,
      systemKind: "debug",
      title: "t",
      detail: null,
      status: null,
    })),
    activePromptMode: null,
    activeThinking: null,
    activeWorkflows: [],
    activeBackgroundCommands: [],
    pendingTodos: null,
    goal: null,
    modelFallback: null,
    maxSeq: 0,
    timelinePage: {
      kind: "latest",
      segmentLimit: 20,
      returnedSegmentCount: 0,
      hasOlderRows: false,
      olderCursor: null,
    },
  };
}

const k = (paramsKey: string, maxSeq: number) => ({
  paramsKey,
  revisionKey: `${maxSeq}|${paramsKey}`,
});

describe("PR #2067 adversarial", () => {
  it("an oversized newer revision evicts the previous cacheable revision (claimed in PR body, untested there)", () => {
    const cache = createThreadTimelineCache({ maxCacheableRows: 5 });
    cache.getOrBuild(k("shape", 1), () => makeResponse(3));
    expect(cache.size).toBe(1);
    cache.getOrBuild(k("shape", 2), () => makeResponse(50));
    expect(cache.size).toBe(0);
  });

  it("a replacement is most-recently-used for LRU purposes", () => {
    const cache = createThreadTimelineCache({ maxEntries: 2 });
    cache.getOrBuild(k("a", 1), () => makeResponse(1)); // [a]
    cache.getOrBuild(k("b", 1), () => makeResponse(1)); // [a,b]
    cache.getOrBuild(k("a", 2), () => makeResponse(1)); // replace a -> [b,a]
    cache.getOrBuild(k("c", 1), () => makeResponse(1)); // evict b -> [a,c]
    const rebuild = vi.fn(() => makeResponse(1));
    cache.getOrBuild(k("a", 2), rebuild);
    expect(rebuild).not.toHaveBeenCalled();
    cache.getOrBuild(k("b", 1), rebuild);
    expect(rebuild).toHaveBeenCalledTimes(1);
  });

  it("a stale revision request never returns the newer cached value", () => {
    const cache = createThreadTimelineCache();
    const v2 = makeResponse(2);
    cache.getOrBuild(k("shape", 2), () => v2);
    const v1 = makeResponse(1);
    const got = cache.getOrBuild(k("shape", 1), () => v1);
    expect(got).toBe(v1);
    // And the lower revision now owns the slot (caller-supplied truth wins).
    expect(cache.getOrBuild(k("shape", 1), () => makeResponse(9))).toBe(v1);
  });

  it("bounded: N revisions of one shape never exceed one entry", () => {
    const cache = createThreadTimelineCache();
    for (let seq = 1; seq <= 1000; seq++) {
      cache.getOrBuild(k("shape", seq), () => makeResponse(3));
    }
    expect(cache.size).toBe(1);
  });
});