@vellumai/assistant 0.8.5 → 0.8.6

package/src/memory/v3/index-composition.ts

@@ -35,6 +35,16 @@ import type { TreeNode } from "./types.js";
 /** Trailer label introducing a node's own routing hints. */
 const ROUTING_HINTS_LABEL = "Routing hints:";
 
+/**
+ * Flatten a summary to a single line. The index is parsed by the descender as
+ * one child per line, so any embedded newline (or other whitespace run) in a
+ * summary would corrupt that format — collapse every whitespace run to a single
+ * space and trim the ends.
+ */
+function collapseToSingleLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
 /**
  * Resolve a node's display summary: its frontmatter `summary` if non-empty,
  * otherwise the first non-empty line of its body, otherwise the empty string.
@@ -54,9 +64,11 @@ function nodeSummary(node: TreeNode): string {
  * Render one child ref into its index line, or `null` when the ref's target is
  * absent from the supplied indices (validation owns reporting those).
  *
- * A resolvable `node:` child always yields a line — its header (`[node:<id>]`)
- * with a trailing summary when one exists. A `page:` child yields
- * `[page:<slug>] <summary>`; the v2 page index already truncates `summary`.
+ * A resolvable child always yields a line — its header (`[node:<id>]` /
+ * `[page:<slug>]`) with a trailing summary when one exists. Each summary is
+ * collapsed to a single line so an embedded newline can't break the one-child-
+ * per-line format the descender parses; the v2 page index already truncates
+ * `page:` summaries.
  */
 function renderChild(
   kind: "page" | "node",
@@ -67,12 +79,13 @@ function renderChild(
   if (kind === "node") {
     const child = tree.nodes.get(ref);
     if (!child) return null;
-    const summary = nodeSummary(child);
+    const summary = collapseToSingleLine(nodeSummary(child));
     return summary ? `[node:${ref}] ${summary}` : `[node:${ref}]`;
   }
   const entry = pages.bySlug.get(ref);
   if (!entry) return null;
-  return `[page:${ref}] ${entry.summary}`;
+  const summary = collapseToSingleLine(entry.summary);
+  return summary ? `[page:${ref}] ${summary}` : `[page:${ref}]`;
 }
 
 /**

package/src/memory/v3/loop.ts

@@ -36,12 +36,14 @@
  * {@link runScouts}. Toggling a lane off removes its contribution from the
  * candidate set so the offline harness can measure each lane's marginal recall.
  *
- * Cross-pass accumulation. A `visited` candidate accumulator deduplicates slugs
- * across passes by canonical slug, tagging each with the first lane that
- * surfaced it (`sourceBySlug`). The full {@link DescentTrace} carries one
- * {@link DescentPass} per pass (scouts / treeLevels / edgeExpansions / gate),
- * and {@link RetrievalCost} (wall-clock `ms`, the one dimension observable at
- * this composition layer) accumulates across every pass.
+ * Cross-pass accumulation. The `candidates` pool is unioned across every pass
+ * and the gate judges that cumulative pool, so a multi-pass `more` never drops
+ * the non-sticky hits earlier passes surfaced. Each slug is tagged with the
+ * most trusted lane that surfaced it (`sourceBySlug`). The full
+ * {@link DescentTrace}
+ * carries one {@link DescentPass} per pass (scouts / treeLevels /
+ * edgeExpansions / gate), and {@link RetrievalCost} (wall-clock `ms`, the one
+ * dimension observable at this composition layer) accumulates across every pass.
  */
 
 import { getLogger } from "../../util/logger.js";
@@ -57,6 +59,7 @@ import type {
   GateDecision,
 } from "../v2/harness/trace.js";
 import { getPageIndex } from "../v2/page-index.js";
+import { aboveThreshold } from "./auto-edges.js";
 import {
   type CoactivationRow,
   recordCoactivations,
@@ -111,8 +114,22 @@ export async function runRetrievalLoop(
   const passCap = Math.max(1, v3.passCap);
   const lanes = v3.lanes;
 
+  // Learned co-retrieval adjacency (memory_v3_auto_edges), read once and merged
+  // into the edge lane's curated graph when the threshold is set. At threshold 0
+  // (the default) this is undefined and edge behavior is identical to before.
+  const learnedAdjacencyThreshold = v3.edges?.learnedAdjacencyThreshold ?? 0;
+  const learnedAdjacency =
+    learnedAdjacencyThreshold > 0
+      ? aboveThreshold(deps.db, learnedAdjacencyThreshold)
+      : undefined;
+
   // Cross-pass accumulators.
   const sourceBySlug = new Map<string, LaneSource>();
+  // Candidate pool unioned across every pass. Each pass adds its own surfaced
+  // slugs (hot/sparse, dense-filter survivors, tree, edge) and the gate judges
+  // the cumulative pool, so a multi-pass `more` never discards earlier passes'
+  // non-sticky hits.
+  const candidates = new Set<string>();
   // The first pass each slug entered the candidate set. Drives co-activation
   // emission below — pass-1 hits (gap source) vs. later-surfaced pages (target).
   const firstPassBySlug = new Map<string, number>();
@@ -148,18 +165,19 @@ export async function runRetrievalLoop(
     const scoutResult = await runScouts(passInput, { db: deps.db });
     for (const slug of scoutResult.sticky) sticky.add(slug);
 
-    // Tag hot + sparse scout hits with their lane (first lane wins). Dense
-    // slugs are tagged only if they survive the filter below — a dropped dense
-    // near-neighbor never enters the candidate set, so it earns no source tag.
+    // Tag hot + sparse scout hits with their lane (most trusted lane wins —
+    // see tagSlug). Dense slugs are tagged only if they survive the filter
+    // below — a dropped dense near-neighbor never enters the candidate set, so
+    // it earns no source tag.
     for (const scout of scoutResult.scouts) {
       if (scout.lane === "dense") continue;
       for (const slug of scout.slugs) tagSlug(sourceBySlug, slug, scout.lane);
     }
 
-    // 2. Dense filter — judges only the dense lane (hot/sparse bypass it). The
-    // surviving dense slugs replace the raw dense candidates in the running set.
+    // 2. Dense filter — judges only the dense lane (hot/sparse bypass it). Only
+    // the surviving dense slugs enter the candidate pool; a dropped dense
+    // near-neighbor never joins it (and so never reaches the gate).
     const denseScout = scoutResult.scouts.find((s) => s.lane === "dense");
-    const candidates = new Set<string>();
 
     // Hot + sparse lane hits enter the candidate set directly.
     for (const scout of scoutResult.scouts) {
@@ -218,6 +236,11 @@ export async function runRetrievalLoop(
         // hot) so the seed cap spends its budget on query-relevant seeds, not
         // recency. `sourceBySlug` holds each candidate's first-seen lane.
         laneBySlug: sourceBySlug,
+        // Merge the learned co-retrieval graph with the curated edges when
+        // enabled (undefined = curated-only, the default).
+        ...(learnedAdjacency ? { extraAdjacency: learnedAdjacency } : {}),
+        // Cap the lane's contribution to the gate pool (default 400).
+        maxTotalPulls: v3.edges?.maxPulls,
       });
       edgeExpansions = expansion.expansions;
       for (const slug of expansion.pulled) {
@@ -354,17 +377,42 @@ function emitCoactivations(args: {
 }
 
 /**
- * Tag `slug`'s provenance with `lane`, keeping the first lane that surfaced it.
- * The pass order (scouts → tree → edge) gives a deterministic precedence: a
- * slug first seen by a scout lane keeps that label even when the tree or edge
- * lane re-surfaces it.
+ * Lane-trust order for `sourceBySlug` provenance (lower = more trusted). A slug
+ * surfaced by several lanes is tagged with the most trusted one. Mirrors
+ * `SEED_LANE_RANK` in {@link expandEdges}'s module, the downstream consumer that
+ * ranks seeds by this tag before the candidate cap: LLM-vetted tree/dense seeds
+ * rank above lexical sparse, recency-only hot, and associative edge pulls.
+ * Keeping the two orders aligned ensures the upgrade picks the lane the cap
+ * actually trusts. Any lane absent here (or an edge pull) ranks last.
+ */
+const LANE_TRUST_RANK: Readonly<Record<LaneSource, number>> = {
+  tree: 0,
+  dense: 1,
+  sparse: 2,
+  hot: 3,
+  edge: 4,
+};
+
+/**
+ * Tag `slug`'s provenance with `lane`, upgrading to the most trusted lane that
+ * surfaces it (see {@link LANE_TRUST_RANK}). A slug first seen via a low-trust
+ * lane (e.g. `edge`) is relabeled when a higher-trust lane (e.g. `dense`) also
+ * surfaces it, so the downstream seed cap ranks it by its strongest signal
+ * rather than a stale first-seen lane. Pass provenance (`firstPassBySlug`) is
+ * tracked separately and keeps earliest-pass semantics — only the lane upgrades.
  */
 function tagSlug(
   sourceBySlug: Map<string, LaneSource>,
   slug: string,
   lane: LaneSource,
 ): void {
-  if (!sourceBySlug.has(slug)) sourceBySlug.set(slug, lane);
+  const current = sourceBySlug.get(slug);
+  if (
+    current === undefined ||
+    LANE_TRUST_RANK[lane] < LANE_TRUST_RANK[current]
+  ) {
+    sourceBySlug.set(slug, lane);
+  }
 }
 
 /**

package/src/memory/v3/scouts.ts

@@ -361,11 +361,22 @@ function applyQuotaAndMmr(
 function mmrReorder(pool: readonly ScoredSlug[], lambda: number): ScoredSlug[] {
   if (pool.length <= 1) return [...pool];
 
-  // Normalize relevance to [0, 1] by the pool max so it shares a scale with the
-  // redundancy term (also [0, 1]). All-zero scores collapse to pure diversity.
+  // Normalize relevance to [0, 1] so it shares a scale with the redundancy term
+  // (also [0, 1]). The pool is score-descending, so `pool[0]` is the max and the
+  // last entry is the min. When the max is positive we divide by it — the
+  // healthy case, kept exactly as-is. When every cosine is <= 0 (all candidates
+  // weakly/negatively similar) dividing by the max would collapse relevance to a
+  // single value and degrade ranking to diversity-only; instead normalize from
+  // the observed min..max range so the relevance ordering is preserved. A
+  // zero-width range (all scores equal) has no gradient to preserve, so it
+  // collapses to pure diversity.
   const maxScore = pool[0].score;
-  const relevance = (hit: ScoredSlug): number =>
-    maxScore > 0 ? hit.score / maxScore : 0;
+  const minScore = pool[pool.length - 1].score;
+  const range = maxScore - minScore;
+  const relevance = (hit: ScoredSlug): number => {
+    if (maxScore > 0) return hit.score / maxScore;
+    return range > 0 ? (hit.score - minScore) / range : 0;
+  };
 
   const remaining = [...pool];
   const selected: ScoredSlug[] = [];

package/src/memory/v3/shadow-diff.ts

@@ -0,0 +1,287 @@
+/**
+ * Memory v3 shadow-diff — compare the v3 shadow selection against the live v2
+ * router selection, turn-for-turn, from the `memory_v2_activation_logs` table.
+ *
+ * When v3 runs in shadow mode it logs its per-turn selection as a `v3_shadow`
+ * row while the live v2 router logs its own selection as a `router` row on the
+ * same turn. This module pairs the two and reports where they agree, what v3
+ * surfaced that v2 did not, and what v2 had that v3 dropped — broken down by the
+ * v3 provenance lane so a shadow run is analyzable by where its recall comes
+ * from.
+ *
+ * Pairing is by timestamp, NOT by the `turn` column: the shadow middleware logs
+ * the orchestrator's per-runtime turn counter while v2 logs the cumulative
+ * conversation turn, so the two numbers diverge. The shadow row and its sibling
+ * router row are written within the same turn (a second or two apart), so each
+ * shadow row is matched to the nearest router row in the same conversation
+ * within a tolerance window.
+ *
+ * The v2 comparand is the router's FRESH per-turn pick (`status: "injected"`),
+ * not its full in-context set. v2 accumulates pages across turns (`in_context`
+ * carry-over can reach the hundreds on a long conversation) whereas v3 selects
+ * fresh each turn; comparing fresh-against-fresh keeps the diff meaningful. The
+ * carried-over count is surfaced per turn as context, not folded into the sets.
+ *
+ * Pure and DB-free: the route handler reads the rows and hands them here.
+ */
+
+import type { MemoryV2ConceptRowRecord } from "../memory-v2-activation-log-store.js";
+
+/** An activation-log row reduced to what the diff needs. */
+export interface ShadowDiffLogRow {
+  conversationId: string;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  concepts: MemoryV2ConceptRowRecord[];
+}
+
+/** One paired (v2 router ↔ v3 shadow) turn. */
+export interface ShadowDiffTurn {
+  conversationId: string;
+  /** Epoch ms of the v3 shadow row. */
+  shadowAt: number;
+  /** Epoch ms of the paired v2 router row. */
+  routerAt: number;
+  /** `routerAt - shadowAt`; small (within tolerance) by construction. */
+  deltaMs: number;
+  /** Size of the v2 fresh pick (`status: "injected"`). */
+  v2Count: number;
+  /** Size of the v3 shadow selection. */
+  v3Count: number;
+  /** v2 pages carried over from prior turns (`in_context`); annotation only. */
+  v2CachedCount: number;
+  /** `|overlap| / |v2 ∪ v3|`; 0 when both sets are empty. */
+  jaccard: number;
+  /** Slugs both systems picked, sorted. */
+  overlap: string[];
+  /** Slugs v3 surfaced but v2 did not freshly inject, sorted. */
+  v3Only: string[];
+  /** Slugs v2 freshly injected but v3 missed, sorted. */
+  v2Only: string[];
+  /** Provenance lane for each v3 slug (overlap + v3-only). */
+  laneBySlug: Record<string, string>;
+}
+
+/** A shadow row with no router row inside the tolerance window. */
+export interface UnpairedShadowTurn {
+  conversationId: string;
+  shadowAt: number;
+  v3Count: number;
+}
+
+/** A slug with how many paired turns it appeared in. */
+export interface SlugFrequency {
+  slug: string;
+  count: number;
+}
+
+export interface ShadowDiffResult {
+  /** Pairing tolerance actually used (ms). */
+  toleranceMs: number;
+  /** Total v3 shadow rows in the read window. */
+  shadowRows: number;
+  /** Shadow rows that paired to a router row. */
+  turnsCompared: number;
+  /** Shadow rows that did not pair. */
+  unpaired: UnpairedShadowTurn[];
+  agg: {
+    meanV2: number;
+    meanV3: number;
+    meanOverlap: number;
+    meanJaccard: number;
+    totalOverlap: number;
+    totalV3Only: number;
+    totalV2Only: number;
+    /** v3-only slug count by the lane that surfaced it — v3's extra reach. */
+    v3OnlyByLane: Record<string, number>;
+    /** overlap slug count by the v3 lane that recovered v2's pick. */
+    overlapByLane: Record<string, number>;
+    /** Most frequently dropped v2 pages (recall-regression watchlist). */
+    v2OnlyTop: SlugFrequency[];
+    /** Most frequent v3 extras (associative reach beyond v2). */
+    v3OnlyTop: SlugFrequency[];
+  };
+  /** Per-turn detail, newest first, capped at the requested limit. */
+  turns: ShadowDiffTurn[];
+}
+
+/** Status on a v2 router row that counts as a fresh per-turn selection. */
+const V2_PICKED_STATUS = "injected";
+/** Status on a v2 router row that means carried-over from a prior turn. */
+const V2_CACHED_STATUS = "in_context";
+/** How many slugs to list in the top-frequency aggregates. */
+const TOP_FREQUENCY_LIMIT = 15;
+
+function selectedV2Slugs(concepts: MemoryV2ConceptRowRecord[]): Set<string> {
+  const slugs = new Set<string>();
+  for (const c of concepts) {
+    if (c.status === V2_PICKED_STATUS) slugs.add(c.slug);
+  }
+  return slugs;
+}
+
+function cachedV2Count(concepts: MemoryV2ConceptRowRecord[]): number {
+  let n = 0;
+  for (const c of concepts) {
+    if (c.status === V2_CACHED_STATUS) n += 1;
+  }
+  return n;
+}
+
+function v3LaneBySlug(
+  concepts: MemoryV2ConceptRowRecord[],
+): Map<string, string> {
+  const bySlug = new Map<string, string>();
+  for (const c of concepts) {
+    bySlug.set(c.slug, c.lane ?? "unknown");
+  }
+  return bySlug;
+}
+
+/** Increment a string-keyed tally in place. */
+function bump(tally: Record<string, number>, key: string): void {
+  tally[key] = (tally[key] ?? 0) + 1;
+}
+
+/** Sort a frequency map into the top-N slugs, ties broken by slug name. */
+function topSlugs(freq: Map<string, number>, limit: number): SlugFrequency[] {
+  return [...freq.entries()]
+    .map(([slug, count]) => ({ slug, count }))
+    .sort((a, b) => b.count - a.count || a.slug.localeCompare(b.slug))
+    .slice(0, limit);
+}
+
+/**
+ * Pair each shadow row to the nearest unconsumed router row in the same
+ * conversation within `toleranceMs`, then diff the two selections. Pairing is
+ * greedy by absolute time delta; since real turns are minutes apart while a
+ * shadow/router sibling pair lands a second or two apart, the greedy match is a
+ * clean bijection in practice.
+ */
+export function computeShadowDiff(
+  shadow: readonly ShadowDiffLogRow[],
+  router: readonly ShadowDiffLogRow[],
+  opts: { toleranceMs: number; detailLimit: number },
+): ShadowDiffResult {
+  const { toleranceMs, detailLimit } = opts;
+
+  // Index router rows by conversation, time-sorted, with a consumed flag so a
+  // router row pairs to at most one shadow row.
+  const routerByConv = new Map<
+    string,
+    Array<{ row: ShadowDiffLogRow; consumed: boolean }>
+  >();
+  for (const row of router) {
+    const bucket = routerByConv.get(row.conversationId) ?? [];
+    bucket.push({ row, consumed: false });
+    routerByConv.set(row.conversationId, bucket);
+  }
+  for (const bucket of routerByConv.values()) {
+    bucket.sort((a, b) => a.row.createdAt - b.row.createdAt);
+  }
+
+  const sortedShadow = [...shadow].sort((a, b) => a.createdAt - b.createdAt);
+
+  const turns: ShadowDiffTurn[] = [];
+  const unpaired: UnpairedShadowTurn[] = [];
+  const v3OnlyByLane: Record<string, number> = {};
+  const overlapByLane: Record<string, number> = {};
+  const v2OnlyFreq = new Map<string, number>();
+  const v3OnlyFreq = new Map<string, number>();
+
+  for (const sh of sortedShadow) {
+    const bucket = routerByConv.get(sh.conversationId);
+    let best: { row: ShadowDiffLogRow; consumed: boolean } | undefined;
+    let bestDelta = Number.POSITIVE_INFINITY;
+    for (const candidate of bucket ?? []) {
+      if (candidate.consumed) continue;
+      const delta = Math.abs(candidate.row.createdAt - sh.createdAt);
+      if (delta < bestDelta) {
+        bestDelta = delta;
+        best = candidate;
+      }
+    }
+
+    if (!best || bestDelta > toleranceMs) {
+      unpaired.push({
+        conversationId: sh.conversationId,
+        shadowAt: sh.createdAt,
+        v3Count: new Set(sh.concepts.map((c) => c.slug)).size,
+      });
+      continue;
+    }
+    best.consumed = true;
+
+    const v2Set = selectedV2Slugs(best.row.concepts);
+    const laneBySlug = v3LaneBySlug(sh.concepts);
+    const v3Set = new Set(laneBySlug.keys());
+
+    const overlap: string[] = [];
+    const v3Only: string[] = [];
+    for (const slug of v3Set) {
+      if (v2Set.has(slug)) {
+        overlap.push(slug);
+        bump(overlapByLane, laneBySlug.get(slug)!);
+      } else {
+        v3Only.push(slug);
+        bump(v3OnlyByLane, laneBySlug.get(slug)!);
+        v3OnlyFreq.set(slug, (v3OnlyFreq.get(slug) ?? 0) + 1);
+      }
+    }
+    const v2Only: string[] = [];
+    for (const slug of v2Set) {
+      if (!v3Set.has(slug)) {
+        v2Only.push(slug);
+        v2OnlyFreq.set(slug, (v2OnlyFreq.get(slug) ?? 0) + 1);
+      }
+    }
+
+    const unionSize = new Set([...v2Set, ...v3Set]).size;
+    turns.push({
+      conversationId: sh.conversationId,
+      shadowAt: sh.createdAt,
+      routerAt: best.row.createdAt,
+      deltaMs: best.row.createdAt - sh.createdAt,
+      v2Count: v2Set.size,
+      v3Count: v3Set.size,
+      v2CachedCount: cachedV2Count(best.row.concepts),
+      jaccard: unionSize === 0 ? 0 : overlap.length / unionSize,
+      overlap: overlap.sort(),
+      v3Only: v3Only.sort(),
+      v2Only: v2Only.sort(),
+      laneBySlug: Object.fromEntries(laneBySlug),
+    });
+  }
+
+  const n = turns.length;
+  const sum = (pick: (t: ShadowDiffTurn) => number): number =>
+    turns.reduce((acc, t) => acc + pick(t), 0);
+  const mean = (pick: (t: ShadowDiffTurn) => number): number =>
+    n === 0 ? 0 : sum(pick) / n;
+
+  // Newest-first for the detail listing; aggregates are order-independent.
+  const detail = [...turns]
+    .sort((a, b) => b.shadowAt - a.shadowAt)
+    .slice(0, detailLimit);
+
+  return {
+    toleranceMs,
+    shadowRows: shadow.length,
+    turnsCompared: n,
+    unpaired,
+    agg: {
+      meanV2: mean((t) => t.v2Count),
+      meanV3: mean((t) => t.v3Count),
+      meanOverlap: mean((t) => t.overlap.length),
+      meanJaccard: mean((t) => t.jaccard),
+      totalOverlap: sum((t) => t.overlap.length),
+      totalV3Only: sum((t) => t.v3Only.length),
+      totalV2Only: sum((t) => t.v2Only.length),
+      v3OnlyByLane,
+      overlapByLane,
+      v2OnlyTop: topSlugs(v2OnlyFreq, TOP_FREQUENCY_LIMIT),
+      v3OnlyTop: topSlugs(v3OnlyFreq, TOP_FREQUENCY_LIMIT),
+    },
+    turns: detail,
+  };
+}

package/src/memory/v3/shadow-middleware.ts

@@ -34,6 +34,7 @@ import {
   PluginExecutionError,
 } from "../../plugins/types.js";
 import type { ContentBlock } from "../../providers/types.js";
+import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import type { DrizzleDb } from "../db-connection.js";
@@ -151,10 +152,13 @@ const SHADOW_CONFIG_SNAPSHOT: MemoryV2ConfigSnapshot = {
  * becomes a zeroed concept row tagged `source: "router"` and
  * `status: "injected"` — the shadow has no activation scores to record, and the
  * `mode='v3_shadow'` row tag (not the concept source) is what distinguishes
- * shadow telemetry from live router selections.
+ * shadow telemetry from live router selections. Each row also carries the
+ * `lane` that surfaced the slug (from `sourceBySlug`) so a shadow run can be
+ * analyzed by provenance.
  */
 function buildShadowConceptRows(
   selectedSlugs: readonly string[],
+  sourceBySlug: ReadonlyMap<string, string>,
 ): MemoryV2ConceptRowRecord[] {
   return selectedSlugs.map((slug) => ({
     slug,
@@ -170,6 +174,7 @@ function buildShadowConceptRows(
     spreadContribution: 0,
     source: "router",
     status: "injected",
+    ...(sourceBySlug.get(slug) ? { lane: sourceBySlug.get(slug) } : {}),
   }));
 }
 
@@ -232,11 +237,37 @@ async function runShadowAndLog(
 
     if (signal.aborted) return;
 
+    // Per-turn summary so a shadow run is analyzable from the logs — the pool
+    // shape, how many passes ran, and the gate's verdict + rationale. The
+    // selection set + per-slug lane land in the activation log below.
+    const passes = output.trace?.passes ?? [];
+    const lastGate = passes[passes.length - 1]?.gate;
+    const laneTally: Record<string, number> = {};
+    for (const lane of output.sourceBySlug.values()) {
+      laneTally[lane] = (laneTally[lane] ?? 0) + 1;
+    }
+    log.info(
+      {
+        conversationId: args.conversationId,
+        turn: args.turnIndex,
+        selected: output.selectedSlugs.length,
+        poolSize: output.sourceBySlug.size,
+        laneTally,
+        passes: passes.length,
+        gateDecision: lastGate?.decision,
+        gateReasoning: lastGate?.reasoning,
+      },
+      "v3 shadow selection",
+    );
+
     recordMemoryV2ActivationLog({
       conversationId: args.conversationId,
       turn: args.turnIndex,
       mode: "v3_shadow",
-      concepts: buildShadowConceptRows(output.selectedSlugs),
+      concepts: buildShadowConceptRows(
+        output.selectedSlugs,
+        output.sourceBySlug,
+      ),
       config: SHADOW_CONFIG_SNAPSHOT,
     });
   } catch (err) {
@@ -253,6 +284,11 @@ async function runShadowAndLog(
  * Flag-gated INSIDE the middleware (per-turn, live-toggle): when v3 shadow is
  * off it is a pure pass-through. When on, it fires the v3 loop detached and
  * returns the unchanged downstream (v2) result immediately.
+ *
+ * The shadow loop spends filter + gate LLM calls, so — like the other
+ * guardian-trust background memory loops (`enqueueAutoAnalysisOnCompaction`,
+ * `enqueueMemoryRetrospectiveOnCompaction`) — it is gated on actor trust: an
+ * untrusted turn passes through without kicking off the v3 loop.
  */
 export const memoryV3ShadowMiddleware: Middleware<MemoryArgs, MemoryResult> =
   async function memoryV3Shadow(args, next) {
@@ -262,6 +298,12 @@ export const memoryV3ShadowMiddleware: Middleware<MemoryArgs, MemoryResult> =
       return next(args);
     }
 
+    if (isUntrustedTrustClass(args.trustContext?.trustClass)) {
+      // Untrusted actor: don't spend shadow retrieval LLM calls — mirrors the
+      // live path's trust gate. Pure pass-through, no detached work.
+      return next(args);
+    }
+
     // Detached — never awaited on the path that returns the result, so the
     // shadow can neither block nor slow the live turn. Errors are swallowed
     // inside `runShadowAndLog`.

package/src/memory/v3/traversal.ts

@@ -165,13 +165,18 @@ export async function walkTree(
       const offeredRefs = new Set(offeredNodes.map((c) => c.ref));
 
       // Honor the descend pick in the order it was returned, dedup'd, filtered
-      // to genuinely-offered node children, and capped by `breadthBudget`.
+      // to genuinely-offered node children, skipping nodes already visited
+      // elsewhere in the DAG, and capped by `breadthBudget`. Filtering visited
+      // nodes *before* the budget check ensures the budget is spent only on
+      // nodes the walk will actually descend — an already-visited pick must not
+      // consume a slot that an unvisited sibling could use.
       const descended: string[] = [];
       const descendedSet = new Set<string>();
       for (const choice of result.descend) {
         if (choice.kind !== "node") continue;
         if (!offeredRefs.has(choice.ref)) continue;
         if (descendedSet.has(choice.ref)) continue;
+        if (visited.has(nodeKey(choice.ref))) continue;
         if (descended.length >= breadthBudget) break;
         descendedSet.add(choice.ref);
         descended.push(choice.ref);

package/src/memory/v3/tree-walk.ts

@@ -320,8 +320,13 @@ export function createDescender(args: CreateDescenderArgs): DescendDecision {
       parsed.data.descend,
       new Map(offeredNodes.map((c) => [c.ref, c])),
     );
+    // Recall-safe fallback: an *omitted* `keep_pages` means the model gave no
+    // instruction at this node, so keep every offered page — dropping all pages
+    // a node presented on a silent omission is the worse failure. An *explicit*
+    // `[]` is the model genuinely keeping nothing here and is honored as-is.
+    const keepSlugs = parsed.data.keep_pages ?? offeredPageSlugs;
     const keep = resolveOffered(
-      parsed.data.keep_pages ?? [],
+      keepSlugs,
       new Map(offeredPages.map((c) => [c.ref, c])),
     );
     return { descend, keep, reasoning: parsed.data.reasoning ?? "" };