sweet-search 2.6.13 → 2.6.15

package/core/infrastructure/code-graph-repository.js

@@ -312,6 +312,77 @@ export class CodeGraphRepository {
     }
   }
 
+  /**
+   * Find the named entities immediately ADJACENT to a shown line window in
+   * the same file: the nearest ones lying fully ABOVE the window
+   * (end_line < startLine) and the nearest ones starting BELOW it
+   * (start_line > endLine). Powers the agent-format same-file span map —
+   * the pointer that tells an agent which sibling symbols sit just outside
+   * the chunk window it was shown.
+   *
+   * Entities enclosing the window (e.g. the surrounding class) never match
+   * either predicate, so results are true siblings. Inner entities contained
+   * in an already-kept row (closures inside the adjacent function) are
+   * filtered so the map names outermost neighbors only.
+   *
+   * @param {string} filePath
+   * @param {number} startLine - first shown line (1-based)
+   * @param {number} endLine - last shown line (1-based)
+   * @param {{ perSide?: number }} [opts] - max entities per side (default 2)
+   * @returns {{ above: Array<{id,name,type,startLine,endLine,parentClass}>,
+   *             below: Array<{id,name,type,startLine,endLine,parentClass}> }}
+   */
+  findAdjacentEntities(filePath, startLine, endLine, opts = {}) {
+    const perSide = opts.perSide ?? 2;
+    const empty = { above: [], below: [] };
+    if (!filePath || !Number.isFinite(startLine) || !Number.isFinite(endLine)) return empty;
+    const db = this._open();
+    if (!db) return empty;
+    const mapRow = row => ({
+      id: row.id,
+      name: row.name,
+      type: row.type,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      parentClass: row.parent_class || null,
+    });
+    // Keep outermost neighbors: drop rows contained in an already-kept row.
+    const keepOutermost = rows => {
+      const kept = [];
+      for (const row of rows) {
+        if (kept.some(k => row.start_line >= k.start_line && row.end_line <= k.end_line)) continue;
+        kept.push(row);
+        if (kept.length >= perSide) break;
+      }
+      return kept.map(mapRow);
+    };
+    try {
+      const aboveRows = prepareCached(db, `
+        SELECT id, name, type, start_line, end_line, parent_class
+        FROM entities
+        WHERE file_path = ?
+          AND end_line < ?
+          AND name IS NOT NULL AND name != ''
+          AND ${this._entityVisibilitySql(db)}
+        ORDER BY end_line DESC, start_line ASC
+        LIMIT 8
+      `).all(filePath, startLine, ...this._entityVisibilityParams(db));
+      const belowRows = prepareCached(db, `
+        SELECT id, name, type, start_line, end_line, parent_class
+        FROM entities
+        WHERE file_path = ?
+          AND start_line > ?
+          AND name IS NOT NULL AND name != ''
+          AND ${this._entityVisibilitySql(db)}
+        ORDER BY start_line ASC, end_line DESC
+        LIMIT 8
+      `).all(filePath, endLine, ...this._entityVisibilityParams(db));
+      return { above: keepOutermost(aboveRows), below: keepOutermost(belowRows) };
+    } catch {
+      return empty;
+    }
+  }
+
   /**
    * Get a single entity by id, with file:line metadata.
    *

package/core/search/context-expander.js

@@ -19,6 +19,7 @@
  */
 
 import { readFileRange } from './search-pattern-chunks.js';
+import { computeSufficiencyVerdict } from './query-sufficiency.js';
 import { statSync } from 'fs';
 import path from 'path';
 
