tgrep-mcp 0.3.0

package/server.mjs

@@ -0,0 +1,2274 @@
+#!/usr/bin/env node
+/**
+ * tgrep-mcp - a stdio MCP server that exposes the tgrep search tool as MCP tools.
+ *
+ * tgrep answers regex queries from a prebuilt trigram index instead of scanning every file. This
+ * server keeps a search backend resident so that repeated queries do not pay process startup on
+ * every call.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 over stdin and stdout. stdout carries protocol frames
+ * only. Diagnostics and audit records go to stderr.
+ *
+ * Backends, tried in this order:
+ *
+ *   1. direct - a TCP JSON-RPC connection to a resident `tgrep serve` process. The port is
+ *      advertised in <index-dir>/serve.json. This is the fast path.
+ *   2. cli - `tgrep <flags> -- <pattern> <target> --json` in a child process. Slower, because each
+ *      call creates a process and reads the index again. This is the fallback.
+ *
+ * The direct protocol is not a documented tgrep interface. It is verified against the tgrep release
+ * named in VERIFIED_TGREP_VERSION, and any connection or protocol error falls back to the CLI
+ * backend. Set TGREP_DIRECT=off to use the CLI backend only.
+ *
+ * Configuration comes from the environment, from the workspace roots the client declares, and from
+ * the working directory. The server has no machine-specific defaults.
+ *
+ * Environment (all optional):
+ *   TGREP_BIN                   tgrep executable. Default: <package dir>/bin/tgrep[.exe] when that
+ *                               file exists, otherwise `tgrep` resolved from PATH. An npm install
+ *                               does not ship the vendored binary, so set this or install tgrep.
+ *   TGREP_INDEX_ROOT            Directory for per-root indexes. Default: the platform cache
+ *                               directory, for example %LOCALAPPDATA%\tgrep-mcp\index on Windows.
+ *   TGREP_DEFAULT_ROOT          Root searched when a call omits `path`. Default: the client's
+ *                               declared workspace root, otherwise the working directory.
+ *   TGREP_ALLOWED_ROOTS         Separator-separated list of roots that may be searched. `*` allows
+ *                               any path. Default: the default root plus client workspace roots.
+ *   TGREP_TIMEOUT_MS            Per-operation timeout in milliseconds. Default: 60000. Index builds
+ *                               use four times this value.
+ *   TGREP_TOOL_TIMEOUT_MS       Deadline for one tool call. Default: 4x TGREP_TIMEOUT_MS + 30s.
+ *   TGREP_DIRECT                auto (default) or off.
+ *   TGREP_DAEMON_WAIT_MS        Time to wait for a newly started `tgrep serve` to become ready.
+ *                               Default: 15000.
+ *   TGREP_MAX_CONCURRENCY       Tool calls that may run at once, across roots. Default: 4.
+ *   TGREP_MAX_CALLS_PER_MINUTE  Call budget. 0 disables it. Default: 600.
+ *   TGREP_MAX_RESULTS           Upper bound for the maxResults argument. Default: 5000.
+ *   TGREP_MAX_PER_FILE          Upper bound for the maxPerFile argument. Default: 10000.
+ *   TGREP_MAX_LINE_CHARS        Per-match text cap. Default: 512.
+ *   TGREP_MAX_OUTPUT_BYTES      Per-call budget for match text. Default: 262144.
+ *   TGREP_INDEX_STALE_MS        Index age that raises a staleness warning. Default: 24 hours.
+ *   TGREP_LOG_LEVEL             quiet, normal (default), or debug.
+ */
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { createConnection } from 'node:net'
+import { homedir } from 'node:os'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SERVER_NAME = 'tgrep'
+
+/**
+ * Server version, read from the package manifest so that serverInfo matches the published version.
+ * Falls back to a literal when the file is absent, which is the case for a single-file copy.
+ */
+function resolveVersion() {
+  try {
+    const manifest = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'))
+    if (typeof manifest?.version === 'string' && manifest.version.length > 0) return manifest.version
+  } catch {
+    // no manifest available
+  }
+  return '0.3.0'
+}
+
+const VERSION = resolveVersion()
+
+const SUPPORTED_PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07']
+const FALLBACK_PROTOCOL = '2025-06-18'
+
+const MAX_RESULTS_DEFAULT = 200
+const RENDER_LINES = 60
+const CLI_OUTPUT_CAP_BYTES = 16 * 1024 * 1024
+const CLI_STDERR_CAP_BYTES = 256 * 1024
+const MAX_FRAME_BYTES = 8 * 1024 * 1024
+
+// ---------------------------------------------------------------------------
+// Logging — stderr is the only safe channel, stdout is the protocol stream
+// ---------------------------------------------------------------------------
+
+const LOG_LEVELS = { quiet: 0, normal: 1, debug: 2 }
+let logLevel = LOG_LEVELS.normal
+
+function log(message, level = 'normal') {
+  if (LOG_LEVELS[level] > logLevel) return
+  try {
+    process.stderr.write(`[tgrep-mcp] ${message}\n`)
+  } catch {
+    // stderr gone: nothing useful left to do about it
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Configuration — everything machine-specific enters here, from the environment
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve an integer env var, clamped to [min, max]. An unparseable value falls back with a
+ * recorded issue instead of killing the server: a typo in a client config should degrade the tool,
+ * not make it disappear from the client's tool list.
+ */
+function envInt(env, name, fallback, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const raw = env[name]
+  if (raw === undefined || String(raw).trim() === '') return { value: fallback, issue: null }
+  const parsed = Number(String(raw).trim())
+  if (!Number.isFinite(parsed)) return { value: fallback, issue: `${name}="${raw}" is not a number; using ${fallback}` }
+  const clamped = Math.min(max, Math.max(min, Math.floor(parsed)))
+  return { value: clamped, issue: clamped === parsed ? null : `${name}=${raw} clamped to ${clamped}` }
+}
+
+function envString(env, name) {
+  const raw = env[name]
+  if (raw === undefined) return null
+  const text = String(raw).trim()
+  return text.length === 0 ? null : text
+}
+
+/** Per-user index location for this platform. Deliberately outside any repository. */
+function defaultIndexRoot(env, platform, home) {
+  if (platform === 'win32') {
+    const base = env.LOCALAPPDATA || env.APPDATA || join(home, 'AppData', 'Local')
+    return join(base, 'tgrep-mcp', 'index')
+  }
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'tgrep-mcp', 'index')
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'tgrep-mcp', 'index')
+}
+
+/**
+ * Where the tgrep executable comes from, in priority order: an explicit TGREP_BIN, the binary
+ * vendored next to this file, then PATH. `source` is reported by tgrep_status so an operator can
+ * see which one won without reading this source.
+ */
+function resolveBin(env, platform, here, exists = existsSync) {
+  const explicit = envString(env, 'TGREP_BIN')
+  if (explicit !== null) {
+    const candidate = resolve(explicit)
+    return { path: candidate, source: 'TGREP_BIN', absolute: true, present: exists(candidate) }
+  }
+  const vendored = join(here, 'bin', platform === 'win32' ? 'tgrep.exe' : 'tgrep')
+  if (exists(vendored)) return { path: vendored, source: 'vendored', absolute: true, present: true }
+  return { path: platform === 'win32' ? 'tgrep.exe' : 'tgrep', source: 'PATH', absolute: false, present: null }
+}
+
+/** Case-insensitive de-duplication on Windows, where two spellings can name one directory. */
+function dedupePaths(paths, platform = process.platform) {
+  const seen = new Set()
+  const out = []
+  for (const path of paths) {
+    const abs = resolve(path)
+    const key = platform === 'win32' ? abs.toLowerCase() : abs
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(abs)
+  }
+  return out
+}
+
+/**
+ * Parse the allow-list. `*` disables the check. Unset means "the default root and whatever
+ * workspace roots the client declares" — never "any path". Windows drive letters collide with the
+ * POSIX separator, so the split character is platform-dependent.
+ */
+function parseAllowedRoots(raw, defaultRoot, platform = process.platform, cwd = process.cwd()) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return { allowAll: false, roots: dedupePaths([resolve(cwd, defaultRoot)], platform), explicit: false }
+  }
+  const text = String(raw).trim()
+  if (text === '*') return { allowAll: true, roots: [], explicit: true }
+  const parts = text
+    .split(platform === 'win32' ? /[;,]/ : /[:,]/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+    .map((part) => resolve(cwd, part))
+  return { allowAll: false, roots: dedupePaths(parts, platform), explicit: true }
+}
+
+/**
+ * Build the effective configuration. Pure: it reads the environment and the filesystem, never
+ * writes, so it can be unit-tested for any platform without side effects.
+ */
+function buildConfig(env = process.env, platform = process.platform, here = HERE, home = homedir(), cwd = process.cwd()) {
+  const issues = []
+  const take = (result) => {
+    if (result.issue !== null) issues.push(result.issue)
+    return result.value
+  }
+
+  const timeoutMs = take(envInt(env, 'TGREP_TIMEOUT_MS', 60000, { min: 1000, max: 3_600_000 }))
+  const defaultTimeoutMs = timeoutMs * 4 + 30_000
+  const rawDefaultRoot = envString(env, 'TGREP_DEFAULT_ROOT')
+  const defaultRoot = resolve(cwd, rawDefaultRoot ?? cwd)
+  const rawIndexRoot = envString(env, 'TGREP_INDEX_ROOT')
+  const indexRoot = resolve(cwd, rawIndexRoot ?? defaultIndexRoot(env, platform, home))
+  const allowed = parseAllowedRoots(env.TGREP_ALLOWED_ROOTS, defaultRoot, platform, cwd)
+  if (!allowed.allowAll && allowed.roots.length === 0) {
+    issues.push('TGREP_ALLOWED_ROOTS matched no usable path; falling back to the default root')
+    allowed.roots = dedupePaths([defaultRoot], platform)
+  }
+
+  const direct = (envString(env, 'TGREP_DIRECT') ?? 'auto').toLowerCase()
+  if (direct !== 'auto' && direct !== 'off') issues.push(`TGREP_DIRECT="${direct}" is not auto|off; using auto`)
+
+  const rawLogLevel = (envString(env, 'TGREP_LOG_LEVEL') ?? 'normal').toLowerCase()
+  if (!(rawLogLevel in LOG_LEVELS)) issues.push(`TGREP_LOG_LEVEL="${rawLogLevel}" is not quiet|normal|debug; using normal`)
+
+  return {
+    platform,
+    cwd,
+    bin: resolveBin(env, platform, here),
+    indexRoot,
+    defaultRoot,
+    defaultRootSource: rawDefaultRoot === null ? 'cwd' : 'TGREP_DEFAULT_ROOT',
+    indexRootSource: rawIndexRoot === null ? 'platform-cache' : 'TGREP_INDEX_ROOT',
+    allowed,
+    timeoutMs,
+    toolTimeoutMs: take(envInt(env, 'TGREP_TOOL_TIMEOUT_MS', defaultTimeoutMs, { min: 5000, max: 3_600_000 })),
+    daemonWaitMs: take(envInt(env, 'TGREP_DAEMON_WAIT_MS', 15000, { min: 1000, max: 300_000 })),
+    direct: direct === 'off' ? 'off' : 'auto',
+    maxConcurrency: take(envInt(env, 'TGREP_MAX_CONCURRENCY', 4, { min: 1, max: 64 })),
+    maxCallsPerMinute: take(envInt(env, 'TGREP_MAX_CALLS_PER_MINUTE', 600, { min: 0, max: 1_000_000 })),
+    maxResultsDefault: MAX_RESULTS_DEFAULT,
+    maxResultsCeiling: take(envInt(env, 'TGREP_MAX_RESULTS', 5000, { min: 1, max: 1_000_000 })),
+    maxPerFileCeiling: take(envInt(env, 'TGREP_MAX_PER_FILE', 10000, { min: 1, max: 1_000_000 })),
+    maxLineChars: take(envInt(env, 'TGREP_MAX_LINE_CHARS', 512, { min: 32, max: 100_000 })),
+    maxOutputBytes: take(envInt(env, 'TGREP_MAX_OUTPUT_BYTES', 256 * 1024, { min: 4096, max: 64 * 1024 * 1024 })),
+    indexStaleMs: take(envInt(env, 'TGREP_INDEX_STALE_MS', 24 * 60 * 60 * 1000, { min: 60_000, max: 365 * 24 * 60 * 60 * 1000 })),
+    logLevel: LOG_LEVELS[rawLogLevel] ?? LOG_LEVELS.normal,
+    issues,
+  }
+}
+
+const CONFIG = buildConfig()
+logLevel = CONFIG.logLevel
+
+/**
+ * The tgrep release whose serve protocol this server was verified against. The direct backend is
+ * undocumented internal API, so a different release is reported by tgrep_status as degraded rather
+ * than trusted silently.
+ */
+const VERIFIED_TGREP_VERSION = '1.0.8'
+
+// Negotiated during initialize; also reported by tgrep_status.
+let MCP_PROTOCOL_VERSION = FALLBACK_PROTOCOL
+let clientInfo = null
+
+// ---------------------------------------------------------------------------
+// Errors — one code vocabulary shared by text and structuredContent
+// ---------------------------------------------------------------------------
+
+const ERROR_CODES = Object.freeze({
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  PATH_NOT_ALLOWED: 'PATH_NOT_ALLOWED',
+  NOT_FOUND: 'NOT_FOUND',
+  BINARY_MISSING: 'BINARY_MISSING',
+  INDEX_FAILED: 'INDEX_FAILED',
+  BACKEND_UNAVAILABLE: 'BACKEND_UNAVAILABLE',
+  TIMEOUT: 'TIMEOUT',
+  CANCELLED: 'CANCELLED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+})
+
+/** A tool execution failure the caller can act on: stable code, optional hint and retry delay. */
+class ToolError extends Error {
+  constructor(code, message, { hint, details, retryAfterSeconds } = {}) {
+    super(message)
+    this.name = 'ToolError'
+    this.code = code
+    this.hint = hint
+    this.details = details
+    this.retryAfterSeconds = retryAfterSeconds
+  }
+
+  toStructured() {
+    const error = { code: this.code, message: this.message }
+    if (this.hint !== undefined) error.hint = this.hint
+    if (this.details !== undefined && Object.keys(this.details).length > 0) error.details = this.details
+    if (this.retryAfterSeconds !== undefined) error.retryAfterSeconds = this.retryAfterSeconds
+    return error
+  }
+}
+
+/** A JSON-RPC level failure. Per the spec these cover unknown methods/tools and invalid arguments. */
+class ProtocolError extends Error {
+  constructor(code, message, data) {
+    super(message)
+    this.name = 'ProtocolError'
+    this.code = code
+    this.data = data
+  }
+}
+
+function asToolError(error) {
+  if (error instanceof ToolError) return error
+  return new ToolError(ERROR_CODES.INTERNAL_ERROR, String(error?.message ?? error))
+}
+
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+
+const ARG_SPECS = Object.freeze({
+  tgrep_search: {
+    pattern: { type: 'string', required: true, maxLength: 2048 },
+    path: { type: 'string', maxLength: 4096 },
+    glob: { type: 'string', maxLength: 512 },
+    ignoreCase: { type: 'boolean' },
+    maxPerFile: { type: 'integer', min: 1, ceiling: 'maxPerFileCeiling' },
+    maxResults: { type: 'integer', min: 1, ceiling: 'maxResultsCeiling' },
+    includeGitIgnored: { type: 'boolean' },
+  },
+  tgrep_index: {
+    path: { type: 'string', maxLength: 4096 },
+  },
+  tgrep_status: {
+    path: { type: 'string', maxLength: 4096 },
+  },
+})
+
+/**
+ * Validate a tools/call argument bag. Returns issues rather than throwing, so the caller decides
+ * whether a problem is a protocol error (bad arguments) or a tool error (bad world).
+ */
+function validateArguments(toolName, raw, ceilings = {}) {
+  const spec = ARG_SPECS[toolName]
+  if (spec === undefined) {
+    return { ok: false, issues: [{ code: 'unknown_tool', message: `unknown tool: ${toolName}` }] }
+  }
+  const bag = raw === undefined || raw === null ? {} : raw
+  if (typeof bag !== 'object' || Array.isArray(bag)) {
+    return { ok: false, issues: [{ code: 'invalid_arguments', message: 'arguments must be an object' }] }
+  }
+
+  const issues = []
+  const value = {}
+  for (const key of Object.keys(bag)) {
+    if (!Object.hasOwn(spec, key)) {
+      issues.push({ code: 'unknown_argument', argument: key, message: `unknown argument "${key}"` })
+      continue
+    }
+    const rule = spec[key]
+    const given = bag[key]
+    if (given === undefined || given === null) continue
+
+    if (rule.type === 'string') {
+      if (typeof given !== 'string') {
+        issues.push({ code: 'invalid_type', argument: key, message: `"${key}" must be a string` })
+        continue
+      }
+      if (given.includes('\u0000')) {
+        issues.push({ code: 'invalid_value', argument: key, message: `"${key}" must not contain NUL` })
+        continue
+      }
+      if (rule.maxLength !== undefined && given.length > rule.maxLength) {
+        issues.push({ code: 'invalid_value', argument: key, message: `"${key}" exceeds ${rule.maxLength} characters` })
+        continue
+      }
+      value[key] = given
+      continue
+    }
+
+    if (rule.type === 'boolean') {
+      if (typeof given !== 'boolean') {
+        issues.push({ code: 'invalid_type', argument: key, message: `"${key}" must be a boolean` })
+        continue
+      }
+      value[key] = given
+      continue
+    }
+
+    if (rule.type === 'integer') {
+      if (typeof given !== 'number' || !Number.isInteger(given)) {
+        issues.push({ code: 'invalid_type', argument: key, message: `"${key}" must be an integer` })
+        continue
+      }
+      const ceiling = rule.ceiling === undefined ? Infinity : (ceilings[rule.ceiling] ?? Infinity)
+      if (given < (rule.min ?? -Infinity) || given > ceiling) {
+        issues.push({
+          code: 'invalid_value',
+          argument: key,
+          message: `"${key}" must be between ${rule.min ?? '-inf'} and ${ceiling}`,
+        })
+        continue
+      }
+      value[key] = given
+      continue
+    }
+  }
+
+  for (const [key, rule] of Object.entries(spec)) {
+    if (rule.required === true && value[key] === undefined) {
+      issues.push({ code: 'missing_argument', argument: key, message: `"${key}" is required` })
+    }
+  }
+  if (issues.length === 0 && value.pattern !== undefined && value.pattern.length === 0) {
+    issues.push({ code: 'invalid_value', argument: 'pattern', message: '"pattern" must not be empty' })
+  }
+
+  return issues.length > 0 ? { ok: false, issues } : { ok: true, value }
+}
+
+// ---------------------------------------------------------------------------
+// Paths — containment, identity, and display
+// ---------------------------------------------------------------------------
+
+function normalizeForCompare(path, platform = process.platform) {
+  const abs = resolve(path)
+  return platform === 'win32' ? abs.toLowerCase() : abs
+}
+
+/**
+ * True when `child` is `parent` or lives under it. Path-aware on purpose: a plain string prefix would
+ * let `/srv/app` match `/srv/application`, and on Windows `relative()` returns an absolute path when
+ * the two sides are on different volumes, which no `..` check on a string would catch.
+ */
+function isInside(parent, child, platform = process.platform) {
+  const from = normalizeForCompare(parent, platform)
+  const to = normalizeForCompare(child, platform)
+  if (from === to) return true
+  const rel = relative(from, to)
+  if (rel.length === 0) return true
+  if (isAbsolute(rel)) return false
+  return rel.split(/[\\/]/)[0] !== '..'
+}
+
+function checkPathAllowed(target, allowed, platform = process.platform) {
+  if (allowed.allowAll) return true
+  return allowed.roots.some((root) => isInside(root, target, platform))
+}
+
+/**
+ * Per-root index directory. The readable slug is decorative; the digest is the identity, so two roots
+ * that sanitize to the same slug (`/srv/a/b` and `/srv/a_b`) can never share one index and serve each
+ * other's files. Both parts fold case on Windows, where one directory has many names.
+ */
+function indexDirFor(root, indexRoot = CONFIG.indexRoot, platform = process.platform) {
+  const abs = resolve(root)
+  const folded = platform === 'win32' ? abs.toLowerCase() : abs
+  const digest = createHash('sha256').update(folded).digest('hex').slice(0, 16)
+  const slug = basename(folded)
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .replace(/^[_.-]+|[_.-]+$/g, '')
+    .slice(0, 40)
+  return join(indexRoot, `${slug || 'root'}-${digest}`)
+}
+
+/** Path relative to a root, forward-slashed for the wire. Throws if it escapes the root. */
+function relativeScope(root, target, platform = process.platform) {
+  if (!isInside(root, target, platform)) {
+    throw new ToolError(ERROR_CODES.PATH_NOT_ALLOWED, `${target} is outside the index root ${root}`)
+  }
+  const rel = relative(resolve(root), resolve(target))
+  return rel.split(sep).join('/')
+}
+
+/** Normalize a reported path to a forward-slashed path relative to the search root. */
+function displayPath(root, target, platform = process.platform) {
+  const abs = isAbsolute(target) ? target : resolve(root, target)
+  if (isInside(root, abs, platform)) return relative(resolve(root), resolve(abs)).split(sep).join('/')
+  return abs.split(sep).join('/')
+}
+
+/**
+ * The index a root belongs to: one index per outermost allowed root, so searching a subdirectory
+ * reuses the repository index with a narrower scope instead of building a second one.
+ */
+function canonicalRootFor(target, allowed, platform = process.platform) {
+  if (allowed.allowAll) return resolve(target)
+  const containing = allowed.roots.filter((root) => isInside(root, target, platform))
+  if (containing.length === 0) return resolve(target)
+  return containing.sort((a, b) => a.length - b.length)[0]
+}
+
+/**
+ * Resolve the `path` argument into the root to search, the exact target, and the scope to narrow to.
+ * The allow-list is enforced here: this is the only door into the filesystem.
+ */
+function resolveSearchTarget(rawPath, config, allowed, stat = statSync) {
+  const candidate = rawPath === undefined || rawPath === null || rawPath === ''
+    ? resolve(config.defaultRoot)
+    : resolve(config.cwd, String(rawPath))
+
+  if (!checkPathAllowed(candidate, allowed, config.platform)) {
+    const shown = allowed.allowAll ? '(unexpected: allow-all rejected)' : allowed.roots.join(', ')
+    throw new ToolError(
+      ERROR_CODES.PATH_NOT_ALLOWED,
+      `path is outside the allowed search roots: ${candidate}`,
+      {
+        hint: 'Search an allowed root, set TGREP_ALLOWED_ROOTS to include this path, or set it to "*" to allow any path.',
+        details: { allowedRoots: allowed.roots },
+      },
+    )
+  }
+
+  let info
+  try {
+    info = stat(candidate)
+  } catch (error) {
+    throw new ToolError(ERROR_CODES.NOT_FOUND, `path does not exist: ${candidate}`, {
+      hint: 'Pass an absolute path to a file or directory that exists.',
+      details: { cause: String(error?.message ?? error) },
+    })
+  }
+
+  const isDirectory = info.isDirectory()
+  if (!isDirectory && !info.isFile()) {
+    throw new ToolError(ERROR_CODES.VALIDATION_ERROR, `path is neither a file nor a directory: ${candidate}`)
+  }
+
+  const anchor = isDirectory ? candidate : dirname(candidate)
+  const root = canonicalRootFor(anchor, allowed, config.platform)
+  const scope = isDirectory ? candidate : dirname(candidate)
+  return { root, target: candidate, kind: isDirectory ? 'directory' : 'file', scope: relativeScope(root, scope, config.platform) }
+}
+
+// ---------------------------------------------------------------------------
+// Output hygiene
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip control characters — a matched line is untrusted input to the client's terminal — and cap
+ * its length so one pathological line cannot dominate the context window.
+ */
+function sanitizeText(value, maxChars) {
+  let text = String(value ?? '')
+  text = text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
+  if (maxChars !== undefined && text.length > maxChars) text = `${text.slice(0, maxChars)}…`
+  return text
+}
+
+/**
+ * Compare two index-relative paths from the wire, which may arrive with either separator. Used to
+ * narrow a file search to exactly the requested file.
+ */
+function sameRelativePath(a, b, platform = process.platform) {
+  const norm = (value) => {
+    const text = String(value ?? '')
+      .split(/[\\/]/)
+      .filter((part) => part.length > 0 && part !== '.')
+      .join('/')
+    return platform === 'win32' ? text.toLowerCase() : text
+  }
+  return norm(a) === norm(b)
+}
+
+/** Cap a match list by count and by total text bytes, reporting whichever bound bound first. */function capMatches(matches, limit, maxBytes) {
+  const kept = []
+  let bytes = 0
+  let truncatedByBytes = false
+  for (const match of matches) {
+    if (kept.length >= limit) break
+    const size = match.text.length + match.path.length + 16
+    if (kept.length > 0 && bytes + size > maxBytes) {
+      truncatedByBytes = true
+      break
+    }
+    bytes += size
+    kept.push(match)
+  }
+  return { kept, truncatedByBytes }
+}
+
+// ---------------------------------------------------------------------------
+// Concurrency primitives
+// ---------------------------------------------------------------------------
+
+/** Counting semaphore with hand-off on release, so a waiter never loses a waking race. */
+function createSemaphore(limit) {
+  let active = 0
+  const waiters = []
+  const release = () => {
+    const next = waiters.shift()
+    if (next !== undefined) next()
+    else active -= 1
+  }
+  return {
+    async acquire() {
+      if (active < limit) {
+        active += 1
+        return release
+      }
+      await new Promise((resolveWaiter) => waiters.push(resolveWaiter))
+      return release
+    },
+    snapshot: () => ({ limit, active, queued: waiters.length }),
+  }
+}
+
+/** Token bucket. The realistic failure mode is a runaway agent loop, not an attacker. */
+function createRateLimiter(perMinute) {
+  let tokens = perMinute
+  let last = Date.now()
+  return {
+    take(now = Date.now()) {
+      if (perMinute <= 0) return { allowed: true }
+      // A clock that jumps backwards must not drain the budget: treat it as no elapsed time.
+      const elapsed = Math.max(0, now - last)
+      tokens = Math.min(perMinute, tokens + (elapsed / 60000) * perMinute)
+      last = Math.max(last, now)
+      if (tokens < 1) {
+        return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil(((1 - tokens) * 60000) / perMinute)) }
+      }
+      tokens -= 1
+      return { allowed: true, remaining: Math.floor(tokens) }
+    },
+    snapshot: () => ({ perMinute, tokens: Math.floor(tokens) }),
+  }
+}
+
+/**
+ * Circuit breaker for the undocumented direct protocol. Without it every call against a broken
+ * protocol pays a full daemon spawn (~300ms) before falling back to the CLI.
+ */
+function createCircuitBreaker({ threshold = 3, cooldownMs = 30000, maxCooldownMs = 300000 } = {}) {
+  let state = 'closed'
+  let failures = 0
+  let openedAt = 0
+  let cooldown = cooldownMs
+  return {
+    allow(now = Date.now()) {
+      if (state === 'closed') return true
+      if (state === 'half-open') return false
+      if (now - openedAt >= cooldown) {
+        state = 'half-open'
+        openedAt = now
+        return true
+      }
+      return false
+    },
+    recordSuccess() {
+      state = 'closed'
+      failures = 0
+      cooldown = cooldownMs
+    },
+    recordFailure(now = Date.now()) {
+      failures += 1
+      if (state === 'half-open' || failures >= threshold) {
+        state = 'open'
+        openedAt = now
+        cooldown = Math.min(maxCooldownMs, cooldown * 2)
+      }
+    },
+    snapshot: () => ({
+      state,
+      failures,
+      cooldownMs: cooldown,
+      opensInMs: state === 'open' ? Math.max(0, cooldown - (Date.now() - openedAt)) : 0,
+    }),
+  }
+}
+
+/** Cooperative cancellation, so a client's notifications/cancelled stops work we no longer owe. */
+function createCancellationToken() {
+  const hooks = []
+  const token = {
+    cancelled: false,
+    onCancel(hook) {
+      if (token.cancelled) hook()
+      else hooks.push(hook)
+    },
+    cancel() {
+      if (token.cancelled) return
+      token.cancelled = true
+      for (const hook of hooks.splice(0)) {
+        try {
+          hook()
+        } catch {
+          // cancellation is best effort
+        }
+      }
+    },
+  }
+  return token
+}
+
+// ---------------------------------------------------------------------------
+// Metrics and health
+// ---------------------------------------------------------------------------
+
+function percentile(sorted, fraction) {
+  if (sorted.length === 0) return null
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1))
+  return sorted[index]
+}
+
+const metrics = {
+  startedAt: Date.now(),
+  tools: new Map(), // name -> { calls, errors, latencies: number[] }
+  directAttempts: 0,
+  directSuccesses: 0,
+  directFailures: 0,
+  cliFallbacks: 0,
+  indexBuilds: 0,
+  rateLimited: 0,
+}
+
+const LATENCY_SAMPLES = 200
+
+function recordToolCall(tool, elapsedMs, ok) {
+  let entry = metrics.tools.get(tool)
+  if (entry === undefined) {
+    entry = { calls: 0, errors: 0, latencies: [] }
+    metrics.tools.set(tool, entry)
+  }
+  entry.calls += 1
+  if (!ok) entry.errors += 1
+  entry.latencies.push(elapsedMs)
+  if (entry.latencies.length > LATENCY_SAMPLES) entry.latencies.shift()
+}
+
+function snapshotMetrics() {
+  const tools = {}
+  for (const [name, entry] of metrics.tools) {
+    const sorted = [...entry.latencies].sort((a, b) => a - b)
+    tools[name] = {
+      calls: entry.calls,
+      errors: entry.errors,
+      p50Ms: percentile(sorted, 0.5),
+      p95Ms: percentile(sorted, 0.95),
+      maxMs: sorted.length > 0 ? sorted[sorted.length - 1] : null,
+    }
+  }
+  return {
+    uptimeMs: Date.now() - metrics.startedAt,
+    tools,
+    direct: {
+      attempts: metrics.directAttempts,
+      successes: metrics.directSuccesses,
+      failures: metrics.directFailures,
+      fallbacks: metrics.cliFallbacks,
+      circuit: directBreaker.snapshot(),
+    },
+    indexBuilds: metrics.indexBuilds,
+    rateLimited: metrics.rateLimited,
+  }
+}
+
+/**
+ * Collapse named checks into one verdict — the shape the best-practices guide asks for: a single
+ * status the operator can alert on, plus the per-check detail that explains it.
+ */
+function aggregateHealth(checks) {
+  if (checks.some((check) => check.status === 'unhealthy')) return 'unhealthy'
+  if (checks.some((check) => check.status === 'degraded')) return 'degraded'
+  return 'healthy'
+}
+
+/** Every call writes one audit line to stderr: who asked for what, and how it ended. */
+function audit(record) {
+  log(`audit ${JSON.stringify(record)}`, 'normal')
+}
+
+// ---------------------------------------------------------------------------
+// Backend 1: direct JSON-RPC over TCP to a resident `tgrep serve`
+// ---------------------------------------------------------------------------
+
+/**
+ * One persistent newline-delimited JSON-RPC connection to a tgrep server.
+ *
+ * tgrep's wire format (verified against tgrep-cli/src/serve.rs at the release named in
+ * VERIFIED_TGREP_VERSION): one JSON object per
+ * line, `{jsonrpc, id, method, params}`, methods `search | files | status | reload`, every reply
+ * newline-terminated. The port is advertised in `<index-dir>/serve.json` as `{pid, port}`.
+ */
+class DirectClient {
+  constructor(port) {
+    this.port = port
+    this.socket = null
+    this.buffer = ''
+    this.waiters = new Map()
+    this.nextId = 0
+    this.failed = null
+  }
+
+  connect(timeoutMs) {
+    return new Promise((resolveConnect, reject) => {
+      const socket = createConnection({ host: '127.0.0.1', port: this.port })
+      this.socket = socket
+      const timer = setTimeout(() => {
+        socket.destroy()
+        reject(new Error(`connect timeout after ${timeoutMs}ms`))
+      }, timeoutMs)
+      socket.once('connect', () => {
+        clearTimeout(timer)
+        socket.setNoDelay(true)
+        resolveConnect()
+      })
+      socket.once('error', (error) => {
+        clearTimeout(timer)
+        this.fail(error)
+        reject(error)
+      })
+      socket.on('data', (chunk) => this.onData(chunk))
+      socket.on('close', () => this.fail(new Error('connection closed by server')))
+    })
+  }
+
+  onData(chunk) {
+    this.buffer += chunk.toString('utf8')
+    let index
+    while ((index = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, index)
+      this.buffer = this.buffer.slice(index + 1)
+      if (line.trim().length === 0) continue
+      let message
+      try {
+        message = JSON.parse(line)
+      } catch (error) {
+        log(`dropped unparseable server frame: ${String(error?.message ?? error)}`, 'debug')
+        continue
+      }
+      const waiter = this.waiters.get(message.id)
+      if (waiter === undefined) continue
+      this.waiters.delete(message.id)
+      waiter(message)
+    }
+  }
+
+  /** Reject every in-flight request once the connection is unusable. */
+  fail(error) {
+    if (this.failed === null) this.failed = error
+    for (const waiter of this.waiters.values()) waiter({ __transportError: error })
+    this.waiters.clear()
+  }
+
+  call(method, params, timeoutMs) {
+    const socket = this.socket
+    if (this.failed !== null) return Promise.resolve({ __transportError: this.failed })
+    if (socket === null || socket.destroyed) {
+      return Promise.resolve({ __transportError: new Error('not connected') })
+    }
+    const id = ++this.nextId
+    return new Promise((resolveCall) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(id)
+        resolveCall({ __transportError: new Error(`${method} timed out after ${timeoutMs}ms`) })
+      }, timeoutMs)
+      this.waiters.set(id, (message) => {
+        clearTimeout(timer)
+        resolveCall(message)
+      })
+      try {
+        socket.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+      } catch (error) {
+        clearTimeout(timer)
+        this.waiters.delete(id)
+        resolveCall({ __transportError: error })
+      }
+    })
+  }
+
+  close() {
+    try {
+      this.socket?.destroy()
+    } catch {
+      // best effort
+    }
+    this.fail(new Error('client closed'))
+  }
+}
+
+/** root -> { client, pid, status } — one daemon per searched root. */
+const daemons = new Map()
+const seenRoots = new Set()
+
+function indexPathFor(root, config = CONFIG) {
+  return join(indexDirFor(root, config.indexRoot, config.platform), 'meta.json')
+}
+
+function serveInfoPathFor(root, config = CONFIG) {
+  return join(indexDirFor(root, config.indexRoot, config.platform), 'serve.json')
+}
+
+function indexAgeMs(root, config = CONFIG) {
+  try {
+    return Date.now() - statSync(indexPathFor(root, config)).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+function readServeInfo(root) {
+  try {
+    const info = JSON.parse(readFileSync(serveInfoPathFor(root), 'utf8'))
+    return typeof info?.port === 'number' ? info : null
+  } catch {
+    return null
+  }
+}
+
+async function probeExistingServer(root) {
+  const info = readServeInfo(root)
+  if (info === null) return null
+  const client = new DirectClient(info.port)
+  try {
+    await client.connect(3000)
+    const status = await client.call('status', {}, 5000)
+    if (status.__transportError !== undefined || status.error !== undefined) throw new Error('status failed')
+    return { client, pid: info.pid, spawned: false }
+  } catch (error) {
+    client.close()
+    log(`existing server for ${root} unusable (${String(error?.message ?? error)}); will start our own`)
+    return null
+  }
+}
+
+/** Read-only liveness probe for health checks: never spawns a daemon. */
+async function pingDaemon(root) {
+  const info = readServeInfo(root)
+  if (info === null) return { reachable: false, reason: 'no serve.json' }
+  const client = new DirectClient(info.port)
+  try {
+    await client.connect(2000)
+    const status = await client.call('status', {}, 4000)
+    client.close()
+    if (status.__transportError !== undefined) {
+      return { reachable: false, reason: String(status.__transportError.message ?? status.__transportError) }
+    }
+    if (status.error !== undefined) return { reachable: false, reason: JSON.stringify(status.error) }
+    return { reachable: true, pid: info.pid, port: info.port }
+  } catch (error) {
+    client.close()
+    return { reachable: false, reason: String(error?.message ?? error) }
+  }
+}
+
+async function spawnServer(root, config, token) {
+  const indexDir = indexDirFor(root, config.indexRoot, config.platform)
+  mkdirSync(indexDir, { recursive: true })
+  // A stale serve.json from a dead server would make us connect to the wrong (or no) port.
+  rmSync(serveInfoPathFor(root, config), { force: true })
+  const child = spawn(config.bin.path, ['serve', '--index-path', indexDir, root], {
+    windowsHide: true,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  })
+  token?.onCancel(() => {
+    try {
+      child.kill()
+    } catch {
+      // best effort
+    }
+  })
+  let stderrTail = ''
+  child.stderr.on('data', (chunk) => {
+    stderrTail = `${stderrTail}${chunk.toString('utf8')}`.slice(-2000)
+  })
+  child.on('error', (error) => log(`daemon spawn error: ${String(error?.message ?? error)}`))
+
+  const deadline = Date.now() + config.daemonWaitMs
+  while (Date.now() < deadline) {
+    if (token?.cancelled === true) throw new ToolError(ERROR_CODES.CANCELLED, 'cancelled while starting the search daemon')
+    if (child.exitCode !== null) {
+      throw new ToolError(ERROR_CODES.BINARY_MISSING, `tgrep server exited early (code ${child.exitCode})`, {
+        hint: `Check that TGREP_BIN points at a working tgrep binary (currently ${config.bin.path}).`,
+        details: { stderr: stderrTail.trim() },
+      })
+    }
+    const info = readServeInfo(root)
+    if (info !== null) {
+      const client = new DirectClient(info.port)
+      try {
+        await client.connect(1500)
+        const status = await client.call('status', {}, 5000)
+        if (status.__transportError === undefined && status.error === undefined) {
+          log(`daemon ready for ${root} (pid ${info.pid}, port ${info.port})`, 'debug')
+          return { client, pid: info.pid, child, spawned: true }
+        }
+      } catch {
+        client.close()
+      }
+    }
+    await new Promise((resolveWait) => setTimeout(resolveWait, 150))
+  }
+  try {
+    child.kill()
+  } catch {
+    // best effort
+  }
+  throw new ToolError(
+    ERROR_CODES.BACKEND_UNAVAILABLE,
+    `tgrep server did not become ready within ${config.daemonWaitMs}ms`,
+    { details: { stderr: stderrTail.trim() }, retryAfterSeconds: 5 },
+  )
+}
+
+async function ensureDaemon(root, config, token) {
+  const known = daemons.get(root)
+  if (known?.status === 'ready' && known.client.failed === null) return known
+  if (known?.status === 'starting') return known.promise
+  const entry = { status: 'starting', client: null, child: null, pid: null, spawned: false }
+  entry.promise = (async () => {
+    const reused = await probeExistingServer(root)
+    const started = reused ?? (await spawnServer(root, config, token))
+    entry.client = started.client
+    entry.child = started.child ?? null
+    entry.pid = started.pid
+    entry.spawned = started.spawned === true
+    entry.status = 'ready'
+    daemons.set(root, entry)
+    return entry
+  })()
+  daemons.set(root, entry)
+  try {
+    return await entry.promise
+  } catch (error) {
+    daemons.delete(root)
+    throw error
+  }
+}
+
+/** Drop a daemon: used before a rebuild and at shutdown so no orphan holds the index. */
+function stopDaemon(root) {
+  const entry = daemons.get(root)
+  if (entry === undefined) return false
+  entry.client?.close()
+  const own = entry.child !== null && entry.child !== undefined
+  if (own && entry.child.exitCode === null) {
+    try {
+      entry.child.kill()
+    } catch {
+      // best effort
+    }
+  }
+  // Only a daemon we started leaves an advertisement we are entitled to remove; a reused one
+  // belongs to whoever started it, so leave its serve.json alone.
+  if (own) rmSync(serveInfoPathFor(root), { force: true })
+  daemons.delete(root)
+  return own
+}
+
+function shutdownAll() {
+  for (const root of [...daemons.keys()]) stopDaemon(root)
+}
+
+async function searchDirect(root, plan, args, config, token) {
+  const entry = await ensureDaemon(root, config, token)
+  const params = {
+    pattern: args.pattern,
+    // The protocol returns span and column arrays by default. This tool does not display them, and
+    // building them dominates response time on large result sets, so both are disabled.
+    detail: false,
+    positions: false,
+  }
+  // The protocol scopes directories only: a file target narrows to its directory, then the rows are
+  // filtered to the exact file below.
+  if (plan.scope.length > 0) params.scope = plan.scope
+  if (typeof args.glob === 'string' && args.glob.length > 0) params.glob = [args.glob]
+  if (args.ignoreCase === true) params.case_insensitive = true
+  if (Number.isFinite(args.maxPerFile) && args.maxPerFile > 0) params.max_count = Math.floor(args.maxPerFile)
+
+  const started = Date.now()
+  const response = await entry.client.call('search', params, config.timeoutMs)
+  const elapsedMs = Date.now() - started
+  if (response.__transportError !== undefined) {
+    stopDaemon(root)
+    throw response.__transportError
+  }
+  if (response.error !== undefined) {
+    throw new ToolError(ERROR_CODES.BACKEND_UNAVAILABLE, `tgrep server refused the search: ${JSON.stringify(response.error)}`)
+  }
+
+  const result = response.result ?? {}
+  const rows = Array.isArray(result.matches) ? result.matches : []
+  // The wire scopes directories only, so a file search narrows to its directory and filters here.
+  const targetRel = plan.kind === 'file'
+    ? (plan.scope.length === 0 ? basename(plan.target) : `${plan.scope}/${basename(plan.target)}`)
+    : null
+
+  const matches = []
+  const files = new Set()
+  for (const row of rows) {
+    if (row === null || typeof row !== 'object' || typeof row.file !== 'string') continue
+    const path = row.file.split(sep).join('/').replace(/^\.\//, '')
+    if (targetRel !== null && !sameRelativePath(path, targetRel, config.platform)) continue
+    files.add(path)
+    matches.push({
+      path,
+      line: typeof row.line === 'number' ? row.line : 0,
+      text: sanitizeText(row.content, config.maxLineChars),
+    })
+  }
+
+  return {
+    backend: 'direct',
+    elapsedMs,
+    engineMs: typeof result.elapsed_ms === 'number' ? result.elapsed_ms : undefined,
+    total: targetRel === null
+      ? (typeof result.num_matches === 'number' ? Math.max(result.num_matches, matches.length) : matches.length)
+      : matches.length,
+    files: files.size,
+    matches,
+    daemonPid: entry.pid,
+    reusedDaemon: entry.spawned === false,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backend 2: CLI fallback (`tgrep ... --json` per search)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the tgrep binary once with a plain argv vector (no shell, so no quoting layer) and collect
+ * bounded stdout/stderr. Resolves — never rejects — so a spawn failure becomes a reportable result.
+ */
+function runTgrep(argv, timeoutMs, token, bin = CONFIG.bin.path) {
+  return new Promise((resolveRun) => {
+    let child
+    try {
+      child = spawn(bin, argv, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      resolveRun({ exitCode: null, stdout: '', stderr: String(error?.message ?? error), timedOut: false, spawnError: true, cancelled: false })
+      return
+    }
+    const out = []
+    const err = []
+    let outBytes = 0
+    let errBytes = 0
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill()
+    }, timeoutMs)
+    token?.onCancel(() => {
+      try {
+        child.kill()
+      } catch {
+        // best effort
+      }
+    })
+    child.stdout.on('data', (chunk) => {
+      if (outBytes >= CLI_OUTPUT_CAP_BYTES) return
+      outBytes += chunk.length
+      out.push(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      if (errBytes >= CLI_STDERR_CAP_BYTES) return
+      errBytes += chunk.length
+      err.push(chunk)
+    })
+    child.on('error', (error) => {
+      clearTimeout(timer)
+      resolveRun({ exitCode: null, stdout: '', stderr: String(error?.message ?? error), timedOut, spawnError: true, cancelled: token?.cancelled === true })
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolveRun({
+        exitCode: code,
+        stdout: Buffer.concat(out).toString('utf8'),
+        stderr: Buffer.concat(err).toString('utf8'),
+        timedOut,
+        spawnError: false,
+        cancelled: token?.cancelled === true,
+      })
+    })
+  })
+}
+
+/** Parse ripgrep-compatible `--json` output into flat matches. */
+function parseMatches(stdout) {
+  const matches = []
+  for (const raw of stdout.split('\n')) {
+    if (raw.length === 0 || raw.charCodeAt(0) !== 0x7b) continue
+    let record
+    try {
+      record = JSON.parse(raw)
+    } catch {
+      continue
+    }
+    const data = record?.type === 'match' ? record.data : undefined
+    if (data === undefined) continue
+    matches.push({
+      path: typeof data.path?.text === 'string' ? data.path.text : '',
+      line: typeof data.line_number === 'number' ? data.line_number : 0,
+      text: (typeof data.lines?.text === 'string' ? data.lines.text : '').replace(/\r?\n$/, ''),
+    })
+  }
+  return matches
+}
+
+/** Classify tgrep's stderr so a degraded call is visible instead of silently slower. */
+function modeFromStderr(stderr) {
+  const text = String(stderr ?? '')
+  if (text.includes('falling back')) return 'local-index'
+  if (text.includes('no index')) return 'scan'
+  return 'indexed'
+}
+
+async function searchCli(root, plan, args, config, token) {
+  // Flags must precede `--`: tgrep reads everything after it as the pattern, so a search for the
+  // bare word `index` or `serve` cannot be mistaken for a subcommand.
+  const argv = ['--index-path', indexDirFor(root, config.indexRoot, config.platform), '--no-config']
+  if (typeof args.glob === 'string' && args.glob.length > 0) argv.push('-g', args.glob)
+  if (args.ignoreCase === true) argv.push('-i')
+  if (Number.isFinite(args.maxPerFile) && args.maxPerFile > 0) argv.push('-m', String(Math.floor(args.maxPerFile)))
+  if (args.includeGitIgnored === true) argv.push('--no-ignore-vcs')
+  argv.push('--json', '--', args.pattern, plan.target)
+
+  const started = Date.now()
+  const result = await runTgrep(argv, config.timeoutMs, token, config.bin.path)
+  const elapsedMs = Date.now() - started
+
+  if (result.cancelled) throw new ToolError(ERROR_CODES.CANCELLED, 'search cancelled')
+  if (result.spawnError) {
+    throw new ToolError(ERROR_CODES.BINARY_MISSING, `could not start the tgrep executable: ${config.bin.path}`, {
+      hint: 'Set TGREP_BIN to the tgrep executable, install tgrep on PATH, or vendor it at <server dir>/bin/tgrep(.exe).',
+      details: { stderr: result.stderr.trim().slice(0, 500), source: config.bin.source },
+    })
+  }
+  if (result.timedOut) {
+    throw new ToolError(ERROR_CODES.TIMEOUT, `tgrep search timed out after ${config.timeoutMs}ms`, {
+      hint: 'Narrow the pattern, add a glob, or scope the search to a subdirectory.',
+      retryAfterSeconds: 5,
+    })
+  }
+  if (result.exitCode !== 0) {
+    throw new ToolError(ERROR_CODES.BACKEND_UNAVAILABLE, `tgrep exited with code ${result.exitCode}`, {
+      details: { stderr: result.stderr.trim().split('\n').slice(-3).join(' | ').slice(0, 500) },
+    })
+  }
+
+  const parsed = parseMatches(result.stdout)
+  const files = new Set()
+  const matches = []
+  for (const item of parsed) {
+    const path = displayPath(root, item.path, config.platform)
+    files.add(path)
+    matches.push({ path, line: item.line, text: sanitizeText(item.text, config.maxLineChars) })
+  }
+  return {
+    backend: 'cli',
+    elapsedMs,
+    engineMs: undefined,
+    total: matches.length,
+    files: files.size,
+    matches,
+    mode: modeFromStderr(result.stderr),
+    exitCode: result.exitCode,
+    daemonPid: undefined,
+    reusedDaemon: undefined,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Index lifecycle
+// ---------------------------------------------------------------------------
+
+const indexState = new Map()
+
+/** Build the index for a root, once per process unless `force` is set. */
+async function ensureIndex(root, force, config, token) {
+  const existing = indexState.get(root)
+  if (!force && existing?.status === 'ready') return existing
+  // Without this, two callers racing on a cold root would both run a full build. With per-root
+  // serialisation they should not, but a health check or a future caller could still overlap.
+  if (!force && existing?.status === 'building') return existing.promise
+  if (!force && existsSync(indexPathFor(root, config))) {
+    const state = { status: 'ready', builtMs: null }
+    indexState.set(root, state)
+    return state
+  }
+
+  const task = (async () => {
+    mkdirSync(indexDirFor(root, config.indexRoot, config.platform), { recursive: true })
+    const started = Date.now()
+    metrics.indexBuilds += 1
+    const result = await runTgrep(
+      ['index', '--index-path', indexDirFor(root, config.indexRoot, config.platform), root],
+      config.timeoutMs * 4,
+      token,
+      config.bin.path,
+    )
+    const state = {
+      status: result.exitCode === 0 ? 'ready' : 'failed',
+      builtMs: Date.now() - started,
+      exitCode: result.exitCode,
+      stderr: result.stderr.trim().split('\n').slice(-3).join(' | ').slice(0, 500),
+    }
+    indexState.set(root, state)
+    log(`index ${root}: ${state.status} in ${state.builtMs}ms`)
+    return state
+  })()
+  indexState.set(root, { status: 'building', promise: task })
+  return task
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting, concurrency and root locking
+// ---------------------------------------------------------------------------
+
+const rateLimiter = createRateLimiter(CONFIG.maxCallsPerMinute)
+const globalGate = createSemaphore(CONFIG.maxConcurrency)
+const directBreaker = createCircuitBreaker()
+const rootQueues = new Map()
+
+/**
+ * Serialise work per root (an index build and a search must not overlap) while letting independent
+ * roots proceed in parallel, up to the global concurrency budget.
+ */
+function withRootLock(root, task, config = CONFIG) {
+  const key = normalizeForCompare(root, config.platform)
+  const previous = rootQueues.get(key) ?? Promise.resolve()
+  const next = previous.then(task, task)
+  const settled = next.then(() => undefined, () => undefined)
+  rootQueues.set(key, settled)
+  settled.then(() => {
+    if (rootQueues.get(key) === settled) rootQueues.delete(key)
+  })
+  return next
+}
+
+async function runExclusive(root, task, config = CONFIG) {
+  return withRootLock(root, async () => {
+    const release = await globalGate.acquire()
+    try {
+      return await task()
+    } finally {
+      release()
+    }
+  }, config)
+}
+
+/** Reject rather than hang: a tool call that never answers is worse than one that fails. */
+function withDeadline(promise, ms, label) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new ToolError(ERROR_CODES.TIMEOUT, `${label} exceeded its ${ms}ms deadline`, {
+        hint: 'Narrow the request, or raise TGREP_TOOL_TIMEOUT_MS.',
+      }))
+    }, ms)
+  })
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer))
+}
+
+// ---------------------------------------------------------------------------
+// Client-declared workspace roots (MCP `roots`)
+// ---------------------------------------------------------------------------
+
+let clientRoots = []
+let clientSupportsRoots = false
+
+function uriToPath(uri) {
+  if (typeof uri !== 'string' || !uri.startsWith('file://')) return null
+  try {
+    return fileURLToPath(uri)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The client's workspace roots are the most accurate answer to "what should this server search",
+ * so they outrank both the cwd default and the configured allow-list. A client that does not
+ * declare the roots capability is never asked, so nothing changes for it.
+ */
+function effectiveDefaultRoot(config = CONFIG) {
+  if (config.defaultRootSource === 'TGREP_DEFAULT_ROOT') return config.defaultRoot
+  if (clientRoots.length > 0) return clientRoots[0]
+  return config.defaultRoot
+}
+
+function effectiveAllowed(config = CONFIG) {
+  if (config.allowed.allowAll) return { allowAll: true, roots: [] }
+  return { allowAll: false, roots: dedupePaths([...config.allowed.roots, ...clientRoots], config.platform) }
+}
+
+function configForRequest(config = CONFIG) {
+  return { ...config, defaultRoot: effectiveDefaultRoot(config) }
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+const MATCH_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: 'Path relative to the search root, forward-slashed.' },
+    line: { type: 'integer', description: '1-based line number.' },
+    text: { type: 'string', description: 'Matching line, control characters stripped and length-capped.' },
+  },
+  required: ['path', 'line', 'text'],
+  additionalProperties: false,
+})
+
+const ERROR_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    code: { type: 'string', enum: Object.values(ERROR_CODES) },
+    message: { type: 'string' },
+    hint: { type: 'string' },
+    details: { type: 'object' },
+    retryAfterSeconds: { type: 'number' },
+  },
+  required: ['code', 'message'],
+  additionalProperties: false,
+})
+
+/**
+ * The three output schemas below are `{ oneOf: [...] }` with NO sibling keywords, on purpose.
+ *
+ * The harness enforces a JSON Schema subset (dsh-tools assertSupportedJsonSchema, reached through
+ * dsh-mcp-client's supportedOutputSchema) that rejects a node declaring `type`, `properties`,
+ * `required`, `additionalProperties`, `items`, `enum` or `const` *beside* `oneOf` — and a rejected
+ * schema is silently discarded, which would quietly relax structuredContent from required back to
+ * optional without anyone noticing. So every branch is a complete object schema standing alone, and
+ * the discriminating `const` carries its own `type` (the subset requires a type-correct const).
+ */
+const OK_BRANCH = (properties, required) => ({
+  type: 'object',
+  properties: { ok: { type: 'boolean', const: true }, ...properties },
+  required: ['ok', ...required],
+  additionalProperties: false,
+})
+
+const ERROR_BRANCH = {
+  type: 'object',
+  properties: { ok: { type: 'boolean', const: false }, error: ERROR_SCHEMA },
+  required: ['ok', 'error'],
+  additionalProperties: false,
+}
+
+const SEARCH_SUCCESS_PROPERTIES = {
+  root: { type: 'string', description: 'Indexed root the search ran against.' },
+  target: { type: 'string', description: 'Exact file or directory searched.' },
+  kind: { type: 'string', enum: ['directory', 'file'] },
+  backend: { type: 'string', enum: ['direct', 'cli'] },
+  elapsedMs: { type: 'number' },
+  engineMs: { type: 'number' },
+  buildMs: { type: 'number' },
+  total: { type: 'integer', description: 'Matches tgrep reported before capping.' },
+  files: { type: 'integer' },
+  returned: { type: 'integer' },
+  truncated: { type: 'boolean' },
+  matches: { type: 'array', items: MATCH_SCHEMA },
+  index: { type: 'string' },
+  indexAgeMs: { type: 'number' },
+  mode: { type: 'string' },
+  daemonPid: { type: 'integer' },
+  reusedDaemon: { type: 'boolean' },
+  warnings: { type: 'array', items: { type: 'string' } },
+}
+
+const SEARCH_OUTPUT_SCHEMA = Object.freeze({
+  oneOf: [
+    OK_BRANCH(SEARCH_SUCCESS_PROPERTIES, ['root', 'target', 'kind', 'backend', 'elapsedMs', 'total', 'files', 'returned', 'truncated', 'matches']),
+    ERROR_BRANCH,
+  ],
+})
+
+const INDEX_OUTPUT_SCHEMA = Object.freeze({
+  oneOf: [
+    OK_BRANCH({
+      root: { type: 'string' },
+      status: { type: 'string', enum: ['ready', 'failed'] },
+      builtMs: { type: 'number' },
+      indexDir: { type: 'string' },
+      indexAgeMs: { type: 'number' },
+      daemonRestarted: { type: 'boolean' },
+    }, ['root', 'status', 'indexDir']),
+    ERROR_BRANCH,
+  ],
+})
+
+const STATUS_OUTPUT_SCHEMA = Object.freeze({
+  oneOf: [
+    OK_BRANCH({
+      status: { type: 'string', enum: ['healthy', 'degraded', 'unhealthy'] },
+      version: { type: 'string' },
+      checks: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            status: { type: 'string', enum: ['healthy', 'degraded', 'unhealthy'] },
+            message: { type: 'string' },
+            responseTimeMs: { type: 'number' },
+            details: { type: 'object' },
+          },
+          required: ['name', 'status', 'message'],
+          additionalProperties: false,
+        },
+      },
+      config: { type: 'object' },
+      metrics: { type: 'object' },
+    }, ['status', 'version', 'checks', 'config', 'metrics']),
+    ERROR_BRANCH,
+  ],
+})
+
+/**
+ * Server instructions: the context an agent cannot get from a tool description. Kept to the
+ * relationships between tools and the limits of the backend, never a restatement of the schemas.
+ */
+const INSTRUCTIONS = [
+  'tgrep serves regex search over local code trees from a prebuilt trigram index, so it stays fast on',
+  'trees where scanning every file is slow. Use it for content search; prefer a plain scan when a',
+  'negative result is your conclusion, because tgrep does not honor ripgrep .ignore re-include rules',
+  '(`!pattern`), and an empty result can therefore be wrong.',
+  'Freshness: search results reflect the index as of its last build or watcher event. After a branch',
+  'switch or a large pull, call tgrep_index before trusting an empty or stale-looking result.',
+  'Scope: searches are confined to the allowed roots. Call tgrep_status once to see the effective',
+  'search root, the allowed roots, and the index location on this machine; pass `path` explicitly when',
+  'the default root is not the tree you mean. Include gitignored files only with includeGitIgnored,',
+  'which forces the slower scan backend.',
+  'Recovery: read error.code before retrying. RATE_LIMITED and TIMEOUT carry retryAfterSeconds;',
+  'PATH_NOT_ALLOWED needs a different path or a config change rather than a retry; BINARY_MISSING',
+  'means tgrep itself is not installed where this server can find it.',
+].join('\n')
+
+const TOOLS = [
+  {
+    name: 'tgrep_search',
+    title: 'Search a code tree (tgrep index)',
+    description:
+      'Regex search over a code tree using tgrep, which answers from a prebuilt trigram index instead of '
+      + 'scanning every file. Use it on large trees where a full scan is slow. Returns matching lines as '
+      + 'path:line:text. '
+      + 'Note: tgrep does not apply ripgrep\'s .ignore re-include rules, so on repositories that re-admit '
+      + 'ignored trees through .ignore it can return fewer files than ripgrep. When an empty result is the '
+      + 'conclusion, confirm it with a search tool that follows ripgrep ignore semantics.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Regular expression (ripgrep syntax) to search for.' },
+        path: {
+          type: 'string',
+          description:
+            'File or directory to search, absolute or relative to the server working directory. Defaults to the '
+            + 'workspace root the client declared, else the server default root (tgrep_status reports both). '
+            + 'A path outside the allowed roots is refused. The result reports `root` — the indexed root the search '
+            + 'ran against, which is the outermost allowed root containing the path — and paths are relative to it.',
+        },
+        glob: { type: 'string', description: 'Single glob filter, e.g. "*.ts".' },
+        ignoreCase: { type: 'boolean', description: 'Case-insensitive match.' },
+        maxPerFile: { type: 'integer', description: 'Maximum matching lines per file (tgrep -m).' },
+        maxResults: {
+          type: 'integer',
+          description: `Maximum matches returned in structuredContent (default ${MAX_RESULTS_DEFAULT}, ceiling ${CONFIG.maxResultsCeiling}).`,
+        },
+        includeGitIgnored: {
+          type: 'boolean',
+          description: 'Also search files excluded by .gitignore (rg parity on trees re-admitted by .ignore). Forces the CLI backend.',
+        },
+      },
+      required: ['pattern'],
+      additionalProperties: false,
+    },
+    outputSchema: SEARCH_OUTPUT_SCHEMA,
+  },
+  {
+    name: 'tgrep_index',
+    title: 'Build or rebuild the tgrep index',
+    description:
+      'Build or rebuild the tgrep trigram index for a repository, and restart its search daemon. Runs automatically '
+      + 'on the first search, so call this only to refresh after a branch switch, a large pull, or when results look '
+      + 'stale. The index is written outside the searched repo (never into it).',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description:
+            'Repository root, absolute or relative to the server working directory. Defaults to the same root tgrep_search uses. '
+            + 'The outermost allowed root containing the path is indexed, so a repository is indexed once and subdirectories reuse it.',
+        },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: INDEX_OUTPUT_SCHEMA,
+  },
+  {
+    name: 'tgrep_status',
+    title: 'tgrep server health and configuration',
+    description:
+      'Report this server\'s health, effective configuration, index freshness and call counters. Read-only and cheap: '
+      + 'it never builds an index and never starts a daemon. Use it to find out which roots are searchable, where the '
+      + 'index lives, and why a search failed.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Optional root to report index and daemon detail for.' },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: STATUS_OUTPUT_SCHEMA,
+  },
+]
+
+function renderSearch(payload) {
+  const bits = [`tgrep ${payload.total} match(es) in ${payload.files} file(s) — ${payload.elapsedMs}ms`]
+  bits.push(`backend=${payload.backend}`)
+  if (payload.engineMs !== undefined) bits.push(`engine=${Number(payload.engineMs).toFixed(1)}ms`)
+  if (payload.mode !== undefined) bits.push(`mode=${payload.mode}`)
+  if (payload.index !== undefined) bits.push(`index=${payload.index}`)
+  if (payload.truncated) bits.push(`showing ${payload.returned} of ${payload.total}`)
+  const lines = [bits.join(', ')]
+  for (const warning of payload.warnings ?? []) lines.push(`warning: ${warning}`)
+  if (payload.matches.length === 0) lines.push('(no matches)')
+  for (const item of payload.matches.slice(0, RENDER_LINES)) {
+    lines.push(`${item.path}:${item.line}: ${item.text}`)
+  }
+  if (payload.matches.length > RENDER_LINES) {
+    lines.push(`... ${payload.matches.length - RENDER_LINES} more match(es) in structuredContent`)
+  }
+  return lines.join('\n')
+}
+
+function renderIndex(payload) {
+  if (payload.status === 'ready') {
+    return `tgrep index ready for ${payload.root} in ${payload.builtMs}ms (index at ${payload.indexDir}); daemon restarts on the next search`
+  }
+  return `tgrep index FAILED for ${payload.root}: ${payload.error?.message ?? 'unknown error'}`
+}
+
+function renderStatus(payload) {
+  const lines = [
+    `tgrep-mcp ${payload.version} — ${payload.status.toUpperCase()} (pid ${process.pid}, uptime ${Math.round(payload.metrics.uptimeMs / 1000)}s)`,
+  ]
+  for (const check of payload.checks) {
+    lines.push(`  [${check.status}] ${check.name}: ${check.message}`)
+  }
+  lines.push(`  search root: ${payload.config.defaultRoot} (${payload.config.defaultRootSource})`)
+  lines.push(`  allowed roots: ${payload.config.allowedRoots.length === 0 ? '*' : payload.config.allowedRoots.join(', ')}`)
+  lines.push(`  index root: ${payload.config.indexRoot} (${payload.config.indexRootSource})`)
+  lines.push(`  tgrep binary: ${payload.config.bin.path} (${payload.config.bin.source})`)
+  lines.push(`  concurrency: ${payload.metrics.concurrency.active}/${payload.metrics.concurrency.limit} active, ${payload.metrics.concurrency.queued} queued`)
+  const calls = Object.entries(payload.metrics.tools)
+  if (calls.length > 0) {
+    lines.push(`  calls: ${calls.map(([name, m]) => `${name} ${m.calls} (${m.errors} err, p95 ${m.p95Ms ?? '-'}ms)`).join('; ')}`)
+  }
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Tool execution
+// ---------------------------------------------------------------------------
+
+function toolErrorOutcome(error) {
+  const toolError = asToolError(error)
+  const structured = { ok: false, error: toolError.toStructured() }
+  const { code, message, hint, retryAfterSeconds } = structured.error
+  const text = [`${code}: ${message}`, hint, retryAfterSeconds === undefined ? null : `retry after ${retryAfterSeconds}s`]
+    .filter((part) => part !== null && part !== undefined)
+    .join(' — ')
+  return { isError: true, text, structured }
+}
+
+async function executeSearch(rawArgs, token, config) {
+  const validation = validateArguments('tgrep_search', rawArgs, {
+    maxResultsCeiling: config.maxResultsCeiling,
+    maxPerFileCeiling: config.maxPerFileCeiling,
+  })
+  if (!validation.ok) throw new ProtocolError(-32602, 'invalid arguments for tgrep_search', validation.issues)
+  const args = validation.value
+  const limit = args.maxResults ?? config.maxResultsDefault
+
+  const allowed = effectiveAllowed(config)
+  const plan = resolveSearchTarget(args.path, config, allowed)
+  seenRoots.add(plan.root)
+
+  return runExclusive(plan.root, async () => {
+    const buildStart = Date.now()
+    const index = await ensureIndex(plan.root, false, config, token)
+    const buildMs = Date.now() - buildStart
+
+    let payload = null
+    let directError = null
+    const wantsCli = args.includeGitIgnored === true
+    if (config.direct !== 'off' && !wantsCli) {
+      if (directBreaker.allow()) {
+        metrics.directAttempts += 1
+        try {
+          payload = await searchDirect(plan.root, plan, args, config, token)
+          metrics.directSuccesses += 1
+          directBreaker.recordSuccess()
+        } catch (error) {
+          if (error instanceof ToolError && error.code === ERROR_CODES.CANCELLED) throw error
+          directError = asToolError(error)
+          metrics.directFailures += 1
+          directBreaker.recordFailure()
+          log(`direct backend failed for "${args.pattern}"; falling back to CLI: ${directError.message}`, 'debug')
+        }
+      } else {
+        directError = new ToolError(
+          ERROR_CODES.BACKEND_UNAVAILABLE,
+          'direct backend is paused after repeated protocol failures',
+          { details: directBreaker.snapshot() },
+        )
+      }
+    }
+
+    if (payload === null) {
+      if (directError !== null) metrics.cliFallbacks += 1
+      try {
+        payload = await searchCli(plan.root, plan, args, config, token)
+      } catch (error) {
+        const cliError = asToolError(error)
+        cliError.details = { ...(cliError.details ?? {}), directError: directError?.message ?? null }
+        throw cliError
+      }
+    }
+
+    const { kept, truncatedByBytes } = capMatches(payload.matches, limit, config.maxOutputBytes)
+    const warnings = []
+    if (truncatedByBytes) warnings.push(`match list capped at TGREP_MAX_OUTPUT_BYTES (${config.maxOutputBytes} bytes)`)
+    if (kept.length < payload.matches.length) {
+      warnings.push(`showing ${kept.length} of ${payload.matches.length} matches; raise maxResults or narrow the pattern`)
+    }
+    const age = indexAgeMs(plan.root, config)
+    if (age !== null && age > config.indexStaleMs) {
+      warnings.push(`index is ${Math.round(age / 3600000)}h old; call tgrep_index if the tree changed`)
+    }
+    if (index.status !== 'ready') warnings.push(`index state: ${index.status}`)
+    if (directError !== null && payload.backend === 'cli') {
+      warnings.push(`direct backend unavailable: ${directError.message}`)
+    }
+
+    return {
+      ok: true,
+      root: plan.root,
+      target: plan.target,
+      kind: plan.kind,
+      backend: payload.backend,
+      elapsedMs: payload.elapsedMs,
+      engineMs: payload.engineMs,
+      buildMs,
+      total: payload.total,
+      files: payload.files,
+      returned: kept.length,
+      truncated: kept.length < payload.total,
+      matches: kept,
+      index: index.status,
+      indexAgeMs: age ?? undefined,
+      mode: payload.mode,
+      daemonPid: payload.daemonPid,
+      reusedDaemon: payload.reusedDaemon,
+      warnings,
+    }
+  }, config)
+}
+
+async function executeIndex(rawArgs, token, config) {
+  const validation = validateArguments('tgrep_index', rawArgs, {})
+  if (!validation.ok) throw new ProtocolError(-32602, 'invalid arguments for tgrep_index', validation.issues)
+  const args = validation.value
+
+  const allowed = effectiveAllowed(config)
+  const anchor = args.path === undefined || args.path === ''
+    ? resolve(config.defaultRoot)
+    : resolve(config.cwd, args.path)
+  if (!checkPathAllowed(anchor, allowed, config.platform)) {
+    throw new ToolError(ERROR_CODES.PATH_NOT_ALLOWED, `path is outside the allowed roots: ${anchor}`, {
+      hint: 'Set TGREP_ALLOWED_ROOTS to include this path, or set it to "*" to allow any path.',
+      details: { allowedRoots: allowed.roots },
+    })
+  }
+  let info
+  try {
+    info = statSync(anchor)
+  } catch (error) {
+    throw new ToolError(ERROR_CODES.NOT_FOUND, `path does not exist: ${anchor}`, {
+      details: { cause: String(error?.message ?? error) },
+    })
+  }
+  if (!info.isDirectory()) {
+    throw new ToolError(ERROR_CODES.VALIDATION_ERROR, 'tgrep_index needs a directory, not a file', {
+      hint: 'Pass the repository root directory.',
+    })
+  }
+
+  const root = canonicalRootFor(anchor, allowed, config.platform)
+  seenRoots.add(root)
+
+  return runExclusive(root, async () => {
+    // The daemon pins the current index; release it before publishing a new generation.
+    const daemonRestarted = stopDaemon(root)
+    indexState.delete(root)
+    const state = await ensureIndex(root, true, config, token)
+    const payload = {
+      ok: state.status === 'ready',
+      root,
+      status: state.status,
+      builtMs: state.builtMs,
+      indexDir: indexDirFor(root, config.indexRoot, config.platform),
+      indexAgeMs: indexAgeMs(root, config) ?? undefined,
+      daemonRestarted,
+    }
+    if (state.status !== 'ready') {
+      payload.ok = false
+      payload.error = new ToolError(ERROR_CODES.INDEX_FAILED, state.stderr || `tgrep index exited with code ${state.exitCode}`, {
+        hint: 'Check that the root is readable and that the binary at TGREP_BIN is a working tgrep.',
+        details: { exitCode: state.exitCode },
+      }).toStructured()
+    }
+    return payload
+  }, config)
+}
+
+/** Named checks, each independent: one broken root must not hide a different broken assumption. */
+async function collectChecks(config, root) {
+  const checks = []
+  const time = async (name, fn) => {
+    const started = Date.now()
+    let result
+    try {
+      result = await fn()
+    } catch (error) {
+      result = { status: 'unhealthy', message: String(error?.message ?? error) }
+    }
+    checks.push({ name, responseTimeMs: Date.now() - started, ...result })
+  }
+
+  await time('configuration', async () => (config.issues.length === 0
+    ? { status: 'healthy', message: 'all environment overrides parsed' }
+    : { status: 'degraded', message: config.issues.join('; '), details: { issues: config.issues } }))
+
+  await time('tgrep_binary', async () => {
+    if (config.bin.present === false) {
+      return {
+        status: 'unhealthy',
+        message: `not found at ${config.bin.path} (from ${config.bin.source})`,
+        details: { path: config.bin.path, source: config.bin.source },
+      }
+    }
+    const probe = await runTgrep(['--version'], 5000, null, config.bin.path)
+    if (probe.spawnError) {
+      return { status: 'unhealthy', message: `cannot execute ${config.bin.path}: ${probe.stderr.trim().slice(0, 200)}` }
+    }
+    if (probe.timedOut) return { status: 'degraded', message: 'tgrep --version timed out' }
+    const version = probe.stdout.trim().split('\n')[0] ?? ''
+    const details = { path: config.bin.path, source: config.bin.source, version, verifiedVersion: VERIFIED_TGREP_VERSION }
+    if (probe.exitCode !== 0) {
+      return { status: 'unhealthy', message: `tgrep --version exited with ${probe.exitCode}`, details }
+    }
+    // The direct backend speaks an undocumented protocol, so an unverified release is a real risk
+    // worth surfacing before a search mysteriously returns wrong results.
+    if (!version.includes(VERIFIED_TGREP_VERSION)) {
+      return {
+        status: 'degraded',
+        message: `${version || 'unknown version'} is not the release the direct protocol was verified against (${VERIFIED_TGREP_VERSION}); install that release, or set TGREP_DIRECT=off to use the CLI backend`,
+        details,
+      }
+    }
+    return { status: 'healthy', message: `${version} (${config.bin.source})`, details }
+  })
+
+  await time('index_root', async () => {
+    try {
+      mkdirSync(config.indexRoot, { recursive: true })
+      return { status: 'healthy', message: config.indexRoot, details: { source: config.indexRootSource } }
+    } catch (error) {
+      return { status: 'unhealthy', message: `not writable: ${String(error?.message ?? error)}` }
+    }
+  })
+
+  await time('search_root', async () => {
+    try {
+      if (!statSync(root).isDirectory()) return { status: 'unhealthy', message: `${root} is not a directory` }
+      return { status: 'healthy', message: root, details: { allowedRoots: effectiveAllowed(config).allowAll ? ['*'] : effectiveAllowed(config).roots } }
+    } catch (error) {
+      return { status: 'unhealthy', message: `${root} is not readable: ${String(error?.message ?? error)}` }
+    }
+  })
+
+  await time('index_freshness', async () => {
+    const age = indexAgeMs(root, config)
+    if (age === null) {
+      return { status: 'degraded', message: 'no index yet; the first search will build one', details: { indexDir: indexDirFor(root, config.indexRoot, config.platform) } }
+    }
+    const hours = Math.round(age / 3600000)
+    if (age > config.indexStaleMs) {
+      return { status: 'degraded', message: `index is ${hours}h old; call tgrep_index if the tree changed`, details: { indexAgeMs: age } }
+    }
+    return { status: 'healthy', message: `index age ${hours}h`, details: { indexAgeMs: age } }
+  })
+
+  await time('indexed_daemon', async () => {
+    const ping = await pingDaemon(root)
+    if (ping.reachable) return { status: 'healthy', message: `resident server on port ${ping.port} (pid ${ping.pid})`, details: { pid: ping.pid, port: ping.port } }
+    if (config.direct === 'off') return { status: 'healthy', message: 'not used (TGREP_DIRECT=off)' }
+    if (ping.reason === 'no serve.json') return { status: 'degraded', message: 'no resident server; searches use the CLI backend', details: { direct: config.direct } }
+    const circuit = directBreaker.snapshot()
+    return { status: circuit.state === 'open' ? 'degraded' : 'healthy', message: `resident server unreachable (${ping.reason})`, details: { circuit } }
+  })
+
+  return checks
+}
+
+async function executeStatus(rawArgs, config) {
+  const validation = validateArguments('tgrep_status', rawArgs, {})
+  if (!validation.ok) throw new ProtocolError(-32602, 'invalid arguments for tgrep_status', validation.issues)
+  const args = validation.value
+
+  const allowed = effectiveAllowed(config)
+  let root = resolve(config.defaultRoot)
+  if (args.path !== undefined && args.path !== '') {
+    const candidate = resolve(config.cwd, args.path)
+    if (!checkPathAllowed(candidate, allowed, config.platform)) {
+      throw new ToolError(ERROR_CODES.PATH_NOT_ALLOWED, `path is outside the allowed roots: ${candidate}`, {
+        details: { allowedRoots: allowed.roots },
+      })
+    }
+    root = candidate
+  }
+
+  const checks = await collectChecks(config, root)
+  return {
+    ok: true,
+    status: aggregateHealth(checks),
+    version: VERSION,
+    checks,
+    config: {
+      serverName: SERVER_NAME,
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      client: clientInfo,
+      platform: config.platform,
+      cwd: config.cwd,
+      defaultRoot: config.defaultRoot,
+      defaultRootSource: config.defaultRootSource,
+      indexRoot: config.indexRoot,
+      indexRootSource: config.indexRootSource,
+      allowedRoots: allowed.allowAll ? [] : allowed.roots,
+      allowAllRoots: allowed.allowAll,
+      clientRoots,
+      clientSupportsRoots,
+      bin: config.bin,
+      direct: config.direct,
+      timeouts: { operationMs: config.timeoutMs, toolMs: config.toolTimeoutMs, daemonWaitMs: config.daemonWaitMs },
+      limits: {
+        maxConcurrency: config.maxConcurrency,
+        maxCallsPerMinute: config.maxCallsPerMinute,
+        maxResultsDefault: config.maxResultsDefault,
+        maxResultsCeiling: config.maxResultsCeiling,
+        maxLineChars: config.maxLineChars,
+        maxOutputBytes: config.maxOutputBytes,
+        indexStaleMs: config.indexStaleMs,
+      },
+      issues: config.issues,
+    },
+    metrics: {
+      ...snapshotMetrics(),
+      concurrency: globalGate.snapshot(),
+      rateLimit: rateLimiter.snapshot(),
+      roots: [...seenRoots],
+    },
+  }
+}
+
+/**
+ * Run one tool call under the server's policy: rate budget, deadline, metrics and audit line.
+ * Protocol errors (bad arguments) propagate to the JSON-RPC layer; everything else is a tool error.
+ */
+async function dispatchTool(name, rawArgs, config, token) {
+  if (!Object.hasOwn(ARG_SPECS, name)) {
+    throw new ProtocolError(-32602, `unknown tool: ${name}`, { available: Object.keys(ARG_SPECS) })
+  }
+
+  const budget = rateLimiter.take()
+  if (!budget.allowed) {
+    metrics.rateLimited += 1
+    throw new ToolError(ERROR_CODES.RATE_LIMITED, `call budget exhausted (${config.maxCallsPerMinute}/minute)`, {
+      hint: 'Wait for the budget to refill, or raise TGREP_MAX_CALLS_PER_MINUTE.',
+      retryAfterSeconds: budget.retryAfterSeconds,
+    })
+  }
+
+  const started = Date.now()
+  const requestConfig = configForRequest(config)
+  let outcome
+  try {
+    let structured
+    if (name === 'tgrep_search') {
+      structured = await withDeadline(executeSearch(rawArgs, token, requestConfig), config.toolTimeoutMs, 'tgrep_search')
+      outcome = { isError: false, text: renderSearch(structured), structured }
+    } else if (name === 'tgrep_index') {
+      structured = await withDeadline(executeIndex(rawArgs, token, requestConfig), config.toolTimeoutMs, 'tgrep_index')
+      outcome = structured.ok
+        ? { isError: false, text: renderIndex(structured), structured }
+        : toolErrorOutcome(new ToolError(ERROR_CODES.INDEX_FAILED, structured.error?.message ?? 'index build failed', { details: structured.error?.details }))
+    } else {
+      structured = await withDeadline(executeStatus(rawArgs, requestConfig), config.toolTimeoutMs, 'tgrep_status')
+      outcome = { isError: false, text: renderStatus(structured), structured }
+    }
+  } catch (error) {
+    if (error instanceof ProtocolError) {
+      recordToolCall(name, Date.now() - started, false)
+      audit({ tool: name, outcome: 'protocol_error', code: error.code, elapsedMs: Date.now() - started })
+      throw error
+    }
+    outcome = toolErrorOutcome(error)
+  }
+
+  const elapsedMs = Date.now() - started
+  recordToolCall(name, elapsedMs, outcome.isError !== true)
+  audit({
+    tool: name,
+    outcome: outcome.isError === true ? 'error' : 'ok',
+    code: outcome.structured?.error?.code ?? null,
+    backend: outcome.structured?.backend ?? null,
+    root: outcome.structured?.root ?? null,
+    total: outcome.structured?.total ?? null,
+    returned: outcome.structured?.returned ?? null,
+    elapsedMs,
+  })
+  return outcome
+}
+
+// ---------------------------------------------------------------------------
+// Protocol layer
+// ---------------------------------------------------------------------------
+
+const clientRequests = new Map() // id -> resolve, for requests this server sends to the client
+const inflight = new Map() // client request id -> cancellation token
+let serverRequestSeq = 0
+
+function write(message) {
+  try {
+    process.stdout.write(`${JSON.stringify(message)}\n`)
+  } catch (error) {
+    log(`failed to write a protocol frame: ${String(error?.message ?? error)}`)
+  }
+}
+
+function reply(id, result) {
+  write({ jsonrpc: '2.0', id, result })
+}
+
+function replyError(id, code, message, data) {
+  const error = { code, message }
+  if (data !== undefined) error.data = data
+  write({ jsonrpc: '2.0', id, error })
+}
+
+/** A server-initiated request. Clients that never declared the capability are never asked. */
+function sendClientRequest(method, params, timeoutMs) {
+  const id = `tgrep-${++serverRequestSeq}`
+  return new Promise((resolveRequest) => {
+    const timer = setTimeout(() => {
+      clientRequests.delete(id)
+      resolveRequest({ __timeout: true })
+    }, timeoutMs)
+    clientRequests.set(id, (message) => {
+      clearTimeout(timer)
+      resolveRequest(message)
+    })
+    write({ jsonrpc: '2.0', id, method, params })
+  })
+}
+
+async function refreshClientRoots() {
+  if (!clientSupportsRoots) return
+  const response = await sendClientRequest('roots/list', {}, 5000)
+  if (response.__timeout === true) {
+    log('roots/list timed out; keeping the current workspace roots', 'debug')
+    return
+  }
+  if (response.error !== undefined) {
+    log(`roots/list failed: ${JSON.stringify(response.error)}`, 'debug')
+    return
+  }
+  const roots = Array.isArray(response.result?.roots) ? response.result.roots : []
+  const paths = roots.map((entry) => uriToPath(entry?.uri)).filter((path) => path !== null)
+  if (paths.length > 0) {
+    clientRoots = dedupePaths(paths, CONFIG.platform)
+    log(`client workspace roots: ${clientRoots.join(', ')}`)
+  }
+}
+
+async function handleRequest(message) {
+  const { id, method, params } = message
+  switch (method) {
+    case 'initialize': {
+      const requested = params?.protocolVersion
+      MCP_PROTOCOL_VERSION = SUPPORTED_PROTOCOLS.includes(requested) ? requested : FALLBACK_PROTOCOL
+      clientInfo = params?.clientInfo ?? null
+      clientSupportsRoots = params?.capabilities?.roots !== undefined
+      reply(id, {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, title: 'tgrep code search', version: VERSION },
+        instructions: INSTRUCTIONS,
+      })
+      return
+    }
+    case 'ping':
+      reply(id, {})
+      return
+    case 'tools/list':
+      reply(id, { tools: TOOLS })
+      return
+    case 'tools/call': {
+      const name = params?.name
+      if (typeof name !== 'string' || name.length === 0) {
+        replyError(id, -32602, 'tools/call requires a tool name')
+        return
+      }
+      const token = createCancellationToken()
+      inflight.set(id, token)
+      try {
+        const outcome = await dispatchTool(name, params?.arguments ?? {}, CONFIG, token)
+        if (token.cancelled) return
+        const result = { content: [{ type: 'text', text: outcome.text }], isError: outcome.isError === true }
+        if (outcome.structured !== undefined) result.structuredContent = outcome.structured
+        reply(id, result)
+      } catch (error) {
+        if (token.cancelled) return
+        if (error instanceof ProtocolError) {
+          replyError(id, error.code, error.message, error.data)
+          return
+        }
+        const outcome = toolErrorOutcome(error)
+        reply(id, {
+          content: [{ type: 'text', text: outcome.text }],
+          isError: true,
+          structuredContent: outcome.structured,
+        })
+      } finally {
+        inflight.delete(id)
+      }
+      return
+    }
+    case 'resources/list':
+    case 'prompts/list':
+      replyError(id, -32601, `method not found: ${method}`)
+      return
+    default:
+      replyError(id, -32601, `method not found: ${method}`)
+  }
+}
+
+function handleNotification(message) {
+  switch (message.method) {
+    case 'notifications/initialized':
+      refreshClientRoots().catch((error) => log(`root refresh failed: ${String(error?.message ?? error)}`, 'debug'))
+      return
+    case 'notifications/cancelled': {
+      const target = message.params?.requestId
+      const token = inflight.get(target)
+      if (token !== undefined) {
+        log(`client cancelled request ${target}`, 'debug')
+        token.cancel()
+      }
+      return
+    }
+    case 'notifications/roots/list_changed':
+      refreshClientRoots().catch((error) => log(`root refresh failed: ${String(error?.message ?? error)}`, 'debug'))
+      return
+    default:
+      log(`ignoring notification ${String(message.method)}`, 'debug')
+  }
+}
+
+async function handleLine(line) {
+  let message
+  try {
+    message = JSON.parse(line)
+  } catch (error) {
+    log(`dropped unparseable frame: ${line.slice(0, 120)}`)
+    replyError(null, -32700, `parse error: ${String(error?.message ?? error)}`)
+    return
+  }
+  if (message === null || typeof message !== 'object' || Array.isArray(message)) {
+    replyError(null, -32600, 'invalid request: expected a JSON object')
+    return
+  }
+  // A response to a request this server sent: it has an id and no method.
+  if (message.method === undefined) {
+    const waiter = clientRequests.get(message.id)
+    if (waiter === undefined) {
+      log(`dropped unroutable response with id ${JSON.stringify(message.id)}`, 'debug')
+      return
+    }
+    clientRequests.delete(message.id)
+    waiter(message)
+    return
+  }
+  if (message.id === undefined || message.id === null) {
+    handleNotification(message)
+    return
+  }
+  if (message.jsonrpc !== undefined && message.jsonrpc !== '2.0') {
+    replyError(message.id, -32600, 'invalid request: jsonrpc must be "2.0"')
+    return
+  }
+  handleRequest(message).catch((error) => {
+    log(`request ${String(message.method)} failed: ${String(error?.message ?? error)}`)
+    replyError(message.id, -32603, String(error?.message ?? error))
+  })
+}
+
+function startServer() {
+  let buffer = ''
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk
+    if (buffer.length > MAX_FRAME_BYTES) {
+      log(`dropping ${buffer.length} bytes of oversized frame input`)
+      buffer = ''
+      return
+    }
+    let index
+    while ((index = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, index).trim()
+      buffer = buffer.slice(index + 1)
+      if (line.length === 0) continue
+      handleLine(line).catch((error) => log(`frame handling failed: ${String(error?.message ?? error)}`))
+    }
+  })
+
+  const shutdown = (code) => {
+    shutdownAll()
+    process.exit(code)
+  }
+  process.stdin.on('end', () => shutdown(0))
+  process.on('SIGINT', () => shutdown(0))
+  process.on('SIGTERM', () => shutdown(0))
+  process.on('exit', () => shutdownAll())
+
+  for (const issue of CONFIG.issues) log(`config: ${issue}`)
+  log(`ready — v${VERSION} bin=${CONFIG.bin.path} (${CONFIG.bin.source}) indexRoot=${CONFIG.indexRoot}`)
+  log(`defaultRoot=${CONFIG.defaultRoot} (${CONFIG.defaultRootSource}) allowedRoots=${CONFIG.allowed.allowAll ? '*' : CONFIG.allowed.roots.join(', ')} direct=${CONFIG.direct}`, 'debug')
+}
+
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+if (isMain) startServer()
+
+export {
+  buildConfig,
+  defaultIndexRoot,
+  resolveBin,
+  parseAllowedRoots,
+  dedupePaths,
+  indexDirFor,
+  isInside,
+  checkPathAllowed,
+  canonicalRootFor,
+  relativeScope,
+  displayPath,
+  validateArguments,
+  sanitizeText,
+  capMatches,
+  createSemaphore,
+  createRateLimiter,
+  createCircuitBreaker,
+  aggregateHealth,
+  percentile,
+  renderSearch,
+  envInt,
+  ERROR_CODES,
+  ToolError,
+  ProtocolError,
+  INSTRUCTIONS,
+  TOOLS,
+  CONFIG,
+  SEARCH_OUTPUT_SCHEMA,
+  INDEX_OUTPUT_SCHEMA,
+  STATUS_OUTPUT_SCHEMA,
+}