Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
perf(server): idle-LRU eviction for agent sessions (#2812)
Andrew Mikofalvy93c2b349cf9d
diff --git a/.changeset/agent-session-idle-lru-eviction.md b/.changeset/agent-session-idle-lru-eviction.mdnew file mode 100644index 000000000..bb760279d--- /dev/null+++ b/.changeset/agent-session-idle-lru-eviction.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Agent write bursts across many documents no longer stall with "server busy" (503) once 256 documents have been touched. At the session cap the server now evicts the least-recently-used idle agent session — flushing its document to disk first — so large bursts stream through a bounded working set. Sessions used within the last few seconds are never evicted, and a 503 is still returned only when every session is genuinely in use. Undo history for an evicted session ends with it (same as a disconnect); a later write on that document starts a fresh session under the same agent identity, so edit attribution is unaffected. New diagnostics: an `ok.sessions.evictions_total` OpenTelemetry counter and an `agentSessionEvictions` counter on `GET /api/metrics/reconciliation`.diff --git a/packages/app/tests/integration/agent-session-eviction.test.ts b/packages/app/tests/integration/agent-session-eviction.test.tsnew file mode 100644index 000000000..a70a1854d--- /dev/null+++ b/packages/app/tests/integration/agent-session-eviction.test.ts@@ -0,0 +1,70 @@+/**+ * LRU-idle session eviction against the real server stack.+ *+ * Proves the piece the unit suite's mock cannot: eviction's teardown is the+ * real `DirectConnection.disconnect`, which stores the doc immediately (not+ * debounced) before unloading — an evicted session's writes reach disk, and+ * a fresh session re-reads them intact.+ *+ * @see packages/server/src/agent-sessions.eviction.test.ts — LRU/floor/undo+ * semantics on the unit mock+ */++import { randomUUID } from 'node:crypto';+import { AgentSessionManager, applyAgentMarkdownWrite } from '@inkeep/open-knowledge-server';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import type { TestServer } from './test-harness';+import { createTestServer, readTestDoc } from './test-harness';++let server: TestServer;++beforeAll(async () => {+ server = await createTestServer();+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await server.cleanup();+});++describe('agent-session LRU eviction (real Hocuspocus + persistence)', () => {+ test('evicted session state is persisted: write, evict under pressure, re-read intact', async () => {+ // A dedicated manager over the SAME hocuspocus instance, with a tiny cap+ // and a zero idle floor so cap pressure evicts deterministically.+ const manager = new AgentSessionManager(server.instance.hocuspocus, {+ maxSessions: 2,+ minEvictableIdleMs: 0,+ });++ const docName = `evict-persist-${randomUUID()}`;+ const content = '# Evicted Doc\n\nBytes written before eviction.\n';++ const session = await manager.getSession(docName, 'agent-evict-int');+ session.dc.document.transact(() => {+ applyAgentMarkdownWrite(session.dc.document, content, 'replace');+ }, session.origin);++ // No manual flush: the eviction path itself must persist. Fill the cap+ // with two more distinct docs — the first create evicts our LRU session+ // and awaits its disconnect, which stores the doc before unload.+ await manager.getSession(`evict-fill-a-${randomUUID()}`, 'agent-evict-int');+ await manager.getSession(`evict-fill-b-${randomUUID()}`, 'agent-evict-int');++ expect(manager.hasSession(docName, 'agent-evict-int')).toBe(false);+ expect(manager.evictionCount).toBeGreaterThanOrEqual(1);++ // The write survived teardown to disk.+ expect(readTestDoc(server.contentDir, docName)).toBe(content);++ // A fresh session sees the persisted bytes and starts with a clean undo+ // stack — the evicted session's stack died with it, never corrupting the+ // successor.+ const fresh = await manager.getSession(docName, 'agent-evict-int');+ expect(fresh.dc.document.getText('source').toString()).toBe(content);+ expect(fresh.um.undoStack.length).toBe(0);+ // Same derived writer identity across the evict/recreate boundary.+ expect(fresh.origin.context.session_id).toBe(session.origin.context.session_id);++ await manager.closeAll();+ });+});diff --git a/packages/server/src/agent-sessions.eviction.test.ts b/packages/server/src/agent-sessions.eviction.test.tsnew file mode 100644index 000000000..6c0c3fc31--- /dev/null+++ b/packages/server/src/agent-sessions.eviction.test.ts@@ -0,0 +1,309 @@+/**+ * LRU-idle eviction under capacity pressure.+ *+ * At the cap, `getSession` evicts the least-recently-used session whose idle+ * age clears the floor instead of refusing outright — a burst of writes to+ * many distinct docs streams through a bounded working set. When nothing is+ * idle-eligible, behavior degrades to the pre-eviction contract+ * (`AgentSessionCapacityError` → 503 at the HTTP boundary).+ *+ * Companion to `agent-sessions.test.ts` (session lifecycle) — kept separate+ * so this file can import from `vitest` directly.+ */+import type { Document } from '@hocuspocus/server';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import * as Y from 'yjs';+import {+ type AgentDirectConnection,+ AgentSessionCapacityError,+ AgentSessionManager,+ applyAgentMarkdownWrite,+ applyAgentUndo,+} from './agent-sessions.ts';+import { getMetrics, resetMetrics } from './metrics.ts';++/**+ * Minimal Hocuspocus mock (mirrors the one in `agent-sessions.test.ts`):+ * every openDirectConnection returns a unique DC over a real per-doc Y.Doc so+ * UndoManager creation and transacts behave. `deferCreates` lets a test hold+ * session creation in the pending map to probe the capacity accounting.+ */+function createMockHocuspocus(options: { deferCreates?: boolean } = {}) {+ const ydocs = new Map<string, Y.Doc>();+ const pendingReleases: Array<() => void> = [];++ function makeDC(docName: string): AgentDirectConnection {+ let disconnected = false;+ let ydoc = ydocs.get(docName);+ if (!ydoc) {+ ydoc = new Y.Doc();+ ydocs.set(docName, ydoc);+ }+ const doc = {+ name: docName,+ getText: (name: string) => ydoc.getText(name),+ getMap: (name: string) => ydoc.getMap(name),+ getXmlFragment: (name: string) => ydoc.getXmlFragment(name),+ transact: (fn: () => void, origin?: unknown) => ydoc.transact(fn, origin),+ on: ydoc.on.bind(ydoc),+ off: ydoc.off.bind(ydoc),+ } as unknown as Document;+ return {+ document: doc,+ disconnect: async () => {+ disconnected = true;+ },+ isDisconnected: () => disconnected,+ transact: () => {},+ } as unknown as AgentDirectConnection;+ }++ return {+ releaseAllPending(): void {+ for (const release of pendingReleases.splice(0)) release();+ },+ openDirectConnection: async (docName: string): Promise<AgentDirectConnection> => {+ if (options.deferCreates) {+ await new Promise<void>((resolve) => {+ pendingReleases.push(resolve);+ });+ }+ return makeDC(docName);+ },+ };+}++let mockHocuspocus: ReturnType<typeof createMockHocuspocus>;++beforeEach(() => {+ mockHocuspocus = createMockHocuspocus();+ resetMetrics();+});++afterEach(() => {+ resetMetrics();+});++describe('LRU-idle eviction at the session cap', () => {+ test('a burst of creates past the cap streams through instead of throwing 503', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 4,+ minEvictableIdleMs: 0,+ });++ // 12 distinct docs — 3x the cap. Pre-eviction this threw+ // AgentSessionCapacityError at doc #5; now every create succeeds.+ for (let i = 0; i < 12; i++) {+ await manager.getSession(`burst-doc-${i}.md`, 'agent-burst');+ expect(manager.liveSessionCount).toBeLessThanOrEqual(4);+ }++ // The newest 4 survive; the earliest were evicted in LRU order.+ for (let i = 8; i < 12; i++) {+ expect(manager.hasSession(`burst-doc-${i}.md`, 'agent-burst')).toBe(true);+ }+ for (let i = 0; i < 8; i++) {+ expect(manager.hasSession(`burst-doc-${i}.md`, 'agent-burst')).toBe(false);+ }+ expect(manager.evictionCount).toBe(8);++ await manager.closeAll();+ });++ test('eviction picks the least-recently-used session — a getSession touch protects it', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 3,+ minEvictableIdleMs: 0,+ });++ await manager.getSession('doc-a.md', 'agent-lru');+ await manager.getSession('doc-b.md', 'agent-lru');+ await manager.getSession('doc-c.md', 'agent-lru');++ // Touch A — B becomes the LRU.+ await manager.getSession('doc-a.md', 'agent-lru');++ await manager.getSession('doc-d.md', 'agent-lru');++ expect(manager.hasSession('doc-b.md', 'agent-lru')).toBe(false);+ expect(manager.hasSession('doc-a.md', 'agent-lru')).toBe(true);+ expect(manager.hasSession('doc-c.md', 'agent-lru')).toBe(true);+ expect(manager.hasSession('doc-d.md', 'agent-lru')).toBe(true);++ await manager.closeAll();+ });++ test('a getLiveSession read also refreshes recency', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 3,+ minEvictableIdleMs: 0,+ });++ await manager.getSession('doc-a.md', 'agent-read');+ await manager.getSession('doc-b.md', 'agent-read');+ await manager.getSession('doc-c.md', 'agent-read');++ // Read A (the burst-diff path) — B becomes the LRU.+ expect(manager.getLiveSession('doc-a.md', 'agent-read')).toBeDefined();++ await manager.getSession('doc-d.md', 'agent-read');++ expect(manager.hasSession('doc-b.md', 'agent-read')).toBe(false);+ expect(manager.hasSession('doc-a.md', 'agent-read')).toBe(true);++ await manager.closeAll();+ });++ test('sessions younger than the idle floor are never evicted — capacity error is preserved', async () => {+ // A just-used session may belong to an in-flight request; with a floor+ // higher than the test's runtime nothing is eligible and the cap+ // degrades to the pre-eviction 503 contract.+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 2,+ minEvictableIdleMs: 60_000,+ });++ await manager.getSession('doc-a.md', 'agent-floor');+ await manager.getSession('doc-b.md', 'agent-floor');++ await expect(manager.getSession('doc-c.md', 'agent-floor')).rejects.toBeInstanceOf(+ AgentSessionCapacityError,+ );++ // Nothing was torn down under the (conceptually in-flight) sessions.+ expect(manager.hasSession('doc-a.md', 'agent-floor')).toBe(true);+ expect(manager.hasSession('doc-b.md', 'agent-floor')).toBe(true);+ expect(manager.evictionCount).toBe(0);++ await manager.closeAll();+ });++ test('existing-session reuse at the cap neither evicts nor throws', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 2,+ minEvictableIdleMs: 0,+ });++ const a = await manager.getSession('doc-a.md', 'agent-reuse');+ await manager.getSession('doc-b.md', 'agent-reuse');++ const aAgain = await manager.getSession('doc-a.md', 'agent-reuse');+ expect(aAgain).toBe(a);+ expect(manager.evictionCount).toBe(0);+ expect(manager.liveSessionCount).toBe(2);++ await manager.closeAll();+ });++ test('eviction runs the disconnect teardown spine: DC disconnected, UM destroyed, entry removed', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 1,+ minEvictableIdleMs: 0,+ });++ const victim = await manager.getSession('doc-victim.md', 'agent-teardown');+ await manager.getSession('doc-new.md', 'agent-teardown');++ expect(manager.hasSession('doc-victim.md', 'agent-teardown')).toBe(false);+ expect((victim.dc as unknown as { isDisconnected: () => boolean }).isDisconnected()).toBe(true);+ // um.destroy() ran — the stack is empty and no longer tracking.+ expect(victim.um.undoStack.length).toBe(0);++ await manager.closeAll();+ });++ test('undo after eviction fails cleanly: hasSession is false and a fresh session has no undo stack', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 1,+ minEvictableIdleMs: 0,+ });++ const session = await manager.getSession('doc-undo.md', 'agent-undo-evict');+ session.dc.document.transact(() => {+ applyAgentMarkdownWrite(session.dc.document, '# Before eviction\n', 'replace');+ }, session.origin);+ session.um.stopCapturing();+ expect(session.um.undoStack.length).toBeGreaterThan(0);++ // Pressure-evict by creating a session on another doc.+ await manager.getSession('doc-other.md', 'agent-undo-evict');++ // The HTTP undo handler guards on hasSession before resolving a session;+ // an evicted (docName, agentId) reads as absent → the handler's+ // no-active-session refusal, never a write against torn-down state.+ expect(manager.hasSession('doc-undo.md', 'agent-undo-evict')).toBe(false);++ // A later getSession mints a FRESH session: empty undo stack, undo is a+ // clean no-op (returns false), document content untouched.+ const fresh = await manager.getSession('doc-undo.md', 'agent-undo-evict');+ expect(fresh).not.toBe(session);+ expect(fresh.um.undoStack.length).toBe(0);+ expect(applyAgentUndo(fresh, 'session')).toBe(false);+ expect(fresh.dc.document.getText('source').toString()).toBe('# Before eviction\n');++ await manager.closeAll();+ });++ test('writer identity is continuous across eviction: same session_id, fresh origin object', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 1,+ minEvictableIdleMs: 0,+ });++ const before = await manager.getSession('doc-attr.md', 'agent-85aabbcc');+ await manager.getSession('doc-fill.md', 'agent-85aabbcc');+ const after = await manager.getSession('doc-attr.md', 'agent-85aabbcc');++ // resolveWriterFromOrigin derives the shadow-repo writerId from+ // context.session_id — identical before/after, so attribution chains+ // continue under the same `agent-<id>` writer.+ expect(after.origin.context.session_id).toBe(before.origin.context.session_id);+ expect(after.origin.context.session_id).toBe('85aabbcc');+ // The frozen origin object itself is fresh (Set-identity for the new+ // session's UndoManager trackedOrigins).+ expect(after.origin).not.toBe(before.origin);++ await manager.closeAll();+ });++ test('pending (in-flight) session creations are never evicted and hold their capacity slot', async () => {+ const deferred = createMockHocuspocus({ deferCreates: true });+ const manager = new AgentSessionManager(deferred as never, {+ maxSessions: 1,+ minEvictableIdleMs: 0,+ });++ // Start a create and leave it pending — it occupies the only slot from+ // the pending map, where eviction cannot reach it.+ const pending = manager.getSession('doc-pending.md', 'agent-pending');++ // A second distinct create finds the slot held by a pending entry and+ // nothing evictable in the live map → capacity refusal.+ await expect(manager.getSession('doc-other.md', 'agent-pending')).rejects.toBeInstanceOf(+ AgentSessionCapacityError,+ );++ deferred.releaseAllPending();+ const session = await pending;+ expect(session.docName).toBe('doc-pending.md');+ expect(manager.hasSession('doc-pending.md', 'agent-pending')).toBe(true);++ await manager.closeAll();+ });++ test('evictions increment the in-process metrics counter', async () => {+ const manager = new AgentSessionManager(mockHocuspocus as never, {+ maxSessions: 1,+ minEvictableIdleMs: 0,+ });++ expect(getMetrics().agentSessionEvictions).toBe(0);+ await manager.getSession('doc-m1.md', 'agent-metrics');+ await manager.getSession('doc-m2.md', 'agent-metrics');+ await manager.getSession('doc-m3.md', 'agent-metrics');+ expect(getMetrics().agentSessionEvictions).toBe(2);+ expect(manager.evictionCount).toBe(2);++ await manager.closeAll();+ });+});diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.tsindex ba6c9e9a0..df0bac35c 100644--- a/packages/server/src/agent-sessions.ts+++ b/packages/server/src/agent-sessions.ts@@ -43,8 +43,9 @@ import { getDocExtension, stripDocExtension } from './doc-extensions.ts';import { FrontmatterMalformedError } from './frontmatter-malformed-error.ts';import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';import { getLogger } from './logger.ts';+import { incrementAgentSessionEvictions } from './metrics.ts';import type { PairedWriteOrigin } from './server-observers.ts';-import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';+import { getMeter, setActiveSpanAttributes, withSpanSync } from './telemetry.ts';/*** The post-write content-divergence signal. Defined in (and produced by) the@@ -556,6 +557,13 @@ interface SessionRecord {um: Y.UndoManager;agentId: string;docName: string;+ /**+ * Recency stamp (epoch ms), maintained exclusively by AgentSessionManager:+ * refreshed on every `getSession` / `getLiveSession` hit. The manager's+ * sessions map mirrors it in insertion order (a touch re-inserts the+ * entry), so the map's first entry is always the LRU eviction candidate.+ */+ lastUsedAt: number;}/**@@ -637,11 +645,35 @@ function createUndoOrigin(sessionId: string, agentType?: string): PairedWriteOri** 256 leaves comfortable headroom for realistic local workflows (a handful* of MCP clients across dozens of docs) while keeping the worst-case- * footprint bounded. Hitting the cap surfaces as a 503 at the HTTP boundary- * rather than silently growing memory or crashing the process.+ * footprint bounded. At capacity the manager first evicts the+ * least-recently-used idle session (see `MIN_EVICTABLE_IDLE_MS`) so a burst+ * of writes across many distinct docs streams through a bounded working set;+ * only when no session is idle-eligible does the cap surface as a 503 at the+ * HTTP boundary.*/export const MAX_AGENT_SESSIONS = 256;+/**+ * Minimum idle age before a live session becomes eviction-eligible under+ * capacity pressure.+ *+ * The floor guards in-flight handlers: every HTTP request re-resolves its+ * session via `getSession` at entry (refreshing recency), so a session+ * younger than the floor may still be inside a request whose transact has+ * not run yet. Evicting it would null the DirectConnection under the+ * handler (`dc.document` becomes null on disconnect) and destroy its+ * UndoManager mid-flight. Past the floor a session is quiescent — agent+ * write handlers flush the doc to disk before responding, so nothing is in+ * flight and nothing is unpersisted.+ *+ * Small by design: a burst that fills the cap ages its LRU session by+ * roughly (cap x per-write latency), and every write awaits its disk flush,+ * so realistic bursts are well past the floor by the time eviction is+ * needed. In-code constant, not user config; tests override via the+ * constructor option.+ */+export const MIN_EVICTABLE_IDLE_MS = 5_000;+/*** Thrown by `AgentSessionManager.getSession` when creating a new session* would exceed `MAX_AGENT_SESSIONS`. HTTP handlers catch this and translate@@ -656,17 +688,41 @@ export class AgentSessionCapacityError extends Error {}}+/** Lazy, process-wide eviction counter — instrument is created on first use so+ * module load stays side-effect-free when OTel is disabled (no-op meter). */+let _evictionCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;+function evictionCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {+ _evictionCounter ||= getMeter().createCounter('ok.sessions.evictions_total', {+ description:+ 'Agent sessions evicted (LRU-idle) under capacity pressure to admit a new session. Sustained growth alongside ok.sessions.active pinned at ok.sessions.limit means the working set exceeds the cap.',+ unit: '{sessions}',+ });+ return _evictionCounter;+}+export class AgentSessionManager {+ /**+ * Live sessions in recency order: every touch re-inserts the entry, so+ * iteration starts at the least-recently-used session. Eviction relies on+ * this — do not add write paths that bypass `touchSession`.+ */private sessions = new Map<string, SessionRecord>();/** In-flight promise dedup — concurrent first-calls share one pending openDirectConnection. */private pendingSessions = new Map<string, Promise<SessionRecord>>();private hocuspocus: Hocuspocus;/** Hard cap on simultaneous live sessions. Override is for tests only. */private readonly maxSessions: number;+ /** Idle floor for eviction eligibility. Override is for tests only. */+ private readonly minEvictableIdleMs: number;+ private evictions = 0;- constructor(hocuspocus: Hocuspocus, options: { maxSessions?: number } = {}) {+ constructor(+ hocuspocus: Hocuspocus,+ options: { maxSessions?: number; minEvictableIdleMs?: number } = {},+ ) {this.hocuspocus = hocuspocus;this.maxSessions = options.maxSessions ?? MAX_AGENT_SESSIONS;+ this.minEvictableIdleMs = options.minEvictableIdleMs ?? MIN_EVICTABLE_IDLE_MS;}/** Number of live sessions currently retained. Read-only occupancy probe. */@@ -679,6 +735,21 @@ export class AgentSessionManager {return this.maxSessions;}+ /** Sessions evicted under capacity pressure since construction. */+ public get evictionCount(): number {+ return this.evictions;+ }++ /**+ * Refresh a session's recency: stamp `lastUsedAt` and re-insert the entry+ * so the map's iteration order stays LRU-first.+ */+ private touchSession(key: string, session: SessionRecord): void {+ session.lastUsedAt = Date.now();+ this.sessions.delete(key);+ this.sessions.set(key, session);+ }+private sessionKey(docName: string, agentId: string): string {return `${docName}\0${agentId}`;}@@ -711,7 +782,13 @@ export class AgentSessionManager {* the existence check.*/public getLiveSession(docName: string, agentId: string): SessionRecord | undefined {- return this.sessions.get(this.sessionKey(docName, agentId));+ const key = this.sessionKey(docName, agentId);+ const session = this.sessions.get(key);+ // A read is a use: the burst-diff caller walks the session's UM stacks+ // right after this returns, so refreshing recency keeps eviction from+ // tearing the session down under the read.+ if (session) this.touchSession(key, session);+ return session;}/**@@ -739,7 +816,10 @@ export class AgentSessionManager {const key = this.sessionKey(docName, agentId);const existing = this.sessions.get(key);- if (existing) return existing;+ if (existing) {+ this.touchSession(key, existing);+ return existing;+ }// Reuse in-flight promise if a concurrent first-call is already pendingconst inflight = this.pendingSessions.get(key);@@ -752,12 +832,21 @@ export class AgentSessionManager {// entry. Existing-session lookups returned above. Counts both resolved// and pending so a concurrent burst of distinct ids cannot race past// the cap before any of them lands in `sessions`.- if (this.sessions.size + this.pendingSessions.size >= this.maxSessions) {- log.warn(- { docName, agentId, limit: this.maxSessions },- '[agent-session] session capacity reached, refusing new session',- );- throw new AgentSessionCapacityError(this.maxSessions);+ //+ // At capacity, evict LRU idle sessions until a slot frees so a burst of+ // writes to many distinct docs streams through a bounded working set+ // instead of stalling at the cap. When nothing is idle-eligible (every+ // session touched within the idle floor), degrade to the capacity+ // refusal — an in-flight handler is never torn down under itself.+ while (this.sessions.size + this.pendingSessions.size >= this.maxSessions) {+ const evictedKey = await this.evictLruIdleSession();+ if (evictedKey === null) {+ log.warn(+ { docName, agentId, limit: this.maxSessions },+ '[agent-session] session capacity reached, refusing new session',+ );+ throw new AgentSessionCapacityError(this.maxSessions);+ }}const promise = this._createSession(docName, agentId, identity);@@ -866,7 +955,57 @@ export class AgentSessionManager {`[agent-session] Created session for: ${docName} / ${agentId}`,);- return { dc, origin, undoOrigin, um, agentId, docName };+ return { dc, origin, undoOrigin, um, agentId, docName, lastUsedAt: Date.now() };+ }++ /**+ * Evict the least-recently-used idle session to relieve capacity pressure.+ * Returns the evicted session key, or `null` when nothing is eligible.+ *+ * The sessions map is kept in recency order (every touch re-inserts), so+ * the first entry IS the LRU candidate — and if it is younger than the+ * idle floor, every other entry is younger still, so the scan is O(1).+ *+ * The entry is removed from the map synchronously BEFORE the async+ * teardown so a concurrent create cannot select the same victim. Teardown+ * IS the existing disconnect spine (`cleanupSession`: um.destroy ++ * dc.disconnect); Hocuspocus's `DirectConnection.disconnect` stores the+ * doc immediately (not debounced) before unloading it, so evicted state+ * reaches disk exactly as it does on keepalive teardown. Because the map+ * delete frees the slot before the teardown settles, concurrent creates+ * can transiently hold more DirectConnections than the cap while+ * evictions drain — bounded by the number of evictable sessions and+ * decaying as each disconnect completes.+ *+ * Eviction destroys the session's UndoManager stack — identical to+ * disconnect teardown, where the stack was only ever reachable while the+ * session lived. A later undo for the evicted (docName, agentId) finds no+ * session (`hasSession` false → the handler's no-active-session+ * refusal); a later write mints a fresh session whose origin carries the+ * same session_id, so the derived writer id (`agent-<id>`) and+ * shadow-repo attribution stay continuous across eviction.+ */+ private async evictLruIdleSession(): Promise<string | null> {+ const first = this.sessions.entries().next();+ if (first.done) return null;+ const [key, session] = first.value;+ const idleMs = Date.now() - session.lastUsedAt;+ if (idleMs < this.minEvictableIdleMs) return null;++ this.sessions.delete(key);+ await this.cleanupSession(key, session, {+ docName: session.docName,+ agentId: session.agentId,+ evicted: true,+ });+ this.evictions++;+ incrementAgentSessionEvictions();+ evictionCounter().add(1);+ log.info(+ { docName: session.docName, agentId: session.agentId, idleMs },+ '[agent-session] Evicted LRU idle session under capacity pressure',+ );+ return key;}/** Check if a session exists without creating one. */diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex 8e771d423..dd9ae049b 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -25,6 +25,7 @@ export {colorFromSeed,iconFromClientName,MAX_AGENT_SESSIONS,+ MIN_EVICTABLE_IDLE_MS,} from './agent-sessions.ts';export {__getShowAllWalkStatsForTesting,diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.tsindex 837f2a74d..a17279a72 100644--- a/packages/server/src/metrics.ts+++ b/packages/server/src/metrics.ts@@ -181,6 +181,12 @@ export interface ReconciliationMetrics {* agent-write handlers only AFTER a successful recordContributor;* UI-driven rollback/rename without agentId does NOT increment. */agentWriteCalls: number;+ /** Agent sessions evicted (LRU-idle) under capacity pressure so a new+ * (docName, agentId) session could be admitted under+ * `MAX_AGENT_SESSIONS`. Steady growth alongside 503s means the live+ * working set genuinely exceeds the cap; growth WITHOUT 503s means+ * eviction is absorbing bursts as designed. */+ agentSessionEvictions: number;/** Agent-write calls that carried a non-empty summary through* normalizeSummary — numerator for the summary-adoption metric.* Adoption rate = summariesProvided / agentWriteCalls. */@@ -461,6 +467,7 @@ const counters: ReconciliationMetrics = {effectDiffCaptureFailures: 0,agentPresenceMutationErrors: 0,agentWriteCalls: 0,+ agentSessionEvictions: 0,summariesProvided: 0,summariesTruncated: 0,agentPatchFindMismatches: 0,@@ -568,6 +575,10 @@ export function incrementAgentWriteCalls(): void {counters.agentWriteCalls++;}+export function incrementAgentSessionEvictions(): void {+ counters.agentSessionEvictions++;+}+export function incrementSummariesProvided(): void {counters.summariesProvided++;}@@ -858,6 +869,7 @@ export function resetMetrics(): void {counters.effectDiffCaptureFailures = 0;counters.agentPresenceMutationErrors = 0;counters.agentWriteCalls = 0;+ counters.agentSessionEvictions = 0;counters.summariesProvided = 0;counters.summariesTruncated = 0;counters.agentPatchFindMismatches = 0;