@velaro/cli 1.4.96 → 1.4.97

package/lib/commands/logs.js

@@ -1,6 +1,6 @@
 import { getCredentials }          from '../api.js';
 import { readConfig, ENVS }        from '../config.js';
-import { completeLogSearch, describeCompleteness, describeRawMeta } from '../log-search.js';
+import { completeLogSearch, describeCompleteness, describeRawMeta, fetchJsonRetry } from '../log-search.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
@@ -57,6 +57,10 @@ async function requireAdmin(creds) {
 // ── search handler ────────────────────────────────────────────────────────────
 
 async function searchLogs(argv) {
+  try { await searchLogsInner(argv); } catch (err) { console.error(err?.message ?? String(err)); process.exit(1); }
+}
+
+async function searchLogsInner(argv) {
   const creds   = await getCredentials();
   await requireAdmin(creds);
   const msgBase = await getMsgBase(argv);
@@ -68,14 +72,8 @@ async function searchLogs(argv) {
     process.exit(1);
   }
   const headers = { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) };
-  const getJson = async (query) => {
-    const res = await fetch(`${msgBase}/superadmin/logs/search?${query}`, { headers, signal: AbortSignal.timeout(30000) });
-    if (!res.ok) {
-      console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
-      process.exit(1);
-    }
-    return res.json();
-  };
+  // 40 s: the server's own scan budget is 12 s (+6 s AI search) per request, and a 429 (scan gate full) is retried with Retry-After.
+  const getJson = (query) => fetchJsonRetry(`${msgBase}/superadmin/logs/search?${query}`, () => ({ headers, signal: AbortSignal.timeout(40000) }));
 
   // --raw: the server's own q= search (kept for parity). Proven 2026-10-14 to under-report (q=[HttpFallback]
   // returned 0-2 rows while 136 existed), so it now always prints the server's searchPath/scannedRows/truncated.
@@ -110,6 +108,8 @@ async function searchLogs(argv) {
     regex:    argv.regex ? argv.query : undefined,
     logger:   argv.logger,
     maxRequests: argv.maxRequests ?? 200,
+    maxSeconds: argv.maxSeconds ?? 120,
+    wanted: argv.take ?? 50,
   });
   console.log(`${result.complete ? DIM : YEL}${describeCompleteness(result)}${RESET}`);
   if (!result.entries.length) { console.log('No results.'); return; }
