@cerefox/memory 1.14.2 → 1.14.4

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.14.2";
+export const EF_VERSION = "1.14.4";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.14.2";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.14.2";
+export const CEREFOX_VERSION = "1.14.4";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.14.2";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.14.2";
+export const EF_LAST_CHANGED = "1.14.4";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/_utils.ts

@@ -147,25 +147,32 @@ export function applyByteBudget(
   maxBytes: number,
 ): { accepted: unknown[]; dropped: unknown[]; truncated: boolean; usedBytes: number } {
   const accepted: unknown[] = [];
+  const dropped: unknown[] = [];
   let usedBytes = 0;
   let truncated = false;
-  let cut = rows.length;
 
-  for (const [i, row] of rows.entries()) {
+  for (const row of rows) {
     const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
+    // Skipped, not the end of the list (#266, #268). This used to `break`, so
+    // one oversized top hit suppressed every smaller result behind it: the
+    // Edge Function answered with an empty `accepted`, flipped to the degraded
+    // shape and stripped content from results 2 and 3 that would have fitted
+    // comfortably. The MCP tool has skipped since #266; this is the same rule
+    // reaching the surface GPT Actions and direct HTTP callers use.
     if (usedBytes + rowBytes > maxBytes) {
       truncated = true;
-      cut = i;
-      break;
+      dropped.push(row);
+      continue;
     }
     accepted.push(row);
     usedBytes += rowBytes;
   }
 
   // What did not fit, so a caller can say so instead of reporting nothing
-  // (#254): a first row larger than the budget empties `accepted` entirely,
+  // (#254): every row larger than the budget lands here — they are no longer
+  // a contiguous tail, because the scan no longer stops at the first one —
   // and "no results" is the one answer an agent acts on irreversibly.
-  return { accepted, dropped: rows.slice(cut), truncated, usedBytes };
+  return { accepted, dropped, truncated, usedBytes };
 }
 
 import type { AccessPath } from "./types.ts";
@@ -293,3 +300,28 @@ export function logUsage(supabase: MCPSupabaseClient, params: LogUsageParams): v
     }),
   ).catch(() => {});
 }
+
+/**
+ * Resolve a caller-supplied byte budget against the server ceiling.
+ *
+ * One implementation, because this arithmetic was written out by hand on four
+ * surfaces and each hand-written copy was wrong in its own way (#267, #268):
+ *
+ * - **Non-numeric means unset, not unbounded.** `Math.min("lots", CEILING)` is
+ *   `NaN`; `NaN` compares false against every `>` check and serialises to JSON
+ *   `null`, and `p_max_bytes NULL` means NO limit in Postgres. So the one
+ *   parameter that exists to bound a reply, handed a word, removed the bound.
+ * - **`null` and `undefined` mean unset too.** `Number(null)` is `0`, which is
+ *   finite, so a clamp to `>= 1` turned an explicitly-null budget into a
+ *   ONE-BYTE budget — a client that serialises optional fields as `null` asked
+ *   for content and got none.
+ * - **A real number of zero or less means "almost nothing", and is honoured.**
+ *   Falling back to the ceiling there would hand a caller whose allowance had
+ *   run out the largest possible reply.
+ */
+export function resolveByteBudget(requested: unknown, ceiling: number): number {
+  if (requested === null || requested === undefined || requested === "") return ceiling;
+  const n = Math.floor(Number(requested));
+  if (!Number.isFinite(n)) return ceiling;
+  return Math.min(Math.max(n, 1), ceiling);
+}

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts

@@ -7,7 +7,7 @@
 
 import type { MCPSupabaseClient } from "./types.ts";
 
