sweet-search 2.6.17 → 2.7.0

package/core/search/search-server.js

@@ -15,6 +15,17 @@ import { LATE_INTERACTION_CONFIG } from '../infrastructure/config/index.js';
 import { clearCache } from '../embedding/embedding-cache.js';
 import { launchMaintainer } from '../indexing/maintainer-launcher.mjs';
 import { projectSocketPath, projectPidFile, tcpPort, resolveProjectRoot } from './server-identity.js';
+import {
+  AgentSpanLedger,
+  applyReadOmissionDecisions,
+  collectAgentShownSpans,
+  collectReadShownSpans,
+  collectSemanticShownSpans,
+  exactRereadOmissionEnabled,
+  flagEnabled,
+  resolveAgentSessionId,
+  validAgentSessionId,
+} from './agent-span-ledger.js';
 import {
   upsertSelf as registryUpsertSelf,
   touchSelf as registryTouchSelf,
@@ -22,6 +33,7 @@ import {
   pruneAndList as registryPruneAndList,
   selectEvictionTargets as registrySelectEvictionTargets,
 } from './daemon-registry.js';
+import { renderRegexDialectHint } from './regex-dialect.js';
 
 // =============================================================================
 // Server constants
@@ -36,9 +48,19 @@ export const SEARCH_SERVER_TIMEOUT_MS = 30_000;
 export const SEARCH_SERVER_MAX_URL_LENGTH = 16_384;
 export const SEARCH_SERVER_MAX_QUERY_LENGTH = 2_000;
 export const SEARCH_SERVER_MAX_READ_PATH_LENGTH = 8_192;
+const AGENT_SPAN_BODY_MAX_BYTES = 64 * 1024;
 
 const AGENT_FORMATS = new Set(['agent', 'agent_preview', 'agent_full', 'agent_full_xl']);
 
+export function resolveAgentSearchRequest(rawFormat, agentRequested = false) {
+  const explicit = AGENT_FORMATS.has(rawFormat) ? rawFormat : undefined;
+  const requested = agentRequested === true;
+  return {
+    agentFormat: explicit || (requested ? 'agent' : undefined),
+    renderText: requested && rawFormat === 'text' && !explicit,
+  };
+}
+
 function canonicalProjectRoot(root) {
   const resolved = path.resolve(root || process.cwd());
   try {
@@ -62,6 +84,14 @@ function parseInteger(value, name) {
   return n;
 }
 
+function parseBoundedSearchInteger(value, name, max) {
+  if (value == null || value === '') return 0;
+  if (!/^\d+$/.test(value)) throw new Error(`${name} must be a non-negative integer`);
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n > max) throw new Error(`${name} must be <= ${max}`);
+  return n;
+}
+
 function reusableLateInteractionIndex(searcher) {
   const idx = searcher?.lateInteractionIndex || null;
   if (!idx) return null;
@@ -78,6 +108,85 @@ function readSemanticError(status, message, extra = {}) {
   };
 }
 
+export function buildAgentSpanDaemonResponse(payload, {
+  isUnixSocket = false,
+  ledger = null,
+} = {}) {
+  if (!isUnixSocket) return readSemanticError(403, '/agent-spans is only available via Unix socket');
+  if (!ledger || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return readSemanticError(400, 'Invalid agent-span request');
+  }
+  const { operation, sessionId, force = false } = payload;
+  if (!validAgentSessionId(sessionId)) return readSemanticError(400, 'Invalid session id');
+  if (operation === 'reset' || operation === 'drop') {
+    ledger.reset(sessionId);
+    return { status: 200, contentType: 'application/json', body: JSON.stringify({ ok: true }) };
+  }
+  if (operation !== 'observe' && operation !== 'read') {
+    return readSemanticError(400, 'Invalid agent-span operation');
+  }
+  if (!Array.isArray(payload.spans) || payload.spans.length > 20) {
+    return readSemanticError(400, 'Invalid agent-span receipts');
+  }
+  if ((payload.query != null
+      && (typeof payload.query !== 'string' || payload.query.length > SEARCH_SERVER_MAX_QUERY_LENGTH))
+      || (payload.regex != null
+        && (typeof payload.regex !== 'string' || payload.regex.length > SEARCH_SERVER_MAX_QUERY_LENGTH))) {
+    return readSemanticError(400, 'Invalid agent-span query context');
+  }
+
+  const call = ledger.beginCall(sessionId);
+  if (call == null) return readSemanticError(400, 'Invalid session id');
+  ledger.rememberQueryAtCall(sessionId, call, payload.query, payload.regex);
+  const decisions = operation === 'read'
+    ? ledger.decideAndObserveAtCall(sessionId, call, payload.spans, { force: force === true })
+    : (ledger.observeAtCall(sessionId, call, payload.spans), []);
+  return {
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      ok: true,
+      call,
+      decisions,
+      queryEvidence: ledger.queryEvidence(sessionId),
+    }),
+  };
+}
+
+async function readBoundedJsonBody(req, maxBytes = AGENT_SPAN_BODY_MAX_BYTES) {
+  const declared = Number(req.headers?.['content-length'] || 0);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    const err = new Error('Request body too large');
+    err.status = 413;
+    throw err;
+  }
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > maxBytes) {
+      const err = new Error('Request body too large');
+      err.status = 413;
+      throw err;
+    }
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    const err = new Error('Invalid JSON body');
+    err.status = 400;
+    throw err;
+  }
+}
+
+function beginAgentSpanUrlCall(url, ledger, { enabled = true } = {}) {
+  if (!enabled || !ledger || !flagEnabled(url.searchParams.get('exactRereadOmission'))) return null;
+  const sessionId = url.searchParams.get('agentSessionId');
+  if (!validAgentSessionId(sessionId)) return null;
+  const call = ledger.beginCall(sessionId);
+  return call == null ? null : { sessionId, call };
+}
+
 export async function buildReadSemanticDaemonResponse(reqUrl, {
   isUnixSocket = false,
   serverReady = false,
@@ -85,6 +194,7 @@ export async function buildReadSemanticDaemonResponse(reqUrl, {
   searcher = null,
   readSemanticFn = null,
   formatReadSemanticResultFn = null,
+  agentSpanLedger = null,
 } = {}) {
   if (!isUnixSocket) {
     return readSemanticError(403, '/read-semantic is only available via Unix socket');
@@ -141,6 +251,7 @@ export async function buildReadSemanticDaemonResponse(reqUrl, {
     return readSemanticError(400, err.message);
   }
   const verbose = url.searchParams.get('verbose') === 'true';
+  const agentSpanCall = beginAgentSpanUrlCall(url, agentSpanLedger, { enabled: format === 'agent' });
 
   try {
     let readSemantic = readSemanticFn;
@@ -162,6 +273,11 @@ export async function buildReadSemanticDaemonResponse(reqUrl, {
       verbose,
       _lateInteractionIndex: reusableLateInteractionIndex(searcher),
     });
+    if (agentSpanCall) {
+      const spans = collectSemanticShownSpans(result, { projectRoot: serverRoot });
+      agentSpanLedger.rememberQueryAtCall(agentSpanCall.sessionId, agentSpanCall.call, query);
+      agentSpanLedger.observeAtCall(agentSpanCall.sessionId, agentSpanCall.call, spans);
+    }
     const body = formatReadSemanticResult(result, format);
     return {
       status: result?.ok === false ? 404 : 200,
@@ -183,6 +299,7 @@ export async function buildTraceDaemonResponse(reqUrl, {
   serverReady = false,
   initError = null,
   searcher = null,
+  agentSpanLedger = null,
 } = {}) {
   if (!isUnixSocket) {
     return readSemanticError(403, '/trace is only available via Unix socket');
@@ -231,6 +348,7 @@ export async function buildTraceDaemonResponse(reqUrl, {
   } catch (err) {
     return readSemanticError(400, err.message);
   }
+  const agentSpanCall = beginAgentSpanUrlCall(url, agentSpanLedger, { enabled: !json });
 
   try {
     const { traceSymbol, formatStructuralContext } = await import('./search-trace.js');
@@ -243,6 +361,14 @@ export async function buildTraceDaemonResponse(reqUrl, {
       maxDepth: maxDepth ?? 3,
       tokenBudget: tokenBudget ?? null,
     });
+    if (agentSpanCall) {
+      agentSpanLedger.rememberQueryAtCall(
+        agentSpanCall.sessionId,
+        agentSpanCall.call,
+        `${symbol} ${queryHint}`.trim(),
+      );
+      agentSpanLedger.observeAtCall(agentSpanCall.sessionId, agentSpanCall.call, []);
+    }
     // handleTraceCli writes `console.log(json ? JSON : formatStructuralContext)`,
     // i.e. body + exactly one trailing newline in BOTH modes.
     const body = json ? JSON.stringify(result, null, 2) : formatStructuralContext(result);
@@ -266,6 +392,7 @@ export async function buildReadDaemonResponse(reqUrl, {
   serverReady = false,
   initError = null,
   searcher = null,
+  agentSpanLedger = null,
 } = {}) {
   if (!isUnixSocket) {
     return readSemanticError(403, '/read is only available via Unix socket');
@@ -291,6 +418,10 @@ export async function buildReadDaemonResponse(reqUrl, {
   const requestedRoot = url.searchParams.get('projectRoot') || '';
   const fmtParam = url.searchParams.get('format') || 'agent';
   const format = (fmtParam === 'json' || fmtParam === 'raw') ? fmtParam : 'agent';
+  const exactRereadOmission = format === 'agent'
+    && flagEnabled(url.searchParams.get('exactRereadOmission'));
+  const agentSessionId = url.searchParams.get('agentSessionId');
+  const force = url.searchParams.get('force') === 'true';
 
   if (paths.length === 0) return readSemanticError(400, 'Missing path parameter ?path=');
   if (paths.length > 20) return readSemanticError(413, 'read accepts at most 20 files');
@@ -331,7 +462,21 @@ export async function buildReadDaemonResponse(reqUrl, {
   try {
     const { readFiles, formatReadResults } = await import('./search-read.js');
     const out = await readFiles(files, { projectRoot: serverRoot, includeMetadata });
-    const body = formatReadResults(out, format);
+    let queryEvidence = null;
+    if (exactRereadOmission && agentSpanLedger && validAgentSessionId(agentSessionId)) {
+      const spans = collectReadShownSpans(out, { projectRoot: serverRoot });
+      const agentSpanCall = beginAgentSpanUrlCall(url, agentSpanLedger);
+      if (agentSpanCall) {
+        const compactDecisions = agentSpanLedger.decideAndObserveAtCall(
+          agentSpanCall.sessionId, agentSpanCall.call, spans, { force },
+        );
+        const decisions = Array.from({ length: out.files.length }, () => ({ omit: false }));
+        spans.forEach((span, index) => { decisions[span.resultIndex] = compactDecisions[index]; });
+        applyReadOmissionDecisions(out, decisions);
+        queryEvidence = agentSpanLedger.queryEvidence(agentSpanCall.sessionId);
+      }
+    }
+    const body = formatReadResults(out, format, { surface: 'cli', queryEvidence });
     // handleReadCli appends '\n' for non-json output (the extra process.stdout
     // .write('\n')); json gets no trailing newline. Mirror exactly.
     const allFailed = out.files.length > 0 && out.files.every(f => !f.ok);
@@ -437,13 +582,54 @@ function buildTextSearchResponse(results, stats, totalTime, { summary = false, m
     });
   }
 
+  const regexDialectNote = renderRegexDialectHint(stats?.regexDialectHint);
+  if (regexDialectNote) out += `${regexDialectNote}\n`;
+
+  return out;
+}
+
+/** Render a packaged agent response for the native captured-output CLI. */
+export function renderAgentSearchResponse(response) {
+  const results = response?.results || [];
+  const routing = response?.stats?.routing || {};
+  const routedMode = routing.mode || response?.mode || 'auto';
+  let out = `# sweet-search: routed=${routedMode} budget=${response?.tokenBudget ?? '?'} used=${response?.tokensUsed ?? '?'} results=${results.length} subMode=${response?.subMode ?? 'agent'}\n`;
+  if (response?.confidence) {
+    out += `# confidence=${response.confidence}${response.confidenceReason ? ` (${response.confidenceReason})` : ''}`;
+    if (response.sufficiencyVerdict) out += ` sufficient=${response.sufficiencyVerdict}`;
+    out += '\n';
+  }
+  for (const result of results) {
+    const symbol = result.symbol ? ` [${result.symbolType || 'code'}: ${result.symbol}]` : '';
+    const kind = result.expansionKind ? ` kind=${result.expansionKind}` : '';
+    const stale = result.stale ? ' STALE' : '';
+    out += `\n## #${result.rank} ${result.file}:${result.startLine}-${result.endLine}${symbol} (${result.presentation}${kind}${stale}) score=${(result.score || 0).toFixed(3)}\n`;
+    if (result.headerContext) out += `### imports\n\`\`\`\n${result.headerContext}\n\`\`\`\n`;
+    if (result.code) out += `\`\`\`\n${result.code}\n\`\`\`\n`;
+    else if (result.summary) out += `${result.summary}\n`;
+    if (result.neighbors?.rendered) {
+      out += `### related (1-hop graph, ~${result.neighbors.tokens} tok)\n${result.neighbors.rendered}\n`;
+    }
+    if (result.sameFile?.rendered) out += `${result.sameFile.rendered}\n`;
+    if (result.continuation?.rendered) {
+      out += `${result.continuation.rendered}\n`;
+      if (result.continuation.kind === 'symbol' && result.continuation.code) {
+        out += `\`\`\`\n${result.continuation.code}\n\`\`\`\n`;
+      }
+    }
+    if (result.familyManifest?.rendered) out += `${result.familyManifest.rendered}\n`;
+  }
+  if (results.length === 0) out += '(no matches)\n';
+  const regexDialectNote = renderRegexDialectHint(response?.stats?.regexDialectHint);
+  if (regexDialectNote) out += `${regexDialectNote}\n`;
   return out;
 }
 
-function buildJsonSearchResponse(results, stats, totalTime) {
+function buildJsonSearchResponse(results, stats, totalTime, extra = {}) {
   return JSON.stringify({
     results,
     stats: { ...stats, server_ms: totalTime },
+    ...extra,
   });
 }
 
@@ -525,6 +711,7 @@ export async function startServer() {
   // Track request count for periodic cache clearing in long-running sessions.
   let requestCount = 0;
   const CACHE_CLEAR_INTERVAL = 1000;  // Clear caches every 1000 requests
+  let agentSpanLedger = null;
 
   let tcpServer;
   let unixServer;
@@ -632,7 +819,29 @@ export async function startServer() {
       console.log(`[Server] Cache cleared after ${requestCount} requests`);
     }
 
-    if (req.method === 'GET' && reqUrl.startsWith('/search?')) {
+    if (req.method === 'POST' && reqUrl === '/agent-spans') {
+      if (req.socket.remoteAddress) {
+        const response = readSemanticError(403, '/agent-spans is only available via Unix socket');
+        res.writeHead(response.status, { 'Content-Type': response.contentType });
+        res.end(response.body);
+        return;
+      }
+      let response;
+      try {
+        const payload = await readBoundedJsonBody(req);
+        response = buildAgentSpanDaemonResponse(payload, {
+          isUnixSocket: true,
+          ledger: agentSpanLedger ||= new AgentSpanLedger(),
+        });
+        if (response.status === 200 && (payload.operation === 'read' || payload.operation === 'observe')) {
+          lastActivityMs = Date.now();
+        }
+      } catch (err) {
+        response = readSemanticError(err.status || 400, err.message || 'Invalid request body');
+      }
+      res.writeHead(response.status, { 'Content-Type': response.contentType });
+      res.end(response.body);
+    } else if (req.method === 'GET' && reqUrl.startsWith('/search?')) {
       // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
       lastActivityMs = Date.now();
       if (!serverReady) {
@@ -650,9 +859,36 @@ export async function startServer() {
         return;
       }
       const url = new URL(reqUrl, `http://localhost:${SEARCH_SERVER_PORT}`);
+      const isUnixSocket = !req.socket.remoteAddress;
+      if (isUnixSocket
+          && (AGENT_FORMATS.has(url.searchParams.get('format'))
+            || url.searchParams.get('agent') === 'true')
+          && flagEnabled(url.searchParams.get('exactRereadOmission'))
+          && !agentSpanLedger) {
+        agentSpanLedger = new AgentSpanLedger();
+      }
       const query = url.searchParams.get('q') || '';
       const mode = url.searchParams.get('mode') || 'auto';
       const topK = parseInt(url.searchParams.get('k') || '10', 10);
+      const requestedRoot = url.searchParams.get('projectRoot') || '';
+      if (requestedRoot.length > SEARCH_SERVER_MAX_READ_PATH_LENGTH) {
+        res.writeHead(413, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `Project root too long (max ${SEARCH_SERVER_MAX_READ_PATH_LENGTH} chars)` }));
+        return;
+      }
+      if (requestedRoot) {
+        const serverRoot = canonicalProjectRoot(searcher.projectRoot || process.cwd());
+        const clientRoot = canonicalProjectRoot(requestedRoot);
+        if (serverRoot !== clientRoot) {
+          res.writeHead(409, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: 'Daemon project root mismatch',
+            serverProjectRoot: serverRoot,
+            requestedProjectRoot: clientRoot,
+          }));
+          return;
+        }
+      }
 
       // Additional search options
       const expand = url.searchParams.get('expand') !== 'false';
@@ -680,6 +916,21 @@ export async function startServer() {
       }
       const maxMatches = parseInt(url.searchParams.get('maxMatches') || '0', 10);
       const contextLines = parseInt(url.searchParams.get('contextLines') || '0', 10);
+      const fileFilter = url.searchParams.get('fileFilter') || undefined;
+      if (fileFilter && fileFilter.length > SEARCH_SERVER_MAX_READ_PATH_LENGTH) {
+        res.writeHead(413, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `File filter too long (max ${SEARCH_SERVER_MAX_READ_PATH_LENGTH} chars)` }));
+        return;
+      }
+      let perFileCap; let maxFiles;
+      try {
+        perFileCap = parseBoundedSearchInteger(url.searchParams.get('perFileCap'), 'perFileCap', 1000);
+        maxFiles = parseBoundedSearchInteger(url.searchParams.get('maxFiles'), 'maxFiles', 1000);
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+        return;
+      }
       const fixedString = url.searchParams.get('fixedString') === 'true';
       const symbolType = url.searchParams.get('type') || '';
       const useLiteralFilter = url.searchParams.get('literalFilter') !== 'false';
@@ -688,7 +939,12 @@ export async function startServer() {
 
       // Agent mode: context packaging (ColGrep agent format)
       const rawFormat = url.searchParams.get('format');
-      const agentFormat = AGENT_FORMATS.has(rawFormat) ? rawFormat : undefined;
+      const agentRequested = url.searchParams.get('agent') === 'true';
+      const { agentFormat, renderText: renderAgentText } = resolveAgentSearchRequest(
+        rawFormat,
+        agentRequested,
+      );
+      const isAgentFormat = Boolean(agentFormat);
       const tokenBudget = url.searchParams.has('budget')
         ? parseInt(url.searchParams.get('budget'), 10)
         : undefined;
@@ -703,6 +959,10 @@ export async function startServer() {
         res.end(JSON.stringify({ error: `Query too long (max ${SEARCH_SERVER_MAX_QUERY_LENGTH} chars)` }));
         return;
       }
+      const agentSpanCall = beginAgentSpanUrlCall(url, agentSpanLedger, {
+        enabled: isUnixSocket && Boolean(agentFormat)
+          && url.searchParams.get('trackAgentSpans') !== 'false',
+      });
 
       try {
         const start = Date.now();
@@ -712,6 +972,9 @@ export async function startServer() {
           regex,
           maxMatches,
           contextLines,
+          fileFilter,
+          perFileCap,
+          maxFiles,
           fixedString,
           type: symbolType,
           globs,
@@ -721,6 +984,7 @@ export async function startServer() {
           rerank,
           fusion,
           useLateInteraction,
+          _isAgentFormat: isAgentFormat,
           ...(agentFormat && { format: agentFormat, tokenBudget }),
         });
 
@@ -729,11 +993,37 @@ export async function startServer() {
         // produced these results (defends against multi-repo bench reusing
         // a stale daemon — see eval/agent-read-workflows/run-bench.js).
         if (searchResult.format === 'agent') {
+          if (agentSpanCall) {
+            agentSpanLedger.rememberQueryAtCall(
+              agentSpanCall.sessionId,
+              agentSpanCall.call,
+              query,
+              regex,
+            );
+            const spans = collectAgentShownSpans(searchResult.results, {
+              projectRoot: searcher.projectRoot || process.cwd(),
+            });
+            agentSpanLedger.observeAtCall(agentSpanCall.sessionId, agentSpanCall.call, spans);
+          }
           searchResult.serverProjectRoot = searcher.projectRoot || null;
           searchResult.serverPid = process.pid;
-          res.writeHead(200, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify(searchResult));
+          if (renderAgentText) {
+            res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end(renderAgentSearchResponse(searchResult));
+          } else {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(searchResult));
+          }
         } else {
+          if (agentSpanCall) {
+            agentSpanLedger.rememberQueryAtCall(
+              agentSpanCall.sessionId,
+              agentSpanCall.call,
+              query,
+              regex,
+            );
+            agentSpanLedger.observeAtCall(agentSpanCall.sessionId, agentSpanCall.call, []);
+          }
           let { results, stats } = searchResult;
 
           // Enrich with summaries if summary mode
@@ -749,7 +1039,10 @@ export async function startServer() {
             res.end(out);
           } else {
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(buildJsonSearchResponse(results, stats, totalTime));
+            res.end(buildJsonSearchResponse(results, stats, totalTime, {
+              ...(searchResult.fileSummary ? { fileSummary: searchResult.fileSummary } : {}),
+              ...(searchResult.familyManifest ? { familyManifest: searchResult.familyManifest } : {}),
+            }));
           }
         }
       } catch (err) {
@@ -759,6 +1052,11 @@ export async function startServer() {
     } else if (req.method === 'GET' && reqUrl.startsWith('/read-semantic?')) {
       // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
       lastActivityMs = Date.now();
+      if (!req.socket.remoteAddress
+          && reqUrl.includes('exactRereadOmission=true')
+          && !agentSpanLedger) {
+        agentSpanLedger = new AgentSpanLedger();
+      }
       // read-semantic needs the indexes — wait out the cold-start init race
       // (bounded) so a freshly-spawned daemon doesn't 503 the first request.
       await waitForServerReady();
@@ -767,12 +1065,18 @@ export async function startServer() {
         serverReady,
         initError,
         searcher,
+        agentSpanLedger,
       });
       res.writeHead(response.status, { 'Content-Type': response.contentType });
       res.end(response.body);
     } else if (req.method === 'GET' && reqUrl.startsWith('/trace?')) {
       // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
       lastActivityMs = Date.now();
+      if (!req.socket.remoteAddress
+          && reqUrl.includes('exactRereadOmission=true')
+          && !agentSpanLedger) {
+        agentSpanLedger = new AgentSpanLedger();
+      }
       // trace needs the code-graph — wait out the cold-start init race (bounded)
       // so a freshly-spawned daemon doesn't 503 the first request.
       await waitForServerReady();
@@ -781,17 +1085,24 @@ export async function startServer() {
         serverReady,
         initError,
         searcher,
+        agentSpanLedger,
       });
       res.writeHead(response.status, { 'Content-Type': response.contentType });
       res.end(response.body);
     } else if (req.method === 'GET' && reqUrl.startsWith('/read?')) {
       // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
       lastActivityMs = Date.now();
+      if (!req.socket.remoteAddress
+          && reqUrl.includes('exactRereadOmission=true')
+          && !agentSpanLedger) {
+        agentSpanLedger = new AgentSpanLedger();
+      }
       const response = await buildReadDaemonResponse(reqUrl, {
         isUnixSocket: !req.socket.remoteAddress,
         serverReady,
         initError,
         searcher,
+        agentSpanLedger,
       });
       res.writeHead(response.status, { 'Content-Type': response.contentType });
       res.end(response.body);
@@ -978,6 +1289,9 @@ export async function queryServer(query, options = {}) {
     topK = 10,
     maxMatches = 0,
     contextLines = 0,
+    fileFilter,
+    perFileCap = 0,
+    maxFiles = 0,
     fixedString = false,
     type = '',
     globs = [],
@@ -991,6 +1305,9 @@ export async function queryServer(query, options = {}) {
     mid = false,
     format,
     tokenBudget,
+    projectRoot,
+    trackAgentSpans = true,
+    _isAgentFormat = false,
   } = options;
 
   return new Promise((resolve, reject) => {
@@ -1004,6 +1321,9 @@ export async function queryServer(query, options = {}) {
     if (regex) params.set('regex', regex);
     if (maxMatches > 0) params.set('maxMatches', maxMatches.toString());
     if (contextLines > 0) params.set('contextLines', contextLines.toString());
+    if (fileFilter) params.set('fileFilter', fileFilter);
+    if (perFileCap > 0) params.set('perFileCap', perFileCap.toString());
+    if (maxFiles > 0) params.set('maxFiles', maxFiles.toString());
     if (fixedString) params.set('fixedString', 'true');
     if (type) params.set('type', type);
     if (!literalFilter) params.set('literalFilter', 'false');
@@ -1016,6 +1336,16 @@ export async function queryServer(query, options = {}) {
     if (mid) params.set('mid', 'true');
     if (format && format.startsWith('agent')) params.set('format', format);
     if (tokenBudget) params.set('budget', tokenBudget.toString());
+    if (projectRoot) params.set('projectRoot', projectRoot);
+    if (_isAgentFormat) params.set('agent', 'true');
+    if (!trackAgentSpans) params.set('trackAgentSpans', 'false');
+    if (trackAgentSpans && format?.startsWith('agent') && exactRereadOmissionEnabled()) {
+      const sessionId = resolveAgentSessionId();
+      if (sessionId) {
+        params.set('exactRereadOmission', 'true');
+        params.set('agentSessionId', sessionId);
+      }
+    }
 
     // Per-project Unix socket (C3) — the canonical local transport.
     const req = http.request({
@@ -1038,6 +1368,44 @@ export async function queryServer(query, options = {}) {
   });
 }
 
+/**
+ * Query the warm daemon's read-semantic route as JSON. The caller may retain
+ * its existing renderer while reusing the daemon's resident model/index.
+ *
+ * @param {{ path: string, query: string, projectRoot: string, maxChars?: number }} request
+ * @returns {Promise<object>}
+ */
+export async function queryReadSemanticServer({ path: file, query, projectRoot, maxChars } = {}) {
+  if (!file || !query || !projectRoot) {
+    throw new TypeError('path, query, and projectRoot are required');
+  }
+  const http = await import('http');
+  const params = new URLSearchParams({
+    path: file,
+    q: query,
+    projectRoot,
+    format: 'json',
+  });
+  if (maxChars > 0) params.set('maxChars', String(maxChars));
+
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      socketPath: projectSocketPath(),
+      path: `/read-semantic?${params.toString()}`,
+      method: 'GET',
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch { reject(new Error('Invalid server response')); }
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 /**
  * Fetch /health from the running daemon. Returns the parsed body, or null if
  * the daemon is unreachable / replies non-200.