@@ -238,21 +238,26 @@ async function diagnoseLogs(argv) {
 
   console.log(`\n${BOLD}── Bot Diagnostic — last ${window} ──────────────────────────────${RESET2}`);
 
-  // Run error search and perf/routing search in parallel
-  async function search(q) {
-    const p = new URLSearchParams({ q, from: from.toISOString(), take: '50' });
-    const r = await fetch(`${msgBase}/superadmin/logs/search?${p}`, {
+  // Run error search and perf/routing search in parallel. FIXED 2026-10-14: the old calls searched the TEXT "level:ERROR" and the
+  // TEXT "WF-AI-ROUTE OR PERF-SLOW", which no log line contains, so this printed "No errors" no matter what. Errors are now the
+  // server-side level filter and the perf/routing pair is a regex; the server's scan metadata is surfaced so an unverified
+  // empty answer is never shown as a clean bill of health.
+  const notes = [];
+  async function search(label, p0) {
+    const p = new URLSearchParams({ from: from.toISOString(), take: '50', ...p0 });
+    const resp = await fetchJsonRetry(`${msgBase}/superadmin/logs/search?${p}`, () => ({
       headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
-      signal: AbortSignal.timeout(15000),
-    });
-    if (!r.ok) return [];
-    return extractLogEntries(await r.json());
+      signal: AbortSignal.timeout(40000),
+    })).catch((err) => { notes.push(`${label}: search failed (${err.message})`); return null; });
+    if (resp && !Array.isArray(resp) && resp.truncated !== false) notes.push(`${label}: ${describeRawMeta(resp)}`);
+    else if (Array.isArray(resp)) notes.push(`${label}: ${describeRawMeta(resp)}`);
+    return resp ? extractLogEntries(resp) : [];
   }
 
-  const [errors, perfAndRouting] = await Promise.all([
-    search('level:ERROR'),
-    search('WF-AI-ROUTE OR PERF-SLOW'),
-  ]);
+  // One at a time: the server runs at most 2 exact scans per instance.
+  const errors = await search('errors', { level: 'ERROR' });
+  const perfAndRouting = await search('perf/routing', { q: 'WF-AI-ROUTE|PERF-SLOW', regex: 'true' });
+  for (const n of notes) console.log(`  \x1b[33m!\x1b[0m  ${n}`);
 
   // ── Errors ──
   console.log(`\n${BOLD}Errors${RESET2}`);
@@ -724,6 +729,7 @@ export const logsCommand = {
         .option('to',            { describe: 'ISO end time (default now)', type: 'string' })
         .option('raw',           { describe: 'Use the server q= search (can under-report; prints searchPath/scannedRows/truncated)', boolean: true, default: false })
         .option('max-requests',  { describe: 'Request budget for the complete read', default: 200, type: 'number' })
+        .option('max-seconds',   { describe: 'Wall-clock budget for the complete read', default: 120, type: 'number' })
         .option('take',          { describe: 'Max lines to print (complete read) / server page size (--raw, max 500)', default: 50, type: 'number' })
         .option('env',           { describe: 'staging or prod', type: 'string' }),
       handler: searchLogs,

package/lib/commands/ops.js

@@ -1,3 +1,4 @@
+import { describeRawMeta, fetchRetry429 } from '../log-search.js';
 import { get, del, post, getCredentials } from '../api.js';
 import { readConfig, ENVS }   from '../config.js';
 
@@ -236,19 +237,25 @@ export const opsCommand = {
       const stagingMsgBaseLocal = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
       const from1h = new Date(Date.now() - 3600000).toISOString();
 
-      const [errRes, perfRes] = await Promise.all([
-        fetch(`${stagingMsgBaseLocal}/superadmin/logs/search?q=level%3AERROR&from=${from1h}&take=5`, {
-          headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
-          signal: AbortSignal.timeout(12000),
-        }),
-        fetch(`${stagingMsgBaseLocal}/superadmin/logs/search?q=WF-AI-ROUTE+OR+PERF-SLOW&from=${from1h}&take=20`, {
-          headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
-          signal: AbortSignal.timeout(12000),
-        }),
-      ]);
-
-      const errors   = errRes.ok  ? extractLogEntries(await errRes.json().catch(() => [])) : [];
-      const perfLogs = perfRes.ok ? extractLogEntries(await perfRes.json().catch(() => [])) : [];
+      // One search at a time: the server runs at most 2 exact scans per instance. 429 (gate full) is retried honouring Retry-After.
+      const errRes  = await fetchRetry429(`${stagingMsgBaseLocal}/superadmin/logs/search?level=ERROR&from=${from1h}&take=5`, () => ({
+        headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+        signal: AbortSignal.timeout(40000),
+      }));
+      const perfRes = await fetchRetry429(`${stagingMsgBaseLocal}/superadmin/logs/search?q=${encodeURIComponent('WF-AI-ROUTE|PERF-SLOW')}&regex=true&from=${from1h}&take=20`, () => ({
+        headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+        signal: AbortSignal.timeout(40000),
+      }));
+
+      // FIXED 2026-10-14: both searches used to look for the literal TEXT "level:ERROR" / "WF-AI-ROUTE OR PERF-SLOW" (never in any log
+      // line), so this check always said "0 errors". Errors are now the server-side level filter, perf/routing a regex, and an
+      // unverified or failed scan is reported instead of being counted as a clean result.
+      const errBody  = errRes.ok  ? await errRes.json().catch(() => null) : null;
+      const perfBody = perfRes.ok ? await perfRes.json().catch(() => null) : null;
+      const errors   = errBody  ? extractLogEntries(errBody)  : [];
+      const perfLogs = perfBody ? extractLogEntries(perfBody) : [];
+      const scanNote = (label, body, ok) => (!ok || !body) ? `${label}: search failed or timed out (HTTP ${ok ? 'ok' : 'error'}), NOT verified` : (body.truncated === false ? null : `${label}: ${describeRawMeta(body)}`);
+      for (const n of [scanNote('errors', errBody, errRes.ok), scanNote('perf/routing', perfBody, perfRes.ok)].filter(Boolean)) console.log(`  ${WARN}  ${n}`);
 
       const perfCount  = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('PERF-SLOW')).length;
       const routeCount = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('WF-AI-ROUTE')).length;

package/lib/log-search.js

@@ -1,93 +1,200 @@
 // Complete Velaro Logger reads (2026-10-14).
 //
-// WHY: velaro-messaging's /superadmin/logs/search and /internal/logs/search silently under-report text queries.
+// WHY: velaro-messaging's /superadmin/logs/search and /internal/logs/search silently under-reported text queries.
 // Proven live that day: q=[HttpFallback] over 3.9 h returned 0-2 rows while 136 existed, and q=AsrsNegotiateFailed
-// (no level) returned 0 while 4 existed. The AI-search path only sees the newest 1,000 candidates and its answer was
-// final; the exact path only sees the newest 5,000 rows of the window before filtering. Neither said so.
+// (no level) returned 0 while 4 existed. The AI-search path only saw the newest 1,000 candidates and its answer was
+// final; the exact path only saw the newest 5,000 rows of the window before filtering. Neither said so.
 //
-// HOW (no q= ever sent): level/siteId/source/integration/platform/environment/correlationId are pushed to the
-// server (Table Storage OData, cheap and exact); includeTotal=true makes the server report totalCountCapped when a
-// slice hit its scan cap; a capped slice is bisected until none is capped; text (contains/regex/logger) is
-// filtered client side. The result says whether it is COMPLETE, so a 0 is never ambiguous.
+// TWO MODES, picked automatically from the first response:
+//  * CURSOR mode (server with velaro-messaging PR #2510, response carries `truncated`/`scannedRows`): the server scans the
+//    window newest-first applying level/site AND text (as an escaped regex, which also forces the exact path) while it
+//    scans, reports `truncated`, and returns `nextCursor` whenever more rows may exist. We follow the cursor until it is
+//    null, so a 2 h window is a handful of requests instead of hundreds.
+//  * BISECT mode (older server): never send q=; push level/site/etc server side; includeTotal=true reports
+//    totalCountCapped for a slice; a capped slice is bisected until none is capped; text is filtered client side.
+// Either way the result says COMPLETE or INCOMPLETE, so a 0 is never ambiguous. Hard caps: maxRequests and maxSeconds.
 //
 // KEEP IN SYNC: this file is duplicated byte for byte in mcp/log-search.js (the npm packages ship separately);
 // cli/lib/log-search.test.js fails if the two copies drift.
 
 const MIN_SLICE_MS = 2000;
 
+export const escapeRegex = (s) => String(s).replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const tsOf = (e) => { const t = Date.parse(e.timestamp ?? e.LogTimestamp ?? ''); return Number.isNaN(t) ? 0 : t; };
+
+/**
+ * fetch that retries ONLY 429 (honouring Retry-After, seconds, capped at 30 s) for up to `retries` attempts and returns the final Response.
+ * `init` may be a function so each attempt gets a fresh AbortSignal.
+ */
+export async function fetchRetry429(url, init = {}, { retries = 3, fetchImpl = fetch, sleepImpl = sleep } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetchImpl(url, typeof init === 'function' ? init() : init);
+    if (res.status === 429 && attempt < retries) {
+      // Number(null) is 0, which would turn a 429 without Retry-After into an immediate retry: a missing header means the 5 s default.
+      const raw = res.headers?.get?.('retry-after');
+      const ra = raw == null || raw === '' ? NaN : Number(raw);
+      await sleepImpl(Math.min(Number.isFinite(ra) && ra >= 0 ? ra : 5, 30) * 1000);
+      continue;
+    }
+    return res;
+  }
+}
+
+/** fetchRetry429 + JSON. Any non-2xx throws an Error carrying `.status` and the response text. */
+export async function fetchJsonRetry(url, init = {}, opts = {}) {
+  const res = await fetchRetry429(url, init, opts);
+  if (!res.ok) {
+    const err = new Error(`HTTP ${res.status}: ${(await res.text().catch(() => '')).slice(0, 400)}`);
+    err.status = res.status;
+    throw err;
+  }
+  return res.json();
+}
+
 /**
  * @param {object} o
- * @param {(query: string) => Promise<any>} o.fetchJson  GET `...search?<query>` and return parsed JSON (caller adds auth)
+ * @param {(query: string) => Promise<any>} o.fetchJson  GET `...search?<query>` and return parsed JSON (caller adds auth/timeout)
  * @param {Date} o.from
  * @param {Date} o.to
  * @param {object} [o.params]  server-side filters: level, siteId, source, integration, platform, environment, correlationId
- * @param {string} [o.contains] case-insensitive substring of the message (client side)
- * @param {string} [o.regex]    regex on the message (client side)
- * @param {string} [o.logger]   substring of the logger name (client side)
+ * @param {string} [o.contains] case-insensitive substring of the message
+ * @param {string} [o.regex]    regex on the message
+ * @param {string} [o.logger]   substring of the logger name
  * @param {number} [o.maxRequests=200]
+ * @param {number} [o.maxSeconds=120]   wall-clock budget for the whole read
+ * @param {number} [o.wanted=Infinity]  CURSOR mode: stop once this many matches were collected (newest first); the result is then `satisfied`
  */
-export async function completeLogSearch({ fetchJson, from, to, params = {}, contains, regex, logger, maxRequests = 200 }) {
+export async function completeLogSearch({ fetchJson, from, to, params = {}, contains, regex, logger, maxRequests = 200, maxSeconds = 120, wanted = Infinity }) {
   const server = {};
   for (const k of ['level', 'siteId', 'source', 'integration', 'platform', 'environment', 'correlationId']) {
     if (params[k] !== undefined && params[k] !== null && params[k] !== '') server[k] = String(k === 'level' ? String(params[k]).toUpperCase() : params[k]);
   }
   const byId = new Map();
   const unresolved = [];
+  const started = Date.now();
   let requests = 0;
   let slices = 0;
   let scanned = 0;
   let budgetExhausted = false;
+  let timeExhausted = false;
 
-  const call = async (a, b, cursor, total) => {
-    if (requests >= maxRequests) { budgetExhausted = true; return null; }
-    requests++;
-    const q = new URLSearchParams({ from: a.toISOString(), to: b.toISOString(), take: '500', ...server });
-    if (total) q.set('includeTotal', 'true');
+  const canRequest = () => {
+    if (requests >= maxRequests) { budgetExhausted = true; return false; }
+    if ((Date.now() - started) / 1000 >= maxSeconds && requests > 0) { timeExhausted = true; return false; }
+    return true;
+  };
+  const norm = (r) => (Array.isArray(r) ? { entries: r } : (r || {}));
+  const add = (e) => byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
+
+  // ---- text handling shared by both modes ----
+  const textQ = regex ?? (contains ? escapeRegex(contains) : undefined);
+  const textLogger = logger ? escapeRegex(logger) : undefined;
+
+  // ---- probe: first CURSOR-mode page, doubles as the new-server detector ----
+  const cursorQuery = (cursor) => {
+    const q = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: '500', ...server });
+    if (textQ) q.set('q', textQ);
+    if (textLogger) q.set('logger', textLogger);
+    if (textQ || textLogger) q.set('regex', 'true'); // regex also forces the exact path (the AI-search path is never consulted)
+    q.set('fallthrough', 'false');
     if (cursor) q.set('cursor', cursor);
-    const r = await fetchJson(q.toString());
-    return Array.isArray(r) ? { entries: r } : (r || {});
+    return q.toString();
   };
 
-  const walk = async (a, b) => {
-    const r = await call(a, b, null, true);
-    if (!r) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (request budget)`); return; }
-    if (r.totalCountCapped === true && (b - a) > MIN_SLICE_MS) {
-      const mid = new Date(a.getTime() + Math.floor((b - a) / 2));
-      await walk(a, mid);
-      await walk(mid, b);
-      return;
-    }
-    if (r.totalCountCapped === true) unresolved.push(`${a.toISOString()}..${b.toISOString()} (still capped at <=2s)`);
-    slices++;
-    scanned += Number(r.totalCount ?? (r.entries?.length ?? 0));
-    for (const e of r.entries ?? []) byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
-    let cursor = r.nextCursor;
-    while (cursor) {
-      const r2 = await call(a, b, cursor, false);
-      if (!r2) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (request budget while paging)`); break; }
-      for (const e of r2.entries ?? []) byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
-      cursor = r2.nextCursor;
+  let mode = 'bisect';
+  let satisfied = false;
+  let cursorDone = false;
+
+  if (canRequest()) {
+    requests++;
+    const probe = norm(await fetchJson(cursorQuery(null)));
+    if (typeof probe.truncated === 'boolean') {
+      mode = 'cursor';
+      scanned += Number(probe.scannedRows ?? 0);
+      for (const e of probe.entries ?? []) add(e);
+      let page = probe;
+      let cursor = probe.nextCursor || null;
+      for (;;) {
+        // The ONLY way a cursor read is COMPLETE: the last page said truncated === false and carried no cursor. `truncated: true` with no
+        // cursor means the server stopped scanning (deadline/cap) and could not say where to continue: INCOMPLETE, never COMPLETE.
+        if (!cursor) {
+          if (page.truncated === false) cursorDone = true;
+          else unresolved.push('the server stopped scanning (truncated) without a cursor to continue from');
+          break;
+        }
+        if (byId.size >= wanted) { satisfied = true; break; }
+        if (!canRequest()) { unresolved.push(`cursor ${cursor} (${timeExhausted ? 'time budget' : 'request budget'})`); break; }
+        requests++;
+        const next = norm(await fetchJson(cursorQuery(cursor)));
+        scanned += Number(next.scannedRows ?? 0);
+        for (const e of next.entries ?? []) add(e);
+        if (next.nextCursor && next.nextCursor === cursor) {
+          unresolved.push('no progress: the server returned the cursor it was given (its scan budget ended before reaching any row)');
+          break;
+        }
+        page = next;
+        cursor = next.nextCursor || null;
+      }
+      slices = 1;
     }
-  };
+  }
 
