sentinel-ir-mcp 0.4.2 → 0.4.4

package/README.md

@@ -25,6 +25,39 @@ 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.4** can keep a log of what the agent asked for (off unless you turn it on):
+
+- **One question in `setup`:** *"Keep a log of what the agent asks for (file
+  names and results, never your code)? [y/N]"*. Or `setup --audit-log`;
+  `--no-audit-log` turns it off. Running `setup` again keeps the setting.
+- **One command to read it:** `npx -y sentinel-ir-mcp@0.4 log` prints the last
+  50 entries as plain lines, `--all` everything, `--json` for scripts:
+
+  ```text
+  2026-10-18 10:32:05 [cursor] file src/app.js: critical
+  2026-10-18 10:32:09 [cursor] REFUSED file secrets/aws.js: excluded by your settings
+  2026-10-18 10:33:40 [cursor] folder .: 42 file(s) (1 critical, 6 medium, 35 low), 3 excluded
+      critical src/app.js
+  ```
+- `doctor` says whether the log is on, where it is and how big, and proves the
+  log can be written. Details: [Audit log](#audit-log).
+
+Also uses `sentinel-ir` 0.4.5 (Python parse errors point where Python does).
+
+**0.4.3** lets you exclude files and folders:
+
+- **One question in `setup`:** *"Files or folders the agent must not read"*,
+  e.g. `secrets, dist, *.min.js` (Enter = none). Or `setup --exclude secrets
+  --exclude dist`. `setup` writes them into the client config, so there is no
+  JSON to edit; running it again keeps them, `--no-exclude` removes them.
+- **Set by you only.** The agent cannot change them, and the analyzed project
+  cannot either: there is no `.sentinelignore`, because a repository could use
+  it to hide its own files.
+- `analyze_file` refuses an excluded path whether or not it exists;
+  `analyze_directory` only counts excluded entries in `skipped.excluded`,
+  because their names can be private too. `doctor` lists the exclusions and
+  how many files and folders they skip in the project.
+
 **0.4.2** makes `analyze_directory` short by default:
 
 - **Short entries:** each file is `{path, risk, analysisStatus, language,
@@ -89,7 +122,7 @@ of safety. Other languages are not supported yet. What is detected in Python
 |---|---|---|
 | `analyze_code` | `code` (string), optional `target` (file name) | compact IR of the given source |
 | `analyze_file` | `path` | compact IR of one file inside the allowed folders |
-| `analyze_directory` | optional `path`, `max_files` (default 50, max 500), `recursive` (default `true`), `detail` (`"summary"` default, or `"full"`) | one short entry per file (path, risk, status, language, lines, operations, up to 3 risk signals; `"full"`: all facts), sorted from highest to lowest risk, plus `riskCounts`, `statusCounts` and `incomplete` (paths whose analysis did not finish; check them separately, their low risk is not evidence of safety); files that could not be read are listed in `skipped.unreadable` and are not counted as analyzed, `truncated` and `skipped` |
+| `analyze_directory` | optional `path`, `max_files` (default 50, max 500), `recursive` (default `true`), `detail` (`"summary"` default, or `"full"`) | one short entry per file (path, risk, status, language, lines, operations, up to 3 risk signals; `"full"`: all facts), sorted from highest to lowest risk, plus `riskCounts`, `statusCounts` and `incomplete` (paths whose analysis did not finish; check them separately, their low risk is not evidence of safety); files that could not be read are listed in `skipped.unreadable` and are not counted as analyzed; excluded files and folders are only counted in `skipped.excluded`; `truncated` and `skipped` |
 
 Every tool returns the result twice: as JSON text (for clients that only read
 text) and as `structuredContent`. All three are annotated
@@ -144,6 +177,8 @@ npx -y sentinel-ir-mcp@0.4 guide                     # optional: text for AGENTS
   refuses your home folder or a whole disk;
 - writes `sentinel-ir-mcp@0.4`, so clients get 0.4.x fixes but no unexpected
   new features;
+- asks which files or folders the agent must not read (`--exclude <name>`,
+  repeatable, skips the question; see [Excluding files](#excluding-files));
 - for VS Code and Claude Code it writes nothing and prints their own install
   command (`code --add-mcp ...`, `claude mcp add ...`) instead.
 
@@ -164,12 +199,14 @@ command. What was measured on which system: [COMPATIBILITY.md](COMPATIBILITY.md)
 `"sentinel-ir"` entry that starts `sentinel-ir-mcp`, existing folders), then
 starts **its own** server with the same folders, performs a real MCP
 handshake, expects exactly the three tools and calls `analyze_directory` with
-`max_files: 1`. It never runs the command stored in the client config. Exit
+`max_files: 1`. It lists your exclusions, how many files and folders they skip
+in the project right now, and warns about one that matches nothing (a typo).
+It never runs the command stored in the client config. Exit
 code 0 when everything passes, 1 otherwise; `--json` gives a machine-readable
 report.
 
 Only `setup` writes files, and only the client config. The MCP server itself
-stays read-only.
+reads only; the one exception is the [audit log](#audit-log), if you turn it on.
 
 **Cursor:** a server from a project `.cursor/mcp.json` starts switched off.
 Open Cursor Settings → Customize → MCPs and turn on the switch next to
@@ -274,10 +311,84 @@ 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.
 
+### Excluding files
+
+```bash
+npx -y sentinel-ir-mcp@0.4 setup --client cursor --exclude secrets --exclude "*.min.js"
+```
+
+| you write | excludes |
+|---|---|
+| `secrets` | every file or folder named `secrets`, anywhere in the project, with everything inside |
+| `config/prod.js` | only this path, relative to the project folder |
+| `*.min.js` | files by mask; `*` and `?` stay within one name |
+| `generated/**/out` | `**` stands for any number of folders |
+
+- Only additions: there is no `!` to re-include something. Absolute paths,
+  `..` and the characters `" & | < > ^ % !` are refused.
+- Windows `\` works like `/`. On Windows and macOS letter case does not
+  matter (`SECRETS/a.js` is excluded by `secrets`), on Linux it does.
+- The check uses the real path, so `lib/../secrets/a.js`, a symlink to an
+  excluded file and a Windows short name (`SECRE~1`) are refused too. It is
+  repeated when the file is opened.
+- `analyze_code` is not affected: it analyzes text the agent already has.
+
+The exclusions only bind this server. An agent that can read files with
+other tools of its client is told about them, but this server cannot stop it.
+
+### Audit log
+
+```bash
+npx -y sentinel-ir-mcp@0.4 setup --client cursor --audit-log   # or answer "y" in setup
+npx -y sentinel-ir-mcp@0.4 log                                 # what the agent asked for
+```
+
+| system | folder |
+|---|---|
+| Windows | `%LOCALAPPDATA%\sentinel-ir-mcp\audit-log\` |
+| macOS | `~/Library/Logs/sentinel-ir-mcp/` |
+| Linux | `~/.local/state/sentinel-ir-mcp/audit-log/` (or `$XDG_STATE_HOME`) |
+
+`--audit-log=<folder>` uses another folder: a full path outside the project
+(the characters `" & | < > ^ % !` are refused because Windows starts the
+server through `cmd`). Then read it with `log --dir <folder>`.
+
+- **What is written:** one JSON line per tool call in `audit-YYYY-MM-DD.jsonl`
+  (local date): time, client name, tool, the path the agent asked for, the
+  result (risk, `analysisStatus`, file counts, up to 20 `critical`/`high` file
+  paths of a folder) or why it was refused (`excluded`, `outside`,
+  `not-found`, `too-large`), and the duration. A line when the server starts.
+- **What is not written:** source code. For `analyze_code` only the size in
+  bytes, the language and the risk. Names of excluded files are not written
+  either, only their count. Long values are cut to 300 characters.
+- **Cleanup:** day files older than 30 days are deleted; a day stops 1 MB
+  below 50 MB with one line saying so, so parallel servers stay under 50 MB
+  too. Other files in the folder are never touched.
+- **Set by you only,** like exclusions: the agent and the project cannot turn
+  it on, off or move it. The log is never written inside the project.
+- **Safe to read:** a path with a newline cannot add a fake line (JSON
+  escapes it), and `log` shows control and bidi characters as `\u{1b}`, so a
+  path cannot recolor or rewrite your terminal.
+- **Never breaks the tools:** when the log cannot be written (disk full, no
+  permission) the tools answer as usual and the server says so once on stderr;
+  `doctor` reports it as `[FAIL]`. Several servers can share the folder: each
+  line is one append, so lines do not mix.
+- `doctor` adds one line, `doctor checked that the log can be written`, and
+  none of its own tool calls.
+- A day file that is a symlink, junction or hard link is not written to, on
+  Windows too, so the log cannot be used to overwrite another file.
+- It records only what the agent asked **this server** for. Other file tools
+  of your AI app are not in it.
+- Files are created readable by you only (`0600`, folder `0700`; on Windows
+  the folder in `%LOCALAPPDATA%` is private to your account).
+
 ### Options
 
 ```text
-sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
+sentinel-ir-mcp [--exclude <name>]... [--audit-log[=<folder>]] [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
+
+  --exclude <name>       file or folder the file tools refuse (repeatable, max 100); see Excluding files
+  --audit-log[=<folder>] keep a log of the tool calls (never source code); see Audit log
 
   --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)
@@ -286,14 +397,19 @@ sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>]
 
 ## What the server can and cannot do
 
-- **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`/`.py`/`.pyi` files up to
+- **Reads only.** The MCP server never writes project files, runs commands or
+  opens network connections. It writes only the [audit log](#audit-log) when
+  you turn it on (outside the project). The separate `setup` command writes
+  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`/`.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.
+- **Exclusions are yours.** They come only from the command line the client
+  starts (written by `setup`), never from the agent or from files in the
+  project. Excluded paths are refused by `analyze_file` and counted, not
+  named, in `skipped.excluded`.
 - **`analyze_directory`** skips `node_modules`, `.git`, hidden folders and
   every symlink, and stops after `max_files` files (`truncated: true`) or
   when the time budget is spent (`timedOut: true`, rest in `notAnalyzed`).

package/bin/sentinel-ir-mcp.js

@@ -8,29 +8,41 @@ const fs = require("fs");
 const path = require("path");
 const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
 const { createServer, DEFAULT_LIMITS } = require("../src/server");
+const { normalizePattern, ExcludeError, MAX_PATTERNS } = require("../src/exclude");
+const { AuditLogError, defaultAuditDir, normalizeAuditDir, assertOutsideProjects } = require("../src/auditLog");
 const { version } = require("../package.json");
 
-const USAGE = `sentinel-ir-mcp ${version} — MCP server for sentinel-ir (JavaScript and TypeScript)
+const USAGE = `sentinel-ir-mcp ${version} — MCP server for sentinel-ir (JavaScript, TypeScript and Python)
 
 Usage: sentinel-ir-mcp [options] [folder ...]
-       sentinel-ir-mcp setup | doctor | guide [--help]
+       sentinel-ir-mcp setup | doctor | guide | log [--help]
 
   setup                  Connect Sentinel-IR to an AI client (shows the change first)
   doctor                 Check Node.js, the client config and a real MCP connection
   guide                  Print short usage instructions for AI agents
+  log                    Show what the agent asked for (needs --audit-log)
 
   folder                 Folder(s) the file tools may read. A folder named like a
-                         command must be written as ./setup, ./doctor or ./guide. Without folders the
-                         server uses the MCP roots offered by the client; if the
+                         command must be written as ./setup, ./doctor, ./guide or
+                         ./log. Without folders the server uses the MCP roots offered by the client; if the
                          client offers none, only analyze_code works.
+  --exclude <name>       A file or folder the file tools must refuse; repeat for more.
+                         secrets = any file or folder named so, config/prod.js =
+                         this path in an allowed folder, *.min.js = by mask,
+                         ** = any folders. Set by you; the project cannot change it.
+  --audit-log            Write a log of what the agent asks this server for (paths,
+                         results, refusals; never source code) to
+                         ${defaultAuditDir()}
+  --audit-log=<folder>   The same log in another folder (a full path outside the project)
   --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
 
-The server only reads files. It never writes, executes or uses the network.
-Only "setup" writes, and only the client config file you confirm.`;
+The server only reads files. It never executes code or uses the network, and it
+writes nothing except the audit log when you turn it on. "setup" writes only the
+client config file you confirm. See the log with: sentinel-ir-mcp log`;
 
 function die(message) {
     process.stderr.write(`sentinel-ir-mcp: ${message}\n\n${USAGE}\n`);
@@ -44,7 +56,7 @@ const NUMBER_OPTIONS = {
 };
 
 function parseArgs(argv) {
-    const opts = { roots: [] };
+    const opts = { roots: [], exclude: [] };
     for (let i = 0; i < argv.length; i++) {
         let arg = argv[i];
         let value;
@@ -57,6 +69,19 @@ function parseArgs(argv) {
             const n = Number(value);
             if (!Number.isInteger(n) || n < 1 || n > max) die(`${arg} must be an integer between 1 and ${max}`);
             opts[key] = n;
+        } else if (arg === "--exclude") {
+            if (value === undefined) value = argv[++i];
+            if (value === undefined) die("--exclude needs a value");
+            try { opts.exclude.push(normalizePattern(value)); } catch (e) {
+                if (!(e instanceof ExcludeError)) throw e;
+                die(e.message);
+            }
+            if (opts.exclude.length > MAX_PATTERNS) die(`at most ${MAX_PATTERNS} --exclude options`);
+        } else if (arg === "--audit-log") {
+            try { opts.auditDir = value === undefined ? defaultAuditDir() : normalizeAuditDir(value); } catch (e) {
+                if (!(e instanceof AuditLogError)) throw e;
+                die(e.message);
+            }
         } else if (arg.startsWith("-")) {
             die(`unknown option ${arg}`);
         } else {
@@ -67,6 +92,12 @@ function parseArgs(argv) {
             opts.roots.push(dir);
         }
     }
+    if (opts.auditDir) {
+        try { assertOutsideProjects(opts.auditDir, opts.roots); } catch (e) {
+            if (!(e instanceof AuditLogError)) throw e;
+            die(e.message);
+        }
+    }
     return opts;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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.4.3",
+    "sentinel-ir": "^0.4.5",
     "zod": "^4.1.0"
   },
   "keywords": [

package/src/analyze.js

@@ -5,6 +5,7 @@ const { constants, realpathSync } = require("fs");
 const path = require("path");
 const { analyzeAsync, compress } = require("sentinel-ir");
 const { AccessError, resolveInside, isInside, isSourceFile } = require("./paths");
+const { isExcluded, NONE } = require("./exclude");
 
 // 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.
@@ -12,12 +13,29 @@ const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants
 
 class TooLargeError extends AccessError {}
 class HardlinkError extends AccessError {}
+class ExcludedError extends AccessError {}
+
+function excludedError(label) {
+    return new ExcludedError(`Excluded by the user's settings: ${label}. Do not try to read it another way.`);
+}
+
+// Checked before the path is looked up, so the answer is the same whether or
+// not the excluded file exists, and again on the real path (symlinks, "..",
+// Windows short names, letter case).
+function resolveAllowed(requested, roots, excluder) {
+    if (excluder.active && roots.length && typeof requested === "string" && requested.trim() !== "" && !requested.includes("\0")) {
+        if (isExcluded(path.resolve(roots[0], requested), roots, excluder)) throw excludedError(requested);
+    }
+    const resolved = resolveInside(requested, roots);
+    if (isExcluded(resolved.real, roots, excluder)) throw excludedError(requested);
+    return resolved;
+}
 
 // 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) {
+async function readInside(full, roots, maxFileBytes, label, excluder = NONE) {
     let handle;
     try {
         handle = await fs.open(full, OPEN_FLAGS);
@@ -38,6 +56,7 @@ async function readInside(full, roots, maxFileBytes, label) {
         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`);
         }
+        if (isExcluded(real, roots, excluder)) throw excludedError(label);
         // 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.
@@ -60,6 +79,10 @@ async function readInside(full, roots, maxFileBytes, label) {
     }
 }
 
+function realNative(p) {
+    try { return realpathSync.native(p); } catch { return p; }
+}
+
 const SKIP_DIRS = new Set(["node_modules", ".git", "__pycache__", "venv", "site-packages"]);
 const RISK_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
 
@@ -71,8 +94,8 @@ async function analyzeCode(code, target, language) {
     return compress(ir);
 }
 
-async function analyzeFile(requested, roots, { maxFileBytes }) {
-    const { real, display } = resolveInside(requested, roots);
+async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE }) {
+    const { real, display } = resolveAllowed(requested, roots, excluder);
     const stat = await fs.stat(real);
     if (!stat.isFile()) throw new AccessError(`Not a file: ${requested}`);
     if (!isSourceFile(real)) {
@@ -81,15 +104,19 @@ 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 readInside(real, roots, maxFileBytes, requested);
+    const code = await readInside(real, roots, maxFileBytes, requested, excluder);
     return analyzeCode(code, display);
 }
 
 // Breadth-first, sorted walk. Symlinks are never followed; node_modules, .git,
-// __pycache__, venv, site-packages and hidden folders are skipped.
-async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
+// __pycache__, venv, site-packages and hidden folders are skipped. Excluded
+// files and folders are only counted: their names can be private too.
+async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive, excluder = NONE }) {
     const files = [];
-    const skipped = { tooLarge: [], symlinks: 0, unreadable: [], hardlinks: [] };
+    const skipped = { excluded: 0, tooLarge: [], symlinks: 0, unreadable: [], hardlinks: [] };
+    // Exclusions match the real names: on Windows dir may be spelled with
+    // short names (SRC~1) that the patterns do not know.
+    const prefix = excluder.active ? path.relative(realNative(root), realNative(dir)) : "";
     let truncated = false;
     const queue = [dir];
     while (queue.length && !truncated) {
@@ -107,7 +134,9 @@ async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
         for (const entry of entries) {
             const full = path.join(current, entry.name);
             const rel = path.relative(root, full).split(path.sep).join("/");
-            if (entry.isSymbolicLink()) {
+            if (excluder.active && excluder.matches(path.join(prefix, path.relative(dir, full)))) {
+                skipped.excluded++;
+            } else if (entry.isSymbolicLink()) {
                 skipped.symlinks++;
             } else if (entry.isDirectory()) {
                 if (recursive && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) queue.push(full);
@@ -192,14 +221,14 @@ function fullEntry(rel, ir) {
 async function analyzeDirectory(
     requested,
     roots,
-    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary" }
+    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary", excluder = NONE }
 ) {
     const started = Date.now();
-    const { real, root, display } = resolveInside(requested, roots);
+    const { real, root, display } = resolveAllowed(requested, roots, excluder);
     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 { files, skipped, truncated } = await collectFiles(real, root, { maxFiles, maxFileBytes, recursive, excluder });
     const results = [];
     const notAnalyzed = [];
     for (const { full, rel } of files) {
@@ -212,8 +241,12 @@ async function analyzeDirectory(
         // One file that cannot be read or analyzed must not hide the others.
         let ir;
         try {
-            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel), rel);
+            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel, excluder), rel);
         } catch (err) {
+            if (err instanceof ExcludedError) {
+                skipped.excluded++;
+                continue;
+            }
             const list = err instanceof TooLargeError ? skipped.tooLarge
                 : err instanceof HardlinkError ? skipped.hardlinks : skipped.unreadable;
             list.push(rel);

package/src/auditLog.js

@@ -0,0 +1,204 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { homeOf } = require("./clients");
+
+// An optional record, for the user, of what the agent asked this server for.
+// One JSON object per line in one file per local day; never any source code.
+// Turned on only by the user (--audit-log on the command line the client
+// starts), never by the agent or by files in the project.
+
+const FILE_RE = /^audit-(\d{4})-(\d{2})-(\d{2})\.jsonl$/;
+const KEEP_DAYS = 30;
+const MAX_DAY_BYTES = 50 * 1024 * 1024;
+// A day stops this far below the limit, so lines that parallel servers append
+// in the same instant still end below MAX_DAY_BYTES (a line is at most ~10 kB).
+const DAY_RESERVE = 1024 * 1024;
+const MAX_TEXT = 300;
+const MAX_LISTED = 20;
+// Characters cmd.exe acts on: an MCP entry on Windows runs through "cmd /c".
+const UNSAFE_DIR = /["&|<>^%!\u0000-\u001f]/;
+const OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0);
+
+class AuditLogError extends Error {}
+
+function defaultAuditDir(env = process.env, platform = process.platform) {
+    if (platform === "win32") {
+        const local = env.LOCALAPPDATA || path.join(homeOf(env), "AppData", "Local");
+        return path.join(local, "sentinel-ir-mcp", "audit-log");
+    }
+    if (platform === "darwin") return path.join(homeOf(env), "Library", "Logs", "sentinel-ir-mcp");
+    const state = env.XDG_STATE_HOME || path.join(homeOf(env), ".local", "state");
+    return path.join(state, "sentinel-ir-mcp", "audit-log");
+}
+
+// "--audit-log" (default folder) or "--audit-log=<folder>"; must be absolute
+// because a client starts the server from a folder you do not choose.
+function normalizeAuditDir(raw) {
+    if (typeof raw !== "string" || raw.trim() === "") throw new AuditLogError("--audit-log=<folder> needs a folder");
+    const dir = raw.trim();
+    if (UNSAFE_DIR.test(dir)) throw new AuditLogError(`audit log folder "${raw}" contains a character that is not allowed (" & | < > ^ % !)`);
+    if (!path.isAbsolute(dir)) throw new AuditLogError(`audit log folder "${raw}" must be a full path, e.g. ${process.platform === "win32" ? "C:\\logs\\sentinel" : "/home/me/logs"}`);
+    return path.resolve(dir);
+}
+
+function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+function realOrResolved(p) {
+    // The folder may not exist yet: resolve its nearest existing parent.
+    let current = path.resolve(p);
+    const rest = [];
+    for (;;) {
+        try { return path.join(fs.realpathSync(current), ...rest.reverse()); } catch { /* go up */ }
+        const parent = path.dirname(current);
+        if (parent === current) return path.resolve(p);
+        rest.push(path.basename(current));
+        current = parent;
+    }
+}
+
+// A log inside the project could be committed or read by the agent.
+function assertOutsideProjects(dir, projects, caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    const fold = (p) => (caseInsensitive ? p.toLowerCase() : p);
+    const real = fold(realOrResolved(dir));
+    for (const project of projects) {
+        if (isInside(real, fold(realOrResolved(project)))) {
+            throw new AuditLogError(`the audit log folder ${dir} is inside the project folder ${project}; pick a folder outside it`);
+        }
+    }
+}
+
+function pad(n) { return String(n).padStart(2, "0"); }
+function dayName(date) { return `audit-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}.jsonl`; }
+
+function cut(value, max = MAX_TEXT) {
+    if (typeof value !== "string") return value;
+    if (value.length <= max) return value;
+    let end = max;
+    const code = value.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff) end--;
+    return value.slice(0, end) + "…";
+}
+
+function logFiles(dir) {
+    let names;
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => FILE_RE.test(n)).sort();
+}
+
+function pruneOld(dir, now) {
+    const limit = new Date(now);
+    limit.setHours(0, 0, 0, 0);
+    limit.setDate(limit.getDate() - KEEP_DAYS);
+    for (const name of logFiles(dir)) {
+        const [, y, m, d] = FILE_RE.exec(name);
+        if (new Date(Number(y), Number(m) - 1, Number(d)) < limit) {
+            try {
+                if (fs.lstatSync(path.join(dir, name)).isFile()) fs.unlinkSync(path.join(dir, name));
+            } catch { /* another server may have removed it */ }
+        }
+    }
+}
+
+// What a tool call is logged as: what was asked and the outcome, no code.
+function describeCall(tool, args, outcome) {
+    const entry = { tool };
+    if (tool === "analyze_code") {
+        entry.bytes = Buffer.byteLength(typeof args.code === "string" ? args.code : "", "utf8");
+        if (typeof args.target === "string") entry.target = cut(args.target);
+        if (typeof args.language === "string") entry.language = args.language;
+    } else {
+        entry.path = cut(typeof args.path === "string" ? args.path : ".");
+        if (tool === "analyze_directory") {
+            for (const [k, v] of [["max_files", args.max_files], ["recursive", args.recursive], ["detail", args.detail]]) if (v !== undefined) entry[k] = v;
+        }
+    }
+    if (outcome.error) {
+        entry.ok = false;
+        entry.reason = outcome.reason;
+        entry.message = cut(outcome.error);
+        return entry;
+    }
+    entry.ok = true;
+    const r = outcome.result;
+    if (tool === "analyze_directory") {
+        entry.analyzed = r.analyzed;
+        entry.riskCounts = r.riskCounts;
+        entry.incomplete = r.incomplete.length;
+        entry.excluded = r.skipped.excluded;
+        const notRead = r.skipped.tooLarge.length + r.skipped.unreadable.length + r.skipped.hardlinks.length;
+        if (notRead) entry.notRead = notRead;
+        if (r.truncated) entry.truncated = true;
+        if (r.timedOut) entry.timedOut = true;
+        const top = r.files.filter((f) => f.risk === "critical" || f.risk === "high").slice(0, MAX_LISTED);
+        if (top.length) entry.top = top.map((f) => ({ path: cut(f.path), risk: f.risk }));
+    } else {
+        entry.risk = r.world && r.world.risk;
+        entry.analysisStatus = r.analysisStatus;
+        entry.language = r.language;
+        if (tool === "analyze_file" && r.mission && typeof r.mission.target === "string") entry.file = cut(r.mission.target);
+    }
+    return entry;
+}
+
+function createAuditLog({ dir, now = () => Date.now(), onError = (m) => process.stderr.write(`sentinel-ir-mcp: ${m}\n`) } = {}) {
+    if (!dir) return { active: false, record() {}, flush: async () => {} };
+    let queue = Promise.resolve();
+    let prunedFor = null;
+    let fullDay = null;
+    let failed = false;
+
+    async function append(line, file) {
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        // Once per server and day, so a server running for weeks still cleans up.
+        if (prunedFor !== file) { prunedFor = file; pruneOld(dir, now()); }
+        // Windows has no O_NOFOLLOW, so the checks below refuse a day file that
+        // is a symlink, junction or hard link on every system before any write.
+        const before = await fs.promises.lstat(file, { bigint: true }).catch((e) => {
+            if (e.code === "ENOENT") return null;
+            throw e;
+        });
+        if (before && !before.isFile()) throw new Error(`${file} is not a regular file`);
+        const handle = await fs.promises.open(file, OPEN_FLAGS, 0o600);
+        try {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile()) throw new Error(`${file} is not a regular file`);
+            if (stat.nlink > 1n) throw new Error(`${file} has a second name (hard link); not writing`);
+            const after = await fs.promises.lstat(file, { bigint: true });
+            const same = (a) => a.isFile() && a.ino === stat.ino && a.dev === stat.dev;
+            if (!same(after) || (before && !same(before))) throw new Error(`${file} was replaced while opening; not writing`);
+            if (stat.size + BigInt(Buffer.byteLength(line)) > BigInt(MAX_DAY_BYTES - DAY_RESERVE)) {
+                if (fullDay !== file) {
+                    fullDay = file;
+                    await handle.write(JSON.stringify({ ts: new Date(now()).toISOString(), event: "full", limitBytes: MAX_DAY_BYTES }) + "\n");
+                }
+                return;
+            }
+            // One write per line: with O_APPEND lines of parallel servers do not interleave.
+            await handle.write(line);
+        } finally {
+            await handle.close();
+        }
+    }
+
+    function record(entry) {
+        const date = new Date(now());
+        const line = JSON.stringify({ ts: date.toISOString(), pid: process.pid, ...entry }) + "\n";
+        const file = path.join(dir, dayName(date));
+        queue = queue.then(() => append(line, file)).then(() => { failed = false; }, (err) => {
+            if (!failed) onError(`cannot write the audit log in ${dir}: ${err.message}`);
+            failed = true;
+        });
+    }
+
+    return { active: true, dir, record, flush: () => queue };
+}
+
+module.exports = {
+    AuditLogError, KEEP_DAYS, MAX_DAY_BYTES, FILE_RE,
+    defaultAuditDir, normalizeAuditDir, assertOutsideProjects, createAuditLog, describeCall, logFiles, dayName, cut
+};