@yeaft/webchat-agent 1.0.349 → 1.0.350

package/yeaft/memory/ams-registry.js

@@ -1,10 +1,10 @@
 /**
- * memory/ams-registry.js — session-keyed AMS lifecycle.
+ * memory/ams-registry.js — Session + VP keyed AMS lifecycle.
  *
- * The Active Memory Set is conceptually session-scoped, with `sessionId`
- * as the unit. A deactivated session can be reactivated later and should
- * resume with the AMS state it had on disconnect (the onDemand segments
- * it had pulled in, the recent LRU touches, whether `adjust` already ran).
+ * A Session can run multiple VPs concurrently. Each VP needs an isolated
+ * prompt snapshot because `ownVpId` is part of the memory ACL. Historical
+ * onDemand/recent ids stay in the version-1 payload for disk compatibility,
+ * but prompt state is rebuilt from query-selected canonical content each turn.
  *
  * Persistence is identity-only:
  *
@@ -18,10 +18,8 @@
  *     "savedAt": "2026-04-29T..."
  *   }
  *
- * Bodies are NOT serialised — they're re-hydrated from the SegmentIndex
- * on load, so a body edited by Dream after save still surfaces correctly
- * the next time the session is opened. Resident layer is derived state
- * (rebuilt every turn from `<scope>/summary.md`) — never persisted.
+ * Bodies are never serialised. Resident is derived state rebuilt every turn
+ * from selected content.md files and is never persisted.
  *
  * For the single-VP Yeaft path (no session id supplied), the registry uses
  * the literal key `"default"` so there's still a stable home for AMS state.
@@ -47,11 +45,12 @@ export const DEFAULT_SESSION_KEY = 'default';
  * @typedef {object} AmsCacheEntry
  * @property {ActiveMemorySet} ams
  * @property {string|null}     ownVpId
+ * @property {string}          sessionKey
  * @property {boolean}         adjustRanThisSession
  */
 
 /**
- * Group-keyed in-memory cache + disk persistence for AMS instances.
+ * Session + VP keyed in-memory cache with Session-level disk compatibility.
  *
  * Lifecycle:
  *   - getOrCreate(sessionId, {ownVpId}) — returns the cached AMS or loads
@@ -75,7 +74,7 @@ export class AmsRegistry {
   }
 
   /**
-   * Resolve the on-disk path for a group's ams.json.
+   * Resolve the on-disk path for a Session's ams.json.
    *
    * `sessionId` is trusted: `nextSessionId()` (sessions/ids.js) emits ids matching
    * `grp_[a-z0-9_-]+_[0-9A-HJKMNP-TV-Z]{8}` (slug + 8-char crockford suffix),
@@ -103,7 +102,7 @@ export class AmsRegistry {
   }
 
   /**
-   * Get the AMS for a group, creating it on first access.
+   * Get the AMS for a Session, creating it on first access.
    * Loads persisted state from disk if any; on cold start returns an
    * empty AMS keyed to the supplied ownVpId.
    *
@@ -112,50 +111,55 @@ export class AmsRegistry {
    * @returns {ActiveMemorySet}
    */
   getOrCreate(sessionId, opts = {}) {
-    const key = sessionId || DEFAULT_SESSION_KEY;
+    const sessionKey = sessionId || DEFAULT_SESSION_KEY;
+    const ownVpId = opts.ownVpId || null;
+    const key = this._cacheKey(sessionKey, ownVpId);
     const cached = this._cache.get(key);
     if (cached) return cached.ams;
 
-    const ownVpId = opts.ownVpId || null;
     const budget = this._budget();
     const ams = new ActiveMemorySet({ ownVpId, budget });
-    const entry = { ams, ownVpId, adjustRanThisSession: false };
-    // Best-effort hydrate from disk — populates ams + entry flags.
-    this._hydrate(key, entry);
+    const entry = { ams, ownVpId, adjustRanThisSession: false, sessionKey };
+    // Best-effort hydrate Session-level compatibility metadata only.
+    this._hydrate(sessionKey, entry);
     this._cache.set(key, entry);
     return ams;
   }
 
