@visual-z/xeno 0.8.4 → 0.9.0

package/src/store/search.ts

@@ -1,728 +0,0 @@
-/**
- * Workspace search: grep, find, ls.
- *
- * The walk reuses buildFileIndex so ignore rules (.gitignore inside a Git
- * work tree, S.6 item 4), the walk cap, and the no-symlink rule stay one
- * implementation. Ripgrep / fd follow the same .gitignore rule, and search an
- * ignored target named explicitly, like the walk. They are used only when
- * they are already on PATH -- never downloaded -- because fetching a binary
- * at runtime is a supply-chain path the Isolation section of README.md
- * told the user they would not be taking.
- *
- * Both engines format the same way so two machines do not silently disagree.
- */
-
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { lstat, readdir, readFile } from "node:fs/promises";
-import { isAbsolute, join, relative, sep } from "node:path";
-import { Worker } from "node:worker_threads";
-import { assertNever } from "../core/exhaustive.ts";
-import { jsPatternFromRipgrep } from "../core/regex-dialect.ts";
-import { buildFileIndex, gitIgnored } from "./file-index.ts";
-import { DEFAULT_IGNORE } from "./workspace.ts";
-import { blobAddress } from "./blobs.ts";
-import { configDir } from "./config.ts";
-import { findRipgrep } from "./tool-binaries.ts";
-import { previewSearchObservation, type SearchObservation } from "../core/search-observation.ts";
-import { failureDiagnostic, failureFromError, READ_ATTEMPTED, NOT_STARTED } from "../core/tool-failure.ts";
-import type { ToolDiagnostic } from "../core/tool-contract.ts";
-import { COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
-
-/**
- * Match / entry cap. Assumed, not measured: enough for a model to read in
- * one result; past this it should refine the query. A silent cut would hide
- * how much evidence was dropped.
- */
-export const DEFAULT_MATCH_LIMIT = 100;
-
-/** Assumed, not measured: same order of magnitude as pi's find default. */
-export const DEFAULT_FIND_LIMIT = 1_000;
-
-/** Assumed, not measured: a directory listing larger than this needs a filter. */
-export const DEFAULT_LS_LIMIT = 500;
-
-/**
- * Assumed, not measured: a longer line belongs in `read`, not in a match
- * list. Cutting it without a cap would let one minified file blow the budget.
- */
-export const MAX_LINE_CHARS = 500;
-
-/**
- * Assumed, not measured: same ballpark as the tool-output cap in tools.ts.
- * Hitting it drops trailing matches and says how many.
- */
-export const MAX_OUTPUT_BYTES = 30_000;
-
-/**
- * Assumed, not measured: a 1 MB file is already past what a match snippet
- * can usefully show; ripgrep is told the same ceiling so the two engines
- * skip the same files.
- */
-export const MAX_FILE_BYTES = 1_000_000;
-
-/**
- * Per-file match ceiling. A linear scan of MAX_FILE_BYTES with a simple
- * pattern was measured at ~0.07ms/MB on bun 1.3; 100ms is assumed slack on
- * top of that. `(a+)+$` against 40 a's was measured at ~220ms here -- JSC
- * aborts the backtrack around there rather than hanging forever -- so a
- * ceiling above that would never fire on the card's catastrophic case, and
- * the agent would see "no matches" instead of a cutoff. The pattern comes
- * from the model, not a person: a hung tool_call has no result in the log.
- */
-export const MATCH_TIMEOUT_MS = 100;
-
-/** Assumed: an rg/fd process that runs longer than this is stuck. */
-export const PROCESS_TIMEOUT_MS = 30_000;
-/** Assumed execution budget, independent of display caps; reaching it makes coverage partial. */
-export const MAX_SEARCH_CAPTURE_BYTES = 32 * 1024 * 1024;
-
-export type SearchEngine = "auto" | "ripgrep" | "walk" | "fd";
-
-export interface SearchResult {
-  content: string;
-  ok: boolean;
-  observation?: SearchObservation;
-  diagnostic?: ToolDiagnostic;
-}
-
-export interface GrepOpts {
-  readonly root: string;
-  /** Absolute path, already confined to root. */
-  readonly path: string;
-  readonly pattern: string;
-  readonly glob?: string;
-  readonly limit?: number;
-  readonly engine?: "auto" | "ripgrep" | "walk";
-  readonly timeoutMs?: number;
-  readonly signal?: AbortSignal;
-  /** Trusted harness budgets, not model arguments. */
-  readonly maxCaptureBytes?: number;
-  readonly maxIndexEntries?: number;
-  /** Trusted admission for each POSIX workspace-relative resource, before content is read. */
-  readonly canRead?: (path: string) => Promise<boolean>;
-}
-
-export interface FindOpts {
-  readonly root: string;
-  readonly path: string;
-  readonly pattern: string;
-  readonly limit?: number;
-  readonly engine?: "auto" | "fd" | "walk";
-  readonly timeoutMs?: number;
-  readonly signal?: AbortSignal;
-  readonly maxCaptureBytes?: number;
-  readonly maxIndexEntries?: number;
-  readonly canRead?: (path: string) => Promise<boolean>;
-}
-
-export interface LsOpts {
-  readonly root: string;
-  readonly path: string;
-  readonly limit?: number;
-  readonly signal?: AbortSignal;
-  readonly canRead?: (path: string) => Promise<boolean>;
-}
-
-function observed(observation: SearchObservation, diagnostic?: ToolDiagnostic): SearchResult {
-  return { ok: diagnostic === undefined, content: previewSearchObservation(observation, "pending-archive", MAX_OUTPUT_BYTES, MAX_LINE_CHARS).text,
-    observation, ...(diagnostic ? { diagnostic } : {}) };
-}
-
-function searchFailure(code: ToolDiagnostic["code"], content: string): SearchResult {
-  return { ok: false, content, diagnostic: failureDiagnostic(code, content, NOT_STARTED) };
-}
-
-export interface MatchLine {
-  readonly path: string;
-  readonly line: number;
-  readonly text: string;
-}
-
-const MATCH_WORKER_SOURCE = `
-const { parentPort } = require("node:worker_threads");
-parentPort.on("message", (msg) => {
-  const { pattern, flags, lines } = msg;
-  try {
-    const re = new RegExp(pattern, flags);
-    const hits = [];
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      re.lastIndex = 0;
-      if (re.test(line)) hits.push({ line: i + 1, text: line });
-    }
-    parentPort.postMessage({ ok: true, hits });
-  } catch (err) {
-    parentPort.postMessage({
-      ok: false,
-      error: err instanceof Error ? err.message : String(err),
-    });
-  }
-});
-`;
-
-export function findOnPath(name: string): string | null {
-  const pathEnv = process.env["PATH"] ?? "";
-  const delim = process.platform === "win32" ? ";" : ":";
-  for (const dir of pathEnv.split(delim)) {
-    if (dir.length === 0) continue;
-    const candidate = join(dir, name);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-function posixRel(root: string, abs: string): string | null {
-  const rel = relative(root, abs);
-  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
-  return rel.split(sep).join("/");
-}
-
-function ignoredRel(rel: string): boolean {
-  if (rel.length === 0) return false;
-  const parts = rel.split("/");
-  return DEFAULT_IGNORE.some((name) => parts.includes(name));
-}
-
-/**
- * Convert a glob to a fully-anchored regexp. Assumed to cover the shapes
- * models actually type (basename wildcards and double-star path globs), not
- * the full gitignore grammar -- a missed edge is a missed file, not a hang.
- */
-export function globToRegExp(glob: string): RegExp {
-  let i = 0;
-  let out = "";
-  while (i < glob.length) {
-    if (glob.startsWith("**/", i)) {
-      out += "(?:.*/)?";
-      i += 3;
-      continue;
-    }
-    if (glob[i] === "*" && glob[i + 1] === "*") {
-      out += ".*";
-      i += 2;
-      continue;
-    }
-    const c = glob[i]!;
-    if (c === "*") out += "[^/]*";
-    else if (c === "?") out += "[^/]";
-    else if (".+^${}()|[]\\".includes(c)) out += `\\${c}`;
-    else out += c;
-    i += 1;
-  }
-  return new RegExp(`^${out}$`);
-}
-
-export function globMatches(glob: string, relPath: string): boolean {
-  const posix = relPath.split(sep).join("/");
-  const slash = posix.lastIndexOf("/");
-  const base = slash === -1 ? posix : posix.slice(slash + 1);
-  const re = globToRegExp(glob);
-  if (glob.includes("/")) return re.test(posix);
-  return re.test(base);
-}
-
-function splitLines(text: string): string[] {
-  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  if (normalized.length === 0) return [];
-  const trimmed = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
-  if (trimmed.length === 0) return [];
-  return trimmed.split("\n");
-}
-
-async function inspectTarget(
-  root: string,
-  abs: string,
-): Promise<{ kind: "file" | "dir"; rel: string } | { error: string; diagnostic: ToolDiagnostic }> {
-  const rel = posixRel(root, abs);
-  const refuse = (message: string) => ({ error: message, diagnostic: failureDiagnostic("permission_denied", message, NOT_STARTED) });
-  if (rel === null) return refuse(`path escapes the workspace root: ${abs}`);
-  if (ignoredRel(rel)) return refuse(`path is ignored: ${rel}`);
-
-  let st;
-  try {
-    let current = root;
-    for (const part of rel.split("/").slice(0, -1)) {
-      current = join(current, part);
-      if ((await lstat(current)).isSymbolicLink()) return refuse(`refusing to follow a symlink in path: ${rel || "."}`);
-    }
-    st = await lstat(abs);
-  } catch (error) {
-    return { error: `cannot inspect path: ${rel || "."}`, diagnostic: failureFromError(error, READ_ATTEMPTED) };
-  }
-  if (st.isSymbolicLink()) {
-    return refuse(`refusing to follow a symlink: ${rel || "."}`);
-  }
-  if (st.isDirectory()) return { kind: "dir", rel };
-  if (st.isFile()) return { kind: "file", rel };
-  const message = `not a file or directory: ${rel || "."}`;
-  return { error: message, diagnostic: failureDiagnostic("invalid_input", message, READ_ATTEMPTED) };
-}
-
-async function listedFiles(abs: string, rel: string, kind: "file" | "dir", options: Parameters<typeof buildFileIndex>[1] = {}) {
-  if (kind === "file") return { paths: ignoredRel(rel) ? [] : [rel], issues: [] };
-  const index = await buildFileIndex(abs, options);
-  return { paths: index.paths.map((p) => (rel.length === 0 ? p : `${rel}/${p}`)), issues: [...(index.issues ?? [])] };
-}
-
-/** Denied filenames cannot reappear in scan diagnostics or archived observations. */
-function policyIssues(issues: SearchObservation["scan"]["reasons"], canRead: GrepOpts["canRead"]): SearchObservation["scan"]["reasons"] {
-  return canRead ? issues.map(issue => ({ code: issue.code })) : [...issues];
-}
-async function resourceAdmitted(path: string, canRead: GrepOpts["canRead"], reasons: SearchObservation["scan"]["reasons"],
-  signal?: AbortSignal, deadline?: number): Promise<boolean> {
-  if (!canRead) return true;
-  let allowed: boolean | undefined = false, abort = () => {};
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const stopped = new Promise<undefined>(resolve => {
-    abort = () => resolve(undefined); signal?.addEventListener("abort", abort, { once: true });
-    if (deadline !== undefined) timer = setTimeout(abort, Math.max(0, deadline - performance.now()));
-    if (signal?.aborted) abort();
-  });
-  try { allowed = await Promise.race([Promise.resolve().then(() => canRead(path)).catch(() => false), stopped]); }
-  finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }
-  if (allowed === undefined || signal?.aborted || deadline !== undefined && performance.now() >= deadline) {
-    reasons.push({ code: signal?.aborted ? "cancelled" : "timeout" }); return false;
-  }
-  if (!allowed && !reasons.some(reason => reason.code === "permission_omitted")) reasons.push({ code: "permission_omitted" });
-  return allowed;
-}
-
-interface WorkerMatch {
-  readonly ok: boolean;
-  readonly hits?: ReadonlyArray<{ readonly line: number; readonly text: string }>;
-}
-
-class LineMatcher {
-  private worker: Worker | null = null;
-
-  private spawn(): Worker {
-    return new Worker(MATCH_WORKER_SOURCE, { eval: true });
-  }
-
-  async match(
-    pattern: string,
-    flags: string,
-    lines: string[],
-    budgetMs = MATCH_TIMEOUT_MS,
-    signal?: AbortSignal,
-  ): Promise<"timeout" | "invalid" | "cancelled" | MatchLine[]> {
-    if (signal?.aborted) return "cancelled";
-    if (this.worker === null) this.worker = this.spawn();
-    const worker = this.worker;
-    return await new Promise((resolve) => {
-      let settled = false;
-      const finish = (value: "timeout" | "invalid" | "cancelled" | MatchLine[]): void => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        worker.off("message", onMessage);
-        worker.off("error", onError);
-        signal?.removeEventListener("abort", abort);
-        resolve(value);
-      };
-      const abort = () => { void worker.terminate(); this.worker = null; finish("cancelled"); };
-      const timer = setTimeout(() => {
-        void worker.terminate();
-        this.worker = null;
-        finish("timeout");
-      }, Math.max(0, Math.min(MATCH_TIMEOUT_MS, budgetMs)));
-      const onMessage = (msg: WorkerMatch) => {
-        if (!msg.ok) {
-          finish("invalid");
-          return;
-        }
-        finish((msg.hits ?? []).map((h) => ({ path: "", line: h.line, text: h.text })));
-      };
-      const onError = () => {
-        void worker.terminate();
-        this.worker = null;
-        finish("invalid");
-      };
-      worker.on("message", onMessage);
-      worker.on("error", onError);
-      signal?.addEventListener("abort", abort, { once: true });
-      worker.postMessage({ pattern, flags, lines });
-    });
-  }
-
-  close(): void {
-    if (this.worker !== null) {
-      void this.worker.terminate();
-      this.worker = null;
-    }
-  }
-}
-
-function runCommand(
-  cmd: string,
-  args: readonly string[],
-  timeoutMs: number,
-  signal?: AbortSignal,
-  maxBytes = MAX_SEARCH_CAPTURE_BYTES,
-): Promise<{ stdout: string; raw: Uint8Array; rawErrors?: Uint8Array; stderr: string; exit: number | null; diagnostic?: ToolDiagnostic; stopped?: "timeout" | "cancelled" | "output_limit" }> {
-  if (signal?.aborted) return Promise.resolve({ stdout: "", raw: new Uint8Array(), stderr: "", exit: null, stopped: "cancelled" });
-  return new Promise((resolve) => {
-    const child = spawn(cmd, [...args], { stdio: ["ignore", "pipe", "pipe"], detached: true });
-    const stdout: Buffer[] = [], stderr: Buffer[] = [];
-    let size = 0, errorSize = 0, stopped: "timeout" | "cancelled" | "output_limit" | undefined;
-    let escalation: ReturnType<typeof setTimeout> | undefined;
-    const kill = (value: "SIGTERM" | "SIGKILL") => { try {
-      if (child.pid && process.platform !== "win32") process.kill(-child.pid, value); else child.kill(value);
-    } catch { /* the process group already exited */ } };
-    const stop = (reason: "timeout" | "cancelled" | "output_limit") => {
-      if (stopped) return; stopped = reason; kill("SIGTERM");
-      escalation = setTimeout(() => kill("SIGKILL"), COMMAND_TERMINATION_GRACE_MS);
-    };
-    const abort = () => stop("cancelled");
-    child.stdout.on("data", (chunk: Buffer) => {
-      const kept = chunk.subarray(0, Math.max(0, maxBytes - size));
-      if (kept.length) stdout.push(Buffer.from(kept)); size += kept.length;
-      if (kept.length < chunk.length) stop("output_limit");
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      // Errors are bounded too; stderr is explanatory, never a source of success or completeness.
-      const kept = chunk.subarray(0, Math.max(0, 65536 - errorSize));
-      if (kept.length) stderr.push(Buffer.from(kept)); errorSize += kept.length;
-      if (kept.length < chunk.length) stop("output_limit");
-    });
-    const timer = setTimeout(() => stop("timeout"), timeoutMs);
-    signal?.addEventListener("abort", abort, { once: true });
-    if (signal?.aborted) abort();
-    child.on("close", (code) => {
-      clearTimeout(timer); clearTimeout(escalation); signal?.removeEventListener("abort", abort);
-      if (stopped) kill("SIGKILL");
-      const raw = Buffer.concat(stdout);
-      const rawErrors = Buffer.concat(stderr);
-      resolve({ stdout: raw.toString("utf8"), raw, rawErrors, stderr: rawErrors.toString("utf8"), exit: code, ...(stopped ? { stopped } : {}) });
-    });
-    child.on("error", (err) => {
-      const raw = Buffer.concat(stdout);
-      clearTimeout(timer); clearTimeout(escalation); signal?.removeEventListener("abort", abort);
-      const facts = child.pid ? READ_ATTEMPTED : NOT_STARTED;
-      const os = (err as { code?: string }).code;
-      const diagnostic = !child.pid && (os === "ENOENT" || os === "ENOTDIR") ? failureDiagnostic("environment_missing", err.message, facts) : failureFromError(err, facts);
-      resolve({ stdout: raw.toString("utf8"), raw, stderr: err.message, exit: null, diagnostic, ...(stopped ? { stopped } : {}) });
-    });
-  });
-}
-
-function rgIgnoreArgs(): string[] {
-  const args: string[] = [];
-  for (const name of DEFAULT_IGNORE) {
-    args.push("--glob", `!${name}`);
-    args.push("--glob", `!${name}/**`);
-    args.push("--glob", `!**/${name}`);
-    args.push("--glob", `!**/${name}/**`);
-  }
-  return args;
-}
-
-function parseRgJson(root: string, stdout: string): MatchLine[] {
-  const hits: MatchLine[] = [];
-  for (const raw of stdout.split("\n")) {
-    if (raw.trim().length === 0) continue;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      continue;
-    }
-    if (typeof parsed !== "object" || parsed === null) continue;
-    const rec = parsed as Record<string, unknown>;
-    if (rec["type"] !== "match") continue;
-    const data = rec["data"];
-    if (typeof data !== "object" || data === null) continue;
-    const d = data as Record<string, unknown>;
-    const pathObj = d["path"];
-    const pathText =
-      typeof pathObj === "object" && pathObj !== null
-        ? rgText(pathObj as Record<string, unknown>)
-        : "";
-    const lineNumber = d["line_number"];
-    const linesObj = d["lines"];
-    const lineText =
-      typeof linesObj === "object" && linesObj !== null
-        ? rgText(linesObj as Record<string, unknown>)
-        : "";
-    if (pathText.length === 0 || typeof lineNumber !== "number") continue;
-    const rel = posixRel(root, pathText) ?? posixRel(root, join(root, pathText));
-    if (rel === null || ignoredRel(rel)) continue;
-    hits.push({
-      path: rel,
-      line: lineNumber,
-      text: lineText.replace(/\n$/, "").replace(/\r/g, ""),
-    });
-  }
-  return hits;
-}
-
-function rgText(value: Record<string, unknown>): string {
-  return typeof value["text"] === "string" ? value["text"] : typeof value["bytes"] === "string" ? Buffer.from(value["bytes"], "base64").toString("utf8") : "";
-}
-
-async function grepRipgrep(opts: GrepOpts, abs: string, limit: number): Promise<SearchResult | null> {
-  const rg = findRipgrep(configDir());
-  if (rg === null) return null;
-  const args = [
-    "--json",
-    "--color=never",
-    "--hidden",
-    "--no-follow",
-    ...(await gitIgnored(abs, opts.signal) ? ["--no-ignore"] : []),
-    "--max-filesize",
-    String(MAX_FILE_BYTES),
-    ...rgIgnoreArgs(),
-  ];
-  if (opts.glob !== undefined) args.push("--glob", opts.glob);
-  args.push("--", opts.pattern, abs);
-  const ran = await runCommand(rg, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS, opts.signal, opts.maxCaptureBytes);
-  const hits = parseRgJson(opts.root, ran.stdout);
-  hits.sort(compareMatch);
-  const failed = ran.stopped !== undefined || ran.exit !== 0 && ran.exit !== 1;
-  const reason = ran.stopped ?? "engine_error";
-  const observation: SearchObservation = { engine: "ripgrep", raw: ran.raw, ...(ran.rawErrors ? { rawErrors: ran.rawErrors } : {}), rows: hits.map(hit => ({ prefix: `${hit.path}:${hit.line}: `, text: hit.text })),
-    sources: [], limit, empty: "No matches found", scan: { status: failed ? "partial" : "unknown", examined_files: null, source_versions: "unknown",
-      reasons: [{ code: "engine_does_not_report_all_skipped_files" }, ...(failed ? [{ code: reason }] : [])] } };
-  return observed(observation, ran.diagnostic ?? (failed ? failureDiagnostic(reason === "timeout" || reason === "cancelled" ? reason : "execution_failed",
-    ran.stderr.trim() || `ripgrep ${reason}; exit ${ran.exit ?? "unknown"}`, READ_ATTEMPTED) : undefined));
-}
-
-function compareMatch(a: MatchLine, b: MatchLine): number {
-  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
-  return a.line - b.line;
-}
-
-async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel: string, limit: number): Promise<SearchResult> {
-  const pattern = jsPatternFromRipgrep(opts.pattern);
-  try {
-    new RegExp(pattern);
-  } catch (err) {
-    return searchFailure("invalid_input", `invalid regex: ${(err as Error).message}`);
-  }
-
-  const deadline = performance.now() + (opts.timeoutMs ?? PROCESS_TIMEOUT_MS);
-  const files = await listedFiles(abs, rel, kind, { deadline, ...(opts.signal ? { signal: opts.signal } : {}),
-    ...(opts.maxIndexEntries === undefined ? {} : { maxEntries: opts.maxIndexEntries }) });
-  const glob = opts.glob;
-  const filtered = glob === undefined ? files.paths : files.paths.filter((p) => globMatches(glob, p));
-  const matcher = new LineMatcher();
-  const hits: MatchLine[] = [];
-  const reasons: SearchObservation["scan"]["reasons"] = policyIssues(files.issues, opts.canRead);
-  const sources: SearchObservation["sources"] = [];
-  let examined = 0, capturedBytes = 0;
-  const budget = Math.min(opts.maxCaptureBytes ?? MAX_SEARCH_CAPTURE_BYTES, MAX_SEARCH_CAPTURE_BYTES);
-  try {
-    for (const fileRel of filtered) {
-      if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
-      if (ignoredRel(fileRel)) continue;
-      if (!await resourceAdmitted(fileRel, opts.canRead, reasons, opts.signal, deadline)) continue;
-      const fileAbs = join(opts.root, fileRel);
-      let st;
-      try {
-        st = await lstat(fileAbs);
-      } catch {
-        reasons.push({ code: "unreadable_file", path: fileRel });
-        continue;
-      }
-      if (st.isSymbolicLink() || !st.isFile()) { reasons.push({ code: "changed_file_type", path: fileRel }); continue; }
-      if (st.size > MAX_FILE_BYTES) { reasons.push({ code: "file_size_limit", path: fileRel }); continue; }
-      let text: string;
-      try {
-        const raw = await readFile(fileAbs);
-        if (raw.length > MAX_FILE_BYTES) { reasons.push({ code: "file_size_limit", path: fileRel }); continue; }
-        text = new TextDecoder("utf-8", { fatal: true }).decode(raw);
-        sources.push({ path: fileRel, sha256: blobAddress(raw) }); examined++;
-      } catch {
-        reasons.push({ code: "unreadable_or_non_utf8_file", path: fileRel });
-        continue;
-      }
-      if (text.includes("\0")) { reasons.push({ code: "binary_file", path: fileRel }); continue; }
-      const lines = splitLines(text);
-      // Reserve the worst-case formatted hits before matching, never discard already observed hits.
-      const reservation = Buffer.byteLength(text) + lines.length * (Buffer.byteLength(fileRel) + String(MAX_FILE_BYTES).length + 3);
-      if (capturedBytes + reservation > budget) { reasons.push({ code: "capture_budget", path: fileRel }); break; }
-      const matched = await matcher.match(pattern, "", lines, deadline - performance.now(), opts.signal);
-      if (matched === "cancelled") { reasons.push({ code: "cancelled", path: fileRel }); break; }
-      if (matched === "timeout") {
-        reasons.push({ code: "match_timeout", path: fileRel });
-        continue;
-      }
-      if (matched === "invalid") {
-        reasons.push({ code: "matcher_failed", path: fileRel }); break;
-      }
-      for (const hit of matched) {
-        hits.push({ path: fileRel, line: hit.line, text: hit.text });
-        capturedBytes += Buffer.byteLength(`${fileRel}:${hit.line}: ${hit.text}\n`);
-      }
-    }
-  } finally {
-    matcher.close();
-  }
-
-  hits.sort(compareMatch);
-  const stopped = reasons.find(reason => ["timeout", "cancelled"].includes(reason.code));
-  return observed({ engine: "walk", rows: hits.map(hit => ({ prefix: `${hit.path}:${hit.line}: `, text: hit.text })), sources, limit, empty: "No matches found",
-    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: examined, source_versions: "recorded" } },
-    stopped ? failureDiagnostic(stopped.code === "cancelled" ? "cancelled" : "timeout", `search ${stopped.code}`, READ_ATTEMPTED) : undefined);
-}
-
-export async function grep(opts: GrepOpts): Promise<SearchResult> {
-  const pattern = opts.pattern;
-  if (pattern.length === 0) return searchFailure("invalid_input", "grep needs a pattern");
-
-  const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
-
-  const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_MATCH_LIMIT;
-  // External search captures bytes before the runtime can inspect each
-  // resource. A policy callback therefore always uses the admitted walk.
-  const engine = opts.canRead ? "walk" : opts.engine ?? "auto";
-
-  switch (engine) {
-    case "walk":
-      return grepWalk(opts, opts.path, target.kind, target.rel, limit);
-    case "ripgrep": {
-      const got = await grepRipgrep(opts, opts.path, limit);
-      if (got === null) return searchFailure("environment_missing", "ripgrep is not on PATH or in xeno's bin directory");
-      return got;
-    }
-    case "auto": {
-      if (findRipgrep(configDir()) !== null) {
-        const got = await grepRipgrep(opts, opts.path, limit);
-        if (got !== null) return got;
-      }
-      return grepWalk(opts, opts.path, target.kind, target.rel, limit);
-    }
-    default:
-      return assertNever(engine, "grep");
-  }
-}
-
-function fdExcludeArgs(): string[] {
-  const args: string[] = [];
-  for (const name of DEFAULT_IGNORE) args.push("--exclude", name);
-  return args;
-}
-
-async function findFd(opts: FindOpts, abs: string, limit: number): Promise<SearchResult | null> {
-  const fd = findOnPath("fd");
-  if (fd === null) return null;
-  const args = [
-    "--glob",
-    "--color=never",
-    "--hidden",
-    ...(await gitIgnored(abs, opts.signal) ? ["--no-ignore"] : []),
-    "--absolute-path",
-    "--print0",
-    ...fdExcludeArgs(),
-  ];
-  let pattern = opts.pattern;
-  if (pattern.includes("/")) {
-    args.push("--full-path");
-    if (!pattern.startsWith("**/") && pattern !== "**") pattern = `**/${pattern}`;
-  }
-  args.push("--", pattern, abs);
-  const ran = await runCommand(fd, args, opts.timeoutMs ?? PROCESS_TIMEOUT_MS, opts.signal, opts.maxCaptureBytes);
-  const paths: string[] = [];
-  // A partial final record is not a path. NUL preserves spaces and newlines in real filenames.
-  for (const line of ran.stdout.split("\0").slice(0, -1)) {
-    if (line.length === 0) continue;
-    const rel = posixRel(opts.root, line);
-    if (rel === null || ignoredRel(rel)) continue;
-    paths.push(rel);
-  }
-  paths.sort((a, b) => (a < b ? -1 : 1));
-  const failed = ran.stopped !== undefined || ran.exit !== 0;
-  const reason = ran.stopped ?? "engine_error";
-  return observed({ engine: "fd", raw: ran.raw, ...(ran.rawErrors ? { rawErrors: ran.rawErrors } : {}), rows: paths.map(text => ({ prefix: "", text })), limit, empty: "No files found matching pattern", sources: [],
-    scan: { status: failed ? "partial" : "unknown", examined_files: null, source_versions: "unknown",
-      reasons: [{ code: "engine_does_not_report_all_skipped_files" }, ...(failed ? [{ code: reason }] : [])] } },
-    ran.diagnostic ?? (failed ? failureDiagnostic(reason === "timeout" || reason === "cancelled" ? reason : "execution_failed",
-      ran.stderr.trim() || `fd ${reason}; exit ${ran.exit ?? "unknown"}`, READ_ATTEMPTED) : undefined));
-}
-
-async function findWalk(opts: FindOpts, abs: string, kind: "file" | "dir", rel: string, limit: number): Promise<SearchResult> {
-  const deadline = performance.now() + (opts.timeoutMs ?? PROCESS_TIMEOUT_MS);
-  const files = await listedFiles(abs, rel, kind, { deadline,
-    ...(opts.signal ? { signal: opts.signal } : {}), ...(opts.maxIndexEntries === undefined ? {} : { maxEntries: opts.maxIndexEntries }) });
-  const reasons = policyIssues(files.issues, opts.canRead), paths: string[] = [];
-  for (const path of files.paths) {
-    if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
-    if (!ignoredRel(path) && globMatches(opts.pattern, path) && await resourceAdmitted(path, opts.canRead, reasons, opts.signal, deadline)) paths.push(path);
-  }
-  paths.sort((a, b) => (a < b ? -1 : 1));
-  const stopped = reasons.find(reason => ["timeout", "cancelled"].includes(reason.code));
-  return observed({ engine: "walk", rows: paths.map(text => ({ prefix: "", text })), sources: [], limit, empty: "No files found matching pattern",
-    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: files.paths.length, source_versions: "unknown" } },
-    stopped ? failureDiagnostic(stopped.code === "cancelled" ? "cancelled" : "timeout", `search ${stopped.code}`, READ_ATTEMPTED) : undefined);
-}
-
-export async function find(opts: FindOpts): Promise<SearchResult> {
-  if (opts.pattern.length === 0) return searchFailure("invalid_input", "find needs a pattern");
-  const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
-  const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_FIND_LIMIT;
-  const engine = opts.canRead ? "walk" : opts.engine ?? "auto";
-  switch (engine) {
-    case "walk":
-      return findWalk(opts, opts.path, target.kind, target.rel, limit);
-    case "fd": {
-      const got = await findFd(opts, opts.path, limit);
-      if (got === null) return searchFailure("environment_missing", "fd is not on PATH");
-      return got;
-    }
-    case "auto": {
-      if (findOnPath("fd") !== null) {
-        const got = await findFd(opts, opts.path, limit);
-        if (got !== null) return got;
-      }
-      return findWalk(opts, opts.path, target.kind, target.rel, limit);
-    }
-    default:
-      return assertNever(engine, "find");
-  }
-}
-
-export async function ls(opts: LsOpts): Promise<SearchResult> {
-  if (opts.signal?.aborted) return searchFailure("cancelled", "directory listing cancelled");
-  const target = await inspectTarget(opts.root, opts.path);
-  if ("error" in target) return { content: target.error, ok: false, diagnostic: target.diagnostic };
-  if (target.kind !== "dir") return searchFailure("invalid_input", `not a directory: ${target.rel || "."}`);
-
-  let entries;
-  try {
-    entries = await readdir(opts.path, { withFileTypes: true });
-  } catch (err) {
-    return { content: `cannot list ${target.rel || "."}: ${(err as Error).message}`, ok: false, diagnostic: failureFromError(err, READ_ATTEMPTED) };
-  }
-
-  const names: string[] = [], reasons: SearchObservation["scan"]["reasons"] = [];
-  const deadline = performance.now() + PROCESS_TIMEOUT_MS;
-  for (const entry of entries) {
-    if (DEFAULT_IGNORE.includes(entry.name)) continue;
-    const childRel = target.rel.length === 0 ? entry.name : `${target.rel}/${entry.name}`;
-    if (ignoredRel(childRel)) continue;
-    if (opts.signal?.aborted || performance.now() >= deadline) { reasons.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); break; }
-    if (!await resourceAdmitted(childRel, opts.canRead, reasons, opts.signal, deadline)) continue;
-    // Do not follow: a symlink is listed as a name, never as the directory
-    // it points at, so a link to / cannot walk the disk.
-    if (entry.isSymbolicLink()) {
-      names.push(entry.name);
-      continue;
-    }
-    if (entry.isDirectory()) names.push(`${entry.name}/`);
-    else if (entry.isFile()) names.push(entry.name);
-  }
-  names.sort((a, b) => {
-    const al = a.toLowerCase();
-    const bl = b.toLowerCase();
-    if (al === bl) return a < b ? -1 : 1;
-    return al < bl ? -1 : 1;
-  });
-
-  const limit = opts.limit !== undefined && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_LS_LIMIT;
-  return observed({ engine: "directory", rows: names.map(text => ({ prefix: "", text })), sources: [], limit, empty: "(empty directory)",
-    scan: { status: reasons.length ? "partial" : "complete", reasons, examined_files: names.length, source_versions: "unknown" } },
-    reasons.some(reason => reason.code === "cancelled" || reason.code === "timeout") ? failureDiagnostic(opts.signal?.aborted ? "cancelled" : "timeout", "directory listing stopped", READ_ATTEMPTED) : undefined);
-}