@yeaft/webchat-agent 1.0.289 → 1.0.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.289",
+  "version": "1.0.292",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/cli-session-runner.js

@@ -0,0 +1,213 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { Engine } from './engine.js';
+import { createRouter } from './routing/router.js';
+import { createCoordinator } from './sessions/coordinator.js';
+import { sessionsRoot } from './sessions/session-crud.js';
+import { openSession, loadSessionMeta } from './sessions/session-store.js';
+import { loadSessionConfig, resolveSessionConfig } from './sessions/session-config.js';
+import { readVp } from './vp/vp-crud.js';
+import { COLLAB_TOOL_POLICY } from './tools/registry.js';
+
+function buildVpPersona(vpId, loaded) {
+  const vp = readVp(vpId, { libDir: join(loaded.yeaftDir, 'virtual-persons') });
+  if (!vp) return null;
+  return {
+    vpId,
+    displayName: vp.displayName || vpId,
+    displayNameZh: vp.displayNameZh || '',
+    role: vp.role || '',
+    roleZh: vp.roleZh || '',
+    persona: vp.persona || '',
+    planInstruction: vp.planInstruction || '',
+  };
+}
+
+function createEngine(loaded, sessionId, vpId) {
+  const effectiveConfig = resolveSessionConfig(
+    loaded.config,
+    loadSessionConfig(loaded.yeaftDir, sessionId),
+  );
+  return new Engine({
+    adapter: loaded.adapter,
+    trace: loaded.trace,
+    config: effectiveConfig,
+    conversationStore: loaded.conversationStore,
+    memoryIndex: loaded.memoryIndex || null,
+    amsRegistry: loaded.amsRegistry || null,
+    toolRegistry: loaded.toolRegistry,
+    skillManager: loaded.skillManager,
+    mcpManager: loaded.mcpManager,
+    yeaftDir: loaded.yeaftDir,
+    toolStats: loaded.toolStats || null,
+    taskManager: loaded.taskManager || null,
+    sessionId,
+    vpId,
+  });
+}
+
+/**
+ * Open a transport-neutral multi-VP runtime for an existing Yeaft Session.
+ * Different VPs run concurrently; each VP owns one serial promise tail and
+ * one Engine, matching the WebSocket runtime's state-isolation rule.
+ *
+ * Returns null when session metadata does not exist so legacy one-engine CLI
+ * invocations can keep their existing behavior.
+ */
+export function createCliSessionRunner({
+  loaded,
+  sessionId,
+  workDir = process.cwd(),
+  engineFactory = createEngine,
+  personaFactory = buildVpPersona,
+} = {}) {
+  if (!loaded || !sessionId) return null;
+  const sessionDir = join(sessionsRoot(loaded.yeaftDir), sessionId);
+  if (!loadSessionMeta(sessionDir)) return null;
+
+  const handle = openSession(sessionsRoot(loaded.yeaftDir), sessionId);
+  const engines = new Map();
+  const tails = new Map();
+  const pending = new Set();
+  let closed = false;
+
+  const engineFor = (vpId) => {
+    let engine = engines.get(vpId);
+    if (!engine) {
+      engine = engineFactory(loaded, sessionId, vpId);
+      engines.set(vpId, engine);
+    }
+    return engine;
+  };
+
+  let coordinator;
+
+  const runEnvelope = async (vpId, envelope, options) => {
+    const meta = handle.getMeta();
+    const engine = engineFor(vpId);
+    const promptText = envelope?.msg?.text || '';
+    const prompt = `@vp-${vpId} ${promptText}`;
+    const messages = loaded.conversationStore.loadSessionHistoryForVp(sessionId, vpId);
+    const todos = [];
+    let resultText = '';
+    let failed = null;
+    const scopedCoordinator = {
+      group: coordinator.group,
+      ingest(input, opts) {
+        return coordinator.ingest({ ...input, _cliTurnContext: envelope._cliTurnContext }, opts);
+      },
+    };
+    const queryOptions = {
+      prompt,
+      messages,
+      sessionId,
+      workDir: meta.workDir || workDir,
+      senderVpId: vpId,
+      sessionMembers: meta.roster.slice(),
+      sessionAnnouncement: meta.announcement || '',
+      vpPersona: personaFactory(vpId, loaded),
+      router: createRouter({ coordinator: scopedCoordinator }),
+      inboundEnvelope: envelope,
+      userAlreadyPersisted: true,
+      threadId: 'main',
+      vpTurnId: envelope?.msg?.id || randomUUID(),
+      collabToolPolicy: meta.roster.length > 1
+        ? COLLAB_TOOL_POLICY.MULTI_VP
+        : COLLAB_TOOL_POLICY.SINGLE_VP,
+      getCurrentTodos: () => todos.slice(),
+      setCurrentTodos: (next) => {
+        todos.splice(0, todos.length, ...(Array.isArray(next) ? next : []));
+      },
+      askUser: options.askUser
+        ? request => options.askUser(request, vpId, queryOptions.vpTurnId)
+        : null,
+      userEffort: options.modelEffort || null,
+    };
+
+    try {
+      for await (const event of engine.query(queryOptions)) {
+        if (event.type === 'text_delta') resultText += event.text || '';
+        await options.onEvent?.({ vpId, event, sessionId, turnId: queryOptions.vpTurnId });
+      }
+    } catch (error) {
+      failed = error;
+      await options.onEvent?.({
+        vpId,
+        sessionId,
+        turnId: queryOptions.vpTurnId,
+        event: { type: 'error', error, retryable: false },
+      });
+    }
+    return { vpId, result: resultText, error: failed };
+  };
+
+  const enqueue = (vpId, envelope) => {
+    if (closed) throw new Error('CLI Session runner is closed');
+    const turnContext = envelope?._cliTurnContext;
+    if (!turnContext) throw new Error('CLI Session envelope is missing its turn context');
+    const previous = tails.get(vpId) || Promise.resolve();
+    const task = previous.catch(() => {}).then(() => runEnvelope(vpId, envelope, turnContext.options));
+    tails.set(vpId, task);
+    pending.add(task);
+    turnContext.pending.add(task);
+    task.finally(() => {
+      pending.delete(task);
+      turnContext.pending.delete(task);
+      if (tails.get(vpId) === task) tails.delete(vpId);
+    }).catch(() => {});
+    return task;
+  };
+
+  coordinator = createCoordinator(handle, { deliver: enqueue });
+
+  async function drain(tasks = pending) {
+    const results = [];
+    while (tasks.size > 0) {
+      const batch = Array.from(tasks);
+      results.push(...await Promise.all(batch));
+      await Promise.resolve();
+    }
+    return results;
+  }
+
+  return {
+    sessionId,
+    get meta() { return handle.getMeta(); },
+    async run(prompt, options = {}) {
+      if (closed) throw new Error('CLI Session runner is closed');
+      const turnContext = Object.freeze({ options: Object.freeze({ ...options }), pending: new Set() });
+      const messageId = randomUUID();
+      // The shared user row is the durability boundary. Every VP Engine skips
+      // its own user append, preventing @all from duplicating the prompt N times.
+      loaded.conversationStore.append({
+        role: 'user',
+        content: prompt,
+        sessionId,
+        threadId: 'main',
+        clientMessageId: messageId,
+        userAuthored: true,
+      });
+      const report = coordinator.ingest({
+        id: messageId,
+        from: 'user',
+        role: 'user',
+        text: prompt,
+        _cliTurnContext: turnContext,
+      });
+      const results = await drain(turnContext.pending);
+      return { report, results };
+    },
+    abort(reason = 'user') {
+      let count = 0;
+      for (const engine of engines.values()) {
+        if (engine.abort?.(reason)) count += 1;
+      }
+      return count;
+    },
+    async close() {
+      closed = true;
+      await drain();
+      handle.close();
+    },
+  };
+}