+  _cacheKey(sessionId, ownVpId) {
+    return `${sessionId || DEFAULT_SESSION_KEY}\u0000${ownVpId || ''}`;
+  }
+
   /**
    * Read the persisted-and-rehydrated `adjustRanThisSession` flag for a
-   * group. Engine consults this on first AMS access so a reactivated group
-   * doesn't re-run `runAdjust` on its first turn back online.
+   * Session. Kept only for version-1 payload compatibility.
    *
    * @param {string|null|undefined} sessionId
    * @returns {boolean}
    */
   adjustRanThisSession(sessionId) {
-    const key = sessionId || DEFAULT_SESSION_KEY;
-    return this._cache.get(key)?.adjustRanThisSession === true;
+    const sessionKey = sessionId || DEFAULT_SESSION_KEY;
+    return [...this._cache.values()].some(entry => (
+      entry.sessionKey === sessionKey && entry.adjustRanThisSession === true
+    ));
   }
 
   /**
    * Update the cached `adjustRanThisSession` flag (does not persist on its
-   * own — call `persist()` to flush). Engine flips this true after
-   * `runAdjust` actually ran.
+   * own — call `persist()` to flush). Kept for old callers and payloads.
    *
    * @param {string|null|undefined} sessionId
    * @param {boolean} value
    */
   setAdjustRanThisSession(sessionId, value) {
-    const key = sessionId || DEFAULT_SESSION_KEY;
-    const entry = this._cache.get(key);
-    if (entry) entry.adjustRanThisSession = Boolean(value);
+    const sessionKey = sessionId || DEFAULT_SESSION_KEY;
+    for (const entry of this._cache.values()) {
+      if (entry.sessionKey === sessionKey) entry.adjustRanThisSession = Boolean(value);
+    }
   }
 
   /**
-   * Mark a group's AMS as dirty so the next persist() actually writes.
-   * The engine calls this after `runAdjust` mutates membership.
+   * Mark a Session's AMS metadata as dirty so the next persist() writes.
    *
    * @param {string|null|undefined} sessionId
    */