@@ -1130,15 +1131,34 @@ function unresolvedExternalRefs(code, ownSymbolName, headerContext, neighborsRen
  *                            or in the surfaced neighbours list
  *   - high_confidence     : score gap puts top-1 well ahead of top-2
  *
- * sufficient := complete_symbol
- *               AND (header_resolved OR neighbors_present OR self_contained_strict)
- *               AND (high_confidence OR header_resolved OR neighbors_present)
+ * Query-conditioned rule (July 2026 — full200 bench forensics showed the
+ * structural rule mislabels systemically: `confidence=low sufficient=YES`
+ * was the modal trailer, 156×, and reasons were structural in ~all cases):
+ * the verdict is now 3-valued and REQUIRES positive query-match evidence
+ * in top-1 (see core/search/query-sufficiency.js):
+ *
+ *   yes     := strong query evidence (exact anchor hit or high subtoken
+ *              overlap) AND (confidence=high OR (confidence=medium AND
+ *              structural resolution))
+ *   no      := no results, or a query with real anchors finding nothing
+ *              in top-1 (confirmed absence)
+ *   unknown := everything ambiguous (incl. the old structural-only YES,
+ *              now reported as reason=well_formed_only)
+ *
+ * Structural facts (complete_symbol / header_resolved / neighbors_present /
+ * self_contained_strict) are kept as diagnostic reasons and as the
+ * resolution gate for medium-confidence YES — they can no longer produce
+ * YES on their own. `sufficient` (boolean) stays = (verdict === 'yes') for
+ * every structured consumer (MCP zod schema, bench counters).
  *
  * @param {object} topResult
  * @param {{ confidence: string }} confidenceInfo
- * @returns {{ sufficient: boolean, reasons: string[], unresolvedExternalCount: number }}
+ * @param {{ query?: string, regex?: string, lowerResults?: object[] }} [queryContext]
+ * @returns {{ sufficient: boolean, verdict: 'yes'|'no'|'unknown',
+ *             sufficiencyReason: string, reasons: string[],
+ *             unresolvedExternalCount: number, evidence: object|null }}
  */
-export function computeSufficiency(topResult, confidenceInfo) {
+export function computeSufficiency(topResult, confidenceInfo, queryContext = {}) {
   const reasons = [];
 
   const isComplete = !!(topResult.symbol &&
@@ -1168,16 +1188,31 @@ export function computeSufficiency(topResult, confidenceInfo) {
 
   if (confidenceInfo?.confidence === 'high') reasons.push('high_confidence');
 
-  // Tightened rule: complete symbol is necessary but NOT sufficient.
-  // We require at least one resolution reason AND at least one specificity
-  // reason. This stops a bare "complete + high_confidence" from claiming
-  // sufficient when the body still references a dozen helpers we never
-  // surfaced (the validation-pipeline failure mode).
   const hasResolution = hasHeader || hasNeighbors || reasons.includes('self_contained_strict');
-  const hasSpecificity = confidenceInfo?.confidence === 'high' || hasHeader || hasNeighbors;
-  const sufficient = isComplete && hasResolution && hasSpecificity;
 
-  return { sufficient, reasons, unresolvedExternalCount: unresolvedCount };
+  // Query-conditioned verdict: structural facts are the resolution gate,
+  // never the whole answer. See query-sufficiency.js for the fusion rule.
+  const { verdict, reason: sufficiencyReason, evidence } = computeSufficiencyVerdict({
+    topResult,
+    confidenceInfo,
+    query: queryContext.query || '',
+    regex: queryContext.regex || '',
+    structural: { isComplete, hasResolution },
+    lowerResults: queryContext.lowerResults || [],
+  });
+
+  if (evidence?.exactHit) reasons.push('query_literal_matched');
+  else if (evidence?.strength === 'strong') reasons.push('query_token_overlap');
+  else if (evidence?.strength === 'none') reasons.push('no_query_evidence');
+
+  return {
+    sufficient: verdict === 'yes',
+    verdict,
+    sufficiencyReason,
+    reasons,
+    unresolvedExternalCount: unresolvedCount,
+    evidence,
+  };
 }
 
 // =============================================================================
@@ -1896,6 +1931,40 @@ export function selectAgentBudget(format, signals, opts = {}) {
  *   'no-syntax-expansion', 'no-header', 'no-diversity', 'no-adaptive-budget'
  * @returns {object} Agent mode response
  */
+/**
+ * Same-file span map (2026-07, within-file blind-spot fix). When the top-1
+ * pack entry is a WINDOWED view of a file (kind chunk/sandwich/syntax — not
+ * a fully-shown symbol) and the sufficiency verdict is not a clear YES, one
+ * compact line names the sibling symbols immediately above/below the shown
+ * window so the agent can sweep the fix surface instead of leaving the file
+ * (the fhir/sushi-1175 miss shape: right file, bug 30 lines above the
+ * window). Names+kinds+lines only — never bodies; ~25-45 tokens.
+ *
+ * @param {{ file:string, startLine:number, endLine:number }} top - top-1 agent result
+ * @param {{ above:Array, below:Array }} adjacent - findAdjacentEntities() result
+ * @returns {{ rendered:string, tokens:number, neighbors:Array }|null}
+ */
+export function buildSameFileMap(top, adjacent) {
+  const above = adjacent?.above || [];
+  const below = adjacent?.below || [];
+  if (above.length === 0 && below.length === 0) return null;
+  const shortType = t => (t === 'function' ? 'fn' : (t || 'sym'));
+  const fmt = (e, pos) => `${e.name} (${shortType(e.type)} ${e.startLine}-${e.endLine} ${pos})`;
+  const neighbors = [
+    ...above.map(e => ({ ...e, position: 'above' })),
+    ...below.map(e => ({ ...e, position: 'below' })),
+  ];
+  const parts = [
+    ...above.map(e => fmt(e, 'above')),
+    ...below.map(e => fmt(e, 'below')),
+  ];
+  // Placeholder-style drill-in hint (the v2.6.13 `ss-grep "<regex>" --in
+  // <file>` convention, which agents demonstrably follow) — embedding the
+  // live query costs ~25-30 tokens per pack for no extra signal.
+  const rendered = `# same file: ${parts.join(' · ')} — sweep: ss-semantic ${top.file} "<query>"`;
+  return { rendered, tokens: estimateTokens(rendered), neighbors };
+}
+
 export function packageForAgent(rankedResults, searchStats, opts) {
   const {
     query,
@@ -2287,19 +2356,78 @@ export function packageForAgent(rankedResults, searchStats, opts) {
 
   const packagingMs = Math.round(performance.now() - start);
 
-  // Sufficiency signal for top-1. Tightened in 2026-05: requires resolution
-  // (header_resolved OR neighbors_present OR self_contained_strict) instead
-  // of the old "complete_symbol + high_confidence" rule.
+  // Sufficiency signal for top-1. Query-conditioned since 2026-07: the
+  // 3-valued verdict requires positive query-match evidence; structural
+  // packaging facts remain as reasons + the medium-confidence resolution
+  // gate. Runs for summary-only top-1 too (verdict can be 'no'/'unknown'
+  // there; never 'yes' without code).
   let sufficient = false;
+  let sufficiencyVerdict = 'no';
+  let sufficiencyReason = 'no_results';
   let sufficiencyReasons = [];
   let unresolvedExternalCount = 0;
-  if (agentResults.length > 0 && agentResults[0].code) {
-    const sufficiency = computeSufficiency(agentResults[0], confidenceInfo);
+  if (agentResults.length > 0) {
+    const sufficiency = computeSufficiency(agentResults[0], confidenceInfo, {
+      query,
+      regex,
+      // Code-bearing lower ranks (full/preview) — soften a false 'no' when
+      // the pack's answer sits below top-1; never used to grant YES.
+      lowerResults: agentResults.slice(1, 4).filter(r => r.code),
+    });
     sufficient = sufficiency.sufficient;
+    sufficiencyVerdict = sufficiency.verdict;
+    sufficiencyReason = sufficiency.sufficiencyReason;
     sufficiencyReasons = sufficiency.reasons;
     unresolvedExternalCount = sufficiency.unresolvedExternalCount || 0;
   }
 
+  // Phase 7: same-file span map (top-1 only). Emitted ONLY when the verdict
+  // is not a clear YES (composes with the query-conditioned verdict: the map
+  // supplies the "where to look next" exactly when the engine says "keep
+  // looking") AND top-1 is a windowed view (kind != 'full' — fully-shown
+  // symbols stay byte-identical) AND the line fits the remaining tier
+  // budget (dropped on overflow, never a truncated pack). Its tokens are
+  // counted inside tokensUsed. Disabled by 'no-same-file-map' ablation.
+  if (!ablations.has('no-same-file-map')
+      && agentResults.length > 0
+      && sufficiencyVerdict !== 'yes'
+      && codeGraphRepo
+      && typeof codeGraphRepo.findAdjacentEntities === 'function') {
+    const top = agentResults[0];
+    const windowed = top.code
+      && top.presentation !== 'summary'
+      && top.expansionKind
+      && top.expansionKind !== 'full'
+      && top.file
+      && Number.isFinite(top.startLine)
+      && Number.isFinite(top.endLine);
+    if (windowed) {
+      let adjacent = null;
+      try {
+        adjacent = codeGraphRepo.findAdjacentEntities(top.file, top.startLine, top.endLine, { perSide: 2 });
+      } catch { adjacent = null; }
+      // Don't name neighbors whose code is ALREADY visible in the pack —
+      // locality clustering pulls same-file companions to ranks 2-3; a map
+      // entry for a shown span is pure noise.
+      if (adjacent) {
+        const shownSameFile = agentResults.filter(r =>
+          r !== top && r.code && r.file === top.file
+          && Number.isFinite(r.startLine) && Number.isFinite(r.endLine));
+        const overlapsShown = e => shownSameFile.some(r =>
+          e.startLine <= r.endLine && e.endLine >= r.startLine);
+        adjacent = {
+          above: adjacent.above.filter(e => !overlapsShown(e)),
+          below: adjacent.below.filter(e => !overlapsShown(e)),
+        };
+      }
+      const map = adjacent ? buildSameFileMap(top, adjacent) : null;
+      if (map && map.tokens <= Math.max(0, tokenBudget - tokensUsed)) {
+        top.sameFile = map;
+        tokensUsed += map.tokens;
+      }
+    }
+  }
+
   return {
     query,
     regex,
@@ -2317,6 +2445,8 @@ export function packageForAgent(rankedResults, searchStats, opts) {
     confidence: confidenceInfo.confidence,
     confidenceReason: confidenceInfo.confidenceReason,
     sufficient,
+    sufficiencyVerdict,
+    sufficiencyReason,
     sufficiencyReasons,
     unresolvedExternalCount,
 

package/core/search/query-sufficiency.js

@@ -0,0 +1,341 @@
+/**
+ * Query-conditioned sufficiency evidence (2026-07).
+ *
+ * Answers ONE question, cheaply: does the top-1 packaged hit contain
+ * positive evidence that it matches what the QUERY asked for? This is the
+ * signal the structural sufficiency rule (complete_symbol / header_resolved /
+ * neighbors_present) never looked at — a perfectly well-formed function that
+ * has nothing to do with the query must not earn `sufficient=YES`.
+ *
+ * Literature anchor: Sufficient Context (Joren et al., ICLR 2025) — a naive
+ * lexical answer-presence check alone reaches F1 0.81 / precision 0.87 on
+ * sufficiency; fusing it (AND, not weighted sum) with an independent
+ * confidence signal is the high-precision pattern. See
+ * eval/task-completion-bench/analysis/sufficiency-redesign-2026-07-06.md.
+ *
+ * Constraints honoured here:
+ *  - engine-local, query-time only: pure string work over the already-
+ *    retrieved top-1 (haystack capped), no I/O, no LLM, sub-millisecond;
+ *  - only ever invoked from packageForAgent (agent formats) — NL/GCSN
+ *    ranking paths never reach this module;
+ *  - identifier-SHAPE heuristics, not capture-filtering stopword lists
+ *    (CLAUDE.md rule): the only stopword set below is a stable ~30-entry
+ *    English query-tokenization list.
+ */
+
+// Query-tokenization stopwords (standard English IR practice — the "OK to
+// keep" category). Filters function words from the subtoken-overlap signal;
+// never used to filter identifier captures.
+const EVIDENCE_STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'can', 'could', 'did', 'do', 'does', 'for',
+  'from', 'how', 'in', 'into', 'is', 'it', 'its', 'not', 'of', 'on', 'or',
+  'should', 'that', 'the', 'this', 'to', 'was', 'were', 'what', 'when',
+  'where', 'which', 'with',
+]);
+
+function envFloat(name, fallback) {
+  const raw = process.env[name];
+  if (raw == null || raw === '') return fallback;
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback;
+}
+
+// Thresholds are parameterized (env-overridable for offline calibration
+// sweeps) — tuned on the task-level dev split of the full200 replay, never
+// hand-picked against held-out. See the design note for the discipline.
+export function sufficiencyThresholds() {
+  return {
+    overlapStrong: envFloat('SS_SUFF_OVERLAP_STRONG', 0.6),
+    overlapNone: envFloat('SS_SUFF_OVERLAP_NONE', 0.2),
+    minInformativeSubtokens: 2,
+    haystackCap: 32768,
+  };
+}
+
+const WORD_CHAR = /[A-Za-z0-9_$]/;
+
+function isWordChar(ch) {
+  return ch != null && WORD_CHAR.test(ch);
+}
+
+/**
+ * Word-boundary substring check without compiling a regex per token.
+ * A match counts only when the char before and after the occurrence are
+ * not identifier chars ("Chunker" must not match inside "ChunkerParams"
+ * unless the query token IS ChunkerParams).
+ */
+export function containsToken(haystack, token, { caseSensitive = true } = {}) {
+  if (!haystack || !token) return false;
+  const hay = caseSensitive ? haystack : haystack.toLowerCase();
+  const needle = caseSensitive ? token : token.toLowerCase();
+  let from = 0;
+  while (from <= hay.length - needle.length) {
+    const idx = hay.indexOf(needle, from);
+    if (idx === -1) return false;
+    const before = idx > 0 ? hay[idx - 1] : null;
+    const after = idx + needle.length < hay.length ? hay[idx + needle.length] : null;
+    if (!isWordChar(before) && !isWordChar(after)) return true;
+    from = idx + 1;
+  }
+  return false;
+}
+
+/**
+ * Identifier-shape heuristic (shape, not a word list): a token reads as a
+ * code identifier when it carries structure natural language words don't —
+ * camelCase humps, underscores/$, digits mixed into letters, dotted/pathy
+ * compounds, or ALL_CAPS constants. Pure lowercase single words ("parse",
+ * "config") are NOT identifier-shaped; they flow into the softer
+ * subtoken-overlap signal instead.
+ */
+export function looksLikeIdentifierToken(token) {
+  if (!token || token.length < 3) return false;
+  if (/[_$]/.test(token)) return true;
+  if (/[a-z][A-Z]/.test(token)) return true;                      // camelCase hump
+  if (/[A-Za-z]\d|\d[A-Za-z]/.test(token)) return true;           // letters+digits
+  if (/[.:/\\-]/.test(token) && /[A-Za-z]{2,}/.test(token)) return true; // dotted/pathy
+  if (/^[A-Z][A-Z0-9]{2,}$/.test(token)) return true;             // SCREAMING caps
+  if (/^[A-Z][a-z]+[A-Z]/.test(token)) return true;               // PascalCase
+  return false;
+}
+
+/**
+ * Pull literal runs out of a user regex (ss-find / ss-grep patterns):
+ * unescape metachar escapes, drop anchors, split on regex syntax, keep
+ * word-ish runs of length ≥ 3. "\\bChunkerParams\\b" → ["ChunkerParams"].
+ */
+export function regexLiteralRuns(regexSource) {
+  if (!regexSource) return [];
+  const unescaped = String(regexSource)
+    .replace(/\\[bBdDsSwWAZz]/g, ' ')       // char-class/anchor escapes → separator
+    .replace(/\\([^A-Za-z0-9])/g, '$1');    // \. \( … → literal char
+  const runs = unescaped.split(/[\^$.|?*+()[\]{}<>=!,\s]+/);
+  const out = [];
+  for (const run of runs) {
+    const trimmed = run.replace(/^[-:/\\]+|[-:/\\]+$/g, '');
+    if (trimmed.length >= 3 && /[A-Za-z]/.test(trimmed)) out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * Split text into normalized informative subtokens: identifier chunks are
+ * split on case humps / non-alnum, lowercased, stopword- and length-filtered.
+ * Single-pass character scanner — this runs over the top-1 haystack on every
+ * agent-format search, so it must stay well under a millisecond at 32KB.
+ */
+export function informativeSubtokens(text) {
+  const out = new Set();
+  if (!text) return out;
+  const s = String(text);
+  const n = s.length;
+  let start = -1;        // current subtoken start
+  let hasAlpha = false;  // subtoken contains a letter (pure digits dropped)
+  const flush = (end) => {
+    if (start === -1) return;
+    if (hasAlpha && end - start >= 3) {
+      const norm = s.slice(start, end).toLowerCase();
+      if (!EVIDENCE_STOPWORDS.has(norm)) out.add(norm);
+    }
+    start = -1;
+    hasAlpha = false;
+  };
+  let prevLower = false; // previous char was a lowercase letter or digit
+  let prevUpper = false; // previous char was uppercase
+  for (let i = 0; i < n; i++) {
+    const c = s.charCodeAt(i);
+    const isLower = c >= 97 && c <= 122;
+    const isUpper = c >= 65 && c <= 90;
+    const isDigit = c >= 48 && c <= 57;
+    if (isLower || isUpper || isDigit) {
+      // camelCase hump: aB starts a new subtoken; ABc splits before the 'Bc'.
+      if (start !== -1 && isUpper && prevLower) {
+        flush(i);
+      } else if (start !== -1 && isLower && prevUpper && i - start >= 2) {
+        const split = i - 1; // "HTTPServer" → "http" + "server"
+        if (split - start >= 3) {
+          const norm = s.slice(start, split).toLowerCase();
+          if (!EVIDENCE_STOPWORDS.has(norm)) out.add(norm);
+        }
+        start = split;
+        hasAlpha = true;
+      }
+      if (start === -1) { start = i; hasAlpha = false; }
+      if (isLower || isUpper) hasAlpha = true;
+      prevLower = isLower || isDigit;
+      prevUpper = isUpper;
+    } else {
+      flush(i);
+      prevLower = false;
+      prevUpper = false;
+    }
+  }
+  flush(n);
+  return out;
+}
+
+/**
+ * Extract the query's evidence anchors.
+ *
+ * @param {string} query   natural-language or symbol query
+ * @param {string} [regex] optional user regex (ss-find)
+ * @returns {{ anchors: string[], subtokens: Set<string> }}
+ *   anchors: exact-match candidates (quoted literals, identifier-shaped
+ *   tokens, regex literal runs) — checked verbatim with word boundaries;
+ *   subtokens: normalized informative subtokens for the overlap signal.
+ */
+export function extractQueryEvidence(query, regex) {
+  const q = String(query || '');
+  const anchors = [];
+  const seen = new Set();
+  const push = (tok) => {
+    if (tok && tok.length >= 3 && !seen.has(tok)) { seen.add(tok); anchors.push(tok); }
+  };
+
+  // Quoted literals (error strings, config keys) — strongest anchors.
+  const quoteRe = /"([^"\n]{3,120})"|'([^'\n]{3,120})'|`([^`\n]{3,120})`/g;
+  let m;
+  while ((m = quoteRe.exec(q)) !== null) push(m[1] || m[2] || m[3]);
+
+  // Identifier-shaped tokens from the query text.
+  for (const raw of q.split(/[\s,;()"'`]+/)) {
+    const tok = raw.replace(/^[^A-Za-z0-9_$]+|[^A-Za-z0-9_$)]+$/g, '');
+    if (looksLikeIdentifierToken(tok)) push(tok);
+  }
+
+  // Literal runs from the regex (the exact thing the caller greps for).
+  for (const run of regexLiteralRuns(regex)) push(run);
+
+  return { anchors, subtokens: informativeSubtokens(q) };
+}
+
+/**
+ * Assess query-match evidence in the top-1 packaged result.
+ *
+ * @param {string} query
+ * @param {string} regex
+ * @param {object} topResult  packaged agent result (symbol, file, code,
+ *                            headerContext, summary)
+ * @returns {{ strength: 'strong'|'partial'|'none', exactHit: boolean,
+ *             matchedAnchor: string|null, overlap: number,
+ *             informativeCount: number }}
+ */
+export function assessQueryEvidence(query, regex, topResult) {
+  const t = sufficiencyThresholds();
+  const { anchors, subtokens } = extractQueryEvidence(query, regex);
+
+  const haystackParts = [
+    topResult?.symbol || '',
+    topResult?.file || '',
+    topResult?.headerContext || '',
+    topResult?.summary || '',
+    topResult?.code || '',
+  ];
+  const haystack = haystackParts.join('\n').slice(0, t.haystackCap);
+
+  let exactHit = false;
+  let matchedAnchor = null;
+  for (const anchor of anchors) {
+    // Case-sensitive when the anchor carries case information; boundary-
+    // checked either way so "Chunker" can't match inside "ChunkerParams".
+    const caseSensitive = /[A-Z]/.test(anchor);
+    if (containsToken(haystack, anchor, { caseSensitive })) {
+      exactHit = true;
+      matchedAnchor = anchor;
+      break;
+    }
+  }
+
+  const informativeCount = subtokens.size;
+  let overlap = 0;
+  if (informativeCount > 0) {
+    const hayTokens = informativeSubtokens(haystack);
+    let matched = 0;
+    for (const tok of subtokens) if (hayTokens.has(tok)) matched++;
+    overlap = matched / informativeCount;
+  }
+
+  let strength = 'partial';
+  if (exactHit || (overlap >= t.overlapStrong && informativeCount >= t.minInformativeSubtokens)) {
+    strength = 'strong';
+  } else if (informativeCount >= t.minInformativeSubtokens && overlap <= t.overlapNone) {
+    // Only a query with enough informative tokens can CONFIRM absence —
+    // a 1-token NL query never earns a discouraging 'none'.
+    strength = 'none';
+  }
+
+  return { strength, exactHit, matchedAnchor, overlap, informativeCount };
+}
+
+/**
+ * Fuse query-match evidence with the engine's confidence bucket and the
+ * structural packaging facts into a 3-valued verdict.
+ *
+ * Rule (design note §2; stricter-YES direction):
+ *   - YES requires strong evidence AND (confidence=high, or confidence=medium
+ *     with resolved structural context). Packaging alone can never say YES;
+ *     confidence=low can never say YES.
+ *   - 'no' is reserved for confirmed absence (no results, or a query with
+ *     real anchors/subtokens finding nothing in top-1). The borg-style
+ *     false-no — literal present with a clear margin — becomes YES.
+ *   - everything ambiguous is 'unknown', never a false binary.
+ *
+ * @param {object} args
+ * @param {object|null} args.topResult
+ * @param {{confidence: string}|null} args.confidenceInfo
+ * @param {string} args.query
+ * @param {string} [args.regex]
+ * @param {{isComplete: boolean, hasResolution: boolean}} args.structural
+ * @param {object[]} [args.lowerResults] code-bearing results below top-1
+ *   (full/preview tiers) — consulted ONLY to soften a would-be 'no': when
+ *   the pack's answer sits at rank 2-3, a flat 'no' would falsely push the
+ *   agent away from a pack that contains it. YES stays top-1-strict.
+ * @returns {{ verdict: 'yes'|'no'|'unknown', reason: string,
+ *             evidence: object|null }}
+ */
+export function computeSufficiencyVerdict({ topResult, confidenceInfo, query, regex, structural, lowerResults = [] }) {
+  if (!topResult) {
+    return { verdict: 'no', reason: 'no_results', evidence: null };
+  }
+
+  const evidence = assessQueryEvidence(query, regex, topResult);
+  const conf = confidenceInfo?.confidence || 'low';
+  const structuralOk = !!(structural?.isComplete && structural?.hasResolution);
+
+  if (evidence.strength === 'none') {
+    for (const r of lowerResults) {
+      if (!r || (!r.code && !r.symbol)) continue;
+      const lower = assessQueryEvidence(query, regex, r);
+      if (lower.strength === 'strong') {
+        return { verdict: 'unknown', reason: 'evidence_below_top1', evidence };
+      }
+    }
+    return { verdict: 'no', reason: 'no_query_evidence', evidence };
+  }
+
+  if (!topResult.code) {
+    // Summary-only top-1: the agent holds no code to answer from.
+    return { verdict: 'unknown', reason: 'top_summary_only', evidence };
+  }
+
+  if (evidence.strength === 'strong') {
+    if (conf === 'high') {
+      return { verdict: 'yes', reason: evidence.exactHit ? 'query_evidence_clear_margin' : 'query_overlap_clear_margin', evidence };
+    }
+    if (conf === 'medium') {
+      // Dev-split calibration (full200 replay): gating medium on structural
+      // resolution cost recall (0.35 vs 0.41) for no precision gain (0.706
+      // vs 0.700) — strong evidence + a medium margin is enough. Low never
+      // reaches yes: re-admitting low+exactHit dropped precision to 0.61.
+      return { verdict: 'yes', reason: 'query_evidence_moderate_margin', evidence };
+    }
+    return { verdict: 'unknown', reason: 'evidence_without_margin', evidence };
+  }
+
+  // Partial evidence — the old structural-YES shape lands here.
+  return {
+    verdict: 'unknown',
+    reason: structuralOk ? 'well_formed_only' : 'partial_query_evidence',
+    evidence,
+  };
+}

package/core/search/search-read.js

@@ -239,6 +239,48 @@ function _attachIndexMetadata(filePathRel, projectRoot) {
   return { indexed: true, chunks, language };
 }
 
+// ---------------------------------------------------------------------------
+// Remainder definition sniffing — fallback symbol names for the "what
+// remains" trailer when the index has no named chunks in the unread span
+// (e.g. C++ files where the chunker recorded `name: null`). Scans ONLY the
+// remainder lines of the buffer already in memory: zero I/O, capped.
+// ---------------------------------------------------------------------------
+
+const SNIFF_MAX_LINES = 4000;
+const UNREAD_SYMBOLS_MAX = 5;        // hard cap on named symbols in the trailer
+const UNREAD_SYMBOLS_MIN_LINES = 20; // smaller remainders get the short form
+const C_FAMILY_EXTS = new Set(['.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.hh', '.hxx', '.java', '.cs', '.m', '.mm']);
+
+// Keyword-introduced definitions (Python/Ruby/JS/TS/Go/Rust/Kotlin/PHP/...).
+const KEYWORD_DEF_RE = /^\s*(?:export\s+|default\s+|pub(?:\([^)]*\))?\s+|static\s+|async\s+|abstract\s+|final\s+|public\s+|private\s+|protected\s+|inline\s+|constexpr\s+|unsafe\s+|override\s+|open\s+|sealed\s+)*(?:def|fn|func|function\*?|class|struct|enum|trait|interface|impl|object|module|proc)\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*(?:(?:::|\.)[A-Za-z_][\w]*)*)/;
+// C-family definitions at low indent: `[return-type] Qualified::name(args...`
+// with no trailing `;` (declarations) — captures the identifier before the
+// first `(`. The return-type prefix is lazy so qualification stays intact.
+const C_DEF_RE = /^(?:[A-Za-z_][\w:<>,*&~\s]*?[\s*&]+)?((?:[A-Za-z_~][\w]*::)*(?:~?[A-Za-z_][\w]*|operator\s*[^\s(]{1,3}))\s*\(/;
+const C_CONTROL_RE = /^\s*(?:if|for|while|switch|return|else|do|catch|case|sizeof|new|delete|throw|goto|using|typedef)\b/;
+
+function _sniffRemainderDefinitions(text, isCFamily) {
+  const names = [];
+  const seen = new Set();
+  const lines = text.split('\n', SNIFF_MAX_LINES);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/\S/.test(line)) continue;
+    let name = null;
+    const kw = line.match(KEYWORD_DEF_RE);
+    if (kw) name = kw[1];
+    else if (isCFamily && /^[A-Za-z_]/.test(line) && !line.trimEnd().endsWith(';') && !C_CONTROL_RE.test(line)) {
+      const m = line.match(C_DEF_RE);
+      if (m) name = m[1].replace(/\s+/g, '');
+    }
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      names.push({ symbol: name, type: null, startLine: i + 1 }); // startLine relative; caller offsets
+    }
+  }
+  return names;
+}
+
 // ---------------------------------------------------------------------------
 // Public API — single read
 // ---------------------------------------------------------------------------
@@ -293,6 +335,47 @@ async function _readFileUnpinned(req) {
     language = meta.language;
   }
 
+  // "What remains" trailer data (2026-07, within-file blind-spot fix): when
+  // a range read stops before EOF, record what the UNREAD remainder below
+  // the window contains — computed from the full chunk table BEFORE the
+  // overlap-narrowing just below. A bare "(lines a-b of N)" marker is
+  // provably ignored by agents (the botan-2738 shape: three reads, never
+  // past line 205 of 272, fix surface below); naming the symbols is what
+  // makes the remainder actionable. Whole-file reads and read-to-EOF stay
+  // byte-identical (unreadBelow stays null).
+  let unreadBelow = null;
+  if (wantsRange && sliced.totalLines > 0 && sliced.endLine < sliced.totalLines) {
+    // Token diet: a tiny remainder needs no symbol list — the range plus the
+    // continue command IS the affordance; names only earn their tokens when
+    // the unread span is big enough to hide a sibling branch.
+    const remainderLines = sliced.totalLines - sliced.endLine;
+    const seen = new Set();
+    let symbols = [];
+    if (remainderLines >= UNREAD_SYMBOLS_MIN_LINES) {
+      for (const c of chunks) {
+        if (c.startLine == null || c.startLine <= sliced.endLine) continue;
+        if (!c.symbol || seen.has(c.symbol)) continue;
+        seen.add(c.symbol);
+        symbols.push({ symbol: c.symbol, type: c.type ?? null, startLine: c.startLine });
+      }
+      // Index had no named chunks in the remainder (common for C/C++ where the
+      // chunker stores name:null) — sniff definition lines from the in-memory
+      // buffer instead. Zero I/O; capped at SNIFF_MAX_LINES.
+      if (symbols.length === 0 && disk.text != null) {
+        const remainder = _sliceLines(disk.text, disk.lineOffsets, sliced.endLine + 1, sliced.totalLines);
+        const isCFamily = C_FAMILY_EXTS.has(path.extname(absPath).toLowerCase());
+        symbols = _sniffRemainderDefinitions(remainder.text, isCFamily)
+          .map(s => ({ ...s, startLine: sliced.endLine + s.startLine }));
+      }
+    }
+    unreadBelow = {
+      startLine: sliced.endLine + 1,
+      endLine: sliced.totalLines,
+      symbols: symbols.slice(0, UNREAD_SYMBOLS_MAX),
+      moreCount: Math.max(0, symbols.length - UNREAD_SYMBOLS_MAX),
+    };
+  }
+
   // If a line range was requested, narrow attached chunks to the overlap.
   if (wantsRange && chunks.length) {
     chunks = chunks.filter(c =>
@@ -315,6 +398,7 @@ async function _readFileUnpinned(req) {
     range: wantsRange ? { startLine: sliced.startLine, endLine: sliced.endLine } : null,
     text: sliced.text,
     chunks,
+    unreadBelow,
     timings: { totalMs: +(performance.now() - t0).toFixed(2) },
   };
 }
@@ -362,6 +446,28 @@ export async function readFiles(files, opts = {}) {
 // Formatting
 // ---------------------------------------------------------------------------
 
+/**
+ * Render the "what remains" trailer for a range read that stopped before
+ * EOF. Names the symbols in the unread remainder plus the exact continue
+ * command — the actionable form (a bare truncation marker is ignored;
+ * see the 2026-07 within-file design note). Returns '' when the read
+ * covered the whole file / reached EOF.
+ *
+ * @param {Object} result - readFile() result
+ * @param {{ command?: 'read'|'ss-read' }} [opts] - continue-command surface
+ * @returns {string} one line without trailing newline, or ''
+ */
+export function renderUnreadBelow(result, { command = 'read' } = {}) {
+  const u = result?.unreadBelow;
+  if (!u) return '';
+  const names = (u.symbols || []).map(s => s.symbol).join(', ');
+  const more = u.moreCount > 0 ? ` +${u.moreCount} more` : '';
+  const cont = command === 'ss-read'
+    ? `ss-read ${result.file} ${u.startLine} ${u.endLine}`
+    : `read ${result.file} ${u.startLine}-${u.endLine}`;
+  return `# unread below (${u.startLine}-${u.endLine})${names ? ': ' + names + more : ''} — continue: ${cont}`;
+}
+
 function _formatAgent(result) {
   if (!result.ok) {
     return `### ${result.file}\n[error] ${result.error}\n`;
@@ -377,7 +483,8 @@ function _formatAgent(result) {
       .filter(Boolean);
     if (names.length) symbolHint = `\nsymbols: ${names.join(', ')}`;
   }
-  return `### ${result.file}${range}${symbolHint}\n${fence}\n${result.text}\n\`\`\`\n`;
+  const remainder = renderUnreadBelow(result);
+  return `### ${result.file}${range}${symbolHint}\n${fence}\n${result.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`;
 }
 
 export function formatReadResults(results, format = 'agent') {

package/eval/agent-read-workflows/bin/_ss-argparse.mjs

@@ -192,3 +192,18 @@ export function extractPositional(args) {
   if (bad) return { pattern: undefined, unknownFlag: bad };
   return { pattern: args[0], unknownFlag: null };
 }
+
+// --- trailer rendering --------------------------------------------------------
+
+// Sufficiency trailer segment: 3-valued verdict (YES / no / unknown) + a
+// compact why-token, e.g. ` sufficient=YES (query_evidence_clear_margin)` vs
+// ` sufficient=unknown (well_formed_only)`. Falls back to the legacy boolean
+// when the engine predates sufficiencyVerdict. The full line shape stays
+// `# confidence=<bucket> (<reason>) sufficient=<verdict> (<why>)`.
+export function renderSufficiency(response) {
+  const verdict = response.sufficiencyVerdict
+    ? (response.sufficiencyVerdict === 'yes' ? 'YES' : response.sufficiencyVerdict)
+    : (response.sufficient ? 'YES' : 'no');
+  const why = response.sufficiencyReason ? ` (${response.sufficiencyReason})` : '';
+  return ` sufficient=${verdict}${why}`;
+}

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 import {
   parseBoolFlag, parseValueFlag, parsePositiveIntFlag,
   buildGrepPattern, stripInertFlags, normalizeArgs, extractPositional,
-  parseLineRange, looksLikeOption,
+  parseLineRange, looksLikeOption, renderSufficiency,
 } from './_ss-argparse.mjs';
 import { renderGrepBody } from '../../../core/search/grep-output-shaping.js';
 
@@ -222,7 +222,7 @@ async function cmdFind(rawArgs) {
     ` budget=${response.tokenBudget} used=${response.tokensUsed} subMode=${response.subMode ?? format}\n`);
   if (response.confidence) {
     process.stdout.write(`# confidence=${response.confidence}${response.confidenceReason ? ' (' + response.confidenceReason + ')' : ''}` +
-      `${response.sufficient ? ' sufficient=YES' : ' sufficient=no'}\n`);
+      `${renderSufficiency(response)}\n`);
   }
 
   // Per-result blocks — identical shape to ss-search's agent packaging.
@@ -242,6 +242,11 @@ async function cmdFind(rawArgs) {
     if (r.neighbors && r.neighbors.rendered) {
       process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
     }
+    // Same-file span map (top-1, windowed chunk, verdict != YES): sibling
+    // symbols just outside the shown window + a copy-paste drill-in command.
+    if (r.sameFile && r.sameFile.rendered) {
+      process.stdout.write(`${r.sameFile.rendered}\n`);
+    }
   }
   if (!response.results || response.results.length === 0) process.stdout.write('(no matches)\n');
   process.exit(0);
@@ -297,7 +302,7 @@ async function cmdRead(args) {
       }
     }
   }
-  const { readFile } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
+  const { readFile, renderUnreadBelow } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
   const r = await readFile({ path: file, projectRoot: PROJECT_ROOT, startLine: start ?? undefined, endLine: end ?? undefined });
   if (!r.ok) {
     process.stderr.write(`[ss-read] error: ${r.error}\n`);
@@ -305,7 +310,11 @@ async function cmdRead(args) {
   }
   const range = r.range ? ` (lines ${r.range.startLine}-${r.range.endLine} of ${r.totalLines})` : ` (${r.totalLines} lines)`;
   const fence = r.language ? '```' + r.language : '```';
-  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`\n`);
+  // "What remains" trailer: on a range read that stops before EOF, one final
+  // line names the symbols in the unread remainder + the exact continue
+  // command (last line for recency — the actionable form of truncation).
+  const remainder = renderUnreadBelow(r, { command: 'ss-read' });
+  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`${remainder ? '\n' + remainder : ''}\n`);
   process.exit(0);
 }
 
@@ -417,7 +426,7 @@ async function cmdAgentSearch(rawArgs) {
     ` results=${response.results.length} subMode=${response.subMode}\n`);
   if (response.confidence) {
     process.stdout.write(`# confidence=${response.confidence}${response.confidenceReason ? ' (' + response.confidenceReason + ')' : ''}` +
-      `${response.sufficient ? ' sufficient=YES' : ' sufficient=no'}\n`);
+      `${renderSufficiency(response)}\n`);
   }
 
   // Per-result blocks
@@ -441,6 +450,11 @@ async function cmdAgentSearch(rawArgs) {
     if (r.neighbors && r.neighbors.rendered) {
       process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
     }
+    // Same-file span map (top-1, windowed chunk, verdict != YES): sibling
+    // symbols just outside the shown window + a copy-paste drill-in command.
+    if (r.sameFile && r.sameFile.rendered) {
+      process.stdout.write(`${r.sameFile.rendered}\n`);
+    }
   }
 
   if (!response.results || response.results.length === 0) {
@@ -474,9 +488,13 @@ async function cmdAgentSearch(rawArgs) {
     headerCount,
     confidence: response.confidence || null,
     sufficient: response.sufficient ?? null,
+    sufficiencyVerdict: response.sufficiencyVerdict ?? null,
+    sufficiencyReason: response.sufficiencyReason ?? null,
     sufficiencyReasons: Array.isArray(response.sufficiencyReasons) ? response.sufficiencyReasons : null,
     unresolvedExternalCount: typeof response.unresolvedExternalCount === 'number'
       ? response.unresolvedExternalCount : null,
+    sameFileMapTokens: response.results?.[0]?.sameFile?.tokens ?? null,
+    sameFileNeighborCount: response.results?.[0]?.sameFile?.neighbors?.length ?? null,
   };
   process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(meta)}\n`);
   process.exit(0);

package/mcp/read-tool.js

@@ -23,6 +23,16 @@ const ReadFileResultSchema = z.object({
     endLine: z.number().int().nullable().optional(),
     signature: z.string().nullable().optional(),
   })).optional(),
+  unreadBelow: z.object({
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    symbols: z.array(z.object({
+      symbol: z.string(),
+      type: z.string().nullable().optional(),
+      startLine: z.number().int().nullable().optional(),
+    })),
+    moreCount: z.number().int(),
+  }).nullable().optional(),
   error: z.string().optional(),
   timings: z.object({ totalMs: z.number() }).optional(),
 });

package/mcp/tool-handlers.js

@@ -42,6 +42,8 @@ export const SearchOutputSchema = z.object({
   confidence: z.enum(['high', 'medium', 'low']).optional(),
   confidenceReason: z.string().optional(),
   sufficient: z.boolean().optional(),
+  sufficiencyVerdict: z.enum(['yes', 'no', 'unknown']).optional(),
+  sufficiencyReason: z.string().optional(),
   sufficiencyReasons: z.array(z.string()).optional(),
   packagingMs: z.number().optional(),
   latencyMs: z.number().optional(),
@@ -125,7 +127,14 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
           const header = `${r.rank}. ${r.file}:${r.startLine}-${r.endLine} (score: ${r.score.toFixed(3)}, ${r.presentation})`;
           const symbolInfo = r.symbol ? `\n   ${r.symbolType || 'symbol'}: ${r.symbol}` : '';
           const code = r.code ? `\n\`\`\`\n${r.code}\n\`\`\`` : '';
-          return header + symbolInfo + code;
+          // Same-file span map (top-1, windowed chunk, verdict != YES) —
+          // MCP phrasing references the MCP drill-in tool name.
+          const sameFile = (r.sameFile && r.sameFile.neighbors?.length)
+            ? `\n   Same file: ${r.sameFile.neighbors
+                .map(n => `${n.name} (${n.type === 'function' ? 'fn' : (n.type || 'sym')} ${n.startLine}-${n.endLine} ${n.position})`)
+                .join(' · ')} — sweep: read-semantic ${r.file}`
+            : '';
+          return header + symbolInfo + code + sameFile;
         });
 
       const summaries = agentResults
@@ -166,6 +175,8 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
         confidence: searchResult.confidence,
         confidenceReason: searchResult.confidenceReason,
         sufficient: searchResult.sufficient,
+        ...(searchResult.sufficiencyVerdict ? { sufficiencyVerdict: searchResult.sufficiencyVerdict } : {}),
+        ...(searchResult.sufficiencyReason ? { sufficiencyReason: searchResult.sufficiencyReason } : {}),
         sufficiencyReasons: searchResult.sufficiencyReasons || [],
         packagingMs: searchResult.packagingMs,
         latencyMs: searchResult.latencyMs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.6.13",
+  "version": "2.6.15",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -167,13 +167,13 @@
     "vitest": "^4.0.16"
   },
   "optionalDependencies": {
-    "@sweet-search/native-darwin-arm64": "2.6.13",
-    "@sweet-search/native-darwin-x64": "2.6.13",
-    "@sweet-search/native-linux-arm64-gnu": "2.6.13",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.6.13",
-    "@sweet-search/native-linux-x64-gnu": "2.6.13",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.6.13",
-    "@sweet-search/bg-priority": "2.6.13"
+    "@sweet-search/native-darwin-arm64": "2.6.15",
+    "@sweet-search/native-darwin-x64": "2.6.15",
+    "@sweet-search/native-linux-arm64-gnu": "2.6.15",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.6.15",
+    "@sweet-search/native-linux-x64-gnu": "2.6.15",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.6.15",
+    "@sweet-search/bg-priority": "2.6.15"
   },
   "engines": {
     "node": ">=18.0.0"