-import { getMaxResponseBytes, logUsage } from "./_utils.ts";
+import { getMaxResponseBytes, logUsage, resolveByteBudget } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { reviewWorkflowEnabled } from "./feature-flags.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
@@ -22,7 +22,11 @@ async function handler(
   const project_name = args.project_name as string | undefined;
   const updated_since = args.updated_since as string | undefined;
   const created_since = args.created_since as string | undefined;
-  const limit = (args.limit as number | undefined) ?? 10;
+  // Sanitised and clamped, like `match_count` on the search tool: the local
+  // stdio server passes tool arguments through unvalidated, so a caller could
+  // ask for a million rows (#267). 500 matches the largest listing the web
+  // API serves, so no legitimate enumeration is cut short.
+  const limit = Math.min(Math.max(1, Math.floor(Number(args.limit)) || 10), 500);
   const include_content = (args.include_content as boolean | undefined) ?? false;
   const requested_max_bytes = args.max_bytes as number | undefined;
 
@@ -47,10 +51,14 @@ async function handler(
     if (!projectId) throw new Error(`Project not found: ${project_name}`);
   }
 
-  // Enforce byte ceiling for content mode
+  // Enforce byte ceiling for content mode, via the one shared resolver every
+  // budget-taking surface uses (#268). It was written out by hand here and on
+  // three other surfaces, and each copy was wrong differently: a non-numeric
+  // value became `NaN` and disabled the limit entirely (#267), and an explicit
+  // `null` coerced to 0 and became a ONE-BYTE budget.
   const ceiling = getMaxResponseBytes();
   const max_bytes = include_content
-    ? Math.min(requested_max_bytes ?? ceiling, ceiling)
+    ? resolveByteBudget(requested_max_bytes, ceiling)
     : null;
 
   const params: Record<string, unknown> = {
@@ -84,14 +92,20 @@ async function handler(
     content: string | null;
   }>;
 
-  logUsage(supabase, {
-    operation: "metadata_search",
-    accessPath: ctx.accessPath,
-    requestor: callerIdentity(args),
-    query_text: JSON.stringify(metadata_filter ?? {}),
-    project_id: projectId,
-    result_count: rows.length,
-  });
+  // Logged once, AFTER the degraded branch below may have found the real
+  // count: firing here unconditionally wrote a `result_count: 0` row for
+  // every budget-wiped search, and adding a second row in the branch made
+  // analytics double-count them (#259).
+  const log = (result_count: number, extra?: Record<string, unknown>) =>
+    logUsage(supabase, {
+      operation: "metadata_search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: JSON.stringify(metadata_filter ?? {}),
+      project_id: projectId,
+      result_count,
+      ...(extra ? { extra } : {}),
+    });
 
   if (rows.length === 0) {
     // The RPC applies the byte budget server-side by stopping at the first row
@@ -100,24 +114,79 @@ async function handler(
     // without content before reporting nothing: an agent that is told "no
     // documents" stops looking, and here that would be false.
     if (include_content && max_bytes !== null) {
-      const { data: headers } = await supabase.rpc("cerefox_metadata_search", {
-        ...params,
-        p_include_content: false,
-        p_max_bytes: null,
-      });
+      // supabase-js RESOLVES with `{ data: null, error }` for PostgREST
+      // failures and for network errors; it does not throw. A try/catch here
+      // was dead code, and worse: `headers` came back null, the branch below
+      // was skipped, and the handler answered "No documents match the given
+      // criteria" — the exact false-empty this branch exists to prevent
+      // (#261). Read the error, and say what is actually known.
+      const { data: headers, error: probeError } = await supabase.rpc(
+        "cerefox_metadata_search",
+        { ...params, p_include_content: false, p_max_bytes: null },
+      );
+      if (probeError) {
+        log(0, { degraded_probe_failed: true });
+        return (
+          `⚠ Nothing fit max_bytes=${max_bytes} with include_content, and the ` +
+          `follow-up query that lists what matched failed: ${probeError.message}. ` +
+          `This is NOT a confirmed empty result — retry with a larger max_bytes, ` +
+          `or with include_content: false.`
+        );
+      }
       const headerRows = (headers ?? []) as Array<{ document_id: string; title: string }>;
       if (headerRows.length > 0) {
-        return (
+        // The caller asked for a budget; honour it in the answer that explains
+        // the budget. `limit` is caller-supplied, so an uncapped list could be
+        // tens of KB in reply to a 2 KB request (#257).
+        const lead =
           `⚠ ${headerRows.length} document(s) match, but none fit max_bytes=${max_bytes} ` +
           `with include_content. This is NOT an empty result. Listing them without ` +
           `content — raise max_bytes, or read one with cerefox_get_document ` +
-          `(outline: true for structure).\n\n` +
-          headerRows.map((r) => `## ${r.title} [id: ${r.document_id}]`).join("\n")
-        );
+          `(outline: true for structure).`;
+        const lines: string[] = [];
+        let used = new TextEncoder().encode(lead).length;
+        for (const r of headerRows) {
+          const line = `## ${r.title} [id: ${r.document_id}]`;
+          const size = new TextEncoder().encode(line).length + 1;
+          if (used + size > max_bytes) break;
+          lines.push(line);
+          used += size;
+        }
+        // What matched, not what the budget allowed through (#257).
+        log(headerRows.length, { returned: lines.length, degraded: true });
+        return lines.length > 0 ? `${lead}\n${lines.join("\n")}` : lead;
       }
     }
+    log(0);
     return "No documents match the given criteria.";
   }
+  // How many documents actually matched, as opposed to how many the budget
+  // let through (#268). The RPC applies `p_max_bytes` by stopping at the first
+  // row that does not fit, so a short list has two indistinguishable causes:
+  // fewer documents matched, or the budget cut the list. Only the caller's
+  // side knows which, and only after asking — so ask, with the same
+  // content-free probe the empty branch above uses.
+  //
+  // Cost, stated honestly: this is a second RPC round-trip, and it fires
+  // whenever a content-bearing search returns less than a full page — which is
+  // the COMMON case, not a rare one, since `limit` defaults to 10. A full page
+  // and a budget-free call both skip it, but nothing else does. The RPC gives
+  // no "there was more" signal, and the alternative to asking is guessing:
+  // a short list is indistinguishable from a cut list from here, and guessing
+  // wrong is the bug (#268). Worth revisiting if the RPC ever returns a total.
+  let matched = rows.length;
+  if (include_content && max_bytes !== null && rows.length < limit) {
+    const { data: headers, error: probeError } = await supabase.rpc(
+      "cerefox_metadata_search",
+      { ...params, p_include_content: false, p_max_bytes: null },
+    );
+    // A failed probe must not invent a count. supabase-js resolves with
+    // `{ data: null, error }` rather than throwing (#261), so read the error:
+    // leaving `matched` at `rows.length` states only what is known.
+    if (!probeError) matched = Math.max(rows.length, ((headers ?? []) as unknown[]).length);
+  }
+
+  log(matched, matched > rows.length ? { returned: rows.length, truncated: true } : undefined);
 
   // The review status is a column of a feature that may be off (#241); when
   // it is, an agent should not see "approved" and wonder what it means.
@@ -145,6 +214,19 @@ async function handler(
     return header;
   });
 
+  // Never hold results back silently (#268). A caller who receives 1 of 5 and
+  // is told nothing believes they saw everything — the same failure as a false
+  // empty, in a quieter form. This notice is framing that is never dropped.
+  if (matched > rows.length) {
+    const held = matched - rows.length;
+    return (
+      `${parts.join("\n\n---\n\n")}\n\n` +
+      `[${rows.length} of ${matched} document(s) shown; ${held} did not fit ` +
+      `max_bytes=${max_bytes}. Raise max_bytes, lower limit, or use ` +
+      `include_content: false to list them all.]`
+    );
+  }
+
   return parts.join("\n\n---\n\n");
 }
 

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -18,8 +18,8 @@
 import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding, resolveEmbedderKind } from "../embeddings/index.ts";
