sweet-search 2.5.13 → 2.6.0

package/core/search/search-server.js

@@ -9,11 +9,19 @@
  */
 
 import fs from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, realpathSync } from 'fs';
+import path from 'node:path';
 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 } from './server-identity.js';
+import { projectSocketPath, projectPidFile, tcpPort, resolveProjectRoot } from './server-identity.js';
+import {
+  upsertSelf as registryUpsertSelf,
+  touchSelf as registryTouchSelf,
+  removeSelf as registryRemoveSelf,
+  pruneAndList as registryPruneAndList,
+  selectEvictionTargets as registrySelectEvictionTargets,
+} from './daemon-registry.js';
 
 // =============================================================================
 // Server constants
@@ -27,6 +35,313 @@ export const SEARCH_SERVER_PORT = 9876;
 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;
+
+function canonicalProjectRoot(root) {
+  const resolved = path.resolve(root || process.cwd());
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function parseFiniteNumber(value, name) {
+  if (value == null || value === '') return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`${name} must be a finite number`);
+  return n;
+}
+
+function parseInteger(value, name) {
+  if (value == null || value === '') return undefined;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isInteger(n)) throw new Error(`${name} must be an integer`);
+  return n;
+}
+
+function reusableLateInteractionIndex(searcher) {
+  const idx = searcher?.lateInteractionIndex || null;
+  if (!idx) return null;
+  if (idx.modelMismatch === true) return null;
+  if (!idx.documents || idx.documents.size === 0) return null;
+  return idx;
+}
+
+function readSemanticError(status, message, extra = {}) {
+  return {
+    status,
+    contentType: 'application/json',
+    body: JSON.stringify({ error: message, ...extra }),
+  };
+}
+
+export async function buildReadSemanticDaemonResponse(reqUrl, {
+  isUnixSocket = false,
+  serverReady = false,
+  initError = null,
+  searcher = null,
+  readSemanticFn = null,
+  formatReadSemanticResultFn = null,
+} = {}) {
+  if (!isUnixSocket) {
+    return readSemanticError(403, '/read-semantic is only available via Unix socket');
+  }
+  if (!serverReady) {
+    const reason = initError?.message
+      ? `Server initialization failed: ${initError.message}`
+      : 'Server is starting, please retry';
+    return readSemanticError(503, reason, { status: initError ? 'failed' : 'starting' });
+  }
+  if (reqUrl.length > SEARCH_SERVER_MAX_URL_LENGTH) {
+    return readSemanticError(414, `Request URL too long (max ${SEARCH_SERVER_MAX_URL_LENGTH} chars)`);
+  }
+
+  let url;
+  try {
+    url = new URL(reqUrl, `http://localhost:${SEARCH_SERVER_PORT}`);
+  } catch {
+    return readSemanticError(400, 'Invalid request URL');
+  }
+
+  const file = url.searchParams.get('path') || url.searchParams.get('file') || '';
+  const query = url.searchParams.get('q') || url.searchParams.get('query') || '';
+  const requestedRoot = url.searchParams.get('projectRoot') || '';
+  const format = url.searchParams.get('format') === 'json' ? 'json' : 'agent';
+
+  if (!file) return readSemanticError(400, 'Missing path parameter ?path=');
+  if (file.length > SEARCH_SERVER_MAX_READ_PATH_LENGTH) {
+    return readSemanticError(413, `Path too long (max ${SEARCH_SERVER_MAX_READ_PATH_LENGTH} chars)`);
+  }
+  if (!query) return readSemanticError(400, 'Missing query parameter ?q=');
+  if (query.length > SEARCH_SERVER_MAX_QUERY_LENGTH) {
+    return readSemanticError(413, `Query too long (max ${SEARCH_SERVER_MAX_QUERY_LENGTH} chars)`);
+  }
+  if (!requestedRoot) return readSemanticError(400, 'Missing projectRoot parameter');
+
+  const serverRoot = canonicalProjectRoot(searcher?.projectRoot || process.cwd());
+  const clientRoot = canonicalProjectRoot(requestedRoot);
+  if (serverRoot !== clientRoot) {
+    return readSemanticError(409, 'Daemon project root mismatch', {
+      serverProjectRoot: serverRoot,
+      requestedProjectRoot: clientRoot,
+    });
+  }
+
+  let topK; let threshold; let contextLines; let maxChars; let maxTokens;
+  try {
+    topK = parseInteger(url.searchParams.get('k') ?? url.searchParams.get('topK'), 'topK');
+    threshold = parseFiniteNumber(url.searchParams.get('threshold'), 'threshold');
+    contextLines = parseInteger(url.searchParams.get('contextLines') ?? url.searchParams.get('context'), 'contextLines');
+    maxChars = parseInteger(url.searchParams.get('maxChars'), 'maxChars');
+    maxTokens = parseInteger(url.searchParams.get('maxTokens'), 'maxTokens');
+  } catch (err) {
+    return readSemanticError(400, err.message);
+  }
+  const verbose = url.searchParams.get('verbose') === 'true';
+
+  try {
+    let readSemantic = readSemanticFn;
+    let formatReadSemanticResult = formatReadSemanticResultFn;
+    if (!readSemantic || !formatReadSemanticResult) {
+      const mod = await import('./search-read-semantic.js');
+      readSemantic = readSemantic || mod.readSemantic;
+      formatReadSemanticResult = formatReadSemanticResult || mod.formatReadSemanticResult;
+    }
+    const result = await readSemantic({
+      path: file,
+      query,
+      projectRoot: serverRoot,
+      topK,
+      threshold,
+      contextLines,
+      maxChars,
+      maxTokens,
+      verbose,
+      _lateInteractionIndex: reusableLateInteractionIndex(searcher),
+    });
+    const body = formatReadSemanticResult(result, format);
+    return {
+      status: result?.ok === false ? 404 : 200,
+      contentType: format === 'json' ? 'application/json' : 'text/plain; charset=utf-8',
+      body: format === 'json' ? body : `${body}\n`,
+    };
+  } catch (err) {
+    return readSemanticError(500, err.message || String(err));
+  }
+}
+
+// Daemon handler for `trace` — structural callers/callees/impact served from the
+// warm daemon so the native client pays no node startup + the code-graph.db is
+// page-cache warm. Byte-identical to the in-process path (search-trace.js
+// handleTraceCli): SAME traceSymbol + formatStructuralContext, with the banner
+// emitted client-side (native binary), exactly like /read-semantic.
+export async function buildTraceDaemonResponse(reqUrl, {
+  isUnixSocket = false,
+  serverReady = false,
+  initError = null,
+  searcher = null,
+} = {}) {
+  if (!isUnixSocket) {
+    return readSemanticError(403, '/trace is only available via Unix socket');
+  }
+  if (!serverReady) {
+    const reason = initError?.message
+      ? `Server initialization failed: ${initError.message}`
+      : 'Server is starting, please retry';
+    return readSemanticError(503, reason, { status: initError ? 'failed' : 'starting' });
+  }
+  if (reqUrl.length > SEARCH_SERVER_MAX_URL_LENGTH) {
+    return readSemanticError(414, `Request URL too long (max ${SEARCH_SERVER_MAX_URL_LENGTH} chars)`);
+  }
+  let url;
+  try {
+    url = new URL(reqUrl, `http://localhost:${SEARCH_SERVER_PORT}`);
+  } catch {
+    return readSemanticError(400, 'Invalid request URL');
+  }
+
+  const symbol = url.searchParams.get('symbol') || url.searchParams.get('q') || '';
+  const requestedRoot = url.searchParams.get('projectRoot') || '';
+  const json = url.searchParams.get('format') === 'json';
+
+  if (!symbol) return readSemanticError(400, 'Missing symbol parameter ?symbol=');
+  if (symbol.length > SEARCH_SERVER_MAX_QUERY_LENGTH) {
+    return readSemanticError(413, `Symbol too long (max ${SEARCH_SERVER_MAX_QUERY_LENGTH} chars)`);
+  }
+  if (!requestedRoot) return readSemanticError(400, 'Missing projectRoot parameter');
+
+  const serverRoot = canonicalProjectRoot(searcher?.projectRoot || process.cwd());
+  const clientRoot = canonicalProjectRoot(requestedRoot);
+  if (serverRoot !== clientRoot) {
+    return readSemanticError(409, 'Daemon project root mismatch', {
+      serverProjectRoot: serverRoot,
+      requestedProjectRoot: clientRoot,
+    });
+  }
+
+  const filePath = url.searchParams.get('file') || undefined;
+  const queryHint = url.searchParams.get('hint') || '';
+  let maxDepth; let tokenBudget;
+  try {
+    maxDepth = parseInteger(url.searchParams.get('depth'), 'depth');
+    tokenBudget = parseInteger(url.searchParams.get('budget'), 'budget');
+  } catch (err) {
+    return readSemanticError(400, err.message);
+  }
+
+  try {
+    const { traceSymbol, formatStructuralContext } = await import('./search-trace.js');
+    // Mirror search-trace.js parseArgs defaults exactly (maxDepth 3, adaptive
+    // budget when null) so the result is identical to the in-process call.
+    const result = traceSymbol(symbol, {
+      projectRoot: serverRoot,
+      filePath,
+      queryHint,
+      maxDepth: maxDepth ?? 3,
+      tokenBudget: tokenBudget ?? null,
+    });
+    // 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);
+    return {
+      status: 200,
+      contentType: json ? 'application/json' : 'text/plain; charset=utf-8',
+      body: `${body}\n`,
+    };
+  } catch (err) {
+    return readSemanticError(500, err.message || String(err));
+  }
+}
+
+// Daemon handler for `read` — filesystem-grounded multi-file reader served from
+// the warm daemon (no per-call node startup). Byte-identical to the in-process
+// path (search-read.js handleReadCli): SAME readFiles + formatReadResults.
+// readFiles statSync's every call (stat-keyed cache absPath|size|mtimeMs), so
+// read-your-writes freshness is preserved across the daemon boundary.
+export async function buildReadDaemonResponse(reqUrl, {
+  isUnixSocket = false,
+  serverReady = false,
+  initError = null,
+  searcher = null,
+} = {}) {
+  if (!isUnixSocket) {
+    return readSemanticError(403, '/read is only available via Unix socket');
+  }
+  // NOTE: /read deliberately does NOT gate on serverReady. `read` returns exact
+  // file bytes from node:fs (search-read.js) and never touches the searcher /
+  // indexes — the only index reference is `searcher?.projectRoot` in the root
+  // check below, already null-tolerant. Gating it on init readiness made `read`
+  // fail (503 → native client exit) during the cold-start window for no reason
+  // (Codex finding). read-semantic/trace DO need indexes and keep their gate
+  // (with a bounded readiness-wait added at the dispatch site).
+  if (reqUrl.length > SEARCH_SERVER_MAX_URL_LENGTH) {
+    return readSemanticError(414, `Request URL too long (max ${SEARCH_SERVER_MAX_URL_LENGTH} chars)`);
+  }
+  let url;
+  try {
+    url = new URL(reqUrl, `http://localhost:${SEARCH_SERVER_PORT}`);
+  } catch {
+    return readSemanticError(400, 'Invalid request URL');
+  }
+
+  const paths = url.searchParams.getAll('path');
+  const requestedRoot = url.searchParams.get('projectRoot') || '';
+  const fmtParam = url.searchParams.get('format') || 'agent';
+  const format = (fmtParam === 'json' || fmtParam === 'raw') ? fmtParam : 'agent';
+
+  if (paths.length === 0) return readSemanticError(400, 'Missing path parameter ?path=');
+  if (paths.length > 20) return readSemanticError(413, 'read accepts at most 20 files');
+  for (const p of paths) {
+    if (p.length > SEARCH_SERVER_MAX_READ_PATH_LENGTH) {
+      return readSemanticError(413, `Path too long (max ${SEARCH_SERVER_MAX_READ_PATH_LENGTH} chars)`);
+    }
+  }
+  if (!requestedRoot) return readSemanticError(400, 'Missing projectRoot parameter');
+
+  const serverRoot = canonicalProjectRoot(searcher?.projectRoot || process.cwd());
+  const clientRoot = canonicalProjectRoot(requestedRoot);
+  if (serverRoot !== clientRoot) {
+    return readSemanticError(409, 'Daemon project root mismatch', {
+      serverProjectRoot: serverRoot,
+      requestedProjectRoot: clientRoot,
+    });
+  }
+
+  let startLine; let endLine;
+  try {
+    startLine = parseInteger(url.searchParams.get('startLine'), 'startLine');
+    endLine = parseInteger(url.searchParams.get('endLine'), 'endLine');
+  } catch (err) {
+    return readSemanticError(400, err.message);
+  }
+  const includeMetadata = url.searchParams.get('metadata') !== 'false';
+  const wantsRange = startLine != null || endLine != null;
+  if (wantsRange && paths.length > 1) {
+    return readSemanticError(400, '--lines requires exactly one path');
+  }
+  const files = paths.map(p => ({
+    path: p,
+    startLine: wantsRange ? startLine : undefined,
+    endLine: wantsRange ? endLine : undefined,
+  }));
+
+  try {
+    const { readFiles, formatReadResults } = await import('./search-read.js');
+    const out = await readFiles(files, { projectRoot: serverRoot, includeMetadata });
+    const body = formatReadResults(out, format);
+    // 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);
+    return {
+      status: allFailed ? 404 : 200,
+      contentType: format === 'json' ? 'application/json' : 'text/plain; charset=utf-8',
+      body: format === 'json' ? body : `${body}\n`,
+    };
+  } catch (err) {
+    return readSemanticError(500, err.message || String(err));
+  }
+}
 
 function buildTextSearchResponse(results, stats, totalTime, { summary = false, mid = false, color = true, decorate = true } = {}) {
   const routeMode = stats?.routing?.mode || 'auto';
@@ -189,6 +504,22 @@ export async function startServer() {
   let initError = null;
   let initTimeMs = null;
 
+  // Bounded readiness wait for the INDEX-DEPENDENT endpoints (read-semantic /
+  // trace). The Unix socket is bound before searcher.init() finishes (below),
+  // and the native client treats "connectable" as "ready" and fires its request
+  // immediately — so a cold-start request used to hit a 503 and the client
+  // exited (Codex finding). Waiting here (up to ~10s, or until a terminal
+  // initError) turns that race into a short latency hit instead of a hard
+  // failure. /read does NOT use this (it needs no indexes); /health is instant.
+  const READINESS_WAIT_MS = 10_000;
+  const waitForServerReady = async (budgetMs = READINESS_WAIT_MS) => {
+    if (serverReady || initError) return;
+    const deadline = Date.now() + budgetMs;
+    while (!serverReady && !initError && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  };
+
   // Track request count for periodic cache clearing in long-running sessions.
   let requestCount = 0;
   const CACHE_CLEAR_INTERVAL = 1000;  // Clear caches every 1000 requests
@@ -196,13 +527,91 @@ export async function startServer() {
   let tcpServer;
   let unixServer;
 
+  // ---------------------------------------------------------------------------
+  // Daemon lifecycle (footprint bound). A warm per-repo daemon holds ~1–2 GB
+  // (HNSW + vocab + float sidecar) and historically NEVER self-terminated, so
+  // resident daemons accumulated unbounded across repos/sessions. Two bounds:
+  //   (1) idle-TTL eviction (default ON): self-stop after no QUERY traffic for
+  //       SWEET_SEARCH_DAEMON_IDLE_TTL_MS. Tracked by WALL CLOCK, not
+  //       requestCount, because an idle daemon never increments requestCount.
+  //   (2) resident-daemon LRU cap (default OFF; SWEET_SEARCH_MAX_DAEMONS): a
+  //       hard ceiling on concurrently-resident daemons via a shared registry.
+  // NOTE: lastActivityMs is set ONLY by real query routes (/search,
+  // /read-semantic) — never by /health or /stop, so liveness probes (prewarm,
+  // isServerRunning) can never keep an idle daemon alive.
+  // ---------------------------------------------------------------------------
+  let lastActivityMs = Date.now();
+  let idleTimer = null;
+  let registryTimer = null;
+  let shuttingDown = false;
+
+  // Close a server, letting in-flight requests finish but never letting an idle
+  // keep-alive socket block exit (bounded grace, then resolve regardless).
+  const closeServerGracefully = (srv, graceMs = 3000) => new Promise((resolve) => {
+    if (!srv) { resolve(); return; }
+    let settled = false;
+    const done = () => { if (!settled) { settled = true; resolve(); } };
+    try {
+      srv.close(done);
+      // Drop idle keep-alive connections immediately; active requests still drain.
+      srv.closeIdleConnections?.();
+    } catch { done(); return; }
+    const t = setTimeout(done, graceMs);
+    if (t.unref) t.unref();
+  });
+
+  // Single idempotent teardown shared by SIGINT, /stop, and the idle timer.
+  const gracefulShutdown = async (reason) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (idleTimer) { clearInterval(idleTimer); idleTimer = null; }
+    if (registryTimer) { clearInterval(registryTimer); registryTimer = null; }
+    if (capEnabled) {
+      try { await registryRemoveSelf(process.pid); } catch (err) {
+        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] registry remove: ${err?.message || err}\n`);
+      }
+    }
+    await closeServerGracefully(tcpServer);
+    await closeServerGracefully(unixServer);
+    try { searcher.close(); } catch (err) {
+      if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] searcher close: ${err?.message || err}\n`);
+    }
+    try { await fs.unlink(pidFile); } catch (err) {
+      if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
+    }
+    try { await fs.unlink(socketPath); } catch (err) {
+      if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
+    }
+    console.log(`[Server] Shutdown (${reason}).`);
+    process.exit(0);
+  };
+
+  // Resident-daemon cap (default OFF). Read once at startup to gate registry
+  // participation; the numeric cap is re-read per enforcement tick.
+  const capEnabled = Number(process.env.SWEET_SEARCH_MAX_DAEMONS ?? 0) > 0;
+
+  // Enforce the LRU cap: prune dead registry entries, then /stop the
+  // least-recently-active peers that are NOT self until we're within the cap.
+  const enforceDaemonCap = async () => {
+    const cap = Number(process.env.SWEET_SEARCH_MAX_DAEMONS ?? 0);
+    if (!(cap > 0)) return;
+    let live;
+    try { live = await registryPruneAndList(); } catch { return; }
+    if (!Array.isArray(live) || live.length <= cap) return;
+    const targets = registrySelectEvictionTargets(live, process.pid, live.length - cap);
+    for (const t of targets) {
+      try { await sendStopToSocket(t.socketPath); } catch (err) {
+        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] cap evict ${t?.socketPath}: ${err?.message || err}\n`);
+      }
+    }
+  };
+
   // Shared request handler for both TCP and Unix socket
   const handleRequest = async (req, res) => {
     const reqUrl = req.url || '';
 
     const componentState = {
       graphIndex: Boolean(searcher.hasGraphIndex),
-      hnswIndex: Boolean(searcher.hasHnswIndex),
       binaryHnswIndex: Boolean(searcher.hasBinaryHnswIndex),
       lateInteractionIndex: Boolean(searcher.hasLateInteractionIndex && searcher.useLateInteraction),
       embeddingService: serverReady,
@@ -222,6 +631,8 @@ export async function startServer() {
     }
 
     if (req.method === 'GET' && reqUrl.startsWith('/search?')) {
+      // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
+      lastActivityMs = Date.now();
       if (!serverReady) {
         const reason = initError?.message
           ? `Server initialization failed: ${initError.message}`
@@ -344,6 +755,45 @@ export async function startServer() {
         res.writeHead(500, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: err.message }));
       }
+    } else if (req.method === 'GET' && reqUrl.startsWith('/read-semantic?')) {
+      // Real query traffic — reset the idle-TTL clock (NOT /health or /stop).
+      lastActivityMs = Date.now();
+      // 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();
+      const response = await buildReadSemanticDaemonResponse(reqUrl, {
+        isUnixSocket: !req.socket.remoteAddress,
+        serverReady,
+        initError,
+        searcher,
+      });
+      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();
+      // 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();
+      const response = await buildTraceDaemonResponse(reqUrl, {
+        isUnixSocket: !req.socket.remoteAddress,
+        serverReady,
+        initError,
+        searcher,
+      });
+      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();
+      const response = await buildReadDaemonResponse(reqUrl, {
+        isUnixSocket: !req.socket.remoteAddress,
+        serverReady,
+        initError,
+        searcher,
+      });
+      res.writeHead(response.status, { 'Content-Type': response.contentType });
+      res.end(response.body);
     } else if (req.method === 'GET' && reqUrl === '/health') {
       const status = initError ? 'failed' : (serverReady ? 'ready' : 'starting');
       // Repo identity — harness uses these to verify the daemon serves the
@@ -379,15 +829,7 @@ export async function startServer() {
       }
       res.writeHead(200, { 'Content-Type': 'text/plain' });
       res.end('Shutting down...\n');
-      if (tcpServer) tcpServer.close();
-      if (unixServer) unixServer.close();
-      try { await fs.unlink(pidFile); } catch (err) {
-        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
-      }
-      try { await fs.unlink(socketPath); } catch (err) {
-        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
-      }
-      process.exit(0);
+      await gracefulShutdown('stop');
     } else {
       res.writeHead(404, { 'Content-Type': 'text/plain' });
       res.end('Not found. Use GET /search?q=<query>&mode=auto&k=10\n');
@@ -474,23 +916,53 @@ export async function startServer() {
     if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] maintainer launch: ${err?.message || err}\n`);
   }
 
-  // Alias for graceful shutdown
-  const server = tcpServer;
+  // Handle graceful shutdown (shared idempotent teardown).
+  process.on('SIGINT', () => { gracefulShutdown('sigint'); });
 
-  // Handle graceful shutdown
-  process.on('SIGINT', async () => {
-    console.log('\n[Server] Shutting down...');
-    if (tcpServer) tcpServer.close();
-    unixServer.close();
-    searcher.close();
-    try { await fs.unlink(pidFile); } catch (err) {
-      if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
-    }
-    try { await fs.unlink(socketPath); } catch (err) {
-      if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
+  // (1) Idle-TTL eviction — default ON. Unref'd so it never keeps the event
+  // loop alive on its own. The TTL is read every tick so tests/operators can
+  // tune it live; 0 disables. Self-stops once no QUERY route has been hit for
+  // longer than the TTL — the actively-used repo's daemon keeps resetting
+  // lastActivityMs and is therefore never idle-evicted while it is being
+  // queried. (The separate LRU cap below is the only path that can stop an
+  // active peer, and only via a newly-started peer within one registry-refresh
+  // interval; see daemon-registry.js selectEvictionTargets.)
+  idleTimer = setInterval(() => {
+    const ttl = Number(process.env.SWEET_SEARCH_DAEMON_IDLE_TTL_MS ?? 1_200_000);
+    if (ttl > 0 && Date.now() - lastActivityMs > ttl) {
+      gracefulShutdown('idle-ttl');
     }
-    process.exit(0);
-  });
+  }, Number(process.env.SWEET_SEARCH_DAEMON_IDLE_CHECK_MS ?? 60_000));
+  if (idleTimer.unref) idleTimer.unref();
+
+  // (2) Resident-daemon LRU cap — default OFF. Only when SWEET_SEARCH_MAX_DAEMONS
+  // is opted into do we touch the shared registry at all: register self, then
+  // refresh our real query activity + prune dead peers + enforce the cap on a
+  // coarse unref'd timer. The maintainer is never enumerated (it never registers).
+  if (capEnabled) {
+    const entry = {
+      pid: process.pid,
+      projectRoot: resolveProjectRoot(),
+      socketPath,
+      pidFile,
+      startedAt: Date.now(),
+      lastActivityMs,
+    };
+    registryUpsertSelf(entry)
+      .then(() => enforceDaemonCap())
+      .catch((err) => {
+        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] registry init: ${err?.message || err}\n`);
+      });
+
+    registryTimer = setInterval(() => {
+      registryTouchSelf(process.pid, lastActivityMs)
+        .then(() => enforceDaemonCap())
+        .catch((err) => {
+          if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] registry tick: ${err?.message || err}\n`);
+        });
+    }, Number(process.env.SWEET_SEARCH_DAEMON_REGISTRY_REFRESH_MS ?? 45_000));
+    if (registryTimer.unref) registryTimer.unref();
+  }
 }
 
 // =============================================================================
