@remnic/core 10.0.85 → 10.0.86

package/src/access-service.ts

@@ -1,9 +1,7 @@
 import { createHash } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
 import { readdirSync, unlinkSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import * as nodeFs from "node:fs/promises";
-import { ZodError } from "zod";
 import { summarizeHourlyStatus } from "./summarizer.js";
 import { decodeCitationNamespace } from "./access-citation-namespace.js";
 import {
@@ -288,6 +286,7 @@ import {
 } from "./capabilities.js";
 import { resolveRecallEnhancementCapabilities } from "./capabilities.js";
 import { type CapsuleListEntry, defaultCapsulesDir } from "./capsule-cli.js";
+import { isCapsuleImportArchiveInputError, validateCapsuleImportArchive } from "./capsule-import-gate.js";
 import type { SemanticDedupLookup } from "./dedup/semantic.js";
 import type { FallbackLlmClient } from "./fallback-llm.js";
 import type { LocalLlmClient } from "./local-llm.js";
@@ -5366,6 +5365,9 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
    * `versioning` defaults to the orchestrator's page-versioning config so
    * `mode: "overwrite"` automatically snapshots prior content without the
    * caller having to construct the config object.
+   *
+   * Remote callers (HTTP and MCP) may only import from the destination
+   * namespace's capsule store; the CLI keeps unrestricted local paths.
    */
   async capsuleImport(
     opts: Omit<ImportCapsuleOptions, "root" | "memoryDir"> & {
@@ -5385,59 +5387,18 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
       maxVersionsPerPage: this.orchestrator.config.versioningMaxPerPage,
       sidecarDir: this.orchestrator.config.versioningSidecarDir,
     };
-    await this.validateCapsuleImportArchivePath(importOptions.archivePath);
+    await validateCapsuleImportArchive(importOptions.archivePath, storage.dir);
     try {
       return await importCapsuleFn({ ...importOptions, root, memoryDir, versioning });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      if (this.isCapsuleImportArchiveInputError(err, message)) {
+      if (isCapsuleImportArchiveInputError(err, message)) {
         throw new EngramAccessInputError(`capsule import failed: ${message}`);
       }
       throw err;
     }
   }
 
-  private async validateCapsuleImportArchivePath(archivePath: string): Promise<void> {
-    let archiveStat;
-    try {
-      archiveStat = await stat(archivePath);
-    } catch (err) {
-      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
-    }
-    if (!archiveStat.isFile()) {
-      throw new EngramAccessInputError("capsule import failed: archivePath must point to a file");
-    }
-    try {
-      await nodeFs.access(archivePath, fsConstants.R_OK);
-    } catch (err) {
-      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
-    }
-  }
-
-  private isCapsuleImportPathInputFsError(err: unknown): boolean {
-    const code =
-      typeof err === "object" && err !== null && "code" in err ? (err as { code?: unknown }).code : undefined;
-    return code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP";
-  }
-
-  private isCapsuleImportArchiveInputError(err: unknown, message: string): boolean {
-    if (err instanceof ZodError) return true;
-    const code =
-      typeof err === "object" && err !== null && "code" in err ? (err as { code?: unknown }).code : undefined;
-    if (typeof code === "string" && code.startsWith("Z_")) return true;
-    return (
-      message.startsWith("importCapsule: archive") ||
-      message.startsWith("importCapsule: bundle") ||
-      message.startsWith("importCapsule: manifest") ||
-      message.startsWith("importCapsule: record") ||
-      /incorrect header check|invalid stored block lengths|not in gzip format|unexpected end of file/i.test(message)
-    );
-  }
-
   /**
    * Export a capsule archive from the orchestrator's memory directory.
    *

package/src/briefing-deadline.ts

@@ -3,20 +3,21 @@ import { isAbortError, raceAbort } from "./abort-error.js";
 export const BRIEFING_DEADLINE_MS = 30_000;
 
 export class BriefingTimeoutError extends Error {
-  constructor(readonly deadlineMs: number) {
-    super(`briefing timed out after ${deadlineMs}ms`);
+  constructor(readonly deadlineMs: number, label = "briefing") {
+    super(`${label} timed out after ${deadlineMs}ms`);
     this.name = "TimeoutError";
   }
 }
 
 export async function withBriefingDeadline<T>(
   run: (signal: AbortSignal) => Promise<T>,
-  abortSignal?: AbortSignal
+  abortSignal?: AbortSignal,
+  label = "briefing",
 ): Promise<T> {
   const controller = new AbortController();
   const signal = abortSignal ? AbortSignal.any([abortSignal, controller.signal]) : controller.signal;
   const timer = setTimeout(
-    () => controller.abort(new BriefingTimeoutError(BRIEFING_DEADLINE_MS)),
+    () => controller.abort(new BriefingTimeoutError(BRIEFING_DEADLINE_MS, label)),
     BRIEFING_DEADLINE_MS
   );
   try {

package/src/buffer-admission.ts

@@ -0,0 +1,45 @@
+/** Buffer session-entry admission: refusal errors and the live-admission probe. */
+
+import { selectEvictedBufferKeys, type BufferEvictionHooks } from "./buffer-eviction.js";
+import type { BufferEntryState } from "./types.js";
+
+/**
+ * Raised when a NEW live-capture session cannot be admitted because the
+ * session-entry cap is full of non-evictable backlog. The turn was never
+ * accepted; the request is retryable once extraction drains an entry.
+ */
+export class BufferAdmissionRefusedError extends Error {
+  constructor(bufferKey: string, maxSessionEntries: number) {
+    super(
+      `buffer[${bufferKey}]: live capture refused at the session-entry cap (${maxSessionEntries}); ` +
+        "buffered backlog is no longer evicted to admit new sessions. Retry after extraction frees an entry",
+    );
+    this.name = "BufferAdmissionRefusedError";
+  }
+}
+
+/** Durable observe capture refused at the entry cap; the request is retryable. */
+export class ReplayAdmissionRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReplayAdmissionRefusedError";
+  }
+}
+
+/**
+ * Live-admission bound (#1908 policy, backlog-safe): a NEW session enters
+ * only while under the cap or when an EMPTY entry can be reclaimed. Buffered
+ * backlog is never dropped for a live capture; the caller refuses instead.
+ */
+export function canAdmitNewEntryUnlocked(
+  entries: Readonly<Record<string, BufferEntryState>>,
+  bufferKey: string,
+  maxSessionEntries: number,
+  hooks: BufferEvictionHooks,
+): boolean {
+  const count = Object.keys(entries).length;
+  if (count < maxSessionEntries) return true;
+  // Probe post-admission (as if this key had landed): admission is safe
+  // exactly when an EMPTY entry could then be reclaimed.
+  return selectEvictedBufferKeys(entries, [bufferKey], Math.max(0, count - 1), hooks).length > 0;
+}

package/src/buffer-eviction-backpressure.test.ts

@@ -0,0 +1,211 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
+import { parseConfig } from "./config.js";
+import { log } from "./logger.js";
+import { TurnIngestionCoordinator } from "./orchestration/turn-ingestion.js";
+import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
+
+class FakeStorage {
+  public saved: BufferState | null = null;
+  public saveCount = 0;
+
+  constructor(private readonly initial: BufferState) {}
+
+  async loadBuffer(): Promise<BufferState> {
+    return structuredClone(this.initial);
+  }
+
+  async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
+    this.saved = structuredClone(state);
+  }
+}
+
+function makeTurn(key: string, content: string, accepted = false): BufferTurn {
+  const turn: BufferTurn = {
+    role: "user",
+    content,
+    timestamp: new Date().toISOString(),
+    sessionKey: key,
+  };
+  if (accepted) turn.acceptedCapture = true;
+  return turn;
+}
+
+function entry(turns: BufferTurn[]): BufferEntryState {
+  return { turns, lastExtractionAt: null, extractionCount: 0 };
+}
+
+function emptyEntry(): BufferEntryState {
+  return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+}
+
+/** default + the given entries; default stays empty unless given. */
+function seededState(entries: Record<string, BufferEntryState>): BufferState {
+  const defaultEntry = entries.default ?? emptyEntry();
+  return {
+    turns: defaultEntry.turns,
+    lastExtractionAt: defaultEntry.lastExtractionAt,
+    extractionCount: defaultEntry.extractionCount,
+    entries: { default: defaultEntry, ...entries },
+  };
+}
+
+function makeBuffer(state: BufferState, maxSessions: number) {
+  const config = parseConfig({ bufferSaveDebounceMs: 0, bufferMaxSessions: maxSessions });
+  const storage = new FakeStorage(state);
+  const buffer = new SmartBuffer(config, storage);
+  return { buffer, storage };
+}
+
+const CAP = 4;
+
+function savedKeys(storage: FakeStorage): string[] {
+  return Object.keys(storage.saved?.entries ?? {});
+}
+
+test("live capture at a cap full of non-empty backlog is refused, never evicts buffered turns", async () => {
+  const { buffer } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+
+  await assert.rejects(
+    buffer.addTurn("new-session", makeTurn("new-session", "live turn")),
+    BufferAdmissionRefusedError,
+  );
+
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"], "oldest backlog lost to live admission");
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b"]);
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+  assert.equal(buffer.getTurns("new-session").length, 0, "refused turn was not buffered");
+
+  // Accepted captures are subject to the same no-backlog-loss limit: refusal
+  // happens before acceptance, preserving accepted-capture non-eviction.
+  assert.equal(
+    await buffer.addTurnBounded("accepted-1", makeTurn("accepted-1", "accepted", true)),
+    null,
+    "accepted capture is refused rather than evicting native backlog",
+  );
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"]);
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b"]);
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+});
+
+test("an already-admitted session keeps accepting turns at a full cap", async () => {
+  const { buffer, storage } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+
+  const decision = await buffer.addTurn("b", makeTurn("b", "another b turn"));
+  assert.equal(decision, "keep_buffering");
+  assert.deepEqual(buffer.getTurns("b").map((t) => t.content), ["backlog b", "another b turn"]);
+  assert.deepEqual(buffer.getTurns("a").map((t) => t.content), ["backlog a"], "existing-session admission must not evict peers");
+  assert.deepEqual(buffer.getTurns("c").map((t) => t.content), ["backlog c"]);
+  assert.equal(savedKeys(storage).length, CAP, "entry count stays at the cap");
+});
+
+test("empty entries are still evicted first to admit a new live session", async () => {
+  const { buffer, storage } = makeBuffer(
+    seededState({
+      "empty-oldest": emptyEntry(),
+      n1: entry([makeTurn("n1", "native 1")]),
+      n2: entry([makeTurn("n2", "native 2")]),
+    }),
+    CAP,
+  );
+
+  const decision = await buffer.addTurn("new-session", makeTurn("new-session", "live turn"));
+  assert.equal(decision, "keep_buffering");
+  const keys = savedKeys(storage);
+  assert.ok(!keys.includes("empty-oldest"), "oldest empty entry reclaimed");
+  assert.ok(keys.includes("new-session"), "new session admitted");
+  assert.deepEqual(buffer.getTurns("n1").map((t) => t.content), ["native 1"], "empty eviction must not touch backlog");
+  assert.deepEqual(buffer.getTurns("n2").map((t) => t.content), ["native 2"]);
+});
+
+test("a retained-only entry is non-evictable backlog: live admission is refused instead", async () => {
+  const retainedOnly: BufferEntryState = {
+    turns: [],
+    retainedTurns: [makeTurn("r", "deferred retry turn")],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  };
+  const { buffer } = makeBuffer(
+    seededState({
+      r: retainedOnly,
+      n1: entry([makeTurn("n1", "native 1")]),
+      n2: entry([makeTurn("n2", "native 2")]),
+    }),
+    CAP,
+  );
+
+  await assert.rejects(
+    buffer.addTurn("new-session", makeTurn("new-session", "live turn")),
+    BufferAdmissionRefusedError,
+  );
+  assert.equal(
+    buffer.getRetainedDeferredTurns("r").length,
+    1,
+    "retained retry turns must not be evicted as 'empty'",
+  );
+});
+test("concurrent multi-session admissions reserve capacity without partial batches", async () => {
+  const { buffer } = makeBuffer(seededState({}), 2);
+  const results = await Promise.all([
+    buffer.addTurnsBounded([{ bufferKey: "batch-a", turns: [makeTurn("batch-a", "a")] }]),
+    buffer.addTurnsBounded([{ bufferKey: "batch-b", turns: [makeTurn("batch-b", "b")] }]),
+  ]);
+
+  assert.equal(results.filter((result) => result !== null).length, 1);
+  assert.equal(results.filter((result) => result === null).length, 1);
+  assert.equal(buffer.getTurns("batch-a").length + buffer.getTurns("batch-b").length, 1);
+});
+
+test("processTurn propagates retryable admission refusal without queueing extraction", async () => {
+  const { buffer } = makeBuffer(
+    seededState({
+      a: entry([makeTurn("a", "backlog a")]),
+      b: entry([makeTurn("b", "backlog b")]),
+      c: entry([makeTurn("c", "backlog c")]),
+    }),
+    CAP,
+  );
+  const config = parseConfig({
+    memoryDir: "/tmp/unused-buffer-eviction-backpressure",
+    bufferSaveDebounceMs: 0,
+    bufferMaxSessions: CAP,
+  });
+  const queued: BufferTurn[][] = [];
+  type CoordinatorDeps = ConstructorParameters<typeof TurnIngestionCoordinator>[0];
+  // SAFETY: this fixture exercises only admission + refusal; the remaining
+  // coordinator deps are never reached on this path.
+  const deps = Object.assign({} as CoordinatorDeps, {
+    buffer,
+    config,
+    queueBufferedExtraction: async (turns: BufferTurn[]) => {
+      queued.push(turns);
+    },
+  });
+  const coordinator = new TurnIngestionCoordinator(deps);
+
+  await assert.rejects(
+    coordinator.processTurn("user", "live turn", "new-session"),
+    BufferAdmissionRefusedError,
+    "caller must receive retryable refusal rather than successful acknowledgment",
+  );
+
+  assert.equal(queued.length, 0, "a refused turn must not queue extraction");
+  assert.equal(buffer.getTurns("new-session").length, 0, "a refused turn must not be buffered");
+  assert.deepEqual(buffer.getTurns("a").map((x) => x.content), ["backlog a"], "backlog dropped during refused admission");
+});

