sentinel-ir-mcp 0.3.0 → 0.4.1

package/README.md

@@ -25,6 +25,44 @@ of safety. Other languages are not supported yet. What is detected in Python
 (and what is not) is listed in the
 [sentinel-ir README](https://gitlab.com/jakubrojicek11/sentinel-ir#python).
 
+**0.4.1** uses `sentinel-ir` 0.4.3:
+
+- **Faster on large JavaScript:** a valid 1 MiB file takes about 5 s instead
+  of about 170 s, so `analyze_directory` no longer runs past the 60 s request
+  timeout of MCP SDK clients on one big file.
+- **Read-time check:** files are opened first and then checked, so a file
+  swapped for a symlink between listing and reading is refused instead of read
+  from outside the allowed folders. A file removed during a scan no longer
+  fails the whole scan; it is listed in `skipped.unreadable`. Files with more
+  than one hard link are refused (`skipped.hardlinks`).
+- **Finite limits:** `--max-file-bytes` is capped at 2 MiB. Valid JavaScript
+  with `sentinel-ir` 0.4.3:
+
+  | size | Linux | Windows CI (Node 20/22/24) |
+  |---|---|---|
+  | 1 MiB | 4–5 s, 0.9 GB | 13–23 s, 0.8 GB |
+  | 2 MiB | 10–14 s, 1.6 GB | 29–40 s, 1.5 GB |
+  | 4 MiB | 25–29 s, 3 GB | process aborts |
+
+  A file above 2 MiB can take longer than the 60 s request timeout on its own.
+- **Time budget:** `analyze_directory` starts no new file after 30 s
+  (`--time-budget-ms`). Then `timedOut` is `true` and the remaining files are
+  listed in `notAnalyzed`. A file already being analyzed is not interrupted.
+- **Parser errors:** incomplete files carry `facts.parseError` with the line,
+  column and kind of the first parser error (from `sentinel-ir` 0.4.3).
+
+**0.4.0** uses `sentinel-ir` 0.4.2:
+
+- **Native code:** `ctypes` / `cffi`, `process.dlopen`, `*.node` addons and
+  FFI packages (`koffi`, `ffi-napi`, `bun:ffi`, ...) are `critical`, with
+  `native_code` in `forbidden` and `nativeCode` in `facts.operations`.
+- **Long sessions:** older versions never freed the WebAssembly parser
+  memory. After roughly 87 MB of analyzed source in one server process every
+  later result became `"incomplete"` (text fallback) without an error. With
+  `sentinel-ir-mcp` 0.3.0 + `sentinel-ir` 0.3.1 over stdio, `analyze_code` on
+  an 18 KB file went `incomplete` from call 4,918 on; 0.4.0 stays `complete`
+  (measurement below).
+
 ## Tools
 
 | tool | input | returns |
@@ -68,9 +106,9 @@ nothing to compile (the parser is WebAssembly).
 Run it in your project folder:
 
 ```bash
-npx -y sentinel-ir-mcp@0.3 setup --client cursor     # or windsurf, claude-desktop, vscode, claude-code
-npx -y sentinel-ir-mcp@0.3 doctor --client cursor    # after restarting the client
-npx -y sentinel-ir-mcp@0.3 guide                     # optional: text for AGENTS.md / client rules
+npx -y sentinel-ir-mcp@0.4 setup --client cursor     # or windsurf, claude-desktop, vscode, claude-code
+npx -y sentinel-ir-mcp@0.4 doctor --client cursor    # after restarting the client
+npx -y sentinel-ir-mcp@0.4 guide                     # optional: text for AGENTS.md / client rules
 ```
 
 `setup` (without `--client` it asks which client):
@@ -84,7 +122,7 @@ npx -y sentinel-ir-mcp@0.3 guide                     # optional: text for AGENTS
   touched;
 - gives the agent one folder (`--project`, default: the current folder) and
   refuses your home folder or a whole disk;
-- writes `sentinel-ir-mcp@0.3`, so clients get 0.3.x fixes but no unexpected
+- writes `sentinel-ir-mcp@0.4`, so clients get 0.4.x fixes but no unexpected
   new features;
 - for VS Code and Claude Code it writes nothing and prints their own install
   command (`code --add-mcp ...`, `claude mcp add ...`) instead.
@@ -97,7 +135,7 @@ npx -y sentinel-ir-mcp@0.3 guide                     # optional: text for AGENTS
 | `vscode`, `claude-code` | nothing; prints the command to run |
 
 On Windows the entry is `"command": "cmd", "args": ["/c", "npx", "-y",
-"sentinel-ir-mcp@0.3", "<folder>"]`: there `npx` is `npx.cmd`, and starting it
+"sentinel-ir-mcp@0.4", "<folder>"]`: there `npx` is `npx.cmd`, and starting it
 without a shell failed with `ENOENT` on a real Windows runner. For VS Code and
 Claude Code, `setup` prints a PowerShell and a Command Prompt version of the
 command. What was measured on which system: [COMPATIBILITY.md](COMPATIBILITY.md).
@@ -138,12 +176,14 @@ To get the newest 0.2.x:
 A folder that is literally named `setup`, `doctor` or `guide` must now be
 passed as `./setup` (or an absolute path); the bare word is the command.
 
-### Upgrading from 0.2.x
+### Upgrading from 0.3.x or older
 
-Configs written by 0.2.x pin `sentinel-ir-mcp@0.2` and keep running 0.2.x,
-which has no Python support. Run `setup` again for your client (it replaces
-only the `"sentinel-ir"` entry); `doctor` warns about an entry that still pins
-0.2 or older. If the client still starts an old version, see
+Configs written by older versions pin `sentinel-ir-mcp@0.3` (or `@0.2`) and
+keep running that line. 0.3.x has no native-code detection, and its parser
+stops working in long sessions (see 0.4.0 below); 0.2.x also has no Python
+support. Run `setup` again for your client (it replaces only the
+`"sentinel-ir"` entry); `doctor` warns about an entry that still pins 0.3 or
+older. If the client still starts an old version, see
 [Getting a newer version](#getting-a-newer-version).
 
 ### One-click install links
@@ -173,7 +213,7 @@ Settings → Developer → Edit Config opens `claude_desktop_config.json`
   "mcpServers": {
     "sentinel-ir": {
       "command": "npx",
-      "args": ["-y", "sentinel-ir-mcp@0.3", "/Users/you/projects/my-app"]
+      "args": ["-y", "sentinel-ir-mcp@0.4", "/Users/you/projects/my-app"]
     }
   }
 }
@@ -192,7 +232,7 @@ project entry has to be switched on once in Cursor Settings → Customize → MC
   "mcpServers": {
     "sentinel-ir": {
       "command": "npx",
-      "args": ["-y", "sentinel-ir-mcp@0.3", "${workspaceFolder}"]
+      "args": ["-y", "sentinel-ir-mcp@0.4", "${workspaceFolder}"]
     }
   }
 }
@@ -208,8 +248,8 @@ with your project's absolute path.
 #### Other clients
 
 Any MCP client that starts stdio servers works with
-`command: "npx"`, `args: ["-y", "sentinel-ir-mcp@0.3", "<folder>"]`
-(on Windows: `command: "cmd"`, `args: ["/c", "npx", "-y", "sentinel-ir-mcp@0.3", "<folder>"]`).
+`command: "npx"`, `args: ["-y", "sentinel-ir-mcp@0.4", "<folder>"]`
+(on Windows: `command: "cmd"`, `args: ["/c", "npx", "-y", "sentinel-ir-mcp@0.4", "<folder>"]`).
 Without folder arguments the server uses the client's
 [MCP roots](https://modelcontextprotocol.io/specification/latest/client/roots)
 if the client offers them; if it offers none, only `analyze_code` works.
@@ -217,9 +257,10 @@ if the client offers them; if it offers none, only `analyze_code` works.
 ### Options
 
 ```text
-sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [folder ...]
+sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
 
-  --max-file-bytes <n>   largest file to analyze (default 1048576 = 1 MiB)
+  --max-file-bytes <n>   largest file to analyze (default 1048576 = 1 MiB, max 2097152 = 2 MiB)
+  --time-budget-ms <n>   analyze_directory starts no new file after this (default 30000, max 600000)
   --max-files <n>        default file limit for analyze_directory (default 50, max 500)
 ```
 
@@ -227,14 +268,22 @@ sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [folder ...]
 
 - **Reads only.** The MCP server never writes files, runs commands or opens
   network connections (only the separate `setup` command writes, and only the
-  client config file you confirm; `doctor` starts this package's own server). The only files it opens are `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts`/`.tsx` files up to
+  client config file you confirm; `doctor` starts this package's own server). The only files it opens are `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts`/`.tsx`/`.py`/`.pyi` files up to
   `--max-file-bytes`.
 - **Only inside the allowed folders.** Every path is resolved to its real path
   (symlinks followed) and must lie inside a folder given on the command line,
   or, without folder arguments, inside one of the client's MCP roots. `../`,
   absolute paths elsewhere and symlinks pointing outside are refused.
 - **`analyze_directory`** skips `node_modules`, `.git`, hidden folders and
-  every symlink, and stops after `max_files` files (`truncated: true`).
+  every symlink, and stops after `max_files` files (`truncated: true`) or
+  when the time budget is spent (`timedOut: true`, rest in `notAnalyzed`).
+  Each file is checked again when it is opened: it must still be a regular
+  file inside the allowed folders.
+- **Hard links are refused.** A hard link inside the folder can point to a
+  file outside it, and the other names of a file cannot be found. So files
+  with more than one hard link are refused (`analyze_file` error,
+  `skipped.hardlinks` in `analyze_directory`). This also refuses harmless hard
+  links, e.g. pnpm's in `node_modules`.
 - **The IR is still untrusted text.** Comments, string bodies and function
   bodies are not copied into it, so instructions hidden there do not reach the
   agent through the IR. It does contain identifiers and some literals from the
@@ -264,13 +313,22 @@ very small files. `analyze_file` on `src/ast-facts.js` took about 160 ms per
 call (average of 10, Node 24, Linux cloud VM); the first call also loads the
 WebAssembly parser.
 
+Long session (one server process over stdio, 6,000 `analyze_code` calls on
+the same 17.8 KB JavaScript file, about 107 MB in total, Node 24):
+
+| version | calls with a different `analysisStatus` than the first | first such call |
+|---|---:|---:|
+| 0.3.0 + `sentinel-ir` 0.3.1 | 1,083 | 4,918 |
+| 0.4.0 + `sentinel-ir` 0.4.2 | 0 | — |
+
 ## Dependencies
 
 Three runtime dependencies: the official
 [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk),
 `zod` (its schema peer dependency) and `sentinel-ir`. With their own
 dependencies that is about 100 packages in `node_modules`; `npm audit`
-reported 0 vulnerabilities at release time. Unlike `sentinel-ir` itself,
+reported 0 vulnerabilities at release time (0.4.0: after updating
+`body-parser` to 2.4.0 in the lock file). Unlike `sentinel-ir` itself,
 this package is not dependency-free.
 
 ## Development

package/bin/sentinel-ir-mcp.js

@@ -23,7 +23,8 @@ Usage: sentinel-ir-mcp [options] [folder ...]
                          command must be written as ./setup, ./doctor or ./guide. Without folders the
                          server uses the MCP roots offered by the client; if the
                          client offers none, only analyze_code works.
-  --max-file-bytes <n>   Largest file to analyze (default ${DEFAULT_LIMITS.maxFileBytes})
+  --max-file-bytes <n>   Largest file to analyze (default ${DEFAULT_LIMITS.maxFileBytes}, max ${DEFAULT_LIMITS.hardMaxFileBytes})
+  --time-budget-ms <n>   analyze_directory starts no new file after this time (default ${DEFAULT_LIMITS.timeBudgetMs}, max ${DEFAULT_LIMITS.hardMaxTimeBudgetMs})
   --max-files <n>        Default file limit for analyze_directory (default ${DEFAULT_LIMITS.maxFiles}, max ${DEFAULT_LIMITS.hardMaxFiles})
   -h, --help             Show this help
   -v, --version          Show the version
@@ -36,6 +37,12 @@ function die(message) {
     process.exit(2);
 }
 
+const NUMBER_OPTIONS = {
+    "--max-file-bytes": ["maxFileBytes", DEFAULT_LIMITS.hardMaxFileBytes],
+    "--max-files": ["maxFiles", DEFAULT_LIMITS.hardMaxFiles],
+    "--time-budget-ms": ["timeBudgetMs", DEFAULT_LIMITS.hardMaxTimeBudgetMs]
+};
+
 function parseArgs(argv) {
     const opts = { roots: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -44,12 +51,12 @@ function parseArgs(argv) {
         if (arg.startsWith("--") && arg.includes("=")) [arg, value] = [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)];
         if (arg === "-h" || arg === "--help") { process.stdout.write(USAGE + "\n"); process.exit(0); }
         if (arg === "-v" || arg === "--version") { process.stdout.write(version + "\n"); process.exit(0); }
-        if (arg === "--max-file-bytes" || arg === "--max-files") {
+        if (Object.hasOwn(NUMBER_OPTIONS, arg)) {
+            const [key, max] = NUMBER_OPTIONS[arg];
             if (value === undefined) value = argv[++i];
             const n = Number(value);
-            const max = arg === "--max-files" ? DEFAULT_LIMITS.hardMaxFiles : Number.MAX_SAFE_INTEGER;
             if (!Number.isInteger(n) || n < 1 || n > max) die(`${arg} must be an integer between 1 and ${max}`);
-            opts[arg === "--max-files" ? "maxFiles" : "maxFileBytes"] = n;
+            opts[key] = n;
         } else if (arg.startsWith("-")) {
             die(`unknown option ${arg}`);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for sentinel-ir: lets AI agents (Claude Desktop, Cursor, Windsurf, ...) read a compact structural IR of JavaScript, TypeScript and Python files instead of the raw source. Read-only, sandboxed to allowed folders.",
   "main": "src/server.js",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "sentinel-ir": "^0.3.0",
+    "sentinel-ir": "^0.4.3",
     "zod": "^4.1.0"
   },
   "keywords": [

package/src/analyze.js

@@ -1,9 +1,64 @@
 "use strict";
 
 const fs = require("fs/promises");
+const { constants, realpathSync } = require("fs");
 const path = require("path");
 const { analyzeAsync, compress } = require("sentinel-ir");
-const { AccessError, resolveInside, isSourceFile } = require("./paths");
+const { AccessError, resolveInside, isInside, isSourceFile } = require("./paths");
+
+// O_NONBLOCK: opening a FIFO swapped in after listing must not block the
+// server forever. Neither flag exists on Windows; the inode check covers that.
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0);
+
+class TooLargeError extends AccessError {}
+class HardlinkError extends AccessError {}
+
+// Reads the file that is actually opened, not the one checked earlier: the
+// path may be swapped for a symlink between the check and the read. The open
+// handle must be a regular file whose inode is the one now found at a real
+// path inside the allowed folders, and at most maxFileBytes are read.
+async function readInside(full, roots, maxFileBytes, label) {
+    let handle;
+    try {
+        handle = await fs.open(full, OPEN_FLAGS);
+    } catch (err) {
+        if (err && err.code === "ELOOP") throw new AccessError(`Access denied: ${label} is a symlink`);
+        throw err;
+    }
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile()) throw new AccessError(`Not a file: ${label}`);
+        if (opened.size > BigInt(maxFileBytes)) {
+            throw new TooLargeError(`File too large: ${label} is ${opened.size} bytes, limit is ${maxFileBytes}`);
+        }
+        // Same realpath as resolveInside: on Windows fs.promises.realpath
+        // expands 8.3 short names (GITLAB~1) and would never match the roots.
+        const real = realpathSync(full);
+        const current = await fs.stat(real, { bigint: true });
+        if (!roots.some((r) => isInside(real, r)) || current.dev !== opened.dev || current.ino !== opened.ino) {
+            throw new AccessError(`Access denied: ${label} changed while it was being read`);
+        }
+        // Another name of the same file may lie outside the allowed folders,
+        // and where it lies cannot be found out, so such files are refused.
+        // Both counts: the handle's alone can read 1 while the path is swapped.
+        const links = opened.nlink > current.nlink ? opened.nlink : current.nlink;
+        if (links > 1n) {
+            throw new HardlinkError(`Access denied: ${label} has ${links} hard links; files with more than one are refused`);
+        }
+        const buffer = Buffer.alloc(Number(opened.size) + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead) break;
+            length += bytesRead;
+        }
+        if (length > maxFileBytes) throw new TooLargeError(`File too large: ${label} grew past the limit of ${maxFileBytes} bytes`);
+        if (length === buffer.length) throw new AccessError(`Access denied: ${label} changed while it was being read`);
+        return buffer.toString("utf8", 0, length);
+    } finally {
+        await handle.close();
+    }
+}
 
 const SKIP_DIRS = new Set(["node_modules", ".git", "__pycache__", "venv", "site-packages"]);
 const RISK_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
@@ -26,7 +81,7 @@ async function analyzeFile(requested, roots, { maxFileBytes }) {
     if (stat.size > maxFileBytes) {
         throw new AccessError(`File too large: ${requested} is ${stat.size} bytes, limit is ${maxFileBytes}`);
     }
-    const code = await fs.readFile(real, "utf8");
+    const code = await readInside(real, roots, maxFileBytes, requested);
     return analyzeCode(code, display);
 }
 
@@ -34,12 +89,20 @@ async function analyzeFile(requested, roots, { maxFileBytes }) {
 // __pycache__, venv, site-packages and hidden folders are skipped.
 async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
     const files = [];
-    const skipped = { tooLarge: [], symlinks: 0, unreadable: [] };
+    const skipped = { tooLarge: [], symlinks: 0, unreadable: [], hardlinks: [] };
     let truncated = false;
     const queue = [dir];
     while (queue.length && !truncated) {
         const current = queue.shift();
-        const entries = (await fs.readdir(current, { withFileTypes: true }))
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        } catch {
+            // Removed or made unreadable while the scan runs.
+            skipped.unreadable.push(path.relative(root, current).split(path.sep).join("/") || ".");
+            continue;
+        }
+        entries = entries
             .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
         for (const entry of entries) {
             const full = path.join(current, entry.name);
@@ -49,7 +112,13 @@ async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
             } else if (entry.isDirectory()) {
                 if (recursive && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) queue.push(full);
             } else if (entry.isFile() && isSourceFile(entry.name)) {
-                const { size } = await fs.stat(full);
+                let size;
+                try {
+                    ({ size } = await fs.lstat(full));
+                } catch {
+                    skipped.unreadable.push(rel);
+                    continue;
+                }
                 if (size > maxFileBytes) {
                     skipped.tooLarge.push(rel);
                 } else if (files.length >= maxFiles) {
@@ -64,20 +133,30 @@ async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
     return { files, skipped, truncated };
 }
 
-async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recursive = true }) {
+async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity }) {
+    const started = Date.now();
     const { real, root, display } = resolveInside(requested, roots);
     const stat = await fs.stat(real);
     if (!stat.isDirectory()) throw new AccessError(`Not a folder: ${requested}`);
 
     const { files, skipped, truncated } = await collectFiles(real, root, { maxFiles, maxFileBytes, recursive });
     const results = [];
+    const notAnalyzed = [];
     for (const { full, rel } of files) {
+        // A running analysis cannot be interrupted, so the budget only stops
+        // new files from starting; the rest are listed in notAnalyzed.
+        if (notAnalyzed.length || Date.now() - started >= timeBudgetMs) {
+            notAnalyzed.push(rel);
+            continue;
+        }
         // One file that cannot be read or analyzed must not hide the others.
         let ir;
         try {
-            ir = await analyzeCode(await fs.readFile(full, "utf8"), rel);
-        } catch {
-            skipped.unreadable.push(rel);
+            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel), rel);
+        } catch (err) {
+            const list = err instanceof TooLargeError ? skipped.tooLarge
+                : err instanceof HardlinkError ? skipped.hardlinks : skipped.unreadable;
+            list.push(rel);
             continue;
         }
         results.push({
@@ -107,6 +186,8 @@ async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recu
         analyzed: results.length,
         truncated,
         maxFiles,
+        timedOut: notAnalyzed.length > 0,
+        notAnalyzed,
         skipped,
         riskCounts,
         statusCounts,
@@ -115,4 +196,4 @@ async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recu
     };
 }
 
-module.exports = { analyzeCode, analyzeFile, analyzeDirectory, SKIP_DIRS };
+module.exports = { analyzeCode, analyzeFile, analyzeDirectory, readInside, SKIP_DIRS };

package/src/clients.js

@@ -4,7 +4,7 @@ const os = require("os");
 const path = require("path");
 
 const SERVER_NAME = "sentinel-ir";
-const PACKAGE_SPEC = "sentinel-ir-mcp@0.3";
+const PACKAGE_SPEC = "sentinel-ir-mcp@0.4";
 const WORKSPACE_VAR = "${workspaceFolder}";
 
 function homeOf(env) {

package/src/doctor.js

@@ -10,7 +10,7 @@ const { readConfig } = require("./setup");
 
 const BIN = path.join(__dirname, "..", "bin", "sentinel-ir-mcp.js");
 const EXPECTED_TOOLS = ["analyze_code", "analyze_directory", "analyze_file"];
-const VALUE_OPTIONS = new Set(["--max-file-bytes", "--max-files"]);
+const VALUE_OPTIONS = new Set(["--max-file-bytes", "--max-files", "--time-budget-ms"]);
 
 function irVersion() {
     try {
@@ -67,8 +67,8 @@ function checkConfig(client, file, explicit, project, add, platform) {
     const runs = `${label}: "${SERVER_NAME}" runs ${entry.command} ${args.join(" ")}`;
     if (entry.command === "npx" && platform === "win32") {
         add("warn", `${client}.entry`, runs, `On Windows a client may not find "npx" without a shell. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
