@vellumai/assistant 0.8.5 → 0.8.7

package/src/memory/schema/infrastructure.ts

@@ -21,6 +21,7 @@ export const cronJobs = sqliteTable("cron_jobs", {
   retryCount: integer("retry_count").notNull().default(0),
   maxRetries: integer("max_retries").notNull().default(3),
   retryBackoffMs: integer("retry_backoff_ms").notNull().default(60000),
+  timeoutMs: integer("timeout_ms"), // script-mode execution timeout override (ms); null = use default
   createdBy: text("created_by").notNull(), // 'agent' | 'user'
   mode: text("mode").notNull().default("execute"), // 'notify' | 'execute'
   routingIntent: text("routing_intent").notNull().default("all_channels"), // 'single_channel' | 'multi_channel' | 'all_channels'
@@ -242,6 +243,16 @@ export const llmUsageEvents = sqliteTable(
     pricingStatus: text("pricing_status").notNull(),
     llmCallCount: integer("llm_call_count"),
     metadataJson: text("metadata_json"),
+    /**
+     * Version of the assistant binary at the moment THIS event was
+     * recorded (not when the batch was uploaded). Telemetry uploads
+     * batch events together and may flush days after the event fired
+     * (offline laptop, network outage, ingest clog — see May 2026
+     * incident). Stamping at record time keeps the version filter on
+     * `/admin/inference` truthful for delayed batches. Null for rows
+     * persisted before migration 267 ran.
+     */
+    assistantVersion: text("assistant_version"),
   },
   (table) => [
     index("idx_llm_usage_events_conversation_id").on(table.conversationId),

package/src/memory/v2/__tests__/backfill-jobs.test.ts

@@ -202,7 +202,10 @@ afterAll(() => {
   rmSync(tmpWorkspace, { recursive: true, force: true });
 });
 
-const { getDb, resetDb } = await import("../../db-connection.js");
+const { getDb } = await import("../../db-connection.js");
+const { resetDbForTesting } = await import(
+  "../../../__tests__/db-test-helpers.js"
+);
 const { initializeDb } = await import("../../db-init.js");
 const { rawExec } = await import("../../raw-query.js");
 const { conversations, memoryJobs, messages } = await import("../../schema.js");
@@ -247,7 +250,7 @@ function makeJob(
 }
 
 beforeEach(() => {
-  resetDb();
+  resetDbForTesting();
   initializeDb();
   // The shared template-DB caching does not clear WAL state between tests,
   // so explicitly truncate every table this suite writes to. Without this,

package/src/memory/v2/__tests__/consolidation-job.test.ts

@@ -105,6 +105,43 @@ mock.module("../../jobs-store.js", () => ({
   isMemoryEnabled: () => true,
 }));
 
+// ── v3 health-injection mocks ───────────────────────────────────────
+//
+// The consolidation handler optionally prepends a v3 health block to the
+// prompt when a v3 flag is on AND the rendered report is non-empty. These
+// mocks let each test (a) toggle the flag, (b) decide what health block the
+// renderer produces, and (c) force the health computation to throw — without
+// materializing a real v3 data dir. The tree/core/page-index loaders are
+// stubbed to inert values; `computeV3Health` is a pass-through whose result is
+// fed to the toggleable `renderV3Health`.
+let v3FlagOn = false;
+mock.module("../../../config/assistant-feature-flags.js", () => ({
+  isAssistantFeatureFlagEnabled: () => v3FlagOn,
+}));
+
+let renderedHealth = "";
+let computeThrows = false;
+mock.module("../../v3/health.js", () => ({
+  computeV3Health: () => {
+    if (computeThrows) throw new Error("simulated health compute failure");
+    return {};
+  },
+  renderV3Health: () => renderedHealth,
+}));
+
+mock.module("../../v3/tree.js", () => ({
+  loadLeafTree: async () => ({ leaves: new Map(), byPage: new Map() }),
+  resolveDataDir: () => "/tmp/v3-data-stub",
+}));
+
+mock.module("../../v3/core.js", () => ({
+  loadCore: async () => new Set<string>(),
+}));
+
+mock.module("../../v2/page-index.js", () => ({
+  getPageIndex: async () => ({ entries: [] }),
+}));
+
 // ── Workspace pin ───────────────────────────────────────────────────
 let tmpWorkspace: string;
 let previousWorkspaceEnv: string | undefined;
@@ -173,6 +210,11 @@ beforeEach(() => {
   emitCalls.length = 0;
   enqueuedJobs.length = 0;
   nextJobIdCounter = 0;
+
+  // v3 health injection defaults: flag off, no rendered block, no throw.
+  v3FlagOn = false;
+  renderedHealth = "";
+  computeThrows = false;
 });
 
 // ---------------------------------------------------------------------------
@@ -305,6 +347,25 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
     expect(existsSync(lockPath())).toBe(false);
   });
 
+  test("enqueues memory_v3_maintain as a follow-up when a v3 flag is on", async () => {
+    v3FlagOn = true;
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    expect(result.kind).toBe("invoked");
+    expect(enqueuedJobs.map((j) => j.type)).toEqual([
+      "memory_v2_reembed",
+      "memory_v3_maintain",
+    ]);
+  });
+
+  test("does not enqueue memory_v3_maintain when v3 flags are off", async () => {
+    v3FlagOn = false;
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    expect(result.kind).toBe("invoked");
+    expect(enqueuedJobs.map((j) => j.type)).toEqual(["memory_v2_reembed"]);
+  });
+
   test("returns run_failed and skips follow-ups when the runner reports failure", async () => {
     runnerImpl = async () => ({
       conversationId: "conv-1",
@@ -348,6 +409,69 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
   });
 });
 
+describe("memoryV2ConsolidateJob — v3 health injection", () => {
+  beforeEach(() => {
+    writeFileSync(
+      bufferPath(),
+      "- [Apr 27, 9:00 AM] Alice prefers VS Code over Vim.\n",
+    );
+  });
+
+  test("prepends the health block when a v3 flag is on and the report is actionable", async () => {
+    v3FlagOn = true;
+    renderedHealth = "memory-v3 health:\n- 2 unassigned slug(s): a, b";
+
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    expect(result.kind).toBe("invoked");
+    const prompt = runnerLastArgs?.prompt as string;
+    // The health block is PREPENDED, separated by a blank line, with the
+    // base consolidation prompt still present underneath it.
+    expect(prompt.startsWith(`${renderedHealth}\n\n`)).toBe(true);
+    expect(prompt).toContain("memory consolidation");
+    expect(prompt).not.toContain(CUTOFF_PLACEHOLDER);
+  });
+
+  test("leaves the prompt unchanged when the report is all-green (empty render)", async () => {
+    v3FlagOn = true;
+    renderedHealth = "";
+
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    expect(result.kind).toBe("invoked");
+    const prompt = runnerLastArgs?.prompt as string;
+    expect(prompt).not.toContain("memory-v3 health:");
+    // Prompt is exactly the resolved consolidation body.
+    expect(prompt).toContain("memory consolidation");
+  });
+
+  test("leaves the prompt unchanged when v3 flags are off even if a block would render", async () => {
+    v3FlagOn = false;
+    renderedHealth = "memory-v3 health:\n- 1 unassigned slug(s): a";
+
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    expect(result.kind).toBe("invoked");
+    const prompt = runnerLastArgs?.prompt as string;
+    expect(prompt).not.toContain("memory-v3 health:");
+    expect(prompt).toContain("memory consolidation");
+  });
+
+  test("falls back to the base prompt when health computation throws", async () => {
+    v3FlagOn = true;
+    computeThrows = true;
+    renderedHealth = "memory-v3 health:\n- should not appear";
+
+    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+    // A health-compute failure must NEVER break consolidation.
+    expect(result.kind).toBe("invoked");
+    const prompt = runnerLastArgs?.prompt as string;
+    expect(prompt).not.toContain("memory-v3 health:");
+    expect(prompt).toContain("memory consolidation");
+  });
+});
+
 describe("memoryV2ConsolidateJob — concurrent invocations", () => {
   beforeEach(() => {
     writeFileSync(bufferPath(), "- [Apr 27, 9:00 AM] Alice prefers VS Code.\n");

package/src/memory/v2/__tests__/harness-metrics.test.ts

@@ -25,6 +25,15 @@ describe("harness/metrics recallAtK", () => {
   test("empty ground truth is vacuously complete (recall 1)", () => {
     expect(recallAtK([], new Set<string>(), 5)).toBe(1);
   });
+
+  test("duplicate selections cannot push recall above 1.0", () => {
+    // A retriever emitting the same slug twice must not double-count it.
+    expect(recallAtK(["a", "a"], new Set(["a"]), 10)).toBe(1);
+    // Duplicates inside the top-k window still count once.
+    const gt = new Set(["a", "b"]);
+    expect(recallAtK(["a", "a", "b"], gt, 10)).toBeCloseTo(1);
+    expect(recallAtK(["a", "a", "b"], gt, 2)).toBeCloseTo(0.5);
+  });
 });
 
 describe("harness/metrics evalTurn", () => {

package/src/memory/v2/__tests__/harness-replay-input.test.ts

@@ -195,7 +195,7 @@ describe("harness/replay-input reconstructInput", () => {
     expect(r).toBeNull();
   });
 
-  test("priorEverInjected unions injected/in_context slugs from earlier router turns", async () => {
+  test("priorEverInjected mirrors production everInjected retention from earlier router turns", async () => {
     insertMessage("u1", "c1", "user", "u1", 10);
     insertMessage("a1", "c1", "assistant", "a1", 20);
     insertMessage("u2", "c1", "user", "u2", 30);
@@ -207,7 +207,12 @@ describe("harness/replay-input reconstructInput", () => {
       [
         makeConcept("p1", "injected"),
         makeConcept("p2", "in_context"),
-        makeConcept("p3", "not_injected"),
+        // page_missing / corrupt concept pages are retained in production's
+        // everInjected (so they aren't re-attempted every turn), so the replay
+        // must include them too.
+        makeConcept("p3", "page_missing"),
+        makeConcept("p4", "corrupt"),
+        makeConcept("p5", "not_injected"),
       ],
       20,
     );
@@ -219,7 +224,7 @@ describe("harness/replay-input reconstructInput", () => {
       WORKSPACE,
     );
     const slugs = (r?.input.priorEverInjected ?? []).map((e) => e.slug).sort();
-    expect(slugs).toEqual(["p1", "p2"]);
-    expect(r?.meta.priorEverInjectedCount).toBe(2);
+    expect(slugs).toEqual(["p1", "p2", "p3", "p4"]);
+    expect(r?.meta.priorEverInjectedCount).toBe(4);
   });
 });

package/src/memory/v2/__tests__/harness-runner.test.ts

@@ -92,6 +92,32 @@ describe("harness/runner runComparison", () => {
     expect(loop?.aggregate.meanRecallAtK[5]).toBeCloseTo(0.75);
   });
 
+  test("threads the abort signal into each retriever's input", async () => {
+    const controller = new AbortController();
+    const seenSignals: (AbortSignal | undefined)[] = [];
+    const capturingRetriever: Retriever = {
+      name: "router",
+      retrieve: async (input): Promise<RetrievalOutput> => {
+        seenSignals.push(input.signal);
+        return { selectedSlugs: [], sourceBySlug: new Map() };
+      },
+    };
+
+    // Fresh reconstructed input per turn so we exercise the per-turn assignment.
+    await runComparison({
+      retrievers: [capturingRetriever],
+      oracleTurns: [oracleTurn("c1", 1, ["a"])],
+      reconstruct: async () => ({
+        ...STUB_RECONSTRUCTED,
+        input: { ...STUB_INPUT },
+      }),
+      ks: [5],
+      signal: controller.signal,
+    });
+
+    expect(seenSignals).toEqual([controller.signal]);
+  });
+
   test("skips turns whose reconstruction returns null", async () => {
     const report = await runComparison({
       retrievers: [fixedRetriever("router", ["a"])],

package/src/memory/v2/__tests__/migration.test.ts

@@ -26,7 +26,12 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
-import type { Provider, ProviderResponse } from "../../../providers/types.js";
+import type {
+  Message,
+  Provider,
+  ProviderResponse,
+  SendMessageOptions,
+} from "../../../providers/types.js";
 
 // -- Mocks that must be installed before importing the module under test ---
 //
@@ -416,8 +421,11 @@ describe("synthesizeConceptPage", () => {
     let capturedSystem: string | undefined;
     const provider: Provider = {
       name: "stub",
-      sendMessage: async (_messages, _tools, system) => {
-        capturedSystem = system;
+      sendMessage: async (
+        _messages: Message[],
+        options?: SendMessageOptions,
+      ) => {
+        capturedSystem = options?.systemPrompt;
         return {
           content: [{ type: "text", text: "synthesized" }],
           model: "stub-model",

package/src/memory/v2/__tests__/page-index.test.ts

@@ -76,7 +76,12 @@ afterEach(() => {
 
 function makePage(
   slug: string,
-  opts: { edges?: string[]; summary?: string; body?: string } = {},
+  opts: {
+    edges?: string[];
+    summary?: string;
+    body?: string;
+    leaves?: string[];
+  } = {},
 ): ConceptPage {
   return {
     slug,
@@ -85,6 +90,7 @@ function makePage(
       ref_files: [],
       ref_urls: [],
       ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+      ...(opts.leaves !== undefined ? { leaves: opts.leaves } : {}),
     },
     body: opts.body ?? "",
   };
@@ -230,6 +236,36 @@ describe("getPageIndex", () => {
     expect(alice.edges).toEqual([bob.id]);
   });
 
+  test("exposes frontmatter leaves in the index entry", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", {
+        summary: "A",
+        leaves: ["page-a", "domain-a/topic-x"],
+      }),
+    );
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.leaves).toEqual([
+      "page-a",
+      "domain-a/topic-x",
+    ]);
+  });
+
+  test("defaults leaves to an empty array when the field is absent", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "A" }));
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.leaves).toEqual([]);
+  });
+
+  test("seeded skill entries carry an empty leaves list", async () => {
+    skillState.entries = [{ id: "browser", content: "Drive a browser." }];
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("skills/browser")?.leaves).toEqual([]);
+  });
+
   test("falls back to body when frontmatter.summary is absent", async () => {
     await writePage(
       workspaceDir,

package/src/memory/v2/__tests__/router.test.ts

@@ -148,8 +148,13 @@ afterEach(() => {
 function makeProvider(response: ProviderResponse): Provider {
   return {
     name: "stub",
-    sendMessage: async (messages, tools, systemPrompt, options) => {
-      providerCalls.push({ messages, tools, systemPrompt, options });
+    sendMessage: async (messages, options) => {
+      providerCalls.push({
+        messages,
+        tools: options?.tools,
+        systemPrompt: options?.systemPrompt,
+        options,
+      });
       // Honor abort like a real provider would — if the signal already
       // aborted, throw the canonical AbortError so callers can assert that
       // signal forwarding actually has teeth.
@@ -752,9 +757,14 @@ describe("runRouter — batched (batch_size set)", () => {
     let callCount = 0;
     providerStub = {
       name: "partial-failure",
-      sendMessage: async (messages, tools, systemPrompt, options) => {
+      sendMessage: async (messages, options) => {
         callCount += 1;
-        providerCalls.push({ messages, tools, systemPrompt, options });
+        providerCalls.push({
+          messages,
+          tools: options?.tools,
+          systemPrompt: options?.systemPrompt,
+          options,
+        });
         if (callCount === 1) throw new Error("batch 1 boom");
         return toolUseResponse([1]);
       },

package/src/memory/v2/__tests__/sweep-job.test.ts

@@ -35,8 +35,10 @@ import {
 
 import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
 import type {
+  Message,
   Provider,
   ProviderResponse,
+  SendMessageOptions,
   ToolUseContent,
 } from "../../../providers/types.js";
 
@@ -99,7 +101,9 @@ afterAll(() => {
   rmSync(tmpWorkspace, { recursive: true, force: true });
 });
 
-const { resetDb, getDb } = await import("../../db-connection.js");
+const { getDb } = await import("../../db-connection.js");
+const { resetDbForTesting } =
+  await import("../../../__tests__/db-test-helpers.js");
 const { initializeDb } = await import("../../db-init.js");
 const { messages, conversations } = await import("../../schema.js");
 const { memoryV2SweepJob } = await import("../sweep-job.js");
@@ -141,9 +145,9 @@ function makeJob(): Parameters<typeof memoryV2SweepJob>[0] {
 function makeEntriesProvider(entries: string[]): Provider {
   return {
     name: "stub",
-    sendMessage: async (msgs, _tools, systemPrompt) => {
+    sendMessage: async (msgs: Message[], options?: SendMessageOptions) => {
       providerCalls.push({
-        systemPrompt,
+        systemPrompt: options?.systemPrompt,
         userText: extractFirstUserText(msgs),
       });
       return {
@@ -212,7 +216,7 @@ function seedMessages(
 }
 
 beforeEach(() => {
-  resetDb();
+  resetDbForTesting();
   initializeDb();
   // Fresh memory dir per test — keeps assertions on file contents independent.
   rmSync(join(tmpWorkspace, "memory"), { recursive: true, force: true });
@@ -275,7 +279,7 @@ describe("memoryV2SweepJob — no recent messages", () => {
 });
 
 // Per-test conversation id ensures each test seeds a row that doesn't
-// collide with the previous test's row in the (shared) test DB. `resetDb`
+// collide with the previous test's row in the (shared) test DB. `resetDbForTesting`
 // is called in the outer beforeEach, but bun's mock module flow keeps the
 // DB intact long enough for the SQL inserts here to clash.
 let convCounter = 0;

package/src/memory/v2/backfill-jobs.ts

@@ -157,8 +157,14 @@ export async function memoryV2ActivationRecomputeJob(
   const workspaceDir = getWorkspaceDir();
   const database = getDb();
 
+  // Activation maps still need to refresh for archived conversations — a
+  // consolidated page can leave stale slugs above epsilon in their persisted
+  // state — so this job opts back into seeing archived rows.
   const conversations = listConversations(
     ACTIVATION_RECOMPUTE_CONVERSATION_LIMIT,
+    "standard",
+    0,
+    "all",
   );
   const edgeIndex = await getEdgeIndex(workspaceDir);
   const nowText = await loadNowText(workspaceDir);

package/src/memory/v2/consolidation-job.ts

@@ -61,6 +61,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
 import { runBackgroundJob } from "../../runtime/background-job-runner.js";
 import { getLogger } from "../../util/logger.js";
@@ -72,6 +73,11 @@ import {
   type MemoryJob,
   type MemoryJobType,
 } from "../jobs-store.js";
+import { getPageIndex } from "../v2/page-index.js";
+import { loadCore } from "../v3/core.js";
+import { computeV3Health, renderV3Health } from "../v3/health.js";
+import { loadLeafTree, resolveDataDir } from "../v3/tree.js";
+import type { LeafPath, Slug } from "../v3/types.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
 
@@ -80,6 +86,14 @@ const log = getLogger("memory-v2-consolidate");
 /** Stable identifier surfaced in `runBackgroundJob` logs and notifications. */
 const JOB_NAME = "memory.consolidate";
 
+/**
+ * v3 plugin flags. Either being on (a) prepends a v3 health block to the
+ * consolidation prompt and (b) enqueues `memory_v3_maintain` as a
+ * post-consolidation follow-up. These gate the v3 plugin itself.
+ */
+const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
+const MEMORY_V3_LIVE = "memory-v3-live" as const;
+
 /**
  * Hard timeout for the consolidation run. Consolidation reads the buffer,
  * rewrites several files, and re-encodes essentials/threads — generous
@@ -95,9 +109,10 @@ const CONSOLIDATION_TIMEOUT_MS = 15 * 60 * 1000;
  * agent touched: mtime-diffing is fragile across filesystems, and the
  * embedder's content-hash cache makes unchanged pages effectively free.
  */
-const FOLLOW_UP_JOB_TYPES: readonly MemoryJobType[] = [
-  "memory_v2_reembed",
-] as const;
+const FOLLOW_UP_JOB_TYPES: readonly MemoryJobType[] = ["memory_v2_reembed"];
+
+/** Follow-up enqueued only when a v3 flag is on. */
+const V3_FOLLOW_UP_JOB_TYPE: MemoryJobType = "memory_v3_maintain";
 
 /**
  * Job handler. See file header for the full lifecycle. Returns a discriminated
@@ -167,13 +182,20 @@ export async function memoryV2ConsolidateJob(
     // it to a regular file under 1 MiB before substitution so a stray path
     // (or a `/dev/zero`-style pseudo-file) cannot exfiltrate megabytes of
     // bytes through the wake hint.
+    //
+    // That resolved prompt is the base; `maybePrependV3Health` prepends a
+    // freshly computed v3 health block when a v3 flag is on and the tree has
+    // actionable drift, leaving it untouched otherwise.
+    const basePrompt = resolveConsolidationPrompt(
+      config.memory.v2.consolidation_prompt_path,
+      cutoff,
+    );
+    const prompt = await maybePrependV3Health(basePrompt, config);
+
     const runResult = await runBackgroundJob({
       jobName: JOB_NAME,
       source: MEMORY_V2_CONSOLIDATION_SOURCE,
-      prompt: resolveConsolidationPrompt(
-        config.memory.v2.consolidation_prompt_path,
-        cutoff,
-      ),
+      prompt,
       trustContext: { sourceChannel: "vellum", trustClass: "guardian" },
       callSite: "mainAgent",
       timeoutMs: CONSOLIDATION_TIMEOUT_MS,
@@ -197,9 +219,17 @@ export async function memoryV2ConsolidateJob(
 
     // Step 5: enqueue follow-up jobs. Enqueueing now keeps the dispatch
     // wiring exercised end-to-end so PR 21 only has to swap in the handler
-    // bodies.
+    // bodies. v3 maintenance is appended only while a v3 path (shadow or live)
+    // is active, so it never fans out on v2-only installs.
     const followUpJobIds: string[] = [];
-    for (const jobType of FOLLOW_UP_JOB_TYPES) {
+    const jobTypes: MemoryJobType[] = [...FOLLOW_UP_JOB_TYPES];
+    if (
+      isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
+      isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config)
+    ) {
+      jobTypes.push(V3_FOLLOW_UP_JOB_TYPE);
+    }
+    for (const jobType of jobTypes) {
       try {
         followUpJobIds.push(enqueueMemoryJob(jobType, {}));
       } catch (err) {
@@ -231,6 +261,56 @@ export async function memoryV2ConsolidateJob(
   }
 }
 
+/**
+ * When a v3 flag is enabled and the v3 tree has actionable structural drift,
+ * prepend a rendered health block to `basePrompt` so the consolidation run can
+ * fold tree maintenance into its pass. Returns `basePrompt` UNCHANGED when:
+ *   - neither `memory-v3-shadow` nor `memory-v3-live` is enabled,
+ *   - the health report is all-green (`renderV3Health` returns ""), or
+ *   - computing the report throws for any reason.
+ *
+ * The block is computed here (not baked into the prompt template) so an
+ * operator's custom consolidation prompt stays untouched and the block reflects
+ * the tree state at run time. Health computation is wrapped so a load/compute
+ * failure can never break consolidation — the run proceeds on the base prompt.
+ */
+async function maybePrependV3Health(
+  basePrompt: string,
+  config: AssistantConfig,
+): Promise<string> {
+  const v3Enabled =
+    isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
+    isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
+  if (!v3Enabled) return basePrompt;
+
+  try {
+    const pageIndex = await getPageIndex(getWorkspaceDir());
+    const pageLeaves = new Map<Slug, LeafPath[]>();
+    const allSlugs: Slug[] = [];
+    for (const entry of pageIndex.entries) {
+      pageLeaves.set(entry.slug, entry.leaves);
+      allSlugs.push(entry.slug);
+    }
+
+    const dataDir = resolveDataDir();
+    const [tree, core] = await Promise.all([
+      loadLeafTree(dataDir, pageLeaves),
+      loadCore(dataDir),
+    ]);
+
+    const report = computeV3Health({ tree, allSlugs, core });
+    const healthBlock = renderV3Health(report);
+    if (healthBlock.length === 0) return basePrompt;
+    return `${healthBlock}\n\n${basePrompt}`;
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "consolidation: v3 health computation failed; using base prompt",
+    );
+    return basePrompt;
+  }
+}
+
 /**
  * Read `memory/buffer.md`. Missing file → empty string so the skip-on-empty
  * branch doesn't have to distinguish "no file" from "blank file".

package/src/memory/v2/harness/metrics.ts

@@ -36,6 +36,10 @@ export interface AggregateEval {
 /**
  * recall@k = |topK(selected) ∩ G| / |G|. An empty ground-truth set is defined
  * as recall 1 (nothing to recall — vacuously complete).
+ *
+ * The top-k window is deduped before intersecting with the ground-truth set so
+ * a retriever that emits the same slug twice (e.g. `['a','a']`) cannot count it
+ * twice and push recall above 1.0. Recall is therefore bounded in [0, 1].
  */
 export function recallAtK(
   selected: readonly string[],
@@ -44,7 +48,7 @@ export function recallAtK(
 ): number {
   if (groundTruth.size === 0) return 1;
   let hit = 0;
-  for (const slug of selected.slice(0, k)) {
+  for (const slug of new Set(selected.slice(0, k))) {
     if (groundTruth.has(slug)) hit++;
   }
   return hit / groundTruth.size;