package/src/buffer-eviction.ts

@@ -10,11 +10,10 @@ export interface BufferEvictionHooks {
 }
 
 /**
- * Pick the keys to evict so `entries` returns to `maxCount`: the oldest empty
- * sessions first; retained failed extractions (#1908) keep their turns, so if
- * empty entries alone cannot reach the cap the oldest NON-empty sessions go
- * too rather than growing unboundedly. "default", the retained keys and
- * entries holding an accepted capture are never chosen.
+ * Pick empty entries to evict so `entries` returns to `maxCount`. Backlog
+ * (active or retained turns) is never evicted; admission must refuse when
+ * empty entries cannot free a slot. "default", retained keys and entries
+ * holding an accepted capture are never chosen.
  */
 export function selectEvictedBufferKeys(
   entries: Readonly<Record<string, BufferEntryState>>,
@@ -35,17 +34,12 @@ export function selectEvictedBufferKeys(
   const candidates = keys.filter(
     (key) => key !== "default" && !retainKeys.includes(key) && !hooks.holdsAcceptedCapture(entries[key]),
   );
+  // Backlog = active turns OR retained retry turns (#1908); only an entry
+  // holding neither counts as empty.
   const emptyRemovable = candidates
-    .filter((key) => (entries[key]?.turns.length ?? 0) === 0)
+    .filter((key) => (entries[key]?.turns.length ?? 0) === 0 && (entries[key]?.retainedTurns?.length ?? 0) === 0)
     .sort(byOldestActivity);
 
   const removableCount = Math.max(0, keys.length - maxCount);
-  const evicted = emptyRemovable.slice(0, removableCount);
-  if (evicted.length < removableCount) {
-    const nonEmptyRemovable = candidates
-      .filter((key) => (entries[key]?.turns.length ?? 0) > 0)
-      .sort(byOldestActivity);
-    return evicted.concat(nonEmptyRemovable.slice(0, removableCount - evicted.length));
-  }
-  return evicted;
+  return emptyRemovable.slice(0, removableCount);
 }

package/src/buffer-incremental-persistence.test.ts

@@ -22,7 +22,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import { SmartBuffer } from "./buffer.js";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
 import { parseConfig } from "./config.js";
 import { StorageManager } from "./storage.js";
 import type { BufferEntryState, BufferState, BufferTurn } from "./types.js";
@@ -161,34 +161,28 @@ test("clearAfterExtraction persists the cleared session state", async () => {
   assert.equal(record?.entry.extractionCount, 1);
 });
 
-test("evicted sessions get their files deleted", async () => {
+test("empty evicted sessions get their files deleted", async () => {
   const storage = new IncrementalStorage(emptyState());
-  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 200 }), storage);
-
-  // normalizeState always materializes a "default" entry, so 198 seeded
-  // sessions + default = 199; new-session reaches exactly 200 (the
-  // addTurnBounded cap). One more UNBOUNDED addTurn pushes to 201 and
-  // pruneEntries evicts the oldest non-default session (s0).
-  for (let i = 0; i < 198; i++) {
-    const key = `s${i}`;
-    await buffer.addTurnBounded(key, makeTurn(key, `content ${i}`));
-  }
+  const buffer = new SmartBuffer(parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 4 }), storage);
+
+  // Clear one persisted entry to make it genuinely empty. Accepted-capture
+  // admission may reclaim this slot, but never a session with buffered turns.
+  await buffer.addTurn("empty-old", makeTurn("empty-old", "will be extracted"));
+  await buffer.flushPendingSave();
+  await buffer.clearAfterExtraction("empty-old");
+  await buffer.addTurnBounded("native-1", makeTurn("native-1", "native 1"));
+  await buffer.addTurnBounded("native-2", makeTurn("native-2", "native 2"));
   await buffer.flushPendingSave();
 