@@ -164,7 +168,7 @@ export class AmsRegistry {
   }
 
   /**
-   * Persist a single group's AMS to disk. No-op when the cached entry
+   * Persist a single Session's AMS metadata to disk. No-op when the cached entry
    * is missing or hasn't been marked dirty.
    *
    * `opts.adjustRanThisSession`, when supplied, also updates the cached
@@ -177,7 +181,7 @@ export class AmsRegistry {
    */
   persist(sessionId, opts = {}) {
     const key = sessionId || DEFAULT_SESSION_KEY;
-    const entry = this._cache.get(key);
+    const entry = [...this._cache.values()].find(item => item.sessionKey === key);
     if (!entry) return false;
     if (!opts.force && !this._dirty.has(key)) return false;
 
@@ -222,48 +226,25 @@ export class AmsRegistry {
   }
 
   /**
-   * Best-effort hydrate: read ams.json, re-resolve segment ids via the
-   * SegmentIndex (skipping ids that no longer exist), populate AMS, and
-   * restore the persisted `adjustRanThisSession` flag onto the cache entry.
-   * Silent on every error — a corrupt or missing file is the cold-start
-   * case, indistinguishable from "first use of this group".
+   * Best-effort hydrate of version-1 metadata. Persisted segment ids are
+   * intentionally ignored because Engine rebuilds prompt state from selected
+   * canonical content on every query. Silent on every error; corrupt or
+   * missing metadata is equivalent to a cold start.
    *
    * @private
    * @param {string} key
    * @param {AmsCacheEntry} entry
    */
-  _hydrate(key, entry) {
+  _hydrate(key, _entry) {
     const path = this.amsPath(key);
     if (!existsSync(path)) return;
     let payload;
     try { payload = JSON.parse(readFileSync(path, 'utf8') || '{}'); }
     catch { return; }
     if (!payload || typeof payload !== 'object') return;
-
-    if (payload.adjustRanThisSession === true) {
-      entry.adjustRanThisSession = true;
-    }
-
-    if (!this.memoryIndex) return;
-
-    const onDemandIds = Array.isArray(payload.onDemandIds) ? payload.onDemandIds : [];
-    const recentIds   = Array.isArray(payload.recentIds)   ? payload.recentIds   : [];
-
-    const onDemandSegs = [];
-    for (const id of onDemandIds) {
-      try {
-        const seg = this.memoryIndex.get(id);
-        if (seg) onDemandSegs.push(seg);
-      } catch { /* skip unresolvable */ }
-    }
-    if (onDemandSegs.length > 0) entry.ams.setOnDemand(onDemandSegs);
-
-    for (const id of recentIds) {
-      try {
-        const seg = this.memoryIndex.get(id);
-        if (seg) entry.ams.touchRecent(seg);
-      } catch { /* skip */ }
-    }
+    // Segment ids in older snapshots are evidence-only now. Engine rebuilds
+    // query-selected canonical content every turn, so hydrating these ids would
+    // reintroduce raw segment bodies into prompt state.
   }
 }
 

package/yeaft/memory/ams.js

@@ -1,15 +1,13 @@
 /**
  * memory/ams.js — DESIGN-H2-AMS §5. Active Memory Set.
  *
- * Per-group session state. Three layers:
+ * Per-Session prompt state. The data structure retains three compatible
+ * layers, but normal query flow now rebuilds only `resident` from ranked,
+ * canonical `content.md` files. `recent` and `onDemand` segment membership is
+ * cleared before rendering because `memory.md` is evidence, not prompt prose.
  *
- *   resident   summaries of all relevant scopes — always-on, high precision
- *   recent     LRU of segments touched in last N turns — warm cache
- *   onDemand   segments the pre-flow FTS pulled in this turn — hot recall
- *
- * AMS is in-memory; it's rebuilt at session start. The disk source of
- * truth is `<scope>/memory.md` + `<scope>/summary.md`. AMS itself
- * doesn't write to disk — that's Dream's job.
+ * AMS is in-memory and does not write to disk; Dream owns canonical content,
+ * catalog summaries, and evidence persistence.
  *
  * Privacy: `vp/<other>` scopes are ALWAYS filtered out
  * for any worker that isn't `<other>`. The owning code passes its own
@@ -145,6 +143,16 @@ export class ActiveMemorySet {
     for (const id of ids) this._onDemand.delete(id);
   }
 
+  /**
+   * Clear persisted segment membership before prompt assembly. Segment ids are
+   * retained on disk for migration/debug compatibility, but canonical content
+   * is now the only prompt-facing representation.
+   */
+  clearSegmentLayers() {
+    this._recent.clear();
+    this._onDemand.clear();
+  }
+
   // ────────────────────────── snapshot ──────────────────────────
 
   /**
@@ -160,7 +168,7 @@ export class ActiveMemorySet {
     const seenPromptText = new Set();
 
     // Resident: pack scopes by priority order (caller provides via insert
-    // order — current group's own vp first, then user, etc.).
+    // order — current Session's own VP first, then user, etc.).
     const { picked: resPicked, cost: resCost } = pickMemoryItems({
       items: [...this._resident.entries()].map(([scope, entry]) => ({
         scope,

package/yeaft/memory/budget.js

@@ -1,35 +1,32 @@
 /**
  * memory/budget.js — DESIGN-PROMPT §3 ③ Memory.
  *
- * Memory budget = `min(100_000, modelMaxContext * 0.20)`.
+ * Prompt-facing memory budget = `min(6_000, modelMaxContext * 0.05)`.
+ * Memory is supporting context, not a second transcript. A small hard ceiling
+ * prevents large-context models from turning weakly related memory into tens of
+ * thousands of prompt tokens.
  *
- * Then split across the three AMS layers (resident / recent / onDemand)
- * with a configurable ratio. The defaults are tuned per DESIGN-PROMPT §3
- * (Resident gets the largest share because UserProfile + CoreMemory
- * collapse into Resident now):
- *
- *   resident   60%   →  24k of a 40k pool (Layer-A summaries +
- *                                          UserProfile + CoreMemory pinned)
- *   recent     15%   →  6k                (LRU of recently-used segments)
- *   onDemand   25%   →  10k               (this turn's FTS recall)
+ * Canonical content is packed into Resident. Recent and OnDemand retain zero
+ * prompt budget because their segment bodies are evidence, not user-facing
+ * memory. FTS still ranks those segments to select the relevant content scopes.
  *
  * Concrete budgets for common models:
- *   200K context → 40K total (20% × 200K)
- *   1M  context → 100K total (capped)
- *   128K context → 25.6K total
+ *   200K context → 6K total (hard cap)
+ *   128K context → 6K total (hard cap)
+ *    64K context → 3.2K total
  *
  * Token counting here is approximate (chars / 4) — accurate enough for
  * budget enforcement. The engine has a real tokenizer for prompt
  * assembly; budget here is a guard rail, not the source of truth.
  */
 
-export const ABSOLUTE_CAP = 100_000;
-export const MODEL_FRACTION = 0.20;
+export const ABSOLUTE_CAP = 6_000;
+export const MODEL_FRACTION = 0.05;
 
 export const DEFAULT_RATIO = {
-  resident: 0.60,
-  recent:   0.15,
-  onDemand: 0.25,
+  resident: 1,
+  recent:   0,
+  onDemand: 0,
 };
 
 /**

package/yeaft/memory/content-backfill.js

@@ -0,0 +1,118 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { listScopes, readScope } from './segment-store.js';
+import {
+  KIND_VALUES,
+  isValidSegmentScope,
+  parseSegments,
+  serializeSegments,
+} from './segment.js';
+import { stripDreamStateBlocks } from './prompt-cleanup.js';
+
+/**
+ * Seed canonical content.md for legacy scopes that only have Dream evidence
+ * segments or the old body-only memory.md format. The migration is
+ * deterministic, idempotent, and never reads raw transcripts. Dream can later
+ * reorganize this seed without losing
+ * the segment provenance kept in memory.md.
+ */
+export function backfillCanonicalContent(memoryRoot) {
+  let created = 0;
+  for (const scope of listScopes(memoryRoot)) {
+    if (scope.startsWith('.legacy/') || scope.startsWith('.dream-bak/')) continue;
+    const contentPath = join(memoryRoot, scope, 'content.md');
+    const rawMemory = readMemoryFile(memoryRoot, scope);
+    const segments = hasSerializedSegmentEnvelope(rawMemory)
+      ? readScope(memoryRoot, scope)
+      : [];
+    const bodies = uniqueBodies(segments);
+    if (bodies.length === 0 && rawMemory) bodies.push(rawMemory);
+    const canonicalBody = bodies.length > 0 ? `${bodies.join('\n\n')}\n` : '';
+    const currentContent = existsSync(contentPath) ? readFileSync(contentPath, 'utf8') : '';
+    if (currentContent.trim()) {
+      // A canonical document already exists. Preserve the raw legacy file in
+      // cold storage, but never leave body-only prose live as evidence.
+      if (segments.length === 0 && rawMemory) archivePlainLegacyMemory(memoryRoot, scope);
+      continue;
+    }
+    if (!canonicalBody) continue;
+    mkdirSync(dirname(contentPath), { recursive: true });
+    const tmp = `${contentPath}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, canonicalBody, 'utf8');
+    renameSync(tmp, contentPath);
+    if (readFileSync(contentPath, 'utf8') !== canonicalBody) {
+      throw new Error(`backfillCanonicalContent: canonical write verification failed for ${scope}`);
+    }
+    if (segments.length === 0 && rawMemory) archivePlainLegacyMemory(memoryRoot, scope);
+    created += 1;
+  }
+  return { created };
+}
+
+function archivePlainLegacyMemory(memoryRoot, scope) {
+  const source = join(memoryRoot, scope, 'memory.md');
+  if (!existsSync(source)) return;
+  const archive = join(memoryRoot, '.legacy', 'plain-memory', scope, 'memory.md');
+  mkdirSync(dirname(archive), { recursive: true });
+  let destination = archive;
+  if (existsSync(destination)) {
+    destination = `${archive}.${Date.now()}`;
+  }
+  renameSync(source, destination);
+}
+
+function readMemoryFile(memoryRoot, scope) {
+  const path = join(memoryRoot, scope, 'memory.md');
+  if (!existsSync(path)) return '';
+  return stripDreamStateBlocks(readFileSync(path, 'utf8'));
+}
+
+function hasSerializedSegmentEnvelope(text) {
+  const source = String(text || '').replace(/^/, '').trim();
+  if (!source.startsWith('---\n')) return false;
+
+  const segments = parseSegments(source);
+  if (segments.length === 0 || segments.some(segment => !isWriterSegment(segment))) return false;
+
+  // The internal writer owns one exact wire format. Re-serializing parsed
+  // segments must reproduce the file byte-for-byte after outer trimming;
+  // otherwise this is user-authored Markdown and must remain opaque.
+  return serializeSegments(segments).trim() === source;
+}
+
+function isWriterSegment(segment) {
+  return /^seg_[0-9a-f]{8}$/.test(segment.id)
+    && isValidSegmentScope(segment.scope)
+    && KIND_VALUES.has(segment.kind)
+    && isStringArray(segment.tags)
+    && isStringArray(segment.sourceMessages)
+    && isValidTimestamp(segment.createdAt)
+    && isValidTimestamp(segment.updatedAt)
+    && typeof segment.body === 'string'
+    && segment.body.length > 0;
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+
+function isValidTimestamp(value) {
+  return typeof value === 'string'
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+function uniqueBodies(segments) {
+  const seen = new Set();
+  const bodies = [];
+  for (const segment of segments) {
+    const body = String(segment?.body || '').trim();
+    if (!body) continue;
+    const key = body.replace(/\s+/g, ' ').toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    bodies.push(body);
+  }
+  return bodies;
+}

package/yeaft/memory/index-db.js

@@ -1,8 +1,8 @@
 /**
  * memory/index-db.js — DESIGN-H2-AMS §4. SQLite + FTS5 segment index.
  *
- * Source of truth: on-disk `~/.yeaft/memory/<scope>/memory.md` files.
- * SQLite is a derived index — rebuildable from disk at any time.
+ * Sources of truth: on-disk evidence memory.md and canonical content.md.
+ * SQLite is a derived scope-selection index, rebuildable from disk at any time.
  *
  * Schema is created idempotently; opening an older DB without the
  * required tables triggers a fresh CREATE. A version PRAGMA guards
@@ -89,7 +89,7 @@ export function openSegmentIndex(dbPath) {
     db.prepare('INSERT INTO schema_meta(key,value) VALUES(?,?)')
       .run('schema_version', String(SCHEMA_VERSION));
   } else if (cur.value !== String(SCHEMA_VERSION)) {
-    // For now, simple drop-and-recreate. v2 may add migrations.
+    // The index is derived state, so schema changes use drop-and-recreate.
     db.exec('DROP TABLE IF EXISTS memory_fts');
     db.exec('DROP TABLE IF EXISTS memory_segments');
     db.exec('DELETE FROM schema_meta');
@@ -119,6 +119,7 @@ export function openSegmentIndex(dbPath) {
  * @property {string}        query        FTS5 MATCH expression
  * @property {string[]=}     scopeFilter  if set, restrict to these scopes
  * @property {number=}       limit        default 50
+ * @property {string=}       requiredTag  restrict rows to a derived record tag
  */
 
 /**
@@ -203,6 +204,8 @@ function makeHandle(db) {
         ? Math.min(500, Math.floor(opts.limit)) : 50;
       const scopeFilter = Array.isArray(opts.scopeFilter) && opts.scopeFilter.length > 0
         ? opts.scopeFilter : null;
+      const requiredTag = typeof opts.requiredTag === 'string' && opts.requiredTag.trim()
+        ? opts.requiredTag.trim() : null;
 
       // Build the SQL dynamically — scope IN (...) needs N placeholders.
       let sql = `
@@ -215,6 +218,10 @@ function makeHandle(db) {
         sql += ` AND s.scope IN (${scopeFilter.map(() => '?').join(',')})`;
         params.push(...scopeFilter);
       }
+      if (requiredTag) {
+        sql += " AND EXISTS (SELECT 1 FROM json_each(s.tags) WHERE json_each.value = ?)";
+        params.push(requiredTag);
+      }
       sql += ` ORDER BY rank LIMIT ?`;
       params.push(limit);
 

package/yeaft/memory/keywords.js

@@ -1,7 +1,7 @@
 /**
  * keywords.js — pure-rule keyword extraction shared by memory recall paths.
  *
- * Pure CPU, no LLM, <1ms. Used by `groups/pre-flow.js` to derive FTS
+ * Pure CPU, no LLM, <1ms. Used by `sessions/pre-flow.js` to derive FTS
  * query terms from the user message before hitting `memory/preflow.js`.
  */
 
@@ -27,6 +27,14 @@ const STOP_WORDS = new Set([
   '他', '她', '吗', '呢', '吧', '把', '被',
   '那', '它', '让', '给', '可以', '什么',
   '怎么', '帮', '帮我', '请', '能', '想',
+  // Generic execution / memory vocabulary is not discriminative enough to
+  // select persistent context on its own.
+  'current', 'state', 'work', 'task', 'item', 'items', 'todo', 'next', 'step',
+  'merge', 'review', 'release', 'tag', 'tags', 'pr', 'pull', 'request', 'issue',
+  'fix', 'feat', 'test', 'tests', 'dream', 'memory', 'session', 'topic', 'status',
+  'blocker', 'blocked', 'context', 'latest',
+  '当前', '状态', '任务', '工作', '工作项', '待办', '下一步', '完成', '合并',
+  '评审', '发布', '标签', '记忆', '主题', '阻塞', '正在', '上下文', '最新',
 ]);
 
 /**
@@ -38,12 +46,22 @@ const STOP_WORDS = new Set([
 export function extractKeywords(prompt) {
   if (!prompt || !prompt.trim()) return [];
 
-  // Tokenize: split on whitespace + punctuation, keep CJK chars.
-  const tokens = prompt
-    .toLowerCase()
-    .replace(/[^\w\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff]+/g, ' ')
-    .split(/\s+/)
-    .filter(t => t.length > 1 && !STOP_WORDS.has(t));
+  const normalized = prompt.toLowerCase();
+  const tokens = [];
+  for (const match of normalized.matchAll(/[a-z0-9_]{2,}/g)) {
+    if (!STOP_WORDS.has(match[0])) tokens.push(match[0]);
+  }
+  for (const match of normalized.matchAll(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff]{2,}/g)) {
+    const run = match[0];
+    if (STOP_WORDS.has(run)) continue;
+    if (run.length === 2) tokens.push(run);
+    else {
+      for (let i = 0; i < run.length - 1; i += 1) {
+        const term = run.slice(i, i + 2);
+        if (!STOP_WORDS.has(term)) tokens.push(term);
+      }
+    }
+  }
 
   const freq = new Map();
   for (const t of tokens) {

package/yeaft/memory/preflow.js

@@ -24,12 +24,14 @@ export const DEFAULT_PICK_LIMIT = 8;
 /**
  * @typedef {object} PreflowOptions
  * @property {string}        userMsg
- * @property {string[]}      relevantScopes      e.g. ['user', 'group/g1', 'vp/alice']
+ * @property {string[]}      relevantScopes      e.g. ['user', 'sessions/s1', 'sessions/s1/vp/alice']
  * @property {string|null}  [ownVpId]
- * @property {string[]}     [currentTags]        tags from the current group/feature context
- * @property {number}       [topK]               max FTS rows to fetch (default 50)
+ * @property {string[]}     [currentTags]        tags from the current Session context
+ * @property {number}       [topK]               max FTS rows to fetch (default 200)
  * @property {number}       [budgetTokens]       onDemand budget (caller-supplied)
  * @property {number}       [pickLimit]          max picked segments (default 8)
+ * @property {boolean}      [uniqueScopes]       pick at most one best hit per scope
+ * @property {boolean}      [canonicalOnly]      search canonical content records only
  */
 
 /**
@@ -54,7 +56,7 @@ export function runPreflow(index, opts) {
   const relevantScopes = Array.isArray(opts.relevantScopes) ? opts.relevantScopes : [];
   const ownVpId = opts.ownVpId || null;
   const currentTags = Array.isArray(opts.currentTags) ? opts.currentTags : [];
-  const topK = Number.isFinite(opts.topK) && opts.topK > 0 ? opts.topK : 50;
+  const topK = Number.isFinite(opts.topK) && opts.topK > 0 ? opts.topK : 200;
   const budgetTokens = Number.isFinite(opts.budgetTokens) && opts.budgetTokens > 0
     ? opts.budgetTokens : Infinity;
   const pickLimit = Number.isFinite(opts.pickLimit) && opts.pickLimit > 0
@@ -77,16 +79,27 @@ export function runPreflow(index, opts) {
     };
   }
 
-  const hits = index.search({ query: ftsQuery, scopeFilter, limit: topK });
-  const reranked = rerank(hits, { currentTags });
+  const hits = index.search({
+    query: ftsQuery,
+    scopeFilter,
+    limit: topK,
+    ...(opts.canonicalOnly ? { requiredTag: 'canonical-content' } : {}),
+  });
+  const reranked = rerank(hits, { currentTags, keywords });
 
   const picked = [];
+  const pickedScopes = new Set();
   let cost = 0;
   let dropped = 0;
   for (const h of reranked) {
+    if (opts.uniqueScopes && pickedScopes.has(h.scope)) {
+      dropped += 1;
+      continue;
+    }
     const tk = approxTokens(h.body);
     if (picked.length < pickLimit && cost + tk <= budgetTokens) {
       picked.push(toSegment(h));
+      pickedScopes.add(h.scope);
       cost += tk;
     } else {
       dropped += 1;
@@ -129,7 +142,7 @@ export function filterScopes(scopes, ownVpId) {
 
 /**
  * Rerank FTS hits with two soft signals on top of bm25:
- *   - tag overlap with the current group/feature context (subtract penalty)
+ *   - tag overlap with the current Session context (subtract penalty)
  *   - recency: recent items get a small bonus
  *
  * SQLite FTS5 bm25 returns NEGATIVE numbers (more negative = better
@@ -138,7 +151,7 @@ export function filterScopes(scopes, ownVpId) {
  * score more negative).
  *
  * @param {import('./index-db.js').SearchHit[]} hits
- * @param {{ currentTags: string[] }} ctx
+ * @param {{ currentTags: string[], keywords?: string[] }} ctx
  * @returns {import('./index-db.js').SearchHit[]}
  */
 export function rerank(hits, ctx) {
@@ -149,7 +162,11 @@ export function rerank(hits, ctx) {
       const overlap = (h.tags || []).reduce(
         (n, t) => n + (tagSet.has(String(t).toLowerCase()) ? 1 : 0), 0,
       );
-      const tagBonus = Math.min(2, overlap * 0.5);   // up to 2 points
+      const queryTerms = new Set((ctx.keywords || []).map(term => String(term).toLowerCase()));
+      const canonicalOverlap = (h.tags || []).reduce(
+        (n, tag) => n + (queryTerms.has(String(tag).toLowerCase()) ? 1 : 0), 0,
+      );
+      const tagBonus = Math.min(2, overlap * 0.5) + Math.min(1.5, canonicalOverlap * 0.15);
       const ageDays = Math.max(0, (now - Date.parse(h.updatedAt || h.createdAt || '')) / 86400000);
       const recencyBonus = Math.min(0.5, 0.2 / Math.max(0.5, ageDays + 1));
       const base = h.rank ?? 0;