mcp-castor 2026.3.0

package/src/harness/services/sandbox_fs.js

@@ -0,0 +1,1238 @@
+/**
+ * Sandboxed Filesystem Service.
+ *
+ * Provides sandboxed file operations (read, write, edit, patch, list, search)
+ * confined to a workspace root.
+ *
+ * - Enforces a strict ignore policy (auto-skips .venv, node_modules, .git,
+ *   __pycache__, and other build/vendor directories).
+ * - Normalizes paths across Windows and WSL mounts.
+ * - Performs AST-validated file edits and bounded slice reads.
+ * - Runs indexed searches (git grep) with a safe fallback walk.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { IS_WINDOWS } from "../../config.js";
+import { normalizeWorkspacePath, toWindowsPath, toPosixWslPath, canonicalizePath } from "../../wsl_bridge.js";
+import { fileTypeFromBuffer, reasonableDetectionSizeInBytes } from "file-type";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Raised when `git grep` fails with a fatal error (any non-zero exit code
+ * other than 1) inside a git repository. Exit code 1 means "no matches" and
+ * is a valid empty result, not an error.
+ *
+ * @extends Error
+ * @property {number|null} code The git process exit code (e.g. 128).
+ * @property {string} stderr The trimmed stderr output from git.
+ */
+export class GitGrepError extends Error {
+  constructor(message, { code = null, stderr = "" } = {}) {
+    super(message);
+    this.name = "GitGrepError";
+    this.code = code;
+    this.stderr = stderr;
+  }
+}
+
+/**
+ * Raised when a `patch` payload to `applyPatch()` exceeds `MAX_PATCH_SIZE`.
+ * The check runs before any `git` subprocess is spawned.
+ *
+ * @extends Error
+ * @property {number} size The actual byte length of the patch payload.
+ * @property {number} limit The maximum allowed byte length.
+ */
+export class PatchTooLargeError extends Error {
+  constructor(message, { size = 0, limit = 0 } = {}) {
+    super(message);
+    this.name = "PatchTooLargeError";
+    this.size = size;
+    this.limit = limit;
+  }
+}
+
+/**
+ * Raised when in-memory syntax validation fails before writing an edit to disk.
+ * Preserves disk pristine state (no bytes modified).
+ */
+export class SyntaxValidationError extends Error {
+  constructor(filePath, reason) {
+    super(
+      `SyntaxValidationError: In-memory syntax validation failed for '${filePath}': ${reason}. File was kept pristine (no changes written to disk).`
+    );
+    this.name = "SyntaxValidationError";
+    this.file = filePath;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Raised when the `git apply` subprocess is killed by a timeout or signal
+ * rather than failing on patch content. Node reports a timeout as
+ * `err.code === "ETIMEDOUT"` and `err.signal === "SIGTERM"` (and
+ * `err.killed === true` on some platforms); this error is emitted for any of
+ * those. It is distinct from the generic `GitApplyError` so a hang/timeout is
+ * distinguishable from a normal "patch does not apply" failure.
+ *
+ * @extends Error
+ * @property {string|null} signal The termination signal (e.g. "SIGTERM").
+ * @property {string} stderr The trimmed stderr output from git, if any.
+ */
+export class GitApplyTimeoutError extends Error {
+  constructor(message, { signal = null, stderr = "" } = {}) {
+    super(message);
+    this.name = "GitApplyTimeoutError";
+    this.signal = signal;
+    this.stderr = stderr;
+  }
+}
+
+/**
+ * Raised by `readFile()` when the target is a binary file (detected by
+ * extension denylist or magic bytes). A text-only model must not ingest
+ * binary content; the error names the file, the detected type, and the
+ * instruction to extract text via a format-appropriate tool instead.
+ *
+ * @extends Error
+ * @property {string} file The resolved file path that was rejected.
+ * @property {string} detectedType The detected type label (mime/ext or the
+ *   denylist reason).
+ * @property {string} reason Why the file was classified as binary.
+ */
+export class BinaryFileError extends Error {
+  constructor(message, { file = "", detectedType = "binary", reason = "" } = {}) {
+    super(message);
+    this.name = "BinaryFileError";
+    this.file = file;
+    this.detectedType = detectedType;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Returns true for `.env` and `.env.*` files (e.g. `.env.local`,
+ * `.env.production`). These are excluded from the fallback directory walk to
+ * prevent secret ingestion when `git grep` is unavailable.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isEnvFile(name) {
+  return name === ".env" || name.startsWith(".env.");
+}
+
+/**
+ * Extension denylist used as a fast-path binary pre-filter. A cheap,
+ * synchronous check that catches common binary formats by extension before
+ * any bytes are read. It is not the sole gate: `detectBinaryType()` performs
+ * an authoritative magic-byte check (via the `file-type` library) on the
+ * first KB of the file, which catches extensionless binaries. The set is a
+ * denylist, not an allowlist — an unknown extension is not treated as
+ * binary here.
+ * @type {Set<string>}
+ */
+const BINARY_EXTENSIONS = new Set([
+  "pdf",
+  "png",
+  "jpg",
+  "jpeg",
+  "webp",
+  "gif",
+  "ico",
+  "zip",
+  "gz",
+  "tar",
+  "7z",
+  "bz2",
+  "xz",
+  "wasm",
+  "exe",
+  "dll",
+  "so",
+  "dylib",
+  "bin",
+  "mp3",
+  "mp4",
+  "avi",
+  "mov",
+  "wav",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "sqlite",
+  "db",
+]);
+
+/**
+ * Returns true when `name`'s extension (case-insensitive) is in the binary
+ * denylist. A name with no extension returns false (the magic-byte check is
+ * the authoritative gate for those).
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isBinaryExtension(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0 || dot === name.length - 1) return false;
+  const ext = name.slice(dot + 1).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+
+/**
+ * Authoritative binary detection via magic bytes, using the `file-type`
+ * library. Reads at most the first `reasonableDetectionSizeInBytes` (4100)
+ * bytes of the file and returns the detected `{ ext, mime }` descriptor, or
+ * `null` when the bytes do not match any known binary signature (i.e. the
+ * file is plausibly text).
+ *
+ * @param {string} filePath
+ * @returns {Promise<{ext:string,mime:string}|null>}
+ */
+async function detectBinaryType(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, reasonableDetectionSizeInBytes);
+    if (len === 0) return null; // empty file is not a binary
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, 0);
+    return await fileTypeFromBuffer(buf);
+  } catch {
+    // Unreadable / vanished file: treat as non-binary here; the caller's own
+    // read will surface the real I/O error.
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // best-effort close
+      }
+    }
+  }
+}
+
+/**
+ * Combined binary gate. Returns a human-readable reason string when the file
+ * is binary, or `null` when it is plausibly text.
+ *
+ * Order of checks:
+ *   1. Extension denylist fast-path (cheap, synchronous).
+ *   2. Magic-byte check via `file-type` on the first KB (authoritative;
+ *      catches extensionless binaries).
+ *
+ * @param {string} filePath
+ * @returns {Promise<string|null>}
+ */
+async function classifyBinary(filePath) {
+  if (isBinaryExtension(path.basename(filePath))) {
+    return `extension '${path.basename(filePath)}' is a known binary type`;
+  }
+  const detected = await detectBinaryType(filePath);
+  if (detected) {
+    return `magic bytes identify it as ${detected.mime} (extension '${detected.ext}')`;
+  }
+  return null;
+}
+
+/**
+ * Classifies the line-ending style of a string.
+ *
+ * Returns:
+ * - "crlf"  -> contains CRLF and no bare LF
+ * - "lf"    -> contains bare LF and no CRLF
+ * - "mixed" -> contains both CRLF and bare LF
+ * - null    -> contains no line endings at all
+ *
+ * Note: `\n` is a substring of `\r\n`, so a bare-LF check must first strip
+ * all CRLF sequences to avoid miscounting.
+ * @param {string} text
+ * @returns {"crlf"|"lf"|"mixed"|null}
+ */
+function lineEndingStyle(text) {
+  const hasCRLF = text.includes("\r\n");
+  const hasBareLF = text.replace(/\r\n/g, "").includes("\n");
+  if (hasCRLF && hasBareLF) return "mixed";
+  if (hasCRLF) return "crlf";
+  if (hasBareLF) return "lf";
+  return null;
+}
+
+/**
+ * Normalizes a string's line endings to a target style.
+ * - "crlf" -> every line ending becomes CRLF
+ * - "lf"   -> every CRLF becomes LF
+ * - "mixed" or null -> left unchanged (no single style to normalize to)
+ * @param {string} text
+ * @param {"crlf"|"lf"|"mixed"|null} style
+ * @returns {string}
+ */
+function normalizeLineEndings(text, style) {
+  if (style === "crlf") return text.replace(/\r?\n/g, "\r\n");
+  if (style === "lf") return text.replace(/\r\n/g, "\n");
+  return text;
+}
+
+export const DEFAULT_IGNORED_DIRS = new Set([
+  ".venv",
+  "venv",
+  "node_modules",
+  ".git",
+  "__pycache__",
+  "target",
+  "dist",
+  "build",
+  "vendor",
+  ".idea",
+  ".vscode",
+]);
+
+/**
+ * Maximum byte length of a `patch` payload accepted by `applyPatch()`.
+ * Enforced before spawning `git` (see `PatchTooLargeError`). Bounds memory
+ * and the child-process input pipe for pathological payloads.
+ * - Unit: bytes
+ * - Default: 2097152 (2 MB)
+ * - Override: None
+ * @type {number}
+ */
+export const MAX_PATCH_SIZE = 2 * 1024 * 1024; // 2 MB
+
+let _sharedAstService = null;
+async function getSharedAstService() {
+  if (!_sharedAstService) {
+    const { AstService } = await import("./ast_service.js");
+    _sharedAstService = new AstService();
+  }
+  return _sharedAstService;
+}
+
+export class SandboxFsService {
+  constructor(options = {}) {
+    // Canonicalize the sandbox root through the OS symlink/junction resolution
+    // layer so a junction/symlink cwd is stored as its real path. Containment
+    // checks then compare realpath(target) against a real root, eliminating
+    // false SymlinkEscapeError/PathEscapeError while still catching real
+    // escapes.
+    const rawRoot = options.root ? normalizeWorkspacePath(options.root) : process.cwd();
+    this.root = canonicalizePath(rawRoot);
+    this.ignoredDirs = new Set([...DEFAULT_IGNORED_DIRS, ...(options.ignoredDirs || [])]);
+    // Timeout for the `git apply` subprocess in `applyPatch()`. Defaults to
+    // 15s; overridable (e.g. by tests) to exercise the timeout path.
+    this.gitApplyTimeoutMs =
+      typeof options.gitApplyTimeoutMs === "number" && options.gitApplyTimeoutMs > 0
+        ? options.gitApplyTimeoutMs
+        : 15_000;
+    this._getAst = options.getAst || null;
+    // Adaptive read-size governor. `null` = ungoverned (the default 64KB cap
+    // applies). When the runner arms the governor (context high-watermark), it
+    // calls setReadGovernor(maxBytes) with a lower cap (16KB). The governor
+    // only ever lowers the effective read cap — it never raises it above the
+    // caller's max_bytes. This is per-session state: the SandboxFsService is
+    // instantiated fresh per run() (see sandboxFsPlugin), so the governor
+    // cannot leak across tasks.
+    this.readGovernorMaxBytes = null;
+  }
+
+  /**
+   * Arm (or disarm) the adaptive read-size governor for this session.
+   *
+   * @param {number|null} maxBytes The governed read cap in bytes. When a
+   *   positive number, subsequent read_file calls are capped at this size
+   *   (only ever lowering the effective cap, never raising it above the
+   *   caller's max_bytes). When null/undefined, the governor is disarmed and
+   *   the default 64KB cap applies.
+   */
+  setReadGovernor(maxBytes) {
+    this.readGovernorMaxBytes =
+      typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : null;
+  }
+
+  /**
+   * Resolves and verifies that a target path is safely within allowed boundaries.
+   * @param {string} inputPath
+   * @returns {string} Normalized absolute path
+   */
+  resolvePath(inputPath) {
+    if (!inputPath) return this.root;
+    if (typeof inputPath !== "string") {
+      throw new Error("InvalidPathError: Path must be a string");
+    }
+    if (inputPath.includes("\0")) {
+      throw new Error("NullByteError: Path contains prohibited null byte character");
+    }
+
+    let p = inputPath.trim();
+    const baseName = path.basename(p.replace(/\\/g, "/")).toUpperCase();
+    const reserved = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\..*)?$/;
+    if (reserved.test(baseName)) {
+      throw new Error(`DeviceNameError: Prohibited access to Windows reserved device '${baseName}'`);
+    }
+
+    if (IS_WINDOWS) {
+      p = toWindowsPath(p);
+      if (!path.isAbsolute(p)) {
+        p = path.resolve(this.root, p);
+      }
+    } else {
+      p = toPosixWslPath(p);
+      if (!path.isAbsolute(p)) {
+        p = path.resolve(this.root, p);
+      }
+    }
+    const normalizedTarget = path.normalize(p);
+    const normalizedRoot = path.normalize(this.root);
+
+    // Canonicalize both sides of the containment comparison through the OS
+    // symlink/junction resolution layer. This ensures a junction-form target
+    // is compared against the real root in the same "real" path space,
+    // eliminating false PathEscapeError/SymlinkEscapeError. Real escapes
+    // (../outside, symlink-to-outside) are still caught because their
+    // realpath lands outside the real root.
+    const realTarget = canonicalizePath(normalizedTarget);
+    const realRoot = canonicalizePath(normalizedRoot);
+    const rel = path.relative(realRoot, realTarget);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+      throw new Error(`PathEscapeError: Access denied. Path '${inputPath}' escapes sandbox root '${this.root}'`);
+    }
+
+    // Symlink escape verification (both sides are now in real-path space)
+    this.verifySymlinkContainment(realTarget, realRoot);
+
+    // Return the ORIGINAL normalized path (not the canonical one) so that
+    // downstream path labels stay consistent with the path the caller passed
+    // in. The containment decision above was made in canonical space, which
+    // is what matters for security; the returned label is used for I/O and
+    // reporting (both the junction and real forms address the same file).
+    return normalizedTarget;
+  }
+
+  verifySymlinkContainment(targetPath, rootPath) {
+    try {
+      if (fs.existsSync(targetPath)) {
+        const real = fs.realpathSync(targetPath);
+        const relReal = path.relative(rootPath, path.normalize(real));
+        if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+          throw new Error(`SymlinkEscapeError: Real path '${real}' escapes sandbox root '${rootPath}'`);
+        }
+      } else {
+        let parent = path.dirname(targetPath);
+        while (parent && parent !== path.dirname(parent)) {
+          if (fs.existsSync(parent)) {
+            const realParent = fs.realpathSync(parent);
+            const relReal = path.relative(rootPath, path.normalize(realParent));
+            if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+              throw new Error(`SymlinkEscapeError: Parent directory '${parent}' resolves to '${realParent}' escaping root '${rootPath}'`);
+            }
+            break;
+          }
+          parent = path.dirname(parent);
+        }
+      }
+    } catch (err) {
+      if (err.message.startsWith("SymlinkEscapeError")) throw err;
+    }
+  }
+
+  /**
+   * Reads a slice of a file with line numbers.
+   */
+  async readFile({ path: filePath, start_line = 1, end_line = null, max_bytes = 64_000 }) {
+    const resolved = this.resolvePath(filePath);
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+      throw new Error(`Path is a directory, not a file: ${filePath}`);
+    }
+
+    // Fail fast on binary files. A text-only model ingesting a PDF/PNG/etc.
+    // as UTF-8 produces mojibake. The binary is detected via the extension
+    // denylist fast-path and/or a magic-byte check (file-type) on the first
+    // KB, and an explicit BinaryFileError is thrown naming the file, the
+    // detected type, and the instruction to extract text via a
+    // format-appropriate tool instead. No silent skip, no truncated-content
+    // passthrough.
+    const binaryReason = await classifyBinary(resolved);
+    if (binaryReason) {
+      const detected = await detectBinaryType(resolved);
+      const detectedType = detected ? `${detected.mime} (.${detected.ext})` : "binary (extension denylist)";
+      throw new BinaryFileError(
+        `BinaryFileError: '${filePath}' is a binary file (${detectedType}); ` +
+          `reason: ${binaryReason}. A text-only model must not ingest binary content. ` +
+          `Do NOT read this file as text. To extract its text, use the bash tool with a ` +
+          `format-appropriate extractor (e.g. 'pdftotext file -' for PDF, 'strings file', 'exiftool file', 'unzip -l file') ` +
+          `and read the extracted text output instead.`,
+        { file: resolved, detectedType, reason: binaryReason }
+      );
+    }
+
+    const raw = fs.readFileSync(resolved, "utf8");
+    const allLines = raw.split("\n");
+    const totalLines = allLines.length;
+
+    const startIdx = Math.max(0, (start_line || 1) - 1);
+    const endIdx = end_line ? Math.min(totalLines, end_line) : Math.min(totalLines, startIdx + 800);
+
+    const slice = allLines.slice(startIdx, endIdx);
+    const numbered = slice
+      .map((line, idx) => `${startIdx + idx + 1}: ${line}`)
+      .join("\n");
+
+    // Adaptive read-size governor. When the runner has armed the governor
+    // (context high-watermark), the effective read cap is lowered to the
+    // governed size (16KB default) — but only ever below the caller's
+    // max_bytes (the governor never raises the cap). A read whose numbered
+    // content exceeds the governed cap is truncated to the cap and a
+    // suffix-scoped notice is appended to the content (never the prompt
+    // prefix, so KV-cache prefix stability is preserved).
+    const governorCap = this.readGovernorMaxBytes;
+    const effectiveMaxBytes =
+      governorCap != null ? Math.min(max_bytes, governorCap) : max_bytes;
+    const content = numbered.slice(0, effectiveMaxBytes);
+    const governedTruncation =
+      governorCap != null &&
+      effectiveMaxBytes === governorCap &&
+      numbered.length > effectiveMaxBytes;
+
+    const governedNotice = governedTruncation
+      ? `\n[Output governed to ${Math.round(governorCap / 1024)}KB due to context pressure. Use narrow start_line/end_line offsets or ast_search.]`
+      : "";
+
+    return {
+      path: resolved,
+      total_lines: totalLines,
+      showing_range: [startIdx + 1, endIdx],
+      content: content + governedNotice,
+      ...(governedTruncation ? { governed: true, governedMaxBytes: governorCap } : {}),
+    };
+  }
+
+  /**
+   * Writes or overwrites a file.
+   */
+  async writeFile({ path: filePath, content, overwrite = true }) {
+    if (!filePath || typeof filePath !== "string" || filePath.trim().length === 0) {
+      throw new Error("InvalidPathError: filePath parameter is required and must be a non-empty string");
+    }
+    const resolved = this.resolvePath(filePath);
+    if (resolved === path.normalize(this.root)) {
+      throw new Error(`InvalidPathError: Target path '${filePath}' resolves to the workspace root directory, not a file`);
+    }
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+      throw new Error(`InvalidPathError: Target path '${filePath}' is an existing directory, cannot overwrite as file`);
+    }
+    if (fs.existsSync(resolved) && !overwrite) {
+      throw new Error(`File already exists and overwrite is false: ${filePath}`);
+    }
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, content, "utf8");
+    return { path: resolved, bytes_written: Buffer.byteLength(content, "utf8"), success: true };
+  }
+
+  /**
+   * Performs an exact or line-ending-normalized text replacement in a file.
+   *
+   * Guard rules:
+   * - 0 occurrences: explicit "target not found" error (no write).
+   * - 1 occurrence: proceed with replacement.
+   * - >1 occurrences without replace_all: refuse with count (no write).
+   * - >1 occurrences with replace_all: replace all.
+   *
+   * `replacement_content` is validated up front. It must be a string. An
+   * explicit empty string `""` is allowed (it deletes the matched region).
+   * `undefined`/`null`/non-string values are rejected with an explicit
+   * `InvalidReplacementError` so they can never be silently coerced to the
+   * literal string `"undefined"` and written to disk.
+   *
+   * Line-ending auto-normalization is localized to the matched region, not a
+   * whole-file boolean. The style of the region is inferred from which form
+   * of the target actually matches the file (exact / CRLF / LF). The
+   * replacement is normalized to that local style, so editing one region of a
+   * mixed CRLF/LF file preserves that region's endings without cross-
+   * pollinating the rest of the file.
+   *
+   * A target whose line endings differ from the file's is auto-normalized to
+   * the local style and the edit succeeds silently (no
+   * `LineEndingMismatchError`). Callers that want an explicit mismatch signal
+   * can pre-check the file's line endings themselves.
+   */
+  async editFile({ path: filePath, target_content, replacement_content, replace_all = false }) {
+    if (!target_content || typeof target_content !== "string" || target_content.length === 0) {
+      throw new Error("target_content cannot be empty");
+    }
+    // Validate replacement_content before any I/O. Must be a string; explicit
+    // "" is allowed (deletion). undefined/null/non-string are rejected so they
+    // can never coerce to the literal "undefined" and corrupt the file.
+    if (typeof replacement_content !== "string") {
+      throw new Error(
+        `InvalidReplacementError: replacement_content must be a string (got ${
+          replacement_content === undefined ? "undefined" : typeof replacement_content
+        }). Pass an explicit empty string "" to delete the matched region. No write performed.`
+      );
+    }
+    const resolved = this.resolvePath(filePath);
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`File not found for edit: ${filePath}`);
+    }
+    const original = fs.readFileSync(resolved, "utf8");
+
+    // Determine the local line-ending style of the matched region by testing
+    // which form of the target actually matches the file.
+    //   1. exact match            -> the target's own endings are the local style
+    //   2. CRLF-normalized match  -> region is CRLF
+    //   3. LF-normalized match    -> region is LF
+    //   4. none                   -> target not found
+    const crlfTarget = target_content.replace(/\r?\n/g, "\r\n");
+    const lfTarget = target_content.replace(/\r\n/g, "\n");
+    const exactCount = original.split(target_content).length - 1;
+    const crlfCount = original.split(crlfTarget).length - 1;
+    const lfCount = original.split(lfTarget).length - 1;
+
+    let effectiveTarget;
+    let localStyle;
+    if (exactCount > 0) {
+      effectiveTarget = target_content;
+      localStyle = lineEndingStyle(target_content);
+    } else if (crlfCount > 0) {
+      effectiveTarget = crlfTarget;
+      localStyle = "crlf";
+    } else if (lfCount > 0) {
+      effectiveTarget = lfTarget;
+      localStyle = "lf";
+    } else {
+      throw new Error(`Target content not found in file: ${filePath}. No write performed.`);
+    }
+
+    const occurrences = original.split(effectiveTarget).length - 1;
+    if (occurrences > 1 && !replace_all) {
+      throw new Error(
+        `AmbiguousTargetError: target_content found ${occurrences} times in file: ${filePath}. ` +
+        `Provide a longer unique target (include surrounding lines) or pass replace_all: true. No write performed.`
+      );
+    }
+
+    // Normalize the replacement to the local style of the matched region. For
+    // a uniform file this is identical to a whole-file normalization; for a
+    // mixed file it preserves the region's own endings without cross-
+    // pollinating the rest of the file.
+    const effectiveReplacement = normalizeLineEndings(replacement_content, localStyle);
+
+    const updated = replace_all
+      ? original.replaceAll(effectiveTarget, effectiveReplacement)
+      : original.replace(effectiveTarget, effectiveReplacement);
+
+    // In-memory AST & syntax validation gate before writing to disk
+    let syntaxVerified = false;
+    const ast = this._getAst ? this._getAst() : await getSharedAstService();
+    if (ast && typeof ast.inferLanguageByExtension === "function" && typeof ast.validateSyntax === "function") {
+      const lang = ast.inferLanguageByExtension(resolved);
+      if (lang) {
+        const check = ast.validateSyntax(resolved, updated, lang);
+        if (check.checked) {
+          if (!check.valid) {
+            throw new SyntaxValidationError(
+              resolved,
+              check.error || `Syntax validation check failed for '${lang}'`
+            );
+          }
+          syntaxVerified = true;
+        }
+      }
+    }
+
+    fs.writeFileSync(resolved, updated, "utf8");
+    return {
+      path: resolved,
+      occurrences_replaced: replace_all ? occurrences : 1,
+      success: true,
+      syntax_verified: syntaxVerified,
+    };
+  }
+
+  /**
+   * Lists directory contents while strictly filtering out ignored directories.
+   */
+  async listDir({ path: dirPath = ".", max_depth = 2 }) {
+    const resolved = this.resolvePath(dirPath);
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    let listingPartial = false;
+    const walk = (currentDir, depth) => {
+      if (depth > max_depth) return [];
+      const entries = [];
+      let files = [];
+      try {
+        files = fs.readdirSync(currentDir, { withFileTypes: true });
+      } catch (err) {
+        process.stderr.write(`[SandboxFs] Unreadable directory ${currentDir}: ${err.message}\n`);
+        listingPartial = true;
+        return [];
+      }
+
+      for (const f of files) {
+        if (this.ignoredDirs.has(f.name)) continue;
+        const full = path.join(currentDir, f.name);
+        const rel = path.relative(resolved, full);
+        if (f.isDirectory()) {
+          entries.push({ name: f.name, path: rel, type: "dir" });
+          entries.push(...walk(full, depth + 1));
+        } else {
+          entries.push({ name: f.name, path: rel, type: "file" });
+        }
+      }
+      return entries;
+    };
+
+    const items = walk(resolved, 1);
+    return { path: resolved, total_items: items.length, items, ...(listingPartial ? { partial: true } : {}) };
+  }
+
+  /**
+   * Pre-validates the file paths referenced by a unified diff patch so the
+   * sandbox boundary is explicit rather than solely delegated to `git apply`
+   * (whose handling of `../` and absolute paths is version- and
+   * config-dependent).
+   *
+   * The target paths are extracted from each file section's `--- a/<p>` and
+   * `+++ b/<p>` headers. For each path:
+   *   - `/dev/null` is allowed (it denotes a newly-created or deleted file).
+   *   - a leading `a/` or `b/` side marker (the standard unified-diff prefix)
+   *     is stripped before validation.
+   *   - a null byte is rejected.
+   *   - an absolute path is rejected (the only legitimate absolute path,
+   *     `/dev/null`, is handled above).
+   *   - a relative path is resolved against the patch base directory and must
+   *     stay within the sandbox root; a path that escapes the root (e.g.
+   *     `../outside`) is rejected.
+   *
+   * This runs BEFORE `git` is spawned, so a malicious or malformed path is
+   * rejected cheaply and deterministically.
+   *
+   * @param {string} patch
+   * @param {string} baseDir The resolved base directory (git apply cwd).
+   * @returns {string[]} the validated relative paths (for reporting).
+   */
+  _validatePatchPaths(patch, baseDir) {
+    const root = this.root;
+    const seen = new Set();
+    for (const line of patch.split(/\r?\n/)) {
+      let target = null;
+      let m = line.match(/^---\s+(.+?)\s*$/);
+      if (m) target = m[1];
+      else {
+        m = line.match(/^\+\+\+\s+(.+?)\s*$/);
+        if (m) target = m[1];
+      }
+      if (target === null) continue;
+      // A trailing tab-separated timestamp (e.g. "--- a/path\t2024-01-01") is
+      // not part of the path.
+      const tabIdx = target.indexOf("\t");
+      if (tabIdx !== -1) target = target.slice(0, tabIdx);
+      // /dev/null denotes a new (---) or deleted (+++) file — always allowed.
+      if (target === "/dev/null") continue;
+      let p = target;
+      if (p.startsWith("a/") || p.startsWith("b/")) p = p.slice(2);
+      if (p.includes("\0")) {
+        throw new Error(
+          `PatchPathError: patch path '${target}' contains a prohibited null byte. No files were modified.`
+        );
+      }
+      if (path.isAbsolute(p)) {
+        throw new Error(
+          `PatchPathError: patch references an absolute path '${target}', which is not allowed. No files were modified.`
+        );
+      }
+      const resolved = path.resolve(baseDir, p);
+      const rel = path.relative(root, resolved);
+      if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(
+          `PatchPathError: patch path '${target}' resolves outside the sandbox root. No files were modified.`
+        );
+      }
+      seen.add(p);
+    }
+    return [...seen];
+  }
+
+  /**
+   * Applies a standard unified diff patch using `git apply`.
+   *
+   * Size cap: the `patch` payload is measured in bytes and rejected with an
+   * explicit `PatchTooLargeError` before any `git` subprocess is spawned if it
+   * exceeds `MAX_PATCH_SIZE` (2 MB). This bounds memory and the child-process
+   * input pipe for pathological payloads.
+   *
+   * Distinct timeout signal: if the `git apply` subprocess is killed by the
+   * timeout (or otherwise terminated by a signal), a distinct
+   * `GitApplyTimeoutError` is thrown instead of the generic `GitApplyError`,
+   * so a hang/timeout is distinguishable from a normal "patch does not apply"
+   * failure. Node reports a timeout as `err.code === "ETIMEDOUT"` and
+   * `err.signal === "SIGTERM"` (and `err.killed === true` on some platforms);
+   * all three are checked.
+   *
+   * Faithful whitespace: `--whitespace=fix` is not used. That flag silently
+   * rewrites whitespace in the applied content (e.g. it strips trailing spaces
+   * and emits "line applied after fixing whitespace errors"), so the on-disk
+   * result could differ from the literal patch. The default `git apply`
+   * behavior writes the patch bytes faithfully (it only warns about
+   * whitespace, it does not modify it).
+   *
+   * Line-ending behavior is context-dependent:
+   *   (a) In a git repository whose `.gitattributes` pins
+   *       `* text=auto eol=lf` (as this workspace does), `git apply`
+   *       normalizes the applied content to LF on write, so a CRLF file is
+   *       converted to LF. This is a property of the repo's `.gitattributes`,
+   *       not of this method.
+   *   (b) In a non-git directory, `git apply` still works (it does not require
+   *       a repository) but no `.gitattributes` normalization applies, so the
+   *       patch bytes are written verbatim (line endings preserved as given).
+   *
+   * The base directory (`dirPath`) is validated against the sandbox root by
+   * `resolvePath()`, and every file path inside the patch is explicitly
+   * pre-validated by `_validatePatchPaths()` before `git` is spawned (rejecting
+   * `../` traversal, absolute paths, and null bytes). This makes the boundary
+   * deterministic rather than relying on `git apply`'s version/config-specific
+   * handling; `git apply` additionally refuses to write through symlinks that
+   * escape the working tree. The adversarial regression tests in
+   * `tests/apply_patch.test.js` pin this boundary.
+   *
+   * @param {object} args
+   * @param {string} args.patch Standard unified diff patch content.
+   * @param {string} [args.dirPath="."] Target base directory (sandbox-relative).
+   * @returns {Promise<{success: boolean, message: string}>}
+   */
+  async applyPatch({ patch, dirPath = "." }) {
+    if (!patch || typeof patch !== "string" || patch.trim().length === 0) {
+      throw new Error("patch cannot be empty");
+    }
+
+    // Enforce the size cap before spawning git.
+    const patchBytes = Buffer.byteLength(patch, "utf8");
+    if (patchBytes > MAX_PATCH_SIZE) {
+      throw new PatchTooLargeError(
+        `PatchTooLargeError: patch is ${patchBytes} bytes, exceeding the ${MAX_PATCH_SIZE} byte limit. ` +
+          `No git subprocess was spawned and no files were modified.`,
+        { size: patchBytes, limit: MAX_PATCH_SIZE }
+      );
+    }
+
+    const resolved = this.resolvePath(dirPath);
+
+    // Explicitly validate every file path in the patch against the sandbox
+    // root before invoking git, so the boundary does not depend on git's
+    // version/config-specific handling of `../` and absolute paths.
+    this._validatePatchPaths(patch, resolved);
+
+    try {
+      // No --whitespace=fix — write the patch bytes faithfully.
+      execFileSync("git", ["apply", "--unidiff-zero", "-"], {
+        cwd: resolved,
+        input: patch,
+        encoding: "utf8",
+        timeout: this.gitApplyTimeoutMs,
+        windowsHide: true,
+      });
+      return { success: true, message: "Patch applied cleanly" };
+    } catch (err) {
+      // A timeout / signal kill is a distinct signal.
+      const isTimeout =
+        err &&
+        (err.killed === true || err.code === "ETIMEDOUT" || err.signal === "SIGTERM");
+      if (isTimeout) {
+        const stderr = err && err.stderr ? String(err.stderr).trim() : "";
+        throw new GitApplyTimeoutError(
+          `GitApplyTimeoutError: git apply was terminated by a timeout/signal ` +
+            `(signal=${err && err.signal ? err.signal : "unknown"}). ` +
+            `The patch was NOT applied (git apply is atomic). ${stderr}`,
+          { signal: err && err.signal ? err.signal : null, stderr }
+        );
+      }
+      const msg = err.stderr ? err.stderr.toString().trim() : (err.message || String(err));
+      throw new Error(`GitApplyError: Failed to apply patch: ${msg}`);
+    }
+  }
+
+  /**
+   * Determines whether dirPath is inside a git repository, distinguishing a
+   * non-git directory from a corrupted git repository.
+   *
+   * Verifies the presence of a .git entry in dirPath or ancestor directories
+   * to ensure corrupted repositories fail fast while non-git directories fall
+   * back to filesystem search.
+   *
+   * @param {string} dirPath - Directory path to inspect.
+   * @returns {Promise<boolean>} True if inside a git repository.
+   */
+  async _isInsideGitRepo(dirPath) {
+    try {
+      const { code } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd: dirPath,
+        timeout: 5_000,
+      });
+      if (code === 0) return true;
+    } catch {
+      // rev-parse failed (non-git dir OR corrupted repo) — fall through to
+      // the .git-presence check below.
+    }
+    // Walk up from dirPath to the filesystem root looking for a `.git`
+    // entry. A real or corrupted repository has one; a non-git directory
+    // does not.
+    let dir = dirPath;
+    for (;;) {
+      try {
+        if (fs.existsSync(path.join(dir, ".git"))) return true;
+      } catch {
+        // ignore stat errors and keep climbing
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break; // reached the filesystem root
+      dir = parent;
+    }
+    return false;
+  }
+
+  /**
+   * Formats and truncates a single grep match line to bound output size.
+   *
+   * Query-centered windowing: if the match query occurs late in a long line, centers
+   * a preview window around the match so the matched token is not truncated away.
+   *
+   * @param {string} rawLine - e.g. "path/to/file.js:42:code content"
+   * @param {string} query - The query string to anchor the preview window
+   * @param {number} [maxLineChars=300] - Maximum line character cap
+   * @returns {string} Truncated, bounded line preview
+   */
+  _formatMatchLine(rawLine, query, maxLineChars = 300) {
+    if (!rawLine || rawLine.length <= maxLineChars) {
+      return rawLine;
+    }
+
+    const matchPrefix = rawLine.match(/^([^:\r\n]+:\d+:)(.*)$/s);
+    if (!matchPrefix) {
+      const qIdx = rawLine.indexOf(query);
+      if (qIdx === -1 || qIdx <= 120) {
+        return `${rawLine.slice(0, maxLineChars).trim()} ... [truncated line: ${rawLine.length} chars]`;
+      }
+      const start = Math.max(0, qIdx - 80);
+      const end = Math.min(rawLine.length, qIdx + query.length + 120);
+      return `... ${rawLine.slice(start, end).trim()} ... [truncated line: ${rawLine.length} chars, match at col ${qIdx + 1}]`;
+    }
+
+    const prefix = matchPrefix[1];
+    const content = matchPrefix[2];
+    if (content.length <= maxLineChars) {
+      return rawLine;
+    }
+
+    const qIdx = content.indexOf(query);
+    if (qIdx === -1 || qIdx <= 120) {
+      const preview = content.slice(0, maxLineChars);
+      return `${prefix} ${preview.trim()} ... [truncated line: ${content.length} chars]`;
+    }
+
+    const start = Math.max(0, qIdx - 80);
+    const end = Math.min(content.length, qIdx + query.length + 120);
+    const preview = content.slice(start, end);
+    return `${prefix} ... ${preview.trim()} ... [truncated line: ${content.length} chars, match at col ${qIdx + 1}]`;
+  }
+
+  /**
+   * Fast indexed search using git grep (respecting .gitignore) or a safe
+   * fallback file search.
+   *
+   * The query is matched as a literal string (`-F` / `--fixed-strings`),
+   * aligning the implementation with the documented "Literal string to
+   * search for" contract.
+   *
+   * A fatal `git grep` error (any non-zero exit code other than 1) inside a
+   * git repository fails fast with a `GitGrepError` instead of falling
+   * through to the manual walk. Exit code 1 ("no matches") is a valid empty
+   * result. In a non-git directory the manual walk is used, but it
+   * explicitly skips `.env` / `.env.*` files to prevent secret ingestion.
+   *
+   * `max_results` caps the total number of matches returned, consistently
+   * across both the git-grep and fallback paths.
+   *
+   * Line length and aggregate payload are strictly bounded:
+   *  - Each match line exceeding 300 chars is query-centered and truncated.
+   *  - Total match payload is capped at 32 KB across all matches.
+   *  - Both `path` and `dirPath` are accepted and passed as git pathspecs.
+   *
+   * @param {object} args
+   * @param {string} args.query Literal string to search for.
+   * @param {string} [args.path] Root search directory or target file path.
+   * @param {string} [args.dirPath] Alias for path.
+   * @param {number} [args.max_results=50] Maximum number of matches returned.
+   * @returns {Promise<{query: string, count: number, matches: string[], skipped?: string[], truncated: boolean}>}
+   */
+  async searchCode({ query, path: targetPath, dirPath, max_results = 50 }) {
+    const rawTarget = targetPath || dirPath || ".";
+    const resolved = this.resolvePath(rawTarget);
+    const cap = Math.max(0, max_results | 0);
+    const MAX_TOTAL_BYTES = 32 * 1024; // 32KB aggregate payload cap
+
+    let isFile = false;
+    try {
+      isFile = fs.existsSync(resolved) && fs.statSync(resolved).isFile();
+    } catch {}
+
+    const searchDir = isFile ? path.dirname(resolved) : resolved;
+    let inRepo = false;
+    try {
+      inRepo = await this._isInsideGitRepo(searchDir);
+    } catch {
+      inRepo = false;
+    }
+
+    if (inRepo) {
+      try {
+        const gitArgs = ["grep", "-n", "-I", "-F", "--untracked", "-e", query];
+        const relSpec = path.relative(this.root, resolved).replace(/\\/g, "/");
+        if (relSpec && relSpec !== "." && relSpec !== "") {
+          gitArgs.push("--", relSpec);
+        }
+
+        const { stdout } = await execFileAsync("git", gitArgs, {
+          cwd: this.root,
+          timeout: 10_000,
+        });
+        const rawLines = stdout.trim().split("\n").filter(Boolean);
+        const matches = [];
+        let totalBytes = 0;
+        let hitPayloadCap = false;
+
+        for (const rawLine of rawLines) {
+          if (matches.length >= cap) break;
+          const formatted = this._formatMatchLine(rawLine, query, 300);
+          const lineBytes = Buffer.byteLength(formatted, "utf8");
+          if (totalBytes + lineBytes > MAX_TOTAL_BYTES) {
+            matches.push(`... [Remaining matches truncated: reached 32KB result payload limit]`);
+            hitPayloadCap = true;
+            break;
+          }
+          matches.push(formatted);
+          totalBytes += lineBytes;
+        }
+
+        return {
+          query,
+          count: matches.length,
+          matches,
+          truncated: hitPayloadCap || rawLines.length > matches.length,
+        };
+      } catch (err) {
+        // git grep exit code 1 means "no matches found", NOT an execution error.
+        if (err && err.code === 1) {
+          return {
+            query,
+            count: 0,
+            matches: [],
+          };
+        }
+
+        // Fatal git error in repo
+        const stderr = err && err.stderr ? String(err.stderr).trim() : "";
+        throw new GitGrepError(
+          `GitGrepError: git grep failed with exit code ${err && err.code} in a git repository: ${stderr || err.message}`,
+          { code: err && err.code, stderr }
+        );
+      }
+    }
+
+    // Fallback: not a git repository. Search files avoiding ignored
+    // directories and `.env` / `.env.*` files (secret-leak prevention). The
+    // total match count is capped at `max_results`.
+    //
+    // Binary files are skipped (reported in `skipped` as "skipped-binary")
+    // rather than read as UTF-8.
+    const matches = [];
+    const skipped = [];
+    let totalBytes = 0;
+    let hitPayloadCap = false;
+
+    const walkSearch = async (cur) => {
+      if (matches.length >= cap || hitPayloadCap) return;
+      let files;
+      try {
+        const stat = fs.statSync(cur);
+        if (stat.isFile()) {
+          files = [{ name: path.basename(cur), isDirectory: () => false, isFile: () => true }];
+          cur = path.dirname(cur);
+        } else {
+          files = fs.readdirSync(cur, { withFileTypes: true });
+        }
+      } catch {
+        return;
+      }
+      for (const f of files) {
+        if (matches.length >= cap || hitPayloadCap) break;
+        if (this.ignoredDirs.has(f.name)) continue;
+        if (isEnvFile(f.name)) continue; // never ingest .env / .env.*
+        const full = path.join(cur, f.name);
+        if (f.isDirectory()) {
+          await walkSearch(full);
+        } else if (f.isFile()) {
+          let size = f.size;
+          if (size === undefined) {
+            try {
+              size = fs.statSync(full).size;
+            } catch {
+              continue;
+            }
+          }
+          if (size < 500_000) {
+            if (isBinaryExtension(f.name)) {
+              skipped.push(`${path.relative(this.root, full).replace(/\\/g, "/")} (skipped-binary: extension '${f.name}')`);
+              continue;
+            }
+            let buf;
+            try {
+              buf = fs.readFileSync(full);
+            } catch {
+              continue;
+            }
+            const head = buf.subarray(0, reasonableDetectionSizeInBytes);
+            const detected = await fileTypeFromBuffer(head);
+            if (detected) {
+              skipped.push(`${path.relative(this.root, full).replace(/\\/g, "/")} (skipped-binary: ${detected.mime} .${detected.ext})`);
+              continue;
+            }
+            const text = buf.toString("utf8");
+            if (text.includes(query)) {
+              const lines = text.split("\n");
+              for (let idx = 0; idx < lines.length; idx++) {
+                const l = lines[idx];
+                if (l.includes(query)) {
+                  if (matches.length >= cap) break;
+                  const relPath = path.relative(this.root, full).replace(/\\/g, "/");
+                  const formatted = this._formatMatchLine(`${relPath}:${idx + 1}:${l}`, query, 300);
+                  const lineBytes = Buffer.byteLength(formatted, "utf8");
+                  if (totalBytes + lineBytes > MAX_TOTAL_BYTES) {
+                    matches.push(`... [Remaining matches truncated: reached 32KB result payload limit]`);
+                    hitPayloadCap = true;
+                    break;
+                  }
+                  matches.push(formatted);
+                  totalBytes += lineBytes;
+                }
+              }
+            }
+          }
+        }
+      }
+    };
+    await walkSearch(resolved);
+    return {
+      query,
+      count: matches.length,
+      matches,
+      skipped,
+      truncated: hitPayloadCap,
+    };
+  }
+}
+
+/**
+ * Castor Plugin to mount SandboxFsService and its tools into Context.
+ */
+export function sandboxFsPlugin(ctx, options = {}) {
+  const fsService = new SandboxFsService({
+    ...options,
+    getAst: () => ctx.get("ast"),
+  });
+  ctx.provide("fs", fsService);
+
+  ctx.registerTool("read_file", {
+    description: "Read a slice of a text file with line numbers (safe, bounded). Always use this tool instead of shell commands (cat, head, tail, sed) in bash.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path" },
+        start_line: { type: "integer", description: "1-indexed starting line", default: 1 },
+        end_line: { type: "integer", description: "1-indexed ending line (optional)" },
+      },
+      required: ["path"],
+    },
+    execute: (args) => fsService.readFile(args),
+  });
+
+  ctx.registerTool("write_file", {
+    description: "Create or overwrite a file with full content",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path" },
+        content: { type: "string", description: "File content to write" },
+        overwrite: { type: "boolean", description: "Whether to overwrite existing file", default: true },
+      },
+      required: ["path", "content"],
+    },
+    execute: (args) => fsService.writeFile(args),
+  });
+
+  ctx.registerTool("edit_file", {
+    description:
+      "Perform exact text search-and-replace in a file with transparent in-memory syntax validation. Always use this tool instead of sed/awk in bash. " +
+      "target_content must occur exactly once unless replace_all is true; ambiguous edits are refused. " +
+      "If the edit introduces syntax errors (JS, TS, Python, JSON, LaTeX, BibTeX), it is automatically rejected before disk write.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path" },
+        target_content: { type: "string", description: "Exact character sequence to replace (must be unique unless replace_all is true)" },
+        replacement_content: { type: "string", description: "Replacement content" },
+        replace_all: { type: "boolean", description: "If true, replace every occurrence of target_content. If false (default), target must occur exactly once.", default: false },
+      },
+      required: ["path", "target_content", "replacement_content"],
+    },
+    execute: (args) => fsService.editFile(args),
+  });
+
+  ctx.registerTool("apply_patch", {
+    description: "Apply a standard unified diff patch atomically using git apply (--unidiff-zero)",
+    parameters: {
+      type: "object",
+      properties: {
+        patch: { type: "string", description: "Standard unified diff patch content" },
+        path: { type: "string", description: "Target base directory", default: "." },
+      },
+      required: ["patch"],
+    },
+    execute: (args) => fsService.applyPatch(args),
+  });
+
+  ctx.registerTool("list_dir", {
+    description: "List directory contents while auto-ignoring .venv, node_modules, and .git. Always use this tool instead of shell commands (ls, find) in bash.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path", default: "." },
+        max_depth: { type: "integer", description: "Recursion depth", default: 2 },
+      },
+    },
+    execute: (args) => fsService.listDir(args),
+  });
+
+  ctx.registerTool("search_code", {
+    description: "Fast code and pattern search across the codebase avoiding ignored directories. Always use this tool instead of shell commands (grep, rg) in bash.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Literal string to search for" },
+        path: { type: "string", description: "Root search directory or target file path", default: "." },
+        dirPath: { type: "string", description: "Alias for path", default: "." },
+      },
+      required: ["query"],
+    },
+    execute: (args) => fsService.searchCode(args),
+  });
+}