@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/plugins/defaults/memory-v3-shadow/__tests__/fresh-set.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+
+import { computeFreshSet } from "../fresh-set.js";
+
+const entry = (slug: string, modifiedAt: number) => ({ slug, modifiedAt });
+
+describe("computeFreshSet", () => {
+  test("ranks by modification time, newest first", () => {
+    const slugs = computeFreshSet(
+      [entry("old", 1000), entry("newest", 3000), entry("mid", 2000)],
+      { k: 3, excludeSlugs: new Set() },
+    );
+    expect(slugs).toEqual(["newest", "mid", "old"]);
+  });
+
+  test("cuts to k after exclusions", () => {
+    const slugs = computeFreshSet(
+      [entry("a", 4000), entry("b", 3000), entry("c", 2000), entry("d", 1000)],
+      { k: 2, excludeSlugs: new Set(["a"]) },
+    );
+    // "a" is excluded BEFORE the cut, so the two slots go to the next-newest.
+    expect(slugs).toEqual(["b", "c"]);
+  });
+
+  test("skips synthetic entries (modifiedAt 0)", () => {
+    const slugs = computeFreshSet(
+      [entry("skills/oura", 0), entry("real-page", 500)],
+      { k: 5, excludeSlugs: new Set() },
+    );
+    expect(slugs).toEqual(["real-page"]);
+  });
+
+  test("k = 0 disables the lane", () => {
+    expect(
+      computeFreshSet([entry("a", 1000)], { k: 0, excludeSlugs: new Set() }),
+    ).toEqual([]);
+  });
+
+  test("breaks modification-time ties by slug, ascending", () => {
+    const slugs = computeFreshSet(
+      [entry("zebra", 1000), entry("apple", 1000), entry("mango", 1000)],
+      { k: 3, excludeSlugs: new Set() },
+    );
+    expect(slugs).toEqual(["apple", "mango", "zebra"]);
+  });
+
+  test("does not mutate the input array", () => {
+    const entries = [entry("b", 1000), entry("a", 2000)];
+    computeFreshSet(entries, { k: 2, excludeSlugs: new Set() });
+    expect(entries.map((e) => e.slug)).toEqual(["b", "a"]);
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/__tests__/injection.test.ts

@@ -215,6 +215,7 @@ function result(
     lanes: {
       core: [],
       hot: [],
+      fresh: [],
       finder: matched.map(([slug]) => ({
         slug,
         descriptor: "",

package/src/plugins/defaults/memory-v3-shadow/__tests__/live-integration.test.ts

@@ -189,7 +189,7 @@ function candidateSlugs(messages: Message[]): Slug[] {
       );
       if (finder) {
         for (const line of finder[1].split("\n")) {
-          const m = /^\[(\d+)\] (\S+)(?: — |$)/.exec(line);
+          const m = /^\[(\d+)\] (?:\([^)]*\) )?(\S+)(?: — |$)/.exec(line);
           if (m) entries.push({ id: Number(m[1]), slug: m[2]! });
         }
       }
@@ -235,6 +235,7 @@ async function runTurn(
     edgeGraph: deps.lanes.edgeGraph,
     coreSlugs: [],
     hotSlugs: [],
+    freshSlugs: [],
     prefixCards: new Map(),
   });
   const active = getActiveSlugs(conversationId);

package/src/plugins/defaults/memory-v3-shadow/__tests__/orchestrate.test.ts

@@ -127,8 +127,9 @@ function depsOf(
 ): OrchestrateDeps {
   const coreSlugs = overrides.coreSlugs ?? [];
   const hotSlugs = overrides.hotSlugs ?? [];
+  const freshSlugs = overrides.freshSlugs ?? [];
   const prefixCards = new Map<Slug, string>(
-    [...coreSlugs, ...hotSlugs].map((slug) => [
+    [...coreSlugs, ...hotSlugs, ...freshSlugs].map((slug) => [
       slug,
       renderCard(slug, RAW[slug] ?? ""),
     ]),
@@ -140,6 +141,7 @@ function depsOf(
     edgeGraph: lanes.edgeGraph,
     coreSlugs,
     hotSlugs,
+    freshSlugs,
     prefixCards,
     ...overrides,
   };
@@ -148,12 +150,14 @@ function depsOf(
 function makeTurn(
   turnNumber: number,
   currentMessage: string,
+  previousAssistantMessage?: string,
 ): MemoryRoutingTurn {
   return {
     conversationId: "conv-xyz",
     turnNumber,
     currentMessage,
     recentContext: "prior context",
+    previousAssistantMessage,
   };
 }
 
@@ -199,7 +203,7 @@ function parsePool(messages: Message[]): {
       );
       if (finder) {
         for (const line of finder[1].split("\n")) {
-          const m = /^\[(\d+)\] (\S+)(?: — |$)/.exec(line);
+          const m = /^\[(\d+)\] (?:\([^)]*\) )?(\S+)(?: — |$)/.exec(line);
           if (m) entries.push({ id: Number(m[1]), slug: m[2]!, line });
         }
       }
@@ -371,6 +375,133 @@ describe("orchestrate — cache-ordered pool (core + hot + finders)", () => {
     ]);
   });
 
+  test("fresh follows hot in the pool and dedups against core/hot", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    const result = await orchestrate(
+      makeTurn(1, "apple"),
+      depsOf(lanes, {
+        coreSlugs: ["topic-c"],
+        hotSlugs: ["topic-d"],
+        // topic-c (core) and topic-d (hot) are defensively dropped; only
+        // topic-b earns a fresh slot.
+        freshSlugs: ["topic-c", "topic-d", "topic-b"],
+      }),
+    );
+
+    expect(lastPool).toEqual(["topic-c", "topic-d", "topic-b", "topic-a"]);
+    expect(result.lanes.fresh).toEqual(["topic-b"]);
+  });
+
+  test('reply-query hits join the finder tail tagged "reply", after primary lanes and before edge', async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    // Primary query matches topic-a; the previous reply matches topic-b. The
+    // edge lane expands topic-a's curated link to topic-d.
+    const result = await orchestrate(
+      makeTurn(1, "apple", "cherry date"),
+      depsOf(lanes, { replyQueryK: 5 }),
+    );
+
+    expect(result.lanes.finder.map((c) => [c.slug, c.lane])).toEqual([
+      ["topic-a", "needle"],
+      ["topic-b", "reply"],
+      ["topic-d", "edge"],
+    ]);
+    // The reply-matched section is recorded for injection/spotlight.
+    expect(result.matchedSections.has("topic-b")).toBe(true);
+  });
+
+  test("a slug both queries surface keeps its primary-lane attribution", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    const result = await orchestrate(
+      makeTurn(1, "apple", "apple banana"),
+      depsOf(lanes, { replyQueryK: 5 }),
+    );
+
+    const topicA = result.lanes.finder.filter((c) => c.slug === "topic-a");
+    expect(topicA).toHaveLength(1);
+    expect(topicA[0]!.lane).toBe("needle");
+  });
+
+  test("no previous assistant message → no reply-lane candidates", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    const result = await orchestrate(
+      makeTurn(1, "apple"),
+      depsOf(lanes, { replyQueryK: 5 }),
+    );
+
+    expect(result.lanes.finder.some((c) => c.lane === "reply")).toBe(false);
+  });
+
+  test("replyQueryK = 0 disables the pass even with a previous reply", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    const result = await orchestrate(
+      makeTurn(1, "apple", "cherry date"),
+      depsOf(lanes, { replyQueryK: 0 }),
+    );
+
+    expect(result.lanes.finder.some((c) => c.lane === "reply")).toBe(false);
+  });
+
+  test('learned-edge expansion surfaces association neighbours tagged "learned", after the static edge lane', async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    // Needle("apple") surfaces topic-a; static links expand a → d; the
+    // learned graph associates a → c (no authored link exists).
+    const learnedGraph = {
+      adjacency: new Map([["topic-a", new Map([["topic-c", undefined]])]]),
+      hubs: new Set<Slug>(),
+      slugs: new Set(SLUGS),
+    };
+    const result = await orchestrate(
+      makeTurn(1, "apple"),
+      depsOf(lanes, { learnedGraph, learnedPerSeed: 3, learnedCap: 20 }),
+    );
+
+    expect(result.lanes.finder.map((c) => [c.slug, c.lane])).toEqual([
+      ["topic-a", "needle"],
+      ["topic-d", "edge"],
+      ["topic-c", "learned"],
+    ]);
+    // Association, not lexical relevance, surfaced topic-c — no matched
+    // section is recorded (injection falls back to the full page).
+    expect(result.matchedSections.has("topic-c")).toBe(false);
+  });
+
+  test("learnedCap = 0 disables the learned pass", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider([]);
+
+    const learnedGraph = {
+      adjacency: new Map([["topic-a", new Map([["topic-c", undefined]])]]),
+      hubs: new Set<Slug>(),
+      slugs: new Set(SLUGS),
+    };
+    const result = await orchestrate(
+      makeTurn(1, "apple"),
+      depsOf(lanes, { learnedGraph, learnedCap: 0 }),
+    );
+
+    expect(result.lanes.finder.some((c) => c.lane === "learned")).toBe(false);
+  });
+
   test("the rendered stable prefix is byte-identical across turns with different queries", async () => {
     const lanes = await buildLanes();
     const deps = depsOf(lanes, {
@@ -456,9 +587,9 @@ describe("orchestrate — cache-ordered pool (core + hot + finders)", () => {
     expect(lastPool.filter((s) => s === "topic-a")).toHaveLength(2);
     expect(lastPool[0]).toBe("topic-a");
     // The finder line shows the matched-section snippet.
-    expect(lastPoolLines.find((l) => /^\[2\] topic-a — /.test(l))).toContain(
-      "apple",
-    );
+    expect(
+      lastPoolLines.find((l) => /^\[2\] (?:\([^)]*\) )?topic-a — /.test(l)),
+    ).toContain("apple");
     // Selecting both ids still yields ONE selection (slug dedup), the finder
     // lane records the hit, and the matched section survives downstream.
     expect(result.selections).toEqual([{ slug: "topic-a", pinned: false }]);

package/src/plugins/defaults/memory-v3-shadow/__tests__/pool-select.test.ts

@@ -316,6 +316,23 @@ describe("selectPool — request shape", () => {
     expect(tail.text).not.toContain("<candidate_cards>");
   });
 
+  test("finder lines render the surfacing lane tag when one is supplied", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [] }));
+    const pool = makePool();
+    pool.finder = [
+      { slug: "topic-x", descriptor: "section: about topic x", lane: "needle" },
+      { slug: "page-a", descriptor: "", lane: "learned" },
+    ];
+    await selectPool(pool, makeTurn("rollout?"));
+
+    const [, tail] = sentBlocks();
+    expect(tail.text).toContain(
+      "[3] (needle) topic-x — section: about topic x",
+    );
+    // Empty descriptor: lane tag still renders, dash omitted.
+    expect(tail.text).toContain("[4] (learned) page-a");
+  });
+
   test("the rendered prefix is byte-identical across turns; only the tail varies", async () => {
     providerStub = makeProvider(toolUseResponse({ ids: [1] }));
     await selectPool(makePool(), makeTurn("first question"));

package/src/plugins/defaults/memory-v3-shadow/__tests__/selection-log-store.test.ts

@@ -202,9 +202,12 @@ describe("summarizeSelections", () => {
     expect(summary.bySource).toEqual({
       core: 0,
       hot: 0,
+      fresh: 0,
       needle: 2,
       dense: 0,
       edge: 2,
+      reply: 0,
+      learned: 0,
     });
     expect(summary.turns).toBe(2);
     // page-1 and page-2 — distinct across the two turns.
@@ -216,9 +219,12 @@ describe("summarizeSelections", () => {
       bySource: {
         core: 0,
         hot: 0,
+        fresh: 0,
         needle: 0,
         dense: 0,
         edge: 0,
+        reply: 0,
+        learned: 0,
       },
       turns: 0,
       distinctSlugs: 0,

package/src/plugins/defaults/memory-v3-shadow/__tests__/shadow-integration.test.ts

@@ -237,7 +237,7 @@ function candidateSlugs(messages: Message[]): Slug[] {
       );
       if (finder) {
         for (const line of finder[1].split("\n")) {
-          const m = /^\[(\d+)\] (\S+)(?: — |$)/.exec(line);
+          const m = /^\[(\d+)\] (?:\([^)]*\) )?(\S+)(?: — |$)/.exec(line);
           if (m) entries.push({ id: Number(m[1]), slug: m[2]! });
         }
       }
@@ -310,6 +310,7 @@ async function runTurn(
     edgeGraph: deps.lanes.edgeGraph,
     coreSlugs: deps.core ?? [],
     hotSlugs: deps.hot ?? [],
+    freshSlugs: [],
     // Mirrors lane init: every stable-prefix slug gets a pre-rendered card.
     prefixCards: new Map(
       stableSlugs.map((slug) => [slug, renderCard(slug, RAW[slug] ?? "")]),
@@ -476,9 +477,12 @@ describe("memory-v3 shadow integration — selection-log readout", () => {
       bySource: {
         core: 0,
         hot: 0,
+        fresh: 0,
         needle: 0,
         dense: 0,
         edge: 0,
+        reply: 0,
+        learned: 0,
       },
       turns: 0,
       distinctSlugs: 0,

package/src/plugins/defaults/memory-v3-shadow/__tests__/shadow-plugin.test.ts

@@ -34,6 +34,7 @@ import type { HotSetEntry, HotSetOptions } from "../hot-set.js";
 import type { OrchestrateResult } from "../orchestrate.js";
 import {
   MEMORY_V3_COMMIT_META_KEY,
+  type MemoryRoutingTurn,
   type SectionIndex,
   type SelectionSource,
 } from "../types.js";
@@ -88,8 +89,9 @@ const CAPABILITY_SLUG = "skills/example";
 const CAPABILITY_CONTENT = "use the kumquat skill to do the thing";
 
 // The orchestrate result the spy returns. `lanes` records where each pooled
-// slug lived: page-core in the core lane, page-hot in the hot lane, and the
-// finder entries page-1 → "needle", page-2 → "dense", page-3 → "edge";
+// slug lived: page-core in the core lane, page-hot in the hot lane, page-fresh
+// in the fresh lane, and the finder entries page-1 → "needle", page-2 → "dense",
+// page-3 → "edge";
 // `attributeSelections` reads it directly. `matchedSections` carries the
 // matched section for the slugs that had one (page-1/page-2) — consumed by the
 // live injector's progressive disclosure, independent of source attribution.
@@ -98,9 +100,12 @@ const orchestrateSpy = mock(
     selections: [
       { slug: "page-core", pinned: false },
       { slug: "page-hot", pinned: false },
+      { slug: "page-fresh", pinned: false },
       { slug: "page-1", pinned: true },
       { slug: "page-2", pinned: false },
       { slug: "page-3", pinned: false },
+      { slug: "page-4", pinned: false },
+      { slug: "page-5", pinned: false },
     ],
     matchedSections: new Map([
       ["page-1", { article: "page-1", title: "", text: "x", ordinal: 0 }],
@@ -109,10 +114,13 @@ const orchestrateSpy = mock(
     lanes: {
       core: ["page-core"],
       hot: ["page-hot"],
+      fresh: ["page-fresh"],
       finder: [
         { slug: "page-1", descriptor: "", lane: "needle" },
         { slug: "page-2", descriptor: "", lane: "dense" },
         { slug: "page-3", descriptor: "", lane: "edge" },
+        { slug: "page-4", descriptor: "", lane: "reply" },
+        { slug: "page-5", descriptor: "", lane: "learned" },
       ],
     },
   }),
@@ -180,9 +188,19 @@ mock.module("../../../../config/loader.js", () => ({
       enabled: memoryEnabled,
       v3: {
         hotSet: { k: 40, halfLifeDays: 14 },
+        freshSet: { k: 50 },
         spotlight: { n: 6, windowTurns: 2 },
         needleK: 100,
         denseK: 100,
+        replyQueryK: 12,
+        learnedEdges: {
+          halfLifeDays: 30,
+          minCount: 3,
+          npmiFloor: 0.2,
+          maxPerPage: 6,
+          perSeed: 3,
+          cap: 20,
+        },
         edge: { hubDegree: 30, seedCount: 18, perSeed: 6, cap: 45 },
       },
       qdrant: { vectorSize: 8, onDisk: false },
@@ -463,12 +481,57 @@ describe("memory-v3 shadow plugin", () => {
       { slug: "page-2", source: "dense", pinned: 0 },
       // page-3 was surfaced by the edge lane → "edge".
       { slug: "page-3", source: "edge", pinned: 0 },
-      // page-core / page-hot sit in the stable prefix → "core" / "hot".
+      // page-4 was first surfaced by the reply-query pass → "reply".
+      { slug: "page-4", source: "reply", pinned: 0 },
+      // page-5 was first surfaced by the learned-edge pass → "learned".
+      { slug: "page-5", source: "learned", pinned: 0 },
+      // page-core / page-hot / page-fresh sit in the stable prefix →
+      // "core" / "hot" / "fresh".
       { slug: "page-core", source: "core", pinned: 0 },
+      { slug: "page-fresh", source: "fresh", pinned: 0 },
       { slug: "page-hot", source: "hot", pinned: 0 },
     ]);
   });
 
+  test("the turn carries the tail of the previous assistant reply for the reply-query pass", async () => {
+    shadowEnabled = true;
+    messages = [
+      {
+        role: "user",
+        content: JSON.stringify([{ type: "text", text: "first question" }]),
+      },
+      {
+        role: "assistant",
+        content: JSON.stringify([
+          { type: "text", text: "the thread continues from my last reply" },
+        ]),
+      },
+      {
+        role: "user",
+        content: JSON.stringify([{ type: "text", text: "and now this" }]),
+      },
+    ];
+    await runShadowObservation("conv-1", 1);
+
+    const turn = (
+      orchestrateSpy.mock.calls as unknown as unknown[][]
+    )[0]![0] as MemoryRoutingTurn;
+    expect(turn.currentMessage).toBe("and now this");
+    expect(turn.previousAssistantMessage).toBe(
+      "the thread continues from my last reply",
+    );
+  });
+
+  test("a conversation-opening turn has no previous assistant message", async () => {
+    shadowEnabled = true;
+    await runShadowObservation("conv-1", 0);
+
+    const turn = (
+      orchestrateSpy.mock.calls as unknown as unknown[][]
+    )[0]![0] as MemoryRoutingTurn;
+    expect(turn.previousAssistantMessage).toBeUndefined();
+  });
+
   test("a selection of a core page a finder also hit attributes to core (pool position wins)", () => {
     const rows = attributeSelections({
       selections: [{ slug: "page-core", pinned: false }],
@@ -476,6 +539,7 @@ describe("memory-v3 shadow plugin", () => {
       lanes: {
         core: ["page-core"],
         hot: [],
+        fresh: [],
         // The needle also hit the core page this turn — the row still logs
         // "core" because that is where the candidate lived in the pool.
         finder: [{ slug: "page-core", descriptor: "", lane: "needle" }],
@@ -598,7 +662,7 @@ describe("memory-v3 shadow plugin", () => {
     orchestrateSpy.mockImplementationOnce(async () => ({
       selections: [],
       matchedSections: new Map(),
-      lanes: { core: [], hot: [], finder: [] },
+      lanes: { core: [], hot: [], fresh: [], finder: [] },
     }));
     const block = await produce("conv-1", 0);
     expect(block).toBeNull();

package/src/plugins/defaults/memory-v3-shadow/card.ts

@@ -72,22 +72,61 @@ function renderTocLine(
   return `[sections: ${headings.map((h) => `§${h}`).join(" · ")}]`;
 }
 
+/** Max characters of a `current:` line carried onto the card. A `current:` is
+ * one line by contract; the cap keeps a runaway value from bloating every
+ * render of the card. */
+const CURRENT_MAX_CHARS = 280;
+
+/**
+ * Render a page's `current:` frontmatter (one-line live state) as a card
+ * annotation, or `null` when the page has none. Whitespace-collapsed and
+ * capped at {@link CURRENT_MAX_CHARS}.
+ */
+function renderCurrentLine(fields: Record<string, unknown>): string | null {
+  const current = fields.current;
+  if (typeof current !== "string") return null;
+  const collapsed = current.replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0) return null;
+  const capped =
+    collapsed.length > CURRENT_MAX_CHARS
+      ? `${collapsed.slice(0, CURRENT_MAX_CHARS).trimEnd()}…`
+      : collapsed;
+  return `[current: ${capped}]`;
+}
+
 /**
- * Render a page's compact card: header marker, head section (uncapped — the
- * corpus's rare long leads inject whole; a length cap is a deliberate
- * non-feature), and one-line TOC.
+ * Render a page's compact card: header marker, optional annotation line, head
+ * section (uncapped — the corpus's rare long leads inject whole; a length cap
+ * is a deliberate non-feature), and one-line TOC.
  *
  * ```
  * # memory/concepts/<slug>.md
+ * [lane: fresh · updated 2026-06-10 14:23]
  * <head section verbatim>
  *
  * [sections: §… · §…]
  * ```
  *
+ * The annotation renders directly under the header: selector-visible metadata
+ * must sit on the always-rendered card surface (section-grain rendering can
+ * hide anything that lives only inside page content). Annotations must derive
+ * only from lane-init state (lane membership, page mtime) so the card stays
+ * byte-identical across turns between lane recomputes.
+ *
+ * A page's `current:` frontmatter (one-line live state — open items,
+ * deadlines, what's pending) renders the same way, first: it exists so
+ * state-shaped questions can select the page, which only works if the
+ * selector can see it on every card render. It changes only when the page is
+ * edited (consolidation), so it shares the lane annotation's cache story.
+ *
  * The TOC line is omitted when the page has no `## ` sections and no usable
- * `links:`. Deterministic for a given (slug, rawPageText).
+ * `links:`. Deterministic for a given (slug, rawPageText, annotation).
  */
-export function renderCard(slug: Slug, rawPageText: string): string {
+export function renderCard(
+  slug: Slug,
+  rawPageText: string,
+  annotation?: string,
+): string {
   const parsed = parseFrontmatterFields(rawPageText);
   // `parseFrontmatterFields` returns null both for "no frontmatter block" and
   // "block present but YAML failed to parse" — strip the block either way so a
@@ -101,6 +140,11 @@ export function renderCard(slug: Slug, rawPageText: string): string {
   const head = (firstHeading ? body.slice(0, firstHeading.index) : body).trim();
 
   let card = injectedConceptHeader(slug);
+  const current = renderCurrentLine(fields);
+  if (current !== null) card += `\n${current}`;
+  if (annotation !== undefined && annotation.length > 0) {
+    card += `\n${annotation}`;
+  }
   if (head.length > 0) card += `\n${head}`;
 
   const toc = renderTocLine(body, fields);

package/src/plugins/defaults/memory-v3-shadow/fresh-set.ts

@@ -0,0 +1,59 @@
+/**
+ * Recency fresh-set lane.
+ *
+ * Returns the top-K page slugs by most-recent on-disk modification
+ * (`PageIndexEntry.modifiedAt`). The fresh set keeps *just-written* pages in
+ * the candidate pool during the window before the other lanes can reach them:
+ * a page consolidated minutes ago has no selection history (so frecency can't
+ * rank it into the hot set) and a "what happened today?"-shaped message gives
+ * the finder lanes nothing lexical to match it on. Recency is exactly the
+ * signal those lanes are missing, so it gets its own lane.
+ *
+ * Like core and hot, the fresh set is a stable-prefix lane: it is computed at
+ * lane init and recomputed only on lane invalidation (the consolidation
+ * cadence), so its membership — and therefore the selector's cache-stable
+ * prefix — never changes mid-window. Page mtimes move on every consolidation
+ * write, which is the same event that invalidates the lanes, so recompute
+ * lag is bounded by the consolidation interval.
+ *
+ * Slugs in `excludeSlugs` (core + hot members) are dropped before the K cut —
+ * those pages already sit in the stable prefix, so re-listing them would only
+ * spend fresh slots on duplicates. Synthetic capability entries carry
+ * `modifiedAt: 0` and are skipped: they have no on-disk write to be fresh by.
+ */
+
+import type { Slug } from "./types.js";
+
+/** The slice of a page-index entry the fresh lane ranks on. */
+export interface FreshSetEntry {
+  slug: Slug;
+  /** File mtime in epoch ms; `0` for synthetic entries (skills, CLI commands). */
+  modifiedAt: number;
+}
+
+export interface FreshSetOptions {
+  /** Maximum number of slugs returned; `0` disables the lane. */
+  k: number;
+  /** Slugs excluded from the result (core + hot — fresh never duplicates the
+   *  rest of the stable prefix). */
+  excludeSlugs: Set<string>;
+}
+
+/**
+ * Compute the top-`k` fresh slugs by file modification time, newest first.
+ *
+ * Deterministic for fixed inputs: ties break `modifiedAt` desc, then slug asc.
+ */
+export function computeFreshSet(
+  entries: readonly FreshSetEntry[],
+  opts: FreshSetOptions,
+): Slug[] {
+  const { k, excludeSlugs } = opts;
+  if (k <= 0) return [];
+
+  return entries
+    .filter((entry) => entry.modifiedAt > 0 && !excludeSlugs.has(entry.slug))
+    .sort((a, b) => b.modifiedAt - a.modifiedAt || (a.slug < b.slug ? -1 : 1))
+    .slice(0, k)
+    .map((entry) => entry.slug);
+}

package/src/plugins/defaults/memory-v3-shadow/injector.ts

@@ -301,14 +301,16 @@ export const memoryV3Injector: Injector = {
       // `produce()` would let a never-attached turn (non-user tail) claim
       // cards in the store, suppressing them until compaction. The valve is
       // scheduled after `recordInjected` so the resident accounting includes
-      // this turn's cards; core/hot lane members are exempt — the selector's
-      // stable prefix must never be pruned out from under it.
+      // this turn's cards; stable-prefix lane members (core/hot/fresh) are
+      // exempt — the selector's stable prefix must never be pruned out from
+      // under it.
       const commit = (): void => {
         recordInjected(ctx.conversationId, entries);
         schedulePruneValve(ctx.conversationId, {
           exemptSlugs: new Set<Slug>([
             ...result.lanes.core,
             ...result.lanes.hot,
+            ...result.lanes.fresh,
           ]),
         });
       };