-    } else if (args.some(a => /^sentinel-ir-mcp@0\.[0-2](\.|$)/.test(a))) {
-        add("warn", `${client}.entry`, runs, `This entry stays on an older version without Python support. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
+    } else if (args.some(a => /^sentinel-ir-mcp@0\.[0-3](\.|$)/.test(a))) {
+        add("warn", `${client}.entry`, runs, `This entry stays on an older version without native-code detection, whose parser stops working in long sessions. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
     } else if (entry.command === "npx" || isWindowsNpxWrapper(entry)) {
         add("ok", `${client}.entry`, runs);
     } else {

package/src/guide.js

@@ -8,9 +8,12 @@ env reads and network/filesystem/process/crypto calls. It reads files only.
 
 Recommended order:
 1. Call analyze_directory on the project (or a sub-folder) first.
-2. Look at "incomplete" and "skipped.unreadable" before anything else. Those
+2. Look at "incomplete", "skipped.unreadable" and "skipped.hardlinks" before
+   anything else. Those
    files were not fully analyzed: a low risk there is NOT evidence of safety.
-   Read their raw source if they matter.
+   Read their raw source if they matter. If "timedOut" is true, the files in
+   "notAnalyzed" were not analyzed at all: call analyze_directory on a
+   sub-folder or analyze_file for them.
 3. Pick the relevant files from "files" (sorted from highest to lowest risk).
 4. Call analyze_file for the full IR of a single file.
 5. Read raw source only for the files you actually need to change or verify.

package/src/server.js

@@ -8,6 +8,12 @@ const { analyzeCode, analyzeFile, analyzeDirectory } = require("./analyze");
 
 const DEFAULT_LIMITS = Object.freeze({
     maxFileBytes: 1024 * 1024,
+    // 4 MiB of JavaScript aborts the process on Windows CI (3 GB on Linux).
+    hardMaxFileBytes: 2 * 1024 * 1024,
+    // Plus one 1 MiB file (up to 23 s on Windows CI) stays below the 60 s
+    // request timeout of MCP SDK clients.
+    timeBudgetMs: 30000,
+    hardMaxTimeBudgetMs: 600000,
     maxFiles: 50,
     hardMaxFiles: 500
 });
@@ -30,7 +36,7 @@ const INSTRUCTIONS =
     "or risk, then read the raw source of the files that matter. Supported: JavaScript (.js, .mjs, .cjs), TypeScript (.ts, .mts, .cts, .tsx) and Python (.py, .pyi); the language is picked from the file extension. " +
     "Rely on analysisStatus, world.risk, forbidden and facts; analysisStatus \"incomplete\" means the file did not parse cleanly. " +
     "analyze_directory lists such files separately in 'incomplete'; their low risk is not evidence of safety. " +
-    "Suggested order: analyze_directory first, check 'incomplete' and 'skipped.unreadable', pick the relevant files, " +
+    "Suggested order: analyze_directory first, check 'incomplete', 'skipped.unreadable' and 'notAnalyzed' (set when the time budget ran out), pick the relevant files, " +
     "then analyze_file, and read raw source only where needed. " +
     "Read-only: nothing is written, executed or sent over the network. " + UNTRUSTED_NOTE;
 
@@ -56,8 +62,9 @@ async function guarded(fn) {
 
 function createServer(options = {}) {
     const limits = {
-        maxFileBytes: options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes,
-        maxFiles: options.maxFiles ?? DEFAULT_LIMITS.maxFiles
+        maxFileBytes: Math.min(options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes, DEFAULT_LIMITS.hardMaxFileBytes),
+        maxFiles: options.maxFiles ?? DEFAULT_LIMITS.maxFiles,
+        timeBudgetMs: Math.min(options.timeBudgetMs ?? DEFAULT_LIMITS.timeBudgetMs, DEFAULT_LIMITS.hardMaxTimeBudgetMs)
     };
     const fixedRoots = canonicalRoots(options.roots || []);
 
@@ -112,6 +119,9 @@ function createServer(options = {}) {
             "you when there were more. 'incomplete' lists files whose analysis did not finish (e.g. parse errors); " +
             "their risk is not reliable, check them separately. statusCounts counts complete vs incomplete. " +
             "Files that could not be read are listed in skipped.unreadable and are not counted as analyzed. " +
+            "Files with more than one hard link are refused and listed in skipped.hardlinks. " +
+            `No new file is started after ${limits.timeBudgetMs / 1000} s: then timedOut is true and the remaining files are in notAnalyzed; ` +
+            "call again on a subfolder or use analyze_file for them. " +
             "Use analyze_file for the full IR of a single file. " + UNTRUSTED_NOTE,
         inputSchema: {
             path: z.string().min(1).optional().describe("Folder path, absolute or relative to the first allowed folder (default: the first allowed folder)"),
@@ -124,6 +134,7 @@ function createServer(options = {}) {
         analyzeDirectory(path ?? ".", await allowedRoots(), {
             maxFiles: max_files ?? limits.maxFiles,
             maxFileBytes: limits.maxFileBytes,
+            timeBudgetMs: limits.timeBudgetMs,
             recursive: recursive ?? true
         })));