@@ -626,6 +1098,34 @@ export async function stopServer({ timeoutMs = 5000 } = {}) {
   }
 }
 
+/**
+ * Send /stop to a daemon on an EXPLICIT socket (variant of stopServer, which
+ * always targets this process's own socket). Used by the resident-daemon LRU
+ * cap to evict a least-recently-active PEER. Returns true if the request
+ * reached the daemon (200, or the connection dropped as it exited).
+ */
+export async function sendStopToSocket(socketPath, { timeoutMs = 5000 } = {}) {
+  if (!socketPath) return false;
+  try {
+    const http = await import('http');
+    return await new Promise((resolve) => {
+      const req = http.request({ socketPath, path: '/stop', method: 'GET' }, (res) => {
+        res.on('data', () => {});
+        res.on('end', () => resolve(true));
+      });
+      req.on('error', (err) => {
+        const msg = (err && err.code) || '';
+        if (msg === 'ECONNRESET' || msg === 'EPIPE' || msg === 'ENOENT') resolve(true);
+        else resolve(false);
+      });
+      req.setTimeout(timeoutMs, () => { req.destroy(); resolve(false); });
+      req.end();
+    });
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Best-effort wait for the daemon to exit. Returns true once /health stops
  * answering at all (within timeoutMs); false otherwise. This intentionally