@vellumai/assistant 0.8.5 → 0.8.6

package/src/memory/v3/coretrieval-seed.ts

@@ -0,0 +1,240 @@
+/**
+ * Memory v3 — co-retrieval edge seeding.
+ *
+ * Warm-starts the learned association graph (`memory_v3_auto_edges`, migration
+ * 263) from the v2 router's selection history. The live edge-learning job
+ * (`edge-learning-job.ts`) only accrues edges from v3's own retrievals, which is
+ * cold until v3 has run for a long time; the v2 router has thousands of turns of
+ * co-selection data already. Seeding projects that history into the same table
+ * the `aboveThreshold` read path already consumes, so the edge-expansion lane
+ * can merge it (via `expandEdges`'s `extraAdjacency` seam) the moment it's wired.
+ *
+ * Signal: two pages that the router *selected together* on a turn are associated.
+ * Scoring is **NPMI** (normalized pointwise mutual information), not raw
+ * co-occurrence — NPMI discounts high-frequency pages, so an always-injected page
+ * doesn't edge to everything it merely co-occurs with. A min co-occurrence floor
+ * drops noise, and an "always-on" frequency ceiling drops pages selected on a
+ * large fraction of all turns (heartbeat/now-md-style infrastructure) that carry
+ * no associative signal.
+ *
+ * `buildCoretrievalGraph` is pure (no I/O) so it is unit-testable; the
+ * `seedCoretrievalEdges` driver reads the rows and writes the table.
+ */
+
+import { getLogger } from "../../util/logger.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const log = getLogger("memory-v3-coretrieval-seed");
+
+/** A pair must co-occur on at least this many turns to earn an edge. */
+export const DEFAULT_MIN_COUNT = 5;
+/**
+ * A candidate *neighbor* selected on more than this fraction of all turns is
+ * "always-on" infrastructure (co-occurs with everything) and is excluded — it
+ * carries no associative signal, only base-rate noise.
+ */
+export const DEFAULT_MAX_NEIGHBOR_FREQ_RATIO = 0.4;
+/** Neighbors kept per source node, ranked by NPMI descending. */
+export const DEFAULT_TOP_K = 20;
+/**
+ * Weight of a perfect-association (NPMI = 1) edge. Each edge is persisted at
+ * `seedWeight × its NPMI score`, so the read threshold
+ * (`memory.v3.edges.learnedAdjacencyThreshold`) acts as a minimum-association
+ * cutoff: with the default 2.0, threshold 1.0 ≈ NPMI ≥ 0.5 and 1.2 ≈ NPMI ≥ 0.6.
+ */
+export const DEFAULT_SEED_WEIGHT = 2.0;
+
+/** Tuning knobs for {@link buildCoretrievalGraph}. */
+export interface CoretrievalGraphOptions {
+  minCount: number;
+  maxNeighborFreqRatio: number;
+  topK: number;
+}
+
+/** Driver knobs: graph tuning plus the persisted seed weight. */
+export interface SeedCoretrievalOptions extends CoretrievalGraphOptions {
+  seedWeight: number;
+}
+
+export const DEFAULT_SEED_OPTIONS: SeedCoretrievalOptions = {
+  minCount: DEFAULT_MIN_COUNT,
+  maxNeighborFreqRatio: DEFAULT_MAX_NEIGHBOR_FREQ_RATIO,
+  topK: DEFAULT_TOP_K,
+  seedWeight: DEFAULT_SEED_WEIGHT,
+};
+
+/** One scored outgoing edge. */
+export interface ScoredEdge {
+  target: string;
+  score: number;
+}
+
+/** Summary of one seeding run, for the CLI/route report. */
+export interface SeedCoretrievalResult {
+  turnsScanned: number;
+  nodes: number;
+  edgesWritten: number;
+  avgDegree: number;
+}
+
+/**
+ * Build the co-retrieval adjacency from per-turn selected-slug sets.
+ *
+ * Pure: takes the already-extracted selection sets (one array per turn) and
+ * returns `source -> ScoredEdge[]` (top-K NPMI neighbors, heaviest first). Turns
+ * with fewer than two distinct slugs contribute no pairs and are ignored.
+ */
+export function buildCoretrievalGraph(
+  turns: ReadonlyArray<ReadonlyArray<string>>,
+  options: CoretrievalGraphOptions = DEFAULT_SEED_OPTIONS,
+): Map<string, ScoredEdge[]> {
+  const sets = turns.map((t) => [...new Set(t)]).filter((s) => s.length >= 2);
+  const n = sets.length;
+  const graph = new Map<string, ScoredEdge[]>();
+  if (n === 0) return graph;
+
+  const freq = new Map<string, number>();
+  const cooccur = new Map<string, Map<string, number>>();
+  const bump = (a: string, b: string) => {
+    let row = cooccur.get(a);
+    if (!row) cooccur.set(a, (row = new Map()));
+    row.set(b, (row.get(b) ?? 0) + 1);
+  };
+  for (const slugs of sets) {
+    for (const slug of slugs) freq.set(slug, (freq.get(slug) ?? 0) + 1);
+    for (let i = 0; i < slugs.length; i++) {
+      for (let j = i + 1; j < slugs.length; j++) {
+        bump(slugs[i], slugs[j]);
+        bump(slugs[j], slugs[i]);
+      }
+    }
+  }
+
+  const freqCap = options.maxNeighborFreqRatio * n;
+  for (const [source, neighbors] of cooccur) {
+    const fSource = freq.get(source)!;
+    const scored: ScoredEdge[] = [];
+    for (const [target, pairCount] of neighbors) {
+      if (pairCount < options.minCount) continue;
+      const fTarget = freq.get(target)!;
+      if (fTarget > freqCap) continue;
+      // NPMI = pmi / -ln(p(a,b)), in [-1, 1]. Higher = stronger association.
+      // p(a,b)=1 (the pair co-occurs on every turn) is perfect association — its
+      // NPMI limit is 1, but the formula is 0/0, so pin it to avoid NaN.
+      const pab = pairCount / n;
+      if (pab >= 1) {
+        scored.push({ target, score: 1 });
+        continue;
+      }
+      const pmi = Math.log(pab / ((fSource / n) * (fTarget / n)));
+      scored.push({ target, score: pmi / -Math.log(pab) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    if (scored.length > 0) graph.set(source, scored.slice(0, options.topK));
+  }
+  return graph;
+}
+
+/**
+ * Extract one selection set per v2 router turn from `memory_v2_activation_logs`.
+ * The set is the router's *fresh* per-turn pick (`status === 'injected'`), which
+ * is the co-selection signal we want — not the accumulated in-context carry-over.
+ *
+ * Best-effort: a missing table (db predates the activation log) or an unparseable
+ * row yields no turns rather than throwing — the caller degrades to "no seed".
+ */
+function readRouterSelections(database: DrizzleDb): string[][] {
+  const turns: string[][] = [];
+  try {
+    const raw = getSqliteFrom(database);
+    const rows = raw
+      .query(
+        `SELECT concepts_json FROM memory_v2_activation_logs WHERE mode = 'router'`,
+      )
+      .all() as Array<{ concepts_json: string }>;
+    for (const row of rows) {
+      let concepts: unknown;
+      try {
+        concepts = JSON.parse(row.concepts_json);
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(concepts)) continue;
+      const selected = new Set<string>();
+      for (const entry of concepts) {
+        if (
+          entry &&
+          typeof entry === "object" &&
+          (entry as { status?: unknown }).status === "injected" &&
+          typeof (entry as { slug?: unknown }).slug === "string"
+        ) {
+          selected.add((entry as { slug: string }).slug);
+        }
+      }
+      if (selected.size >= 2) turns.push([...selected]);
+    }
+  } catch (err) {
+    log.warn(
+      { err },
+      "failed to read router selections for seeding; continuing",
+    );
+  }
+  return turns;
+}
+
+/**
+ * Build the co-retrieval graph from the v2 router history and persist it into
+ * `memory_v3_auto_edges`, weighting each edge by its association strength:
+ * `weight = seedWeight × NPMI`. Edges whose weight is non-positive (NPMI ≤ 0 —
+ * not an association) are skipped. This makes the read threshold a real
+ * minimum-association cutoff rather than all-or-nothing.
+ *
+ * Idempotent: each edge is upserted by OVERWRITING its weight to the current
+ * NPMI-derived value (the seed baseline), so re-running is stable. Tradeoff: the
+ * overwrite resets any reinforcement the edge-learning job accrued between seeds.
+ * That is acceptable while the seed is the dominant signal and organic
+ * co-activation reinforcement is minimal; revisit if/when live reinforcement
+ * becomes load-bearing.
+ */
+export function seedCoretrievalEdges(
+  database: DrizzleDb,
+  options: SeedCoretrievalOptions = DEFAULT_SEED_OPTIONS,
+): SeedCoretrievalResult {
+  const turns = readRouterSelections(database);
+  const graph = buildCoretrievalGraph(turns, options);
+
+  const now = Date.now();
+  let edgesWritten = 0;
+  try {
+    const raw = getSqliteFrom(database);
+    const upsert = raw.prepare(
+      `INSERT INTO memory_v3_auto_edges
+         (source_slug, target_slug, weight, last_reinforced_at)
+         VALUES (?, ?, ?, ?)
+       ON CONFLICT(source_slug, target_slug) DO UPDATE SET
+         weight = excluded.weight,
+         last_reinforced_at = excluded.last_reinforced_at`,
+    );
+    const apply = raw.transaction(() => {
+      for (const [source, edges] of graph) {
+        for (const edge of edges) {
+          const weight = options.seedWeight * edge.score;
+          if (weight <= 0) continue;
+          upsert.run(source, edge.target, weight, now);
+          edgesWritten += 1;
+        }
+      }
+    });
+    apply();
+  } catch (err) {
+    log.warn({ err }, "failed to persist seeded co-retrieval edges");
+  }
+
+  return {
+    turnsScanned: turns.length,
+    nodes: graph.size,
+    edgesWritten,
+    avgDegree: graph.size > 0 ? edgesWritten / graph.size : 0,
+  };
+}

package/src/memory/v3/edges.ts

@@ -15,8 +15,9 @@
  * effective out-neighborhood of a node is `curated[node] ∪ extraAdjacency[node]`.
  *
  * The result is the union of every seed's reachable neighborhood (`pulled`,
- * with seeds themselves excluded) plus a per-seed `EdgeExpansion[]` trace so a
- * harness can attribute each pulled slug to the seed it came from.
+ * with the full seed set excluded — a seed reachable from another seed is still
+ * a seed, not a neighbor) plus a per-seed `EdgeExpansion[]` trace so a harness
+ * can attribute each pulled slug to the seed it came from.
  */
 
 import { getEdgeIndex, getReachable } from "../v2/edge-index.js";
@@ -61,10 +62,11 @@ const MAX_SEEDS_EXPANDED = 150;
 const MAX_PULLS_PER_SEED = 32;
 
 /**
- * Hard ceiling on the size of the unioned `pulled` set. This is the load-bearing
- * bound: it caps the lane's contribution to the gate's pool to a few hundred
- * slugs no matter how many seeds or how dense the graph. Once reached, no
- * further seeds are expanded.
+ * Default ceiling on the size of the unioned `pulled` set. This is the
+ * load-bearing bound: it caps the lane's contribution to the gate's pool no
+ * matter how many seeds or how dense the graph. Once reached, no further seeds
+ * are expanded. Overridable per call via {@link ExpandEdgesArgs.maxTotalPulls}
+ * (the loop wires it to `memory.v3.edges.maxPulls`).
  */
 const MAX_TOTAL_PULLS = 400;
 
@@ -119,6 +121,12 @@ export interface ExpandEdgesArgs {
    * above-threshold edges before passing them in.
    */
   extraAdjacency?: ReadonlyMap<string, ReadonlySet<string>>;
+  /**
+   * Hard ceiling on the unioned `pulled` set — the lane's contribution to the
+   * gate pool. Defaults to {@link MAX_TOTAL_PULLS} when omitted or not a finite
+   * number ≥ 0.
+   */
+  maxTotalPulls?: number;
 }
 
 export interface ExpandEdgesResult {
@@ -171,10 +179,11 @@ function reachableMerged(
  * Expand a set of confident seed slugs to their 1–2 hop curated neighborhood.
  *
  * Each expanded seed produces one `EdgeExpansion { from, pulled }` entry (sorted
- * slugs for deterministic output); the seed itself is never in its own `pulled`.
- * The top-level `pulled` set is the union across all expanded seeds — a slug
- * pulled by more than one seed appears once there but in each contributing
- * seed's expansion.
+ * slugs for deterministic output); no seed ever appears in `pulled` — not its
+ * own entry and not another seed's, even when one seed is a neighbor of another
+ * (the seeds-excluded contract). The top-level `pulled` set is the union across
+ * all expanded seeds — a slug pulled by more than one seed appears once there
+ * but in each contributing seed's expansion.
  *
  * Bounded by {@link MAX_SEEDS_EXPANDED}, {@link MAX_PULLS_PER_SEED}, and
  * {@link MAX_TOTAL_PULLS} so a large seed union or a dense graph can't balloon
@@ -197,6 +206,15 @@ export async function expandEdges(
     laneBySlug,
   } = args;
 
+  // Per-call override of the union ceiling, falling back to the default constant
+  // for an omitted or invalid (negative/NaN) value.
+  const maxTotal =
+    typeof args.maxTotalPulls === "number" &&
+    Number.isFinite(args.maxTotalPulls) &&
+    args.maxTotalPulls >= 0
+      ? args.maxTotalPulls
+      : MAX_TOTAL_PULLS;
+
   const index = await getEdgeIndex(workspaceDir);
   const pulled = new Set<string>();
   const expansions: EdgeExpansion[] = [];
@@ -213,7 +231,14 @@ export async function expandEdges(
     );
   }
 
-  // De-dupe seeds while preserving (ranked) order for a stable trace.
+  // De-dupe seeds while preserving (ranked) order for a stable trace. The full
+  // de-duped seed set is also the exclusion set: a seed reachable from another
+  // seed is itself a confident hit, not a neighbor, so it must never land in
+  // `pulled` (the seeds-excluded contract) — `getReachable` only excludes the
+  // walk's own start node, so a B reachable from A would otherwise leak in.
+  const seedSet = new Set<string>();
+  for (const seed of orderedSeeds) seedSet.add(seed);
+
   const seenSeeds = new Set<string>();
 
   for (const seed of orderedSeeds) {
@@ -223,7 +248,7 @@ export async function expandEdges(
     // Bound the number of seeds expanded, and stop once the union is full —
     // the remaining seeds would only inflate the gate's pool. Checked before
     // doing any per-seed work so an oversized seed set is cheap to truncate.
-    if (seenSeeds.size > MAX_SEEDS_EXPANDED || pulled.size >= MAX_TOTAL_PULLS) {
+    if (seenSeeds.size > MAX_SEEDS_EXPANDED || pulled.size >= maxTotal) {
       break;
     }
 
@@ -231,18 +256,30 @@ export async function expandEdges(
       ? reachableMerged(index.outgoing, extraAdjacency, seed, hops)
       : getReachable(index, seed, hops, "out");
 
-    // Per-seed fan-out cap, then trim to the union's remaining headroom so the
-    // total ceiling is hard (never overshot) and the trace entry lists exactly
-    // the slugs this seed contributed to the bounded union. Sorting first keeps
-    // truncation deterministic — a hub seed always yields the same slice. Slugs
-    // already pulled by an earlier seed don't consume headroom (the union Set
-    // de-dupes), so this is a conservative upper bound on what's admitted.
-    const remaining = MAX_TOTAL_PULLS - pulled.size;
+    // Drop any other seed from this seed's neighborhood (seeds-excluded
+    // contract) and split the rest into slugs already in the union vs. fresh
+    // ones. The per-seed fan-out cap and the union's remaining headroom apply
+    // only to fresh slugs, so a slot is never spent on a duplicate an earlier
+    // seed already pulled — at the cap that would silently drop a unique
+    // neighbor. Sorting first keeps truncation deterministic. The trace lists
+    // every reached slug that made it into the bounded union (fresh admissions
+    // plus the duplicates this seed also reaches), so it stays a faithful
+    // attribution while the budget is reserved for new recall.
+    const sorted = [...reachable].sort();
+    const alreadyPulled = sorted.filter(
+      (slug) => !seedSet.has(slug) && pulled.has(slug),
+    );
+    const fresh = sorted.filter(
+      (slug) => !seedSet.has(slug) && !pulled.has(slug),
+    );
+
+    const remaining = maxTotal - pulled.size;
     const perSeedCap = Math.min(MAX_PULLS_PER_SEED, remaining);
-    const seedPulled = [...reachable].sort().slice(0, perSeedCap);
+    const admitted = fresh.slice(0, perSeedCap);
+    for (const slug of admitted) pulled.add(slug);
 
+    const seedPulled = [...alreadyPulled, ...admitted].sort();
     expansions.push({ from: seed, pulled: seedPulled });
-    for (const slug of seedPulled) pulled.add(slug);
   }
 
   return { pulled, expansions };

package/src/memory/v3/filter.ts

@@ -12,20 +12,19 @@
  * corpus). Hot pages and near-exact sparse hits arrive via the scouts'
  * `sticky` / `bypass` sets and are **never judged**: a literal keyword hit or a
  * page the user has been touching is a strong enough signal that we shouldn't
- * make it earn its place through a fallible cheap judgment. They are unioned
- * straight into `kept`.
+ * make it earn its place through a fallible cheap judgment, and the downstream
+ * gate force-injects every sticky slug regardless — judging it could not change
+ * its fate. The `bypass` subset is additionally unioned straight into `kept`.
  *
  * Fail-open. If no provider is configured or the call errors / returns an
- * unusable response, the filter keeps *all* dense candidates and surfaces a
- * `failureReason` so the loop can record that the filter was bypassed. Dropping
- * candidates on a model outage would silently starve retrieval; keeping them is
- * the safe degradation (the downstream gate still narrows the slate).
+ * unusable response, the filter keeps *all* judged dense candidates and surfaces
+ * a `failureReason` so the loop can record that the filter was bypassed.
+ * Dropping candidates on a model outage would silently starve retrieval; keeping
+ * them is the safe degradation (the downstream gate still narrows the slate).
  *
- * No LLM call when there is nothing to judge. An empty dense set short-circuits
- * to `kept` = the bypass-relevant slugs (no judged additions), with no provider
- * round-trip.
- *
- * This module is currently unwired — a later PR composes it into the loop.
+ * No LLM call when there is nothing to judge. A dense set fully covered by
+ * sticky short-circuits to `kept` = the bypass-relevant slugs (no judged
+ * additions), with no provider round-trip.
  */
 
 import { z } from "zod";
@@ -58,10 +57,12 @@ const FILTER_TOOL_NAME = "filter_dense_hits";
  * Arguments to one filter invocation.
  *
  * `dense` is the bounded dense scout result; only its slugs that are *not*
- * already in `bypass` are judged. `sticky` is the broader keep-in-the-running
- * set (hot + near-exact sparse); `bypass` is the subset strong enough to skip
- * judgment entirely. Bypass slugs that also appear in the dense lane are kept
- * unconditionally and never sent to the model.
+ * already in `sticky` are judged. `sticky` is the keep-in-the-running set (hot +
+ * near-exact sparse) the downstream gate force-injects regardless of this
+ * filter, so judging a sticky page wastes an LLM call that can never change its
+ * fate. `bypass` is the subset of sticky strong enough to skip judgment that the
+ * filter also unions straight into `kept`. Sticky slugs that also appear in the
+ * dense lane are excluded from the judged set and never sent to the model.
  */
 export interface FilterDenseHitsArgs {
   input: RetrievalInput;
@@ -163,19 +164,23 @@ function buildResult(
  * Run the fast dense-hit filter for one pass.
  *
  * Makes at most one forced-tool LLM call over the *judged* set (dense slugs not
- * already in `bypass`). Bypass slugs are kept unconditionally. On an empty
- * judged set no call is made. Any failure (no provider, provider throw, missing
- * tool_use, schema mismatch) fails open: every dense candidate is kept and a
+ * already in `sticky`). Sticky slugs are force-selected by the downstream gate
+ * regardless of this filter, so they are excluded from judgment; bypass slugs
+ * are additionally kept unconditionally here. On an empty judged set no call is
+ * made. Any failure (no provider, provider throw, missing tool_use, schema
+ * mismatch) fails open: every judged dense candidate is kept and a
  * `failureReason` is returned.
  */
 export async function filterDenseHits(
   args: FilterDenseHitsArgs,
 ): Promise<FilterDenseHitsResult> {
-  const { input, dense, bypass } = args;
+  const { input, dense, sticky, bypass } = args;
 
-  // Dense slugs that bypass judgment (near-exact sparse / hot) are kept as-is;
-  // only the remainder is judged.
-  const judged = dense.slugs.filter((slug) => !bypass.has(slug));
+  // Sticky slugs (hot + near-exact sparse) are force-selected by the gate
+  // regardless of this filter, so judging them wastes an LLM call that can't
+  // change their fate. Exclude the full sticky set (a superset of bypass) from
+  // the judged set; only the remaining dense near-neighbors are judged.
+  const judged = dense.slugs.filter((slug) => !sticky.has(slug));
 
   // Nothing to judge → no LLM call. Kept is just the bypass-relevant slugs.
   if (judged.length === 0) {

package/src/memory/v3/gate.ts

@@ -79,9 +79,9 @@ export interface RunGateArgs {
    * Per-candidate one-line summaries, keyed by slug. When present, candidates
    * are rendered to the model as `slug — summary` so the gate can judge
    * relevance on page content rather than the slug alone. Missing entries fall
-   * back to the bare slug; the forced tool's `selected_slugs` enum stays
-   * slug-only. The loop passes this only when `memory.v3.gateCandidateSummaries`
-   * is set.
+   * back to the bare slug; the model answers with the candidate's `[N]` number
+   * (`selected_ids`) regardless, so summaries never change the answer format. The
+   * loop passes this only when `memory.v3.gateCandidateSummaries` is set.
    */
   summaryBySlug?: ReadonlyMap<string, string>;
   /** Optional debug sink — emits one record for the gate's LLM call. */
@@ -102,17 +102,20 @@ export interface RunGateResult {
 }
 
 /**
- * Build the forced tool definition. `selected_slugs` is the ordered final
- * selection; `decision` is the ready/more verdict; `questions` carries the
- * generated follow-up queries on "more" (ignored on "ready"). Mirrors the
- * forced-tool pattern of v2's `select_pages_to_inject`.
+ * Build the forced tool definition. `selected_ids` is the list of bracketed
+ * `[N]` candidate numbers to keep; `decision` is the ready/more verdict;
+ * `questions` carries the generated follow-up queries on "more" (ignored on
+ * "ready"). The schema is candidate-independent — no per-turn enum — so it stays
+ * byte-identical across turns (cache-friendly) and the model answers with the
+ * line numbers rather than reproducing exact slug strings, mirroring the
+ * integer-id output of v2's `select_pages_to_inject`.
  */
-function buildGateTool(candidateSlugs: readonly string[]): ToolDefinition {
+function buildGateTool(): ToolDefinition {
   return {
     name: GATE_TOOL_NAME,
     description:
       "Decide whether the accumulated candidate pages are sufficient to answer " +
-      "the next turn. Return decision='ready' with the final ordered selection " +
+      "the next turn. Return decision='ready' with the final selection " +
       "when the candidates cover the turn; return decision='more' with one or " +
       "more generated follow-up questions (NOT the original message) to seed " +
       "another retrieval pass when coverage is incomplete.",
@@ -120,16 +123,14 @@ function buildGateTool(candidateSlugs: readonly string[]): ToolDefinition {
       type: "object",
       properties: {
         decision: { type: "string", enum: ["ready", "more"] },
-        selected_slugs: {
+        selected_ids: {
           type: "array",
-          items: { type: "string", enum: [...candidateSlugs] },
+          items: { type: "integer" },
           description:
-            "Final ordered page slugs to inject. Each candidate is listed as " +
-            "`slug — summary` when summaries are available; return only the slug " +
-            "(left of the em-dash), and only from the candidate set. Prefer keeping " +
-            "a plausibly-relevant page over dropping it; for a list / 'all of X' / " +
-            "breadth request, include every candidate that plausibly applies rather " +
-            "than trimming to the most prominent few.",
+            "The bracketed `[N]` numbers of the candidate pages to keep. Prefer " +
+            "keeping a plausibly-relevant page over dropping it; for a list / " +
+            "'all of X' / breadth request, include every candidate that plausibly " +
+            "applies rather than trimming to the most prominent few.",
         },
         questions: {
           type: "array",
@@ -144,32 +145,33 @@ function buildGateTool(candidateSlugs: readonly string[]): ToolDefinition {
             "candidates were kept or dropped.",
         },
       },
-      required: ["decision"],
+      required: ["decision", "selected_ids"],
     },
   };
 }
 
 const GateToolResultSchema = z.object({
   decision: z.enum(["ready", "more"]),
-  selected_slugs: z.array(z.string()).optional(),
+  selected_ids: z.array(z.coerce.number()).optional(),
   questions: z.array(z.string()).optional(),
   reasoning: z.string().optional(),
 });
 
 /**
- * Render the candidate list for the prompt. With summaries available each line
- * is `slug — summary` so the model can judge relevance on content; without them
- * it falls back to the bare slug. The slug (left of the em-dash) is what the
- * `selected_slugs` enum constrains, so the model always answers in slugs.
+ * Render the candidate list for the prompt. Each line is `[N] slug — summary`
+ * (or `[N] slug` without a summary), numbered from 1 in candidate order. The
+ * model answers with the `[N]` numbers via `selected_ids`, which the caller maps
+ * back to slugs by index — so the tool schema stays candidate-independent.
  */
 function renderCandidateLines(
   slugs: readonly string[],
   summaryBySlug: ReadonlyMap<string, string> | undefined,
 ): string {
   return slugs
-    .map((slug) => {
+    .map((slug, i) => {
       const summary = summaryBySlug?.get(slug);
-      return summary ? `${slug} — ${summary}` : slug;
+      const body = summary ? `${slug} — ${summary}` : slug;
+      return `[${i + 1}] ${body}`;
     })
     .join("\n");
 }
@@ -267,7 +269,7 @@ export async function runGate(args: RunGateArgs): Promise<RunGateResult> {
     ],
   };
 
-  const gateTool = buildGateTool(candidateSlugs);
+  const gateTool = buildGateTool();
 
   const startedAt = Date.now();
   let response;
@@ -310,25 +312,38 @@ export async function runGate(args: RunGateArgs): Promise<RunGateResult> {
     return failSafe(candidates, sticky);
   }
 
-  const selectedSlugs = orderSelection(
-    parsed.data.selected_slugs ?? [],
-    candidates,
-    sticky,
-  );
+  // Recall-safe fallback: an *omitted* `selected_ids` means the model gave no
+  // instruction, so keep everything that was surfaced — dropping all non-sticky
+  // context on a silent omission is the worse failure. An *explicit* `[]` is the
+  // model genuinely choosing nothing and is honored as-is. Ids are 1-based
+  // indices into the rendered candidate list; out-of-range ids are dropped.
+  const modelSlugs =
+    parsed.data.selected_ids === undefined
+      ? [...candidates]
+      : parsed.data.selected_ids
+          .map((id) => candidateSlugs[Math.trunc(id) - 1])
+          .filter((slug): slug is string => slug !== undefined);
+  const selectedSlugs = orderSelection(modelSlugs, candidates, sticky);
+
+  const reasoning = parsed.data.reasoning?.trim() || undefined;
 
   if (parsed.data.decision === "more") {
     const questions = (parsed.data.questions ?? []).filter(
       (q) => q.trim().length > 0,
     );
-    const decision: GateDecision =
-      questions.length > 0
-        ? { decision: "more", questions }
-        : { decision: "more" };
+    const decision: GateDecision = {
+      decision: "more",
+      ...(questions.length > 0 ? { questions } : {}),
+      ...(reasoning ? { reasoning } : {}),
+    };
     return { decision, selectedSlugs };
   }
 
   // brief generation lands at cutover (P5) — shadow mode injects v2, so this
   // gate produces only the selection + decision. Do NOT synthesize a voice
   // brief here.
-  return { decision: { decision: "ready" }, selectedSlugs };
+  return {
+    decision: { decision: "ready", ...(reasoning ? { reasoning } : {}) },
+    selectedSlugs,
+  };
 }