-  const outcome = await buffer.addTurnBounded("new-session", makeTurn("new-session", "fresh"));
-  assert.notEqual(outcome, null, "addTurnBounded refused below capacity");
-  await buffer.addTurn("overflow", makeTurn("overflow", "one too many"));
-  // The evicted key's file deletion lands on the next persist, like any
-  // other buffered state change.
+  const accepted = await buffer.addTurnBounded("accepted", {
+    ...makeTurn("accepted", "durable accepted"),
+    acceptedCapture: true,
+  });
+  assert.notEqual(accepted, null, "empty entry should be reclaimed to admit accepted capture");
   await buffer.flushPendingSave();
-  assert.ok(storage.deleted.includes("s0"), "oldest session was not evicted under capacity pressure");
-  assert.ok(
-    storage.deleted.length > 0,
-    "capacity pressure evicted entries without deleting their session files",
-  );
-  for (const key of storage.deleted) {
-    assert.equal(storage.sessions.has(key), false, `evicted session ${key} still has a file record`);
-  }
+  assert.ok(storage.deleted.includes("empty-old"), "reclaimed empty entry's file was not deleted");
+  assert.equal(buffer.getTurns("native-1").length, 1);
+  assert.equal(buffer.getTurns("native-2").length, 1);
 });
 
 test("the default entry cap leaves headroom for live sessions during backlog drains (#3303)", async () => {
@@ -273,9 +267,7 @@ test("legacy-only storage keeps the whole-state saveBuffer behavior", async () =
   assert.equal(storage.lastSaved?.entries?.["thread-b"]?.turns[0]?.content, "beta");
 });
 
-test("durable capture at the entry cap evicts native entries instead of refusing (COS-244c)", async () => {
-  // Stalled extraction left the cap full of native (non-accepted)
-  // sessions; addTurnBounded refused every new accepted session.
+test("durable capture at the entry cap is refused without evicting native backlog (COS-244c)", async () => {
   const storage = new IncrementalStorage(emptyState());
   const buffer = new SmartBuffer(
     parseConfig({ triggerMode: "every_n", bufferMaxTurns: 100, bufferMaxSessions: 4 }),
@@ -286,17 +278,13 @@ test("durable capture at the entry cap evicts native entries instead of refusing
   await buffer.flushPendingSave();
 
   const accepted = (key: string): BufferTurn => ({ ...makeTurn(key, "accepted"), acceptedCapture: true });
+  assert.equal(await buffer.addTurnBounded("accepted-0", accepted("accepted-0")), null);
+  await buffer.flushPendingSave();
+  assert.equal(storage.deleted.length, 0, "accepted refusal must not evict native session files");
   for (let i = 0; i < 3; i++) {
-    const outcome = await buffer.addTurnBounded(`accepted-${i}`, accepted(`accepted-${i}`));
-    assert.notEqual(outcome, null, `accepted-${i} refused while native entries were evictable`);
+    assert.ok(buffer.getTurns(`native-${i}`).some((turn) => turn.content === `native ${i}`));
   }
-  await buffer.flushPendingSave();
-  assert.ok(storage.deleted.includes("native-0"), "oldest native entry was not evicted");
-
-  // Accepted work is still never evicted: with only accepted entries left the
-  // cap refuses rather than dropping accepted captures.
-  assert.equal(await buffer.addTurnBounded("accepted-3", accepted("accepted-3")), null);
-  for (let i = 0; i < 3; i++) assert.ok(!storage.deleted.includes(`accepted-${i}`));
+  assert.equal(buffer.getTurns("accepted-0").length, 0, "refused capture was never accepted");
 });
 
 test("at-cap admission evicts nothing when eviction cannot free a slot (COS-244c)", async () => {

package/src/buffer-session.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { SmartBuffer } from "./buffer.js";
+import { SmartBuffer, BufferAdmissionRefusedError } from "./buffer.js";
 import { parseConfig } from "./config.js";
 import type { BufferSurpriseProbe } from "./buffer.js";
 import type { BufferState, BufferTurn } from "./types.js";
@@ -642,13 +642,14 @@ test("getTurns prepends retained deferred turns before live turns", async () =>
   assert.equal(all[1]?.content, "new live turn");
 });
 
-test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers at the cap (#1908 policy)", async () => {
+test("SmartBuffer refuses new sessions instead of dropping backlog at the cap (#1908 policy)", async () => {
   // Pre-#1908 this contract was "never prune non-empty entries". With retry
   // retention (failed extractions keep their turns), unbounded non-empty
   // growth during a provider outage would eventually OOM the daemon — the
-  // documented policy (#1908 step 7) is: retain up to MAX_BUFFER_ENTRY_COUNT
-  // session entries, then prune the OLDEST sessions with a loud warning.
-  // Empty entries are still evicted first.
+  // documented policy (#1908 step 7) bounds the ENTRY COUNT, not by dropping
+  // buffered turns: a NEW session is refused (retryable backpressure) when
+  // only non-empty backlog fills the cap. Empty entries are still evicted
+  // first, and already-admitted sessions keep buffering.
   const entries = Object.fromEntries(
     Array.from({ length: 205 }, (_, index) => [
       `thread-${index}`,
@@ -674,21 +675,32 @@ test("SmartBuffer prefers pruning empty entries and bounds pending-turn buffers
   });
   const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0, bufferMaxSessions: 200 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
 
-  await buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory"));
+  await assert.rejects(
+    buffer.addTurn("active-thread", makeTurn("active-thread", "pending memory")),
+    BufferAdmissionRefusedError,
+    "a new session must be refused while only non-empty backlog fills the cap",
+  );
+
+  // Already-admitted sessions keep buffering; the save reflects the
+  // post-refusal state: nothing was evicted, nothing refused was buffered.
+  await buffer.addTurn("thread-204", makeTurn("thread-204", "another turn"));
+  assert.equal(buffer.getTurns("thread-204").length, 2);
 
   const persistedKeys = Object.keys(storage.saved?.entries ?? {});
-  assert.ok(persistedKeys.length <= 201, `bounded at the cap plus default (got ${persistedKeys.length})`);
+  assert.ok(persistedKeys.length <= 206, `entry count stays at the seeded cap state (got ${persistedKeys.length})`);
   assert.ok(persistedKeys.includes("default"), "default entry never pruned");
-  assert.ok(persistedKeys.includes("active-thread"), "the just-written key is retained");
-  assert.ok(!persistedKeys.includes("thread-0"), "oldest pending entry pruned once over the cap");
+  assert.ok(persistedKeys.includes("thread-0"), "oldest backlog keeps its turns for extraction");
   assert.ok(persistedKeys.includes("thread-204"), "newest pending entry survives");
+  assert.ok(!persistedKeys.includes("active-thread"), "the refused turn was never buffered");
 });
 
-test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 retry-retention bound)", async () => {
+test("pruneEntries never evicts non-empty backlog; live admission is refused past the cap (#1908 retry-retention bound)", async () => {
   // Retained failed extractions keep their turns in the buffer, so during a
   // provider outage non-empty entries can exceed MAX_BUFFER_ENTRY_COUNT (200).
-  // The cap is the documented bound: the oldest non-empty sessions must be
-  // evicted (loudly) rather than growing without bound (codex review).
+  // The cap is still the documented bound: buffered turn data is never the
+  // release valve — a NEW session is refused (retryable backpressure) until
+  // extraction drains an entry, so the daemon cannot OOM on unbounded growth
+  // and no buffered turn is dropped (codex review).
   const entries: NonNullable<BufferState["entries"]> = {};
   for (let i = 0; i < 210; i += 1) {
     const at = new Date(1_700_000_000_000 + i * 60_000).toISOString();
@@ -701,13 +713,17 @@ test("pruneEntries evicts oldest NON-empty session entries past the cap (#1908 r
   const storage = new FakeStorage({ turns: [], lastExtractionAt: null, extractionCount: 0, entries });
   const buffer = new SmartBuffer(parseConfig({ bufferSaveDebounceMs: 0, bufferMaxSessions: 200 }), storage as unknown as ConstructorParameters<typeof SmartBuffer>[1]);
   await buffer.load();
-  await buffer.addTurn("session-newest", makeTurn("session-newest", "new turn"));
+  await assert.rejects(
+    buffer.addTurn("session-newest", makeTurn("session-newest", "new turn")),
+    BufferAdmissionRefusedError,
+    "live admission refuses rather than evicting oldest non-empty backlog",
+  );
 
   const savedKeys = Object.keys(storage.saved?.entries ?? {});
-  assert.ok(savedKeys.length <= 200, `entries bounded at MAX_BUFFER_ENTRY_COUNT (got ${savedKeys.length})`);
-  assert.ok(savedKeys.includes("session-newest"), "the just-written key is retained");
-  assert.equal(buffer.getTurns("session-000").length, 0, "oldest non-empty entry was evicted");
+  assert.ok(savedKeys.length <= 211, `entries bounded at MAX_BUFFER_ENTRY_COUNT plus default (got ${savedKeys.length})`);
+  assert.equal(buffer.getTurns("session-000").length, 1, "oldest non-empty entry keeps its turn for extraction");
   assert.ok(buffer.getTurns("session-209").length > 0, "newest pre-existing entry survives");
+  assert.ok(!savedKeys.includes("session-newest"), "the refused turn was never buffered");
 });
 
 // ---------------------------------------------------------------------------

package/src/buffer-turn-helpers.ts

@@ -398,3 +398,44 @@ export function probeWithTimeout<T>(inflight: Promise<T>, timeoutMs: number): Pr
     if (timer) clearTimeout(timer);
   });
 }
+
+export const isAcceptedTurn = (t: { acceptedCapture?: boolean; writeNamespaceOverride?: string }): boolean =>
+  t.acceptedCapture === true || t.writeNamespaceOverride !== undefined;
+
+export function entryActivityAt(entry: BufferEntryState): number {
+  const lastTurnAt = entry.turns.reduce((latest, turn) => {
+    const parsed = Date.parse(turn.timestamp);
+    return Number.isFinite(parsed) ? Math.max(latest, parsed) : latest;
+  }, -1);
+  const lastExtractionAt =
+    entry.lastExtractionAt === null ? Number.NaN : Date.parse(entry.lastExtractionAt);
+  return Math.max(
+    lastTurnAt,
+    Number.isFinite(lastExtractionAt) ? lastExtractionAt : -1,
+  );
+}
+
+export function entryHoldsAcceptedCapture(entry: BufferEntryState | undefined): boolean {
+  return (entry?.turns ?? []).some(isAcceptedTurn) || (entry?.retainedTurns ?? []).some(isAcceptedTurn);
+}
+
+export function normalizeBufferState(state: BufferState): BufferState {
+  // SAFETY: persisted-state contract — entries, when present, is a record of BufferEntryState.
+  const entries = Object.assign(
+    Object.create(null),
+    state.entries ?? {},
+  ) as NonNullable<BufferState["entries"]>;
+  if (!entries.default) {
+    entries.default = {
+      turns: Array.isArray(state.turns) ? [...state.turns] : [],
+      lastExtractionAt: state.lastExtractionAt ?? null,
+      extractionCount: state.extractionCount ?? 0,
+    };
+  }
+  return {
+    turns: entries.default.turns,
+    lastExtractionAt: entries.default.lastExtractionAt,
+    extractionCount: entries.default.extractionCount,
+    entries,
+  };
+}