-  await walk(from, to);
+  // ---- BISECT mode (older server) ----
+  if (mode === 'bisect' && !budgetExhausted) {
+    const call = async (a, b, cursor, total) => {
+      if (!canRequest()) return null;
+      requests++;
+      const q = new URLSearchParams({ from: a.toISOString(), to: b.toISOString(), take: '500', ...server });
+      if (total) q.set('includeTotal', 'true');
+      if (cursor) q.set('cursor', cursor);
+      return norm(await fetchJson(q.toString()));
+    };
+    const walk = async (a, b) => {
+      const r = await call(a, b, null, true);
+      if (!r) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (${timeExhausted ? 'time' : 'request'} budget)`); return; }
+      if (r.totalCountCapped === true && (b - a) > MIN_SLICE_MS) {
+        const mid = new Date(a.getTime() + Math.floor((b - a) / 2));
+        await walk(a, mid);
+        await walk(mid, b);
+        return;
+      }
+      if (r.totalCountCapped === true) unresolved.push(`${a.toISOString()}..${b.toISOString()} (still capped at <=2s: a log storm; add level/site)`);
+      slices++;
+      scanned += Number(r.totalCount ?? (r.entries?.length ?? 0));
+      for (const e of r.entries ?? []) add(e);
+      let cursor = r.nextCursor;
+      while (cursor) {
+        const r2 = await call(a, b, cursor, false);
+        if (!r2) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (budget while paging)`); break; }
+        for (const e of r2.entries ?? []) add(e);
+        cursor = r2.nextCursor;
+      }
+    };
+    await walk(from, to);
+  }
 
   let rows = [...byId.values()];
   const msg = (e) => String(e.message ?? e.Message ?? '');