package/yeaft/cli.js

@@ -38,7 +38,8 @@ import { ConversationStore } from './conversation/persist.js';
 import { snapshotSessions } from './sessions/session-crud.js';
 import { loadSessionConfig, resolveSessionConfig } from './sessions/session-config.js';
 import { validateSessionId } from './sessions/ids.js';
-import { createJsonlWriter, JsonlInput, runStreamTurn } from './stdio-protocol.js';
+import { createJsonlWriter, JsonlInput, runStreamTurn, runStreamSessionTurn } from './stdio-protocol.js';
+import { createCliSessionRunner } from './cli-session-runner.js';
 
 // ─── Argument parsing ──────────────────────────────────────────
 
@@ -333,16 +334,28 @@ function handleDeleteGroup(config, sessionId) {
 // ─── REPL ──────────────────────────────────────────────────────
 
 async function runREPL(config, args) {
-  // Use loadSession() to wire all subsystems
+  const workDir = resolve(args.workDir || process.cwd());
+  const persisted = args.sessionId ? loadSessionConfig(config.dir, args.sessionId) : {};
+  const effectiveConfig = resolveSessionConfig(config, persisted);
   const session = await loadSession({
-    model: args.model || config.model,
-    language: args.language || config.language,
-    debug: args.debug || config.debug,
+    dir: config.dir,
+    workDir,
+    model: args.model || effectiveConfig.model,
+    language: args.language || effectiveConfig.language,
+    debug: args.debug || effectiveConfig.debug,
     skipMCP: args.skipMCP,
     skipSkills: args.skipSkills,
+    configOverrides: effectiveConfig,
   });
 
   const { engine, conversationStore, trace, skillManager, mcpManager, toolRegistry } = session;
+  const sessionRunner = args.sessionId
+    ? createCliSessionRunner({ loaded: session, sessionId: args.sessionId, workDir })
+    : null;
+  if (args.sessionId && !sessionRunner) {
+    await session.shutdown();
+    throw new Error(`Session not found: ${args.sessionId}`);
+  }
 
   // Load persisted conversation as initial messages. `loadRecent` is now
   // turn-based (one user round-trip = one turn; multi-VP fan-out collapses
@@ -655,9 +668,28 @@ async function runREPL(config, args) {
       return;
     }
 
-    // Regular input → engine.query
+    // Regular input → Session fan-out or legacy single Engine.
     try {
       let responseText = '';
+      if (sessionRunner) {
+        const outcome = await sessionRunner.run(input, {
+          modelEffort: args.modelEffort || session.config.modelEffort || null,
+          onEvent: ({ vpId, event }) => {
+            if (event.type === 'text_delta') {
+              responseText += event.text || '';
+              process.stdout.write(`\n[${vpId}] ${event.text || ''}`);
+            } else if (event.type === 'tool_start') {
+              process.stderr.write(`\n[${vpId}] ${event.name}...\n`);
+            } else if (event.type === 'error') {
+              process.stderr.write(`\n[${vpId}] Error: ${event.error?.message || event.error}\n`);
+            }
+          },
+        });
+        console.log();
+        if (outcome.results.some(result => result.error)) process.exitCode = 1;
+        rl.prompt();
+        return;
+      }
 
       for await (const event of engine.query({
         prompt: input,
@@ -721,6 +753,7 @@ async function runREPL(config, args) {
   });
 
   rl.on('close', async () => {
+    await sessionRunner?.close();
     await session.shutdown();
     console.log('\nBye!');
     process.exit(0);
@@ -766,6 +799,7 @@ async function runStreamJson(config, args) {
     },
   });
   const { engine, conversationStore, skillManager, toolRegistry } = loaded;
+  const sessionRunner = createCliSessionRunner({ loaded, sessionId, workDir });
   const todoState = { value: [] };
 
   write({
@@ -788,8 +822,7 @@ async function runStreamJson(config, args) {
       ...(message.toolCallId && { toolCallId: message.toolCallId }),
       ...(message.toolCalls && { toolCalls: message.toolCalls }),
     }));
-    return runStreamTurn({
-      engine,
+    const turnOptions = {
       prompt,
       messages: priorMessages,
       sessionId,
@@ -800,7 +833,10 @@ async function runStreamJson(config, args) {
       write,
       getCurrentTodos: () => todoState.value.slice(),
       setCurrentTodos: todos => { todoState.value = Array.isArray(todos) ? todos.slice() : []; },
-    });
+    };
+    return sessionRunner
+      ? runStreamSessionTurn({ runner: sessionRunner, ...turnOptions })
+      : runStreamTurn({ engine, ...turnOptions });
   };
 
   let lastResult = null;
@@ -820,6 +856,7 @@ async function runStreamJson(config, args) {
     }
   } finally {
     input?.close();
+    await sessionRunner?.close();
     await loaded.shutdown();
     console.log = originalConsole.log;
     console.info = originalConsole.info;
@@ -836,18 +873,42 @@ async function runOnce(config, args) {
     return;
   }
 
-  // Use loadSession() to wire all subsystems
+  const workDir = resolve(args.workDir || process.cwd());
+  const persisted = args.sessionId ? loadSessionConfig(config.dir, args.sessionId) : {};
+  const effectiveConfig = resolveSessionConfig(config, persisted);
   const session = await loadSession({
-    model: args.model || config.model,
-    language: args.language || config.language,
-    debug: args.debug || config.debug,
+    dir: config.dir,
+    workDir,
+    model: args.model || effectiveConfig.model,
+    language: args.language || effectiveConfig.language,
+    debug: args.debug || effectiveConfig.debug,
     skipMCP: args.skipMCP,
     skipSkills: args.skipSkills,
+    configOverrides: effectiveConfig,
   });
 
   const { engine, conversationStore } = session;
+  const sessionRunner = args.sessionId
+    ? createCliSessionRunner({ loaded: session, sessionId: args.sessionId, workDir })
+    : null;
 
   try {
+    if (args.sessionId && !sessionRunner) {
+      throw new Error(`Session not found: ${args.sessionId}`);
+    }
+    if (sessionRunner) {
+      const outcome = await sessionRunner.run(args.prompt, {
+        modelEffort: args.modelEffort || session.config.modelEffort || null,
+        onEvent: ({ vpId, event }) => {
+          if (event.type === 'text_delta') process.stdout.write(`\n[${vpId}] ${event.text || ''}`);
+          else if (event.type === 'tool_start') process.stderr.write(`\n[${vpId}] ${event.name}...\n`);
+          else if (event.type === 'error') process.stderr.write(`\n[${vpId}] Error: ${event.error?.message || event.error}\n`);
+        },
+      });
+      console.log();
+      if (outcome.results.some(result => result.error)) process.exitCode = 1;
+      return;
+    }
     // Load recent conversation as context
     const priorMessages = conversationStore.loadRecent(20).map(m => ({
       role: m.role,
@@ -903,6 +964,7 @@ async function runOnce(config, args) {
     // Final newline after streaming text
     console.log();
   } finally {
+    await sessionRunner?.close();
     await session.shutdown();
   }
 }

package/yeaft/engine.js

@@ -84,6 +84,8 @@ const AMS_ADJUST_TIMEOUT_MS = 30_000;
 /** Maximum silence while a visible turn waits for a result-producing task. */
 const DEFAULT_ASYNC_TASK_WAIT_TIMEOUT_MS = 120_000;
 
+const DEFAULT_MEMORY_RECALL_LIMIT = 8;
+
 // ─── LLM retry policy defaults ──────────────────────────────────
 // Hard-coded floor / ceiling for retry behaviour. The engine reads the
 // effective policy from `config.llmRetry` so users can dial these via
@@ -442,6 +444,47 @@ function isZhRuntimeLanguage(language) {
   return String(language || '').toLowerCase().startsWith('zh');
 }
 
+function resolveMemoryRecallLimit(config) {
+  const raw = config?.memoryRecallLimit ?? config?.dreamMemoryRecallLimit;
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_MEMORY_RECALL_LIMIT;
+  return Math.max(1, Math.floor(raw));
+}
+
+function loadedMemoryDebugEntries(snapshot) {
+  const snap = snapshot || {};
+  return [
+    ...loadedResidentDebugEntries(snap.resident || []),
+    ...loadedSegmentDebugEntries(snap.recent || [], 'recent'),
+    ...loadedSegmentDebugEntries(snap.onDemand || [], 'onDemand'),
+  ];
+}
+
+function loadedResidentDebugEntries(entries) {
+  return (entries || []).map((entry, index) => ({
+    id: `resident:${entry.scope || index}`,
+    layer: 'resident',
+    scope: entry.scope || null,
+    label: memoryScopeLabel(entry.scope || ''),
+    kind: 'summary',
+    score: null,
+    tags: [],
+    body: entry.summary || '',
+  })).filter(entry => entry.body);
+}
+
+function loadedSegmentDebugEntries(segments, layer) {
+  return (segments || []).map((seg, index) => ({
+    id: seg.id || `${layer}:${index}`,
+    layer,
+    scope: seg.scope || null,
+    label: memoryScopeLabel(seg.scope || ''),
+    kind: seg.kind || null,
+    score: typeof seg.score === 'number' ? seg.score : null,
+    tags: Array.isArray(seg.tags) ? seg.tags : [],
+    body: seg.body || '',
+  })).filter(entry => entry.body);
+}
+
 export class Engine {
   /** @type {import('./llm/adapter.js').LLMAdapter} */
   #adapter;
@@ -906,6 +949,7 @@ export class Engine {
    *   ownVpId: string|null,
    *   scopes: string[],
    *   snapshotBlock: string,
+ *   snapshot: import('./memory/ams.js').AmsSnapshot,
  *   residentEntries: Array<{scope:string, summary:string}>,
    * } | null}
    */
@@ -938,14 +982,15 @@ export class Engine {
     ams.setOnDemand(segs);
 
     // (c) Snapshot — render the AMS layers as a single prompt block.
-    const snapshotBlock = this.#renderAmsSnapshot(ams, this.#config.language || 'en', args.userMsg || '');
+    const snapshot = ams.snapshot({ userMsg: args.userMsg || '' });
+    const snapshotBlock = this.#renderAmsSnapshot(snapshot, this.#config.language || 'en');
 
     const scopes = buildRelevantScopes({
       sessionId: args.sessionId,
       vpId: ownVpId,
     });
 
-    return { ams, sessionKey, ownVpId, scopes, snapshotBlock, residentEntries };
+    return { ams, sessionKey, ownVpId, scopes, snapshotBlock, snapshot, residentEntries };
   }
 
   /**
@@ -953,13 +998,11 @@ export class Engine {
    * injection. Mirrors the heading style of the existing memory blocks
    * so the LLM sees a consistent layout.
    *
-   * @param {import('./memory/ams.js').ActiveMemorySet} ams
+   * @param {import('./memory/ams.js').AmsSnapshot} snap
    * @param {string} [language]
-   * @param {string} [userMsg]
    * @returns {string}
    */
-  #renderAmsSnapshot(ams, language = 'en', userMsg = '') {
-    const snap = ams.snapshot({ userMsg });
+  #renderAmsSnapshot(snap, language = 'en') {
     if (!snap) return '';
     const parts = [];
     if (snap.resident.length === 0 && snap.recent.length === 0 && snap.onDemand.length === 0) {
@@ -1342,7 +1385,7 @@ export class Engine {
    * @returns {Promise<{ profile: string, entries: object[], formatted: string }|null>}
    */
   async #recallMemory(prompt, ctx = {}) {
-    const memory = { profile: '', entries: [], formatted: '' };
+    const memory = { profile: '', entries: [], formatted: '', meta: {} };
     if (!this.#memoryIndex) return memory;
     try {
       const result = runMemoryPreflow(this.#memoryIndex, {
@@ -1351,11 +1394,13 @@ export class Engine {
         chatId: ctx.chatId || this.#chatId,
         vpId: ctx.vpId,
         extraScopes: ctx.extraScopes,
+        pickLimit: resolveMemoryRecallLimit(this.#config),
         fallbackOnEmpty: true,
       });
       memory.profile = result.profile || '';
       memory.entries = result.entries || [];
       memory.formatted = result.formatted || '';
+      memory.meta = result.meta || {};
     } catch {
       // Fail soft — empty injection.
     }
@@ -2029,6 +2074,7 @@ export class Engine {
     if (amsContext && amsContext.snapshotBlock) {
       memoryInjection = amsContext.snapshotBlock;
     }
+    const loadedMemoryForDebug = loadedMemoryDebugEntries(amsContext?.snapshot);
 
     // Diagnostic payload for the Dream debug panel. The full AMS Resident
     // layer can include user and per-VP summaries, but the browser-facing
@@ -2282,19 +2328,20 @@ export class Engine {
       yield { type: 'skill_error', turnId: queryTurnId, skillName: explicitSkillName, message: skillResolutionError };
     }
 
-    // Surface memory recall to the debug panel right after turn_open.
-    // recallResult was loaded above; emit a structured `memory_used`
-    // event so the UI can show "loaded N segments" without parsing
-    // the legacy `recall` event (which only carried entryCount).
-    if (recallResult && Array.isArray(recallResult.entries) && recallResult.entries.length > 0) {
+    // Surface the exact memory that entered the prompt. This must be based on
+    // the AMS snapshot, not raw FTS candidates, otherwise debug can claim memory
+    // was loaded even when prompt cleanup, dedupe, or token budget dropped it.
+    if (loadedMemoryForDebug.length > 0) {
       yield {
         type: 'memory_used',
         turnId: queryTurnId,
-        loaded: recallResult.entries.map(e => ({
-          id: e && e.id || null,
-          score: e && typeof e.score === 'number' ? e.score : null,
-          kind: e && e.kind || null,
-        })),
+        loaded: loadedMemoryForDebug,
+        meta: {
+          recallLimit: resolveMemoryRecallLimit(this.#config),
+          recallCandidates: Number.isFinite(recallResult?.meta?.hitCount)
+            ? recallResult.meta.hitCount
+            : (recallResult && Array.isArray(recallResult.entries) ? recallResult.entries.length : 0),
+        },
       };
     }
 

package/yeaft/memory/preflow.js

@@ -19,6 +19,8 @@ import { extractKeywords } from './keywords.js';
 import { approxTokens } from './budget.js';
 import { isVpForeign } from './store.js';
 
+export const DEFAULT_PICK_LIMIT = 8;
+
 /**
  * @typedef {object} PreflowOptions
  * @property {string}        userMsg
@@ -27,6 +29,7 @@ import { isVpForeign } from './store.js';
  * @property {string[]}     [currentTags]        tags from the current group/feature context
  * @property {number}       [topK]               max FTS rows to fetch (default 50)
  * @property {number}       [budgetTokens]       onDemand budget (caller-supplied)
+ * @property {number}       [pickLimit]          max picked segments (default 8)
  */
 
 /**
@@ -54,6 +57,8 @@ export function runPreflow(index, opts) {
   const topK = Number.isFinite(opts.topK) && opts.topK > 0 ? opts.topK : 50;
   const budgetTokens = Number.isFinite(opts.budgetTokens) && opts.budgetTokens > 0
     ? opts.budgetTokens : Infinity;
+  const pickLimit = Number.isFinite(opts.pickLimit) && opts.pickLimit > 0
+    ? Math.floor(opts.pickLimit) : DEFAULT_PICK_LIMIT;
 
   const keywords = extractKeywords(userMsg);
   if (keywords.length === 0) {
@@ -80,7 +85,7 @@ export function runPreflow(index, opts) {
   let dropped = 0;
   for (const h of reranked) {
     const tk = approxTokens(h.body);
-    if (cost + tk <= budgetTokens) {
+    if (picked.length < pickLimit && cost + tk <= budgetTokens) {
       picked.push(toSegment(h));
       cost += tk;
     } else {
@@ -152,7 +157,7 @@ export function rerank(hits, ctx) {
       return { ...h, _score: score };
     })
     .sort((a, b) => a._score - b._score)
-    .map(({ _score, ...rest }) => rest);
+    .map(({ _score, ...rest }) => ({ ...rest, score: _score }));
 }
 
 function toSegment(h) {
@@ -163,6 +168,7 @@ function toSegment(h) {
     tags: h.tags,
     sourceMessages: h.sourceMessages,
     body: h.body,
+    score: typeof h.score === 'number' ? h.score : (typeof h.rank === 'number' ? h.rank : undefined),
     createdAt: h.createdAt,
     updatedAt: h.updatedAt,
   };

package/yeaft/sessions/pre-flow.js

@@ -259,6 +259,7 @@ export function formatPickedForInjection(picked) {
  * @property {string[]}       [currentTags]        Contextual tags for rerank
  * @property {number}         [topK]               Max FTS rows fetched (default 50)
  * @property {number}         [budgetTokens]       Token budget for picked segments
+ * @property {number}         [pickLimit]          Max picked segments (default 8)
  * @property {boolean}        [fallbackOnEmpty]    Include bounded recent scoped segments when FTS has no hits
  * @property {number}         [fallbackPerScope]   Max fallback segments per scope
  */
@@ -353,6 +354,7 @@ export function runMemoryPreflow(index, opts) {
     currentTags: opts.currentTags || [],
     topK: opts.topK,
     budgetTokens: opts.budgetTokens,
+    pickLimit: opts.pickLimit,
   });
 
   let fallbackUsed = false;
@@ -362,6 +364,7 @@ export function runMemoryPreflow(index, opts) {
       ownVpId: opts.vpId || null,
       budgetTokens: opts.budgetTokens,
       perScope: opts.fallbackPerScope,
+      pickLimit: opts.pickLimit,
     });
     if (fallback.length > 0) {
       fallbackUsed = true;
@@ -400,6 +403,7 @@ function fallbackScopedSegments(index, opts) {
   const scopes = prioritizeFallbackScopes(filterScopes(opts.relevantScopes || [], opts.ownVpId || null));
   const perScope = Number.isFinite(opts.perScope) && opts.perScope > 0 ? Math.floor(opts.perScope) : 2;
   const budgetTokens = Number.isFinite(opts.budgetTokens) && opts.budgetTokens > 0 ? opts.budgetTokens : 1200;
+  const pickLimit = Number.isFinite(opts.pickLimit) && opts.pickLimit > 0 ? Math.floor(opts.pickLimit) : 8;
   const buckets = [];
   for (const scope of scopes) {
     let segs = [];
@@ -419,6 +423,7 @@ function fallbackScopedSegments(index, opts) {
       if (!seg) continue;
       const tk = approxTokens(seg.body || '');
       if (tk <= 0 || cost + tk > budgetTokens) continue;
+      if (out.length >= pickLimit) return out;
       out.push(seg);
       cost += tk;
     }