-import { applyByteBudget, getConfiguredMinSearchScore, getConfiguredSearchAlpha,
-  getMaxResponseBytes, getMinTermCoverage, logUsage } from "./_utils.ts";
+import { getConfiguredMinSearchScore, getConfiguredSearchAlpha,
+  getMaxResponseBytes, getMinTermCoverage, logUsage , resolveByteBudget } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
@@ -27,7 +27,16 @@ import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 interface SearchRow {
   document_id?: string;
   doc_title?: string;
+  /** Document-level modes (`docs`) return this… */
   full_content?: string;
+  /** …while `hybrid` and `fts` return the chunk text under this name. */
+  content?: string;
+  /** Chunk-mode identity: the RPCs return several chunks OF THE SAME document. */
+  chunk_id?: string;
+  chunk_index?: number;
+  /** The chunk's own heading, and its full path from the document root. */
+  title?: string;
+  heading_path?: string[];
   best_score?: number;
   score?: number;
   is_partial?: boolean;
@@ -37,15 +46,86 @@ interface SearchRow {
   below_confidence?: boolean;
 }
 
+/** The row's text, under whichever column name this search mode returns. */
+export function rowContent(row: SearchRow): string {
+  return row.full_content ?? row.content ?? "";
+}
+
+/**
+ * `Document Title › Section` for a chunk row, `Document Title` for a document
+ * row, plus the ids that identify it.
+ *
+ * The chunk RPCs return several chunks OF THE SAME document, so without the
+ * section and the index those results are indistinguishable (#261). Shared by
+ * the rendered path and the degraded one, where identical headings would be
+ * the entire answer.
+ */
+function rowHeading(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  // `heading_path` normally opens with the document's own H1, so the FIRST
+  // element is dropped when it repeats the title. Only the first: a section
+  // legitimately named after the document must still appear (#261).
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const section = path.length
+    ? path.filter(Boolean).join(" › ")
+    : row.title && row.title !== doc
+      ? row.title
+      : "";
+  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  return `${doc}${section ? ` › ${section}` : ""}${docId}${chunk}`;
+}
+
+/**
+ * A short label for a row in the truncation footer: the leaf section, the
+ * chunk index, and the document id.
+ *
+ * Shorter than the rendered heading, which carries the whole breadcrumb — the
+ * footer names up to five rows, and full headings pushed the reply over the
+ * budget it was reporting on (#263). The id stays, because chunk modes span
+ * documents too and two documents sharing a title and a section name are
+ * otherwise indistinguishable, with no way to fetch either (#265). The footer
+ * is inside the budget and drops names it cannot afford, so it is accounted
+ * for either way.
+ */
+function shortLabel(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const leaf = path.filter(Boolean).at(-1) ?? (row.title && row.title !== doc ? row.title : "");
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  // Always the id. Chunk modes are not single-document either, so two
+  // documents sharing a title and a section name would otherwise produce
+  // byte-identical entries with no way to fetch either (#265). The footer is
+  // inside the budget now and drops names it cannot afford, so carrying the
+  // id costs nothing that is not accounted for.
+  const id = row.document_id ? ` [id: ${row.document_id}]` : "";
+  return `${leaf ? `${doc} › ${leaf}` : doc}${chunk}${id}`;
+}
+
+/** One rendered result: heading, score, then the row's text. */
+function renderRow(row: SearchRow): string {
+  const raw = row.best_score ?? row.score;
+  const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
+  const partial = row.is_partial
+    ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
+    : "";
+  // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
+  const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+  // Whichever column this mode returns (#259): `cerefox_search_docs` gives
+  // `full_content`, the chunk RPCs give `content`, and reading only the first
+  // rendered every hybrid/fts result as a title with an empty body.
+  return `## ${rowHeading(row)}${score}${partial}${hash}\n\n${rowContent(row)}`;
+}
+
 /** `## Title [id: …] (score: …) -- 20,297 chars` — everything but the content. */
 function headerLine(row: SearchRow): string {
-  const title = row.doc_title ?? "Untitled";
-  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
   const raw = row.best_score ?? row.score;
   const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
   const size = row.total_chars != null ? ` -- ${row.total_chars.toLocaleString()} chars` : "";
   const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
-  return `## ${title}${docId}${score}${size}${hash}`;
+  return `## ${rowHeading(row)}${score}${size}${hash}`;
 }
 
 /**
@@ -56,15 +136,30 @@ function headerLine(row: SearchRow): string {
  * still honours the limit the caller asked for; if even one header does not
  * fit, the count and the remedy alone still beat silence.
  */
-function degradedToHeaders(matched: SearchRow[], maxBytes: number): string {
-  const biggest = Math.max(
-    ...matched.map((r) => new TextEncoder().encode(JSON.stringify(r)).length),
-  );
+function degradedToHeaders(
+  matched: SearchRow[],
+  rendered: string[],
+  maxBytes: number,
+  belowConfidence: boolean,
+): string {
+  // Rendered bytes, not JSON: the fit decision that reaches here is made in
+  // rendered bytes, and quoting a JSON size produced messages saying the
+  // largest result was 490 bytes and did not fit a 600-byte budget (#265).
+  // Sizes come from the render the caller already paid for — re-rendering
+  // whole documents here just to measure them tripled peak memory.
+  const biggest = Math.max(...rendered.map((t) => new TextEncoder().encode(t).length));
+  // A degraded response must not silently promote 28I's weak-signal
+  // candidates into real matches: an agent told "N result(s) matched" about
+  // rows that cleared no threshold would trust them.
+  const confidence = belowConfidence
+    ? "None of these cleared the confidence threshold — they are the closest " +
+      "candidates, so judge relevance from the scores. "
+    : "";
   const lead =
     `⚠ ${matched.length} result(s) matched, but none fit max_bytes=${maxBytes} ` +
-    `(the largest is ${biggest.toLocaleString()} bytes). This is NOT an empty ` +
-    `knowledge base. Listing what matched, without content — raise max_bytes to ` +
-    `read it, or read one document with cerefox_get_document (outline: true for ` +
+    `(the largest is ${biggest.toLocaleString()} bytes). ${confidence}This is NOT an ` +
+    `empty knowledge base. Listing what matched, without content — raise max_bytes ` +
+    `to read it, or read one document with cerefox_get_document (outline: true for ` +
     `structure, or section: "## Heading" for one part).`;
 
   const lines: string[] = [];
@@ -86,7 +181,12 @@ async function handler(
 ): Promise<string> {
   const query = args.query as string;
   const project_name = args.project_name as string | undefined;
-  const match_count = (args.match_count as number | undefined) ?? 5;
+  // Sanitised, then clamped, exactly as the Edge Function does it. Clamping
+  // alone left `NaN` for a non-numeric value, which serialises to JSON null,
+  // and `LIMIT NULL` in Postgres means NO limit — the unbounded work the
+  // clamp exists to prevent, reachable because the local MCP server passes
+  // tool arguments through unvalidated (#265).
+  const match_count = Math.min(Math.max(1, Math.floor(Number(args.match_count)) || 5), 200);
   const mode = (args.mode as string | undefined) ?? "docs";
   // #133: omit unconfigured tunables so the server resolves them from
   // cerefox_config (one setting governs every access path).
@@ -107,7 +207,14 @@ async function handler(
   const requested_max_bytes = args.max_bytes as number | undefined;
 
   const ceiling = getMaxResponseBytes();
-  const max_bytes = Math.min(requested_max_bytes ?? ceiling, ceiling);
+  // Sanitised before clamping, for the reason `match_count` is: `NaN` makes
+  // every `> max_bytes` comparison below false, so a non-numeric value emitted
+  // every row unbounded — the ceiling bypassed by passing it a word (#266).
+  // A NUMBER of 0 or less still means "almost no budget", as it always did:
+  // falling back to the ceiling there would hand a caller whose remaining
+  // allowance ran out the largest possible reply (#267). Only a missing or
+  // non-numeric value defaults to the ceiling.
+  const max_bytes = resolveByteBudget(requested_max_bytes, ceiling);
 
   if (
     metadata_filter !== null &&
@@ -187,7 +294,137 @@ async function handler(
   if (error) throw new Error(`RPC error: ${error.message}`);
 
   const matched = (data ?? []) as SearchRow[];
-  const { accepted, dropped, truncated, usedBytes } = applyByteBudget(matched, max_bytes);
+
+  // 28I: nothing cleared the relevance threshold, so the server returned its
+  // best-effort candidates flagged below_confidence rather than an empty set
+  // (which agents misread as "this knowledge does not exist"). The flag is
+  // all-or-nothing per response, so it is read from what MATCHED.
+  const belowConfidence = matched.length > 0 && matched.every((r) => r.below_confidence === true);
+
+  if (matched.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: 0,
+    });
+    return "No results found.";
+  }
+
+  // ── Fit the reply to max_bytes, in the units the caller receives ──────────
+  //
+  // The budget is spent on RENDERED text, not on the JSON the RPC returned:
+  // `applyByteBudget` measures `JSON.stringify(row)`, which is the right unit
+  // for the Edge Function (it ships JSON) and the wrong one here (this returns
+  // markdown). Reserving rendered bytes out of a JSON-measured budget
+  // guaranteed nothing, and neither the below-confidence preamble (~185 bytes)
+  // nor the footer was counted by anything (#265).
+  //
+  // So: render, then take as many rows as the whole assembled reply can carry.
+  // Assembling and measuring is the only way to be sure, because the preamble
+  // and the footer both depend on how many rows were kept.
+  const rendered = matched.map(renderRow);
+  const size = (t: string) => new TextEncoder().encode(t).length;
+  const SEP = "\n\n---\n\n";
+
+  // The 28I advisory, long and short. It is charged to the budget like
+  // everything else, but it must never displace the answer it is advising
+  // about: a ~190-byte banner that pushes the only result out of a small reply
+  // leaves the caller with a warning and no content (#265). The short form is
+  // the floor — the contract is that weak candidates are never presented as
+  // confident ones, and that survives in six words.
+  const banner = (take: number, short: boolean) =>
+    !belowConfidence
+      ? ""
+      : short
+        ? `⚠ Below the confidence threshold — judge relevance from the scores.\n\n`
+        : `⚠ No results cleared the confidence threshold. Showing the closest ${take} ` +
+          `candidate(s) with scores — judge relevance yourself; a low score means weak ` +
+          `signal, not necessarily absent knowledge.\n\n`;
+
+  /**
+   * The whole reply for a set of kept rows.
+   *
+   * Everything but the results is optional, in this order: the long advisory
+   * gives way first, then the named list of what was dropped, then the bare
+   * footer. What is NOT optional is saying that results were dropped — a
+   * reply that quietly returns 1 of 5 hits leaves the caller believing they
+   * saw everything, which is the failure this whole file is about (#266).
+   */
+  const assemble = (keptCount: number, short: boolean): string => {
+    const kept = keptIdx.slice(0, keptCount);
+    const body = banner(keptCount, short) + kept.map((i) => rendered[i]!).join(SEP);
+    if (kept.length === matched.length) return body;
+
+    const droppedRows = matched.filter((_, i) => !kept.includes(i));
+    const room = max_bytes - size(body);
+    const footer = (named: number) => {
+      const labels = droppedRows.slice(0, named).map(shortLabel);
+      const rest = droppedRows.length - labels.length;
+      const naming = labels.length
+        ? `: ${labels.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}`
+        : "";
+      return (
+        `\n\n[${kept.length} of ${matched.length} result(s) shown; ${droppedRows.length} did ` +
+        `not fit max_bytes=${max_bytes}${naming}. Raise max_bytes, narrow the query, or ` +
+        `lower match_count.]`
+      );
+    };
+    for (let named = Math.min(5, droppedRows.length); named >= 1; named--) {
+      const candidate = footer(named);
+      if (size(candidate) <= room) return body + candidate;
+    }
+    const bare = footer(0);
+    if (size(bare) <= room) return body + bare;
+    // The floor, ~25 bytes, never dropped: the caller must know there is more.
+    return body + `\n\n[${kept.length} of ${matched.length} shown; raise max_bytes]`;
+  };
+
+  // Which rows the budget can carry, in rank order. Rows that do not fit are
+  // SKIPPED rather than ending the scan: one oversized top hit used to suppress
+  // every smaller result behind it, and the reply then claimed nothing fit when
+  // rows two and three would have fitted comfortably (#266).
+  const sepBytes = size(SEP);
+  const keptIdx: number[] = [];
+  let acc = 0;
+  for (let i = 0; i < rendered.length; i++) {
+    const add = size(rendered[i]!) + (keptIdx.length > 0 ? sepBytes : 0);
+    if (acc + add > max_bytes) continue;
+    acc += add;
+    keptIdx.push(i);
+  }
+
+  // Not one result fits (#254) — the only case that answers with no content,
+  // and now the only case that can truthfully say so.
+  if (keptIdx.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: matched.length,
+      extra: { returned: 0, truncated: true, degraded: true },
+    });
+    return degradedToHeaders(matched, rendered, max_bytes, belowConfidence);
+  }
+
+  // Give up the framing before the content, but never the fact of truncation:
+  // long advisory, then a result, and the "N of M shown" notice always stays.
+  let keptCount = keptIdx.length;
+  let short = false;
+  let output = assemble(keptCount, short);
+  while (size(output) > max_bytes) {
+    if (belowConfidence && !short) short = true;
+    else if (keptCount > 1) {
+      keptCount -= 1;
+      short = belowConfidence;
+    } else break; // one result plus the shortest possible framing: the floor
+    output = assemble(keptCount, short);
+  }
+  const take = keptCount;
 
   logUsage(supabase, {
     operation: "search",
@@ -195,59 +432,12 @@ async function handler(
     requestor: callerIdentity(args),
     query_text: query,
     project_id: projectId,
-    // What the QUERY matched, not what survived the byte budget. The two
-    // differ only when rows were dropped, and recording 0 there made a
-    // budget-wiped search look like an empty knowledge base in analytics too.
+    // What the QUERY matched, not what survived the budget: recording the
+    // latter made a budget-wiped search look like an empty store in analytics.
     result_count: matched.length,
-    ...(truncated ? { extra: { returned: accepted.length, truncated: true } } : {}),
+    ...(take < matched.length ? { extra: { returned: take, truncated: true } } : {}),
   });
 
-  // Nothing matched: the honest empty answer.
-  if (matched.length === 0) return "No results found.";
-
-  // Something matched but none of it fit the budget (#254). Reporting "no
-  // results" here is the most damaging answer the tool can give: an agent
-  // stops looking and often recreates the document it failed to find. Show
-  // the headers instead — a few hundred bytes that name what exists and how
-  // to read it.
-  if (accepted.length === 0) {
-    return degradedToHeaders(matched, max_bytes);
-  }
-
-  const rows = accepted as SearchRow[];
-
-  // 28I: nothing cleared the relevance threshold, so the server returned its
-  // best-effort top candidates flagged below_confidence instead of an empty
-  // set (which agents misread as "this knowledge does not exist").
-  const belowConfidence = rows.length > 0 && rows.every((r) => r.below_confidence === true);
-
-  const parts: string[] = rows.map((row) => {
-    const title = row.doc_title ?? "Untitled";
-    const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
-    const rawScore = row.best_score ?? row.score;
-    const score = rawScore != null ? ` (score: ${rawScore.toFixed(3)})` : "";
-    const partial = row.is_partial
-      ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
-      : "";
-    // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
-    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
-    return `## ${title}${docId}${score}${partial}${hash}\n\n${row.full_content ?? ""}`;
-  });
-
-  let output = parts.join("\n\n---\n\n");
-  if (belowConfidence) {
-    output =
-      `⚠ No results cleared the confidence threshold. Showing the closest ${rows.length} ` +
-      `candidate(s) with scores — judge relevance yourself; a low score means weak signal, ` +
-      `not necessarily absent knowledge.\n\n` + output;
-  }
-  if (truncated) {
-    output +=
-      `\n\n[${accepted.length} of ${matched.length} result(s) shown; truncated at ` +
-      `${usedBytes} bytes. ${dropped.length} did not fit: ` +
-      `${dropped.map((r) => (r as SearchRow).doc_title ?? "Untitled").join(", ")}. ` +
-      `Raise max_bytes, narrow the query, or lower match_count.]`;
-  }
   return output;
 }
 
@@ -269,7 +459,7 @@ export const searchTool: ToolDefinition = {
       query: { type: "string", description: "Natural-language search query" },
       match_count: {
         type: "integer",
-        description: "Maximum number of documents to return (default: 5)",
+        description: "Maximum number of documents to return (default: 5, maximum: 200)",
       },
       project_name: {
         type: "string",