-  if (contains) { const c = contains.toLowerCase(); rows = rows.filter((e) => msg(e).toLowerCase().includes(c)); }
-  if (regex) { const re = new RegExp(regex, 'i'); rows = rows.filter((e) => re.test(msg(e))); }
-  if (logger) { const l = logger.toLowerCase(); rows = rows.filter((e) => String(e.logger ?? e.Logger ?? '').toLowerCase().includes(l)); }
-  rows.sort((x, y) => String(y.timestamp ?? '').localeCompare(String(x.timestamp ?? '')));
+  if (mode === 'bisect') {
+    if (contains) { const c = contains.toLowerCase(); rows = rows.filter((e) => msg(e).toLowerCase().includes(c)); }
+    if (regex) { const re = new RegExp(regex, 'i'); rows = rows.filter((e) => re.test(msg(e))); }
+    if (logger) { const l = logger.toLowerCase(); rows = rows.filter((e) => String(e.logger ?? e.Logger ?? '').toLowerCase().includes(l)); }
+  }
+  rows.sort((x, y) => tsOf(y) - tsOf(x)); // compare as instants: fractional-second digit counts differ between rows
 
-  return { entries: rows, fetched: byId.size, scanned, requests, slices, complete: unresolved.length === 0 && !budgetExhausted, unresolved, budgetExhausted };
+  const complete = mode === 'cursor' ? (cursorDone && unresolved.length === 0) : (unresolved.length === 0 && !budgetExhausted && !timeExhausted);
+  return { entries: rows, fetched: byId.size, scanned, requests, slices, mode, complete, satisfied, unresolved, budgetExhausted, timeExhausted };
 }
 
-/** One line a human or an LLM can trust: says COMPLETE or INCOMPLETE and how much was examined. */
+/** One line a human or an LLM can trust: says COMPLETE or INCOMPLETE and how much the SERVER actually scanned. */
 export function describeCompleteness(r) {
-  const base = `${r.entries.length} matched of ${r.fetched} fetched (server scanned ${r.scanned}) in ${r.requests} request(s)/${r.slices} slice(s)`;
+  const base = `${r.entries.length} matched (${r.fetched} fetched; server scanned ${r.scanned} rows) in ${r.requests} request(s), ${r.mode} mode`;
+  if (r.satisfied) return `${base}; showing the newest matches, more may exist beyond what was asked for (stopped early on purpose).`;
   return r.complete
-    ? `${base}; COMPLETE (no slice hit the server scan cap), so 0 matches means nothing was logged.`
-    : `${base}; INCOMPLETE (${r.unresolved.length} slice(s) unresolved${r.budgetExhausted ? ', request budget exhausted' : ''}): narrow the window or add level/site; a short or empty result is NOT proof of absence.`;
+    ? `${base}; COMPLETE (the whole window was covered), so 0 matches means nothing was logged.`
+    : `${base}; INCOMPLETE (${r.unresolved.length} part(s) not covered${r.budgetExhausted ? ', request budget exhausted' : ''}${r.timeExhausted ? ', time budget exhausted' : ''}): narrow the window or add level/site; a short or empty result is NOT proof of absence.`;
 }
 
 /** For raw (server-side q=) responses: surfaces searchPath/scannedRows/truncated so a 0 is never ambiguous. */
@@ -96,5 +203,7 @@ export function describeRawMeta(resp) {
     return 'server did not report scan metadata (older deploy): treat an empty or short result as unverified, use the complete mode.';
   }
   const t = resp.truncated === true;
-  return `searchPath=${resp.searchPath} scannedRows=${resp.scannedRows} truncated=${t}${t ? ' (NOT proof of absence; continue with nextCursor or narrow the window)' : ''}${resp.nextCursor ? ' nextCursor=present' : ''}`;
+  // exact=false: the answer involves the AI-search index, which is best-effort (written behind, can lag, misses text that starts mid-word).
+  const bestEffort = resp.exact === false ? ' exact=false (answered from the best-effort search index: it can lag and misses text that starts mid-word, so treat counts as a floor, not exact)' : '';
+  return `searchPath=${resp.searchPath} scannedRows=${resp.scannedRows} truncated=${t}${t ? ' (NOT proof of absence; continue with nextCursor or narrow the window)' : ''}${bestEffort}${resp.nextCursor ? ' nextCursor=present' : ''}`;
 }

package/lib/log-search.test.js

@@ -1,51 +1,86 @@
 // Regression (2026-10-14): velaro-messaging's logs search under-reported text queries (q=[HttpFallback] returned 0-2 rows
 // while 136 existed; q=AsrsNegotiateFailed with no level returned 0 while 4 existed) because each scan only examined the
-// newest N rows of the window and never said so. completeLogSearch must find rows behind an arbitrary pile of newer
-// rows, say COMPLETE only when no slice hit the server cap, and never send q=.
+// newest N rows of the window and never said so. completeLogSearch must find rows behind an arbitrary pile of newer rows,
+// say COMPLETE only when the whole window was covered, honour its request/time budgets, and (older servers) never send q=.
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { completeLogSearch, describeCompleteness, describeRawMeta } from './log-search.js';
+import { completeLogSearch, describeCompleteness, describeRawMeta, escapeRegex, fetchJsonRetry } from './log-search.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
-/** Mock of the messaging search endpoint: newest-first scan capped at `cap` rows BEFORE any filter other than level/site. */
-function mockServer(rows, cap = 5000) {
+/**
+ * Mock of the messaging search endpoint.
+ *  legacy=true : OLD server: newest-first fetch capped at `cap` rows BEFORE any non-OData filter, no truncated/scannedRows,
+ *                includeTotal reports totalCountCapped.
+ *  legacy=false: NEW server (#2510): server-side text filtering while scanning (q as regex when regex=true), scan stops after
+ *                `take` matches or `cap` examined rows, returns truncated/scannedRows and a nextCursor whenever more may exist.
+ */
+function mockServer(rows, { cap = 5000, legacy = false } = {}) {
   const calls = [];
   const fetchJson = async (query) => {
     const p = new URLSearchParams(query);
     calls.push(p);
-    assert.equal(p.get('q'), null, 'the complete read must never send q=');
-    assert.equal(p.get('regex'), null);
     const from = new Date(p.get('from')).getTime();
     const to = new Date(p.get('to')).getTime();
     const lvl = p.get('level');
     const site = p.get('siteId');
-    // newest first, server-side filters first, then the fetch cap (the real bug), then in-window filter
+    const take = Number(p.get('take'));
     let pool = rows.filter((r) => (!lvl || r.level === lvl) && (!site || String(r.siteId) === site));
     pool = pool.filter((r) => new Date(r.timestamp).getTime() >= from && new Date(r.timestamp).getTime() <= to);
     pool.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-    const capped = pool.length >= cap;
-    const fetched = pool.slice(0, cap);
-    const take = Number(p.get('take'));
-    let start = 0;
-    if (p.get('cursor')) start = fetched.findIndex((r) => r.id === p.get('cursor')) + 1;
-    const page = fetched.slice(start, start + take);
-    const more = start + take < fetched.length;
-    const out = { entries: page, nextCursor: more ? page[page.length - 1].id : null };
-    if (p.get('includeTotal') === 'true') { out.totalCount = fetched.length; out.totalCountCapped = capped; }
-    return out;
+
+    if (legacy) {
+      // The only request allowed to carry q is the first (the new-server probe), and then only with regex=true, which forces the exact
+      // path: the AI-search path (the one that under-reports) must never be reachable. Every bisect request after it has no q at all.
+      if (p.get('q') !== null) {
+        assert.equal(calls.length, 1, 'only the probe may carry q=; bisect requests must not');
+        assert.equal(p.get('regex'), 'true', 'a q= sent to an old server must force the exact path with regex=true');
+      }
+      const capped = pool.length >= cap;
+      const fetched = pool.slice(0, cap);
+      let start = 0;
+      if (p.get('cursor')) start = fetched.findIndex((r) => r.id === p.get('cursor')) + 1;
+      const page = fetched.slice(start, start + take);
+      const out = { entries: page, nextCursor: start + take < fetched.length ? page[page.length - 1].id : null };
+      if (p.get('includeTotal') === 'true') { out.totalCount = fetched.length; out.totalCountCapped = capped; }
+      return out;
+    }
+
+    const re = p.get('q') ? new RegExp(p.get('q'), 'i') : null;
+    const lre = p.get('logger') ? new RegExp(p.get('logger'), 'i') : null;
+    let startIdx = 0;
+    if (p.get('cursor')) startIdx = pool.findIndex((r) => r.id === p.get('cursor')) + 1;
+    const matches = [];
+    let examined = 0;
+    let more = false;
+    let capHit = false;
+    let lastId = null;
+    for (let i = startIdx; i < pool.length; i++) {
+      if (examined >= cap) { capHit = true; break; }
+      examined++;
+      lastId = pool[i].id;
+      const r = pool[i];
+      if ((!re || re.test(r.message)) && (!lre || lre.test(r.logger))) {
+        if (matches.length >= take) { more = true; break; }
+        matches.push(r);
+      }
+    }
+    let nextCursor = null;
+    if (more) nextCursor = matches[matches.length - 1].id;
+    else if (capHit) nextCursor = lastId;
+    return { entries: matches, nextCursor, searchPath: 'table-storage', scannedRows: examined, truncated: capHit };
   };
   return { fetchJson, calls };
 }
 
-function makeRows(n, needles) {
+function makeRows(n, needles, level = 'WARN') {
   const base = Date.UTC(2026, 9, 14, 13, 45, 0);
   const rows = [];
   for (let i = 0; i < n; i++) {
-    rows.push({ id: `r${String(i).padStart(7, '0')}`, timestamp: new Date(base - i * 1000).toISOString(), level: 'WARN', siteId: 20519, logger: 'VisitorLoggingService', message: needles.has(i) ? '[AsrsNegotiateFailed] site=20715' : `noise ${i}` });
+    rows.push({ id: `r${String(i).padStart(7, '0')}`, timestamp: new Date(base - i * 1000).toISOString(), level, siteId: 20519, logger: 'VisitorLoggingService', message: needles.has(i) ? '[AsrsNegotiateFailed] site=20715' : `noise ${i}` });
   }
   return rows;
 }
@@ -53,28 +88,58 @@ const W = (rows) => [new Date(rows[rows.length - 1].timestamp), new Date(rows[0]
 
 test('the single raw call misses a needle behind 9,000 newer rows (the live bug shape)', async () => {
   const rows = makeRows(12000, new Set([9000]));
-  const { fetchJson } = mockServer(rows, 5000);
+  const { fetchJson } = mockServer(rows, { legacy: true });
   const [from, to] = W(rows);
   const raw = await fetchJson(new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: '500', includeTotal: 'true' }).toString());
   assert.equal(raw.totalCountCapped, true);
   assert.equal(raw.entries.some((e) => e.message.includes('AsrsNegotiate')), false);
 });
 
-test('completeLogSearch finds the needle behind 9,000 newer rows and reports COMPLETE', async () => {
+// ---------------- CURSOR mode (new server) ----------------
+
+test('CURSOR mode: finds a needle behind 9,000 newer rows via server-side text filtering and cursor paging, COMPLETE, few requests', async () => {
   const rows = makeRows(12000, new Set([9000, 11000]));
-  const { fetchJson } = mockServer(rows, 5000);
+  const { fetchJson, calls } = mockServer(rows, { cap: 5000 });
   const [from, to] = W(rows);
-  const r = await completeLogSearch({ fetchJson, from, to, contains: '[AsrsNegotiateFailed]', maxRequests: 200 });
+  const r = await completeLogSearch({ fetchJson, from, to, contains: '[AsrsNegotiateFailed]' });
+  assert.equal(r.mode, 'cursor');
   assert.equal(r.entries.length, 2);
   assert.equal(r.complete, true);
-  assert.ok(r.slices > 1, 'capped slices must have been bisected');
+  assert.ok(r.requests <= 4, `expected a handful of requests, got ${r.requests}`);   // 12,000 rows / 5,000-row scans, not hundreds
+  assert.equal(r.scanned, 12000);                                                    // the REAL server scannedRows, summed
   assert.match(describeCompleteness(r), /COMPLETE/);
   assert.doesNotMatch(describeCompleteness(r), /INCOMPLETE/);
+  // text is sent as an ESCAPED regex with regex=true (forces the exact path), and the AI-search fall-through is disabled
+  assert.equal(calls[0].get('regex'), 'true');
+  assert.equal(calls[0].get('q'), escapeRegex('[AsrsNegotiateFailed]'));
+  assert.equal(calls[0].get('fallthrough'), 'false');
 });
 
-test('a request budget that runs out is INCOMPLETE, never a silent partial', async () => {
-  const rows = makeRows(12000, new Set([9000]));
-  const { fetchJson } = mockServer(rows, 5000);
+test('CURSOR mode: an UNFILTERED default search is a couple of requests, not hundreds (wanted=50 stops after the first page)', async () => {
+  const rows = makeRows(84000, new Set());
+  const { fetchJson } = mockServer(rows, { cap: 60000 });
+  const [from, to] = W(rows);
+  const r = await completeLogSearch({ fetchJson, from, to, wanted: 50 });
+  assert.equal(r.mode, 'cursor');
+  assert.equal(r.requests, 1);
+  assert.equal(r.satisfied, true);
+  assert.ok(r.entries.length >= 50);
+  assert.match(describeCompleteness(r), /more may exist/);
+});
+
+test('CURSOR mode: a genuine 0 follows the cursor to the end and says COMPLETE', async () => {
+  const rows = makeRows(14000, new Set());
+  const { fetchJson } = mockServer(rows, { cap: 5000 });
+  const [from, to] = W(rows);
+  const r = await completeLogSearch({ fetchJson, from, to, contains: 'nope' });
+  assert.equal(r.entries.length, 0);
+  assert.equal(r.complete, true);
+  assert.match(describeCompleteness(r), /0 matches means nothing was logged/);
+});
+
+test('CURSOR mode: the request budget ending mid-cursor is INCOMPLETE, never a silent partial', async () => {
+  const rows = makeRows(20000, new Set([19000]));
+  const { fetchJson } = mockServer(rows, { cap: 5000 });
   const [from, to] = W(rows);
   const r = await completeLogSearch({ fetchJson, from, to, contains: '[AsrsNegotiateFailed]', maxRequests: 2 });
   assert.equal(r.complete, false);
@@ -83,25 +148,73 @@ test('a request budget that runs out is INCOMPLETE, never a silent partial', asy
   assert.match(describeCompleteness(r), /NOT proof of absence/);
 });
 
-test('level and siteId are pushed server side; contains/regex/logger filter client side', async () => {
+test('CURSOR mode: the wall-clock budget ending mid-cursor is INCOMPLETE', async () => {
+  const rows = makeRows(20000, new Set([19000]));
+  const { fetchJson } = mockServer(rows, { cap: 5000 });
+  const slow = async (q) => { await new Promise((r) => setTimeout(r, 30)); return fetchJson(q); };
+  const [from, to] = W(rows);
+  const r = await completeLogSearch({ fetchJson: slow, from, to, contains: '[AsrsNegotiateFailed]', maxSeconds: 0.01 });
+  assert.equal(r.complete, false);
+  assert.equal(r.timeExhausted, true);
+  assert.match(describeCompleteness(r), /time budget exhausted/);
+});
+
+// ---------------- BISECT mode (older server) ----------------
+
+test('BISECT mode (old server): finds the needle behind 9,000 newer rows, never sends q=, reports COMPLETE', async () => {
+  const rows = makeRows(12000, new Set([9000, 11000]));
+  const { fetchJson } = mockServer(rows, { cap: 5000, legacy: true });
+  const [from, to] = W(rows);
+  const r = await completeLogSearch({ fetchJson, from, to, contains: '[AsrsNegotiateFailed]', maxRequests: 200 });
+  assert.equal(r.mode, 'bisect');
+  assert.equal(r.entries.length, 2);
+  assert.equal(r.complete, true);
+  assert.ok(r.slices > 1, 'capped slices must have been bisected');
+});
+
+test('BISECT mode: level and siteId are pushed server side; contains/regex/logger filter client side', async () => {
   const rows = makeRows(300, new Set([10, 20]));
   rows[5].logger = 'Other.Logger';
-  const { fetchJson, calls } = mockServer(rows, 5000);
+  const { fetchJson, calls } = mockServer(rows, { cap: 5000, legacy: true });
   const [from, to] = W(rows);
   const r = await completeLogSearch({ fetchJson, from, to, params: { level: 'warn', siteId: 20519 }, regex: 'Asrs.*Failed', logger: 'visitorlogging' });
   assert.equal(r.entries.length, 2);
-  assert.equal(calls[0].get('level'), 'WARN');
-  assert.equal(calls[0].get('siteId'), '20519');
+  assert.equal(calls.at(-1).get('level'), 'WARN');
+  assert.equal(calls.at(-1).get('siteId'), '20519');
   assert.equal(r.complete, true);
 });
 
-test('a genuine 0 on a complete scan says so (0 means nothing was logged)', async () => {
-  const rows = makeRows(500, new Set());
-  const { fetchJson } = mockServer(rows, 5000);
+test('BISECT mode: a request budget that runs out is INCOMPLETE', async () => {
+  const rows = makeRows(12000, new Set([9000]));
+  const { fetchJson } = mockServer(rows, { cap: 5000, legacy: true });
   const [from, to] = W(rows);
-  const r = await completeLogSearch({ fetchJson, from, to, contains: 'nope' });
-  assert.equal(r.entries.length, 0);
-  assert.match(describeCompleteness(r), /0 matches means nothing was logged/);
+  const r = await completeLogSearch({ fetchJson, from, to, contains: '[AsrsNegotiateFailed]', maxRequests: 2 });
+  assert.equal(r.complete, false);
+  assert.equal(r.budgetExhausted, true);
+});
+
+// ---------------- shared behaviour ----------------
+
+test('results are ordered by instant, not by string: mixed fractional-second digit counts', async () => {
+  const mk = (id, ts) => ({ id, timestamp: ts, level: 'WARN', siteId: 1, logger: 'x', message: 'm' });
+  // as strings "…:10Z" > "…:10.5Z" (because 'Z' > '.') although 10.5 s is LATER than 10 s
+  const rows = [mk('a', '2026-10-14T13:00:10Z'), mk('b', '2026-10-14T13:00:10.5Z'), mk('c', '2026-10-14T13:00:10.25Z')];
+  const fetchJson = async () => ({ entries: rows, nextCursor: null, searchPath: 'table-storage', scannedRows: 3, truncated: false });
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:01:00Z') });
+  assert.deepEqual(r.entries.map((e) => e.id), ['b', 'c', 'a']);
+});
+
+test('fetchJsonRetry honours 429 Retry-After, then succeeds; gives up after the retry budget', async () => {
+  const waits = [];
+  const mkRes = (status, retryAfter, body) => ({ status, ok: status >= 200 && status < 300, headers: { get: () => retryAfter }, json: async () => body, text: async () => 'busy' });
+  let n = 0;
+  const ok = await fetchJsonRetry('u', {}, { fetchImpl: async () => (++n < 3 ? mkRes(429, '2', null) : mkRes(200, null, { done: true })), sleepImpl: async (ms) => { waits.push(ms); } });
+  assert.deepEqual(ok, { done: true });
+  assert.deepEqual(waits, [2000, 2000]);
+
+  n = 0;
+  await assert.rejects(() => fetchJsonRetry('u', {}, { retries: 2, fetchImpl: async () => { n++; return mkRes(429, '1', null); }, sleepImpl: async () => {} }), (e) => e.status === 429);
+  assert.equal(n, 3);
 });
 
 test('describeRawMeta surfaces searchPath/scannedRows/truncated and warns on old deploys', () => {
@@ -117,13 +230,145 @@ test('cli/lib/log-search.js and mcp/log-search.js are byte-identical (the npm pa
   assert.equal(a, b, 'copy cli/lib/log-search.js to mcp/log-search.js (or the reverse)');
 });
 
-test('neither the CLI search handler nor the MCP tool sends q= in complete mode', () => {
+test('no staff log check searches the literal TEXT "level:ERROR" or "X OR Y" (they always matched nothing and printed "no errors")', () => {
+  for (const rel of ['commands/logs.js', 'commands/ops.js', '../../mcp/staff-server.js', '../../mcp/server.js']) {
+    const src = fs.readFileSync(path.join(here, rel), 'utf8');
+    assert.ok(!/q=level%3AERROR/.test(src) && !/search\('level:ERROR'\)/.test(src), `${rel}: still searches the text "level:ERROR"`);
+    assert.ok(!/q=WF-AI-ROUTE\+OR\+PERF-SLOW/.test(src) && !/search\('WF-AI-ROUTE OR PERF-SLOW'\)/.test(src), `${rel}: still searches the text "WF-AI-ROUTE OR PERF-SLOW"`);
+  }
+});
+
+test('the complete-mode handlers use completeLogSearch and never set q= themselves', () => {
   const cli = fs.readFileSync(path.join(here, 'commands', 'logs.js'), 'utf8');
   const mcp = fs.readFileSync(path.join(here, '..', '..', 'mcp', 'staff-server.js'), 'utf8');
-  for (const [name, src, marker] of [['cli', cli, 'Default: COMPLETE read'], ['mcp', mcp, 'Default: COMPLETE read']]) {
-    const tail = src.slice(src.indexOf(marker));
-    const handler = tail.slice(0, 1200);
+  for (const [name, src] of [['cli', cli], ['mcp', mcp]]) {
+    const tail = src.slice(src.indexOf('Default: COMPLETE read'));
+    const handler = tail.slice(0, 1400);
     assert.ok(handler.includes('completeLogSearch('), `${name}: complete mode must call completeLogSearch`);
-    assert.ok(!/params\.set\('q'/.test(handler), `${name}: complete mode must not set q=`);
+    assert.ok(!/params\.set\('q'/.test(handler), `${name}: complete mode must not set q= itself`);
   }
 });
+
+test('timeouts: log searches allow the server scan budget (12 s + 6 s AI search), not the 20 s default', () => {
+  for (const rel of ['commands/logs.js', '../../mcp/staff-server.js']) {
+    assert.match(fs.readFileSync(path.join(here, rel), 'utf8'), /AbortSignal\.timeout\(40000\)/, `${rel}: log search timeout must be 40 s`);
+  }
+});
+
+// ---------------- Opus final check (2026-10-14): the cursor protocol must never turn a truncated scan into COMPLETE ----------------
+
+test('CURSOR mode: truncated=true with NO cursor is INCOMPLETE, never COMPLETE (the server deadline fired before any row)', async () => {
+  const fetchJson = async () => ({ entries: [], nextCursor: null, searchPath: 'table-storage', scannedRows: 0, truncated: true });
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:45:00Z'), contains: 'x' });
+  assert.equal(r.mode, 'cursor');
+  assert.equal(r.complete, false);
+  assert.match(describeCompleteness(r), /INCOMPLETE/);
+  assert.match(r.unresolved.join(' '), /without a cursor/);
+});
+
+test('CURSOR mode: a LATER page that is truncated without a cursor is INCOMPLETE too (it needs truncated===false on the last page)', async () => {
+  let n = 0;
+  const fetchJson = async () => (++n === 1
+    ? { entries: [{ id: 'a', timestamp: '2026-10-14T13:00:00Z', message: 'm' }], nextCursor: 'c1', scannedRows: 10, truncated: true }
+    : { entries: [], nextCursor: null, scannedRows: 0, truncated: true });
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:45:00Z'), contains: 'm' });
+  assert.equal(r.complete, false);
+  assert.equal(r.requests, 2);
+});
+
+test('CURSOR mode: a last page that does not confirm truncated===false is not COMPLETE', async () => {
+  let n = 0;
+  const fetchJson = async () => (++n === 1
+    ? { entries: [], nextCursor: 'c1', scannedRows: 10, truncated: true }
+    : { entries: [], nextCursor: null, scannedRows: 10 });          // truncated missing: unknown, so not proof
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:45:00Z'), contains: 'm' });
+  assert.equal(r.complete, false);
+});
+
+test('CURSOR mode: the server handing back the SAME cursor means no progress: INCOMPLETE, and the loop stops', async () => {
+  let n = 0;
+  const fetchJson = async () => { n++; return { entries: [], nextCursor: 'stuck', scannedRows: 0, truncated: true }; };
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:45:00Z'), contains: 'm', maxRequests: 50 });
+  assert.equal(r.complete, false);
+  assert.match(r.unresolved.join(' '), /no progress/);
+  assert.ok(n <= 3, `must stop at the first repeated cursor, made ${n} requests`);
+});
+
+test('CURSOR mode: a page chain that ends with truncated===false and no cursor IS complete', async () => {
+  let n = 0;
+  const fetchJson = async () => (++n === 1
+    ? { entries: [], nextCursor: 'c1', scannedRows: 5000, truncated: true }
+    : { entries: [{ id: 'a', timestamp: '2026-10-14T13:00:00Z', message: 'm' }], nextCursor: null, scannedRows: 4000, truncated: false });
+  const r = await completeLogSearch({ fetchJson, from: new Date('2026-10-14T13:00:00Z'), to: new Date('2026-10-14T13:45:00Z'), contains: 'm' });
+  assert.equal(r.complete, true);
+  assert.equal(r.scanned, 9000);
+  assert.equal(r.entries.length, 1);
+});
+
+test('fetchRetry429 retries only 429 and returns the final response after the retry budget', async () => {
+  const { fetchRetry429 } = await import('./log-search.js');
+  let n = 0;
+  const waits = [];
+  const mk = (status) => ({ status, ok: status < 300, headers: { get: () => '1' } });
+  const res = await fetchRetry429('u', {}, { retries: 2, fetchImpl: async () => { n++; return mk(429); }, sleepImpl: async (ms) => { waits.push(ms); } });
+  assert.equal(res.status, 429);
+  assert.equal(n, 3);
+  assert.deepEqual(waits, [1000, 1000]);
+  n = 0;
+  const ok = await fetchRetry429('u', {}, { fetchImpl: async () => { n++; return mk(500); }, sleepImpl: async () => {} });
+  assert.equal(ok.status, 500);
+  assert.equal(n, 1);                                                   // a 500 is not retried
+});
+
+test('bot_full_diagnostic: errors use the server-side level=ERROR filter, patterns are a separate read; neither is the old text regex', () => {
+  for (const rel of ['../../mcp/staff-server.js', '../../mcp/server.js']) {
+    const src = fs.readFileSync(path.join(here, rel), 'utf8');
+    const a = src.indexOf('const velaroLoggerP = safeJson');
+    const body = src.slice(a, a + 2600);
+    assert.ok(body.includes('level=ERROR'), `${rel}: errors must use level=ERROR`);
+    assert.ok(body.includes("WF-AI-ROUTE|PERF-SLOW"), `${rel}: patterns are their own read`);
+    assert.ok(!body.includes("'ERROR|WF-AI-ROUTE|PERF-SLOW'"), `${rel}: still runs the regex ERROR|... over message text`);
+    assert.ok(/errRes[\s\S]*patRes/.test(body), `${rel}: two reads expected`);
+  }
+});
+
+test('both MCP servers retry 429 on their messaging calls (GETs)', () => {
+  for (const rel of ['../../mcp/staff-server.js', '../../mcp/server.js']) {
+    const src = fs.readFileSync(path.join(here, rel), 'utf8');
+    assert.ok(src.includes('fetchRetry429('), `${rel}: messagingApi must retry 429`);
+  }
+});
+
+test('describeRawMeta surfaces the best-effort caveat when exact=false (an AI-search-index answer is a floor, never exact)', () => {
+  const m = describeRawMeta({ entries: [], searchPath: 'ai-search', scannedRows: 400, truncated: false, exact: false });
+  assert.match(m, /exact=false/);
+  assert.match(m, /best-effort search index/);
+  assert.match(m, /floor, not exact/);
+  // an authoritative table answer carries no caveat
+  assert.doesNotMatch(describeRawMeta({ entries: [], searchPath: 'table-storage', scannedRows: 400, truncated: false, exact: true }), /exact=false/);
+  // an older server that does not send exact at all is not accused of being best-effort
+  assert.doesNotMatch(describeRawMeta({ entries: [], searchPath: 'table-storage', scannedRows: 400, truncated: false }), /exact=false/);
+});
+
+test('ops health and the diagnostics run their log searches ONE AT A TIME and retry 429 (the server runs 2 exact scans per instance)', () => {
+  const parallelSearch = /await Promise\.all\(\[\s*(search\(|messagingApi\(|fetch\()/;
+  for (const rel of ['commands/ops.js', 'commands/logs.js', '../../mcp/staff-server.js', '../../mcp/server.js']) {
+    const src = fs.readFileSync(path.join(here, rel), 'utf8');
+    assert.ok(!parallelSearch.test(src), rel + ': log searches must not be fired in parallel');
+  }
+  assert.ok(fs.readFileSync(path.join(here, 'commands', 'ops.js'), 'utf8').includes('fetchRetry429('));
+});
+
+test('fetchRetry429: a 429 with NO Retry-After waits the 5 s default (Number(null) is 0: it must not become an immediate retry)', async () => {
+  const { fetchRetry429 } = await import('./log-search.js');
+  const waits = [];
+  let n = 0;
+  const noHeader = (status) => ({ status, ok: status < 300, headers: { get: () => null } });
+  await fetchRetry429('u', {}, { fetchImpl: async () => (++n < 3 ? noHeader(429) : noHeader(200)), sleepImpl: async (ms) => { waits.push(ms); } });
+  assert.deepEqual(waits, [5000, 5000]);
+  // an explicit Retry-After: 0 is honoured as 0 (retry now), it is not mistaken for "missing"
+  const zero = [];
+  n = 0;
+  await fetchRetry429('u', {}, { fetchImpl: async () => (++n < 2 ? { status: 429, ok: false, headers: { get: () => '0' } } : noHeader(200)), sleepImpl: async (ms) => { zero.push(ms); } });
+  assert.deepEqual(zero, [0]);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.96",
+  "version": "1.4.97",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {