Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

perf(server): bound the exec tool mtime safety sweep (#2732)

Andrew Mikofalvyf5d4692af9c6
diff --git a/.changeset/exec-mtime-sweep-bounding.md b/.changeset/exec-mtime-sweep-bounding.md
new file mode 100644
index 000000000..d9c0d504c
--- /dev/null
+++ b/.changeset/exec-mtime-sweep-bounding.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The `exec` MCP tool's post-command mutation safety sweep is now scoped to the paths the command can actually touch (its own path operands), instead of statting up to 1000 files across the whole knowledge base twice on every call. Path-scoped commands like `cat notes/a.md` or `grep -rn oauth articles/` now sweep only those paths, making exec noticeably cheaper on large knowledge bases. When the sweep does cover the whole tree (bare `ls`, `find`, recursive `grep` with no directory) and the corpus exceeds the 1000-file scan cap, the response now carries an explicit warning that mutation detection was partial, instead of silently presenting a capped sweep as full coverage.
diff --git a/packages/server/src/bash/mtime-scan.test.ts b/packages/server/src/bash/mtime-scan.test.ts
index e14f5ae67..c89b9e4aa 100644
--- a/packages/server/src/bash/mtime-scan.test.ts
+++ b/packages/server/src/bash/mtime-scan.test.ts
@@ -4,7 +4,14 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
-import { diffMtimes, snapshotMtimes } from './mtime-scan.ts';
+import {
+ deriveScanRoots,
+ diffMtimes,
+ SCAN_WHOLE_TREE,
+ snapshotMtimes,
+ snapshotMtimesForRoots,
+} from './mtime-scan.ts';
+import type { Stage } from './parse-command.ts';
let tmp: string;
@@ -48,6 +55,185 @@ describe('snapshotMtimes', () => {
});
});
+function stage(...args: string[]): Stage {
+ return { command: args[0], args };
+}
+
+describe('deriveScanRoots', () => {
+ test('cat file operands become roots', () => {
+ expect(deriveScanRoots([stage('cat', 'a.md', 'sub/b.md')]).sort()).toEqual([
+ 'a.md',
+ 'sub/b.md',
+ ]);
+ });
+
+ test('bare ls scans the whole tree', () => {
+ expect(deriveScanRoots([stage('ls', '-la')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('ls with a dir operand scopes to it', () => {
+ expect(deriveScanRoots([stage('ls', 'articles/')])).toEqual(['articles/']);
+ });
+
+ test('grep drops the pattern positional but keeps operands', () => {
+ expect(deriveScanRoots([stage('grep', '-rn', 'oauth', 'articles/')])).toEqual(['articles/']);
+ });
+
+ test('recursive grep with no operand scans the whole tree', () => {
+ expect(deriveScanRoots([stage('grep', '-rn', 'oauth')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('non-recursive grep with no operand (stdin) contributes nothing', () => {
+ expect(deriveScanRoots([stage('cat', 'a.md'), stage('grep', 'oauth')])).toEqual(['a.md']);
+ });
+
+ test('grep -e pattern value is dropped, leaving only path operands', () => {
+ expect(deriveScanRoots([stage('grep', '-e', 'oauth', 'articles/')])).toEqual(['articles/']);
+ });
+
+ test('recursive grep with -e pattern and no path operand scans the whole tree', () => {
+ expect(deriveScanRoots([stage('grep', '-rn', '-e', 'oauth')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('find roots are the leading non-flag args; glob predicates are skipped', () => {
+ expect(deriveScanRoots([stage('find', 'specs', '-name', '*.md')])).toEqual(['specs']);
+ });
+
+ test('find literal predicate values stay watched', () => {
+ expect(deriveScanRoots([stage('find', 'specs', '-newer', 'ref.md')]).sort()).toEqual([
+ 'ref.md',
+ 'specs',
+ ]);
+ });
+
+ test('find with no path root scans the whole tree', () => {
+ expect(deriveScanRoots([stage('find', '-name', 'SPEC.md')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('glob operand reduces to its literal dir prefix', () => {
+ expect(deriveScanRoots([stage('cat', 'articles/*.md')])).toEqual(['articles']);
+ });
+
+ test('bare glob operand scans the whole tree', () => {
+ expect(deriveScanRoots([stage('cat', '*.md')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('glob-bearing attached flag values are match patterns, not paths', () => {
+ expect(deriveScanRoots([stage('grep', '-rn', '--include=*.md', 'oauth', 'articles/')])).toEqual(
+ ['articles/'],
+ );
+ });
+
+ test('literal attached flag values are watched as candidate write targets', () => {
+ expect(deriveScanRoots([stage('sort', '--weird=out.md', 'in.md')]).sort()).toEqual([
+ 'in.md',
+ 'out.md',
+ ]);
+ });
+
+ test('stdin consumers with no operand contribute nothing', () => {
+ expect(deriveScanRoots([stage('cat', 'a.md'), stage('head', '-5'), stage('wc', '-l')])).toEqual(
+ ['a.md'],
+ );
+ });
+
+ test('whole-tree subsumes every other root', () => {
+ expect(deriveScanRoots([stage('cat', 'a.md'), stage('ls')])).toEqual([SCAN_WHOLE_TREE]);
+ });
+
+ test('grep-derived whole tree subsumes other pipeline operands', () => {
+ expect(deriveScanRoots([stage('grep', '-rn', 'oauth'), stage('cat', 'a.md')])).toEqual([
+ SCAN_WHOLE_TREE,
+ ]);
+ });
+
+ test('find-derived whole tree subsumes other pipeline operands', () => {
+ expect(deriveScanRoots([stage('find', '-name', 'SPEC.md'), stage('cat', 'a.md')])).toEqual([
+ SCAN_WHOLE_TREE,
+ ]);
+ });
+});
+
+describe('snapshotMtimesForRoots', () => {
+ test('file root records only that file', async () => {
+ writeFileSync(resolve(tmp, 'a.md'), 'a');
+ writeFileSync(resolve(tmp, 'b.md'), 'b');
+
+ const { snapshot, truncated } = await snapshotMtimesForRoots(tmp, ['a.md']);
+ expect(truncated).toBe(false);
+ expect([...snapshot.keys()]).toEqual(['a.md']);
+ });
+
+ test('dir root walks its subtree, not siblings', async () => {
+ mkdirSync(resolve(tmp, 'sub/nested'), { recursive: true });
+ writeFileSync(resolve(tmp, 'sub/a.md'), 'a');
+ writeFileSync(resolve(tmp, 'sub/nested/b.md'), 'b');
+ writeFileSync(resolve(tmp, 'outside.md'), 'o');
+
+ const { snapshot } = await snapshotMtimesForRoots(tmp, ['sub']);
+ expect([...snapshot.keys()].sort()).toEqual(['sub/a.md', 'sub/nested/b.md']);
+ });
+
+ test('missing root: creation during exec is caught by pre/post diff', async () => {
+ const before = (await snapshotMtimesForRoots(tmp, ['new.md'])).snapshot;
+ writeFileSync(resolve(tmp, 'new.md'), 'created');
+ const after = (await snapshotMtimesForRoots(tmp, ['new.md'])).snapshot;
+ expect(diffMtimes(before, after).changed).toEqual(['new.md']);
+ });
+
+ test('overlapping roots dedupe (dir + file inside it)', async () => {
+ mkdirSync(resolve(tmp, 'sub'), { recursive: true });
+ writeFileSync(resolve(tmp, 'sub/a.md'), 'a');
+
+ const { snapshot } = await snapshotMtimesForRoots(tmp, ['sub', 'sub/a.md']);
+ expect([...snapshot.keys()]).toEqual(['sub/a.md']);
+ });
+
+ test('cap truncates and reports it', async () => {
+ writeFileSync(resolve(tmp, 'a.md'), 'a');
+ writeFileSync(resolve(tmp, 'b.md'), 'b');
+ writeFileSync(resolve(tmp, 'c.md'), 'c');
+
+ const { snapshot, truncated } = await snapshotMtimesForRoots(tmp, [SCAN_WHOLE_TREE], 2);
+ expect(truncated).toBe(true);
+ expect(snapshot.size).toBe(2);
+ });
+
+ test('exactly-at-cap is not truncated', async () => {
+ writeFileSync(resolve(tmp, 'a.md'), 'a');
+ writeFileSync(resolve(tmp, 'b.md'), 'b');
+
+ const { truncated } = await snapshotMtimesForRoots(tmp, [SCAN_WHOLE_TREE], 2);
+ expect(truncated).toBe(false);
+ });
+
+ test('roots inside skipped dirs stay outside the coverage domain', async () => {
+ mkdirSync(resolve(tmp, 'node_modules/pkg'), { recursive: true });
+ writeFileSync(resolve(tmp, 'node_modules/pkg/x.md'), 'x');
+
+ const { snapshot } = await snapshotMtimesForRoots(tmp, ['node_modules/pkg']);
+ expect(snapshot.size).toBe(0);
+ });
+
+ test('root with a skipped dir in a middle segment stays outside the coverage domain', async () => {
+ mkdirSync(resolve(tmp, 'content/node_modules/pkg'), { recursive: true });
+ writeFileSync(resolve(tmp, 'content/node_modules/pkg/x.md'), 'x');
+
+ const { snapshot } = await snapshotMtimesForRoots(tmp, ['content/node_modules/pkg']);
+ expect(snapshot.size).toBe(0);
+ });
+
+ test('whole-tree sentinel matches snapshotMtimes', async () => {
+ writeFileSync(resolve(tmp, 'a.md'), 'a');
+ mkdirSync(resolve(tmp, 'sub'), { recursive: true });
+ writeFileSync(resolve(tmp, 'sub/b.md'), 'b');
+
+ const scoped = await snapshotMtimesForRoots(tmp, [SCAN_WHOLE_TREE]);
+ const full = await snapshotMtimes(tmp);
+ expect([...scoped.snapshot.keys()].sort()).toEqual([...full.snapshot.keys()].sort());
+ });
+});
+
describe('diffMtimes', () => {
test('empty before + empty after → no changes', () => {
const result = diffMtimes(new Map(), new Map());
diff --git a/packages/server/src/bash/mtime-scan.ts b/packages/server/src/bash/mtime-scan.ts
index 68c62bed2..6e3f990f9 100644
--- a/packages/server/src/bash/mtime-scan.ts
+++ b/packages/server/src/bash/mtime-scan.ts
@@ -1,25 +1,43 @@
/**
* Post-exec security-invariant check.
*
- * Before every `exec` call we snapshot `(relPath, mtimeMs)` for files in
- * `projectDir`; after the call we re-snapshot and diff. Any path whose
- * mtime changed (or that newly exists) on a read-only command indicates
- * a parser bug that let a writer through — we abort the response with
- * `security_invariant_violation`.
+ * Before every `exec` call we snapshot `(relPath, mtimeMs)` for the files
+ * the command could plausibly touch; after the call we re-snapshot and
+ * diff. Any path whose mtime changed (or that newly exists) on a
+ * read-only command indicates a parser bug that let a writer through —
+ * we abort the response with `security_invariant_violation`.
*
* This is the defense-in-depth backstop — a lean alternative to
- * subprocess isolation. Typical overhead for dirs ≤500 files is <10ms.
+ * subprocess isolation. The scan is scoped by `deriveScanRoots`: because
+ * `parseCommand` tokenizes the whole command line, any write target a
+ * parser bug could smuggle through must appear among the command's own
+ * tokens, so watching the token-derived path set (plus the whole tree
+ * when a command implicitly operates on the cwd) covers the threat
+ * surface without statting the full corpus on every call.
*
* Bounded at `SCAN_CAP` entries; traversal skips hidden OK directories
- * (`.git/`, `.ok/`, `node_modules/`).
+ * (`.git/`, `.ok/`, `node_modules/`). Callers MUST surface the
+ * `truncated` flag — a capped sweep covers only the first `SCAN_CAP`
+ * files and must not be presented as full coverage.
*/
import type { Dirent } from 'node:fs';
import { readdir, stat } from 'node:fs/promises';
import { relative, resolve } from 'node:path';
import { OK_DIR } from '@inkeep/open-knowledge-core';
+import { argsOf, nonFlagArgs } from './extract-paths.ts';
+import { isRecursiveGrepFlag, type Stage } from './parse-command.ts';
-/** Upper bound on the number of files we scan. Typical content dirs are well under 500. */
-const SCAN_CAP = 1000;
+/**
+ * Upper bound on the number of files we scan. Typical content dirs are well
+ * under 500; the cap keeps worst-case overhead at ~2×1000 stats per call.
+ */
+export const SCAN_CAP = 1000;
+
+/**
+ * Scan-root sentinel meaning "the whole base directory". Subsumes every
+ * other root when present.
+ */
+export const SCAN_WHOLE_TREE = '';
const SKIP_DIRS: ReadonlySet<string> = new Set([
'.git',
@@ -34,20 +52,158 @@ const SKIP_DIRS: ReadonlySet<string> = new Set([
type MtimeSnapshot = Map<string, number>;
+interface SnapshotResult {
+ snapshot: MtimeSnapshot;
+ /** True when the scan hit `cap` before covering every in-scope file. */
+ truncated: boolean;
+}
+
+/** Glob metacharacters just-bash may expand into file operands. */
+const GLOB_RE = /[*?[]/;
+
/**
- * Snapshot `(relPath, mtimeMs)` for files in `projectDir`. Bounded; returns
- * early at SCAN_CAP with a `truncated` flag caller can act on.
+ * Longest literal directory prefix of a glob-bearing token:
+ * `articles/*.md` → `articles`; `*.md` → `` (whole tree).
*/
-export async function snapshotMtimes(
- projectDir: string,
-): Promise<{ snapshot: MtimeSnapshot; truncated: boolean }> {
- const root = resolve(projectDir);
+function literalDirPrefix(token: string): string {
+ const idx = token.search(GLOB_RE);
+ const head = token.slice(0, idx);
+ const slash = head.lastIndexOf('/');
+ return slash >= 0 ? head.slice(0, slash) : SCAN_WHOLE_TREE;
+}
+
+/**
+ * Derive the scan roots for a pipeline: the paths the command's own tokens
+ * could name as a write target, or `SCAN_WHOLE_TREE` when a command
+ * implicitly operates on the whole cwd.
+ *
+ * Per-command rules (over-inclusion is safe — a non-path token costs one
+ * failed stat; under-inclusion would blind the sweep):
+ * - `grep`: the match pattern is not a path operand — the leading
+ * positional in `grep PAT [path…]`, or the value of `-e`/`--regexp`.
+ * Both are dropped, leaving only path operands. Recursive grep with no
+ * path operand defaults to `.` → whole tree; non-recursive grep with no
+ * operand reads stdin → touches nothing.
+ * - `find`: leading non-flag args are the roots (none → `.` → whole
+ * tree). Predicate values after the first `-flag` are kept as watch
+ * paths only when glob-free (`-newer ref.md` yes, `-name '*.md'` no).
+ * - `ls` with no operand lists the cwd → whole tree (the write target of
+ * a hypothetical smuggled ls writer is unknowable, so stay wide).
+ * - stdin consumers (`cat`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`)
+ * with no operand touch no disk path → contribute nothing.
+ * - `=`-attached flag values (`--flag=path`) are watched when glob-free:
+ * an output-flag variant that slipped the denylist names its target
+ * there. Glob-bearing attached values (`--include=*.md`) are match
+ * patterns, not paths.
+ * - Glob-bearing operands reduce to their literal directory prefix
+ * (`articles/*.md` → `articles`; bare `*.md` → whole tree).
+ *
+ * Derive from the PRE-augmentation stages: the injected exclude filters
+ * (`--exclude-dir=node_modules`, `-not -path ...`) are generated by our own
+ * code, never attacker-controlled, and would otherwise pull excluded dirs
+ * into the scan.
+ */
+export function deriveScanRoots(stages: Stage[]): string[] {
+ const roots = new Set<string>();
+ for (const stage of stages) {
+ const args = argsOf(stage);
+ const positional = nonFlagArgs(args);
+ let candidates: string[];
+ switch (stage.command) {
+ case 'grep': {
+ // The regex pattern is not a path operand: in `grep PAT [path…]` it is
+ // the leading positional, and in `-e PAT` / `--regexp PAT` it is the
+ // flag's value. Drop both so a pattern neither seeds a dead root nor
+ // masks the empty-operand → whole-tree fallback below.
+ let patternViaFlag = false;
+ const patternValues = new Set<string>();
+ for (let i = 0; i < args.length; i++) {
+ const a = args[i];
+ if (a === '-e' || a === '--regexp') {
+ patternViaFlag = true;
+ const value = args[i + 1];
+ if (value !== undefined) patternValues.add(value);
+ } else if (a.startsWith('--regexp=')) {
+ patternViaFlag = true;
+ }
+ }
+ const operands = positional.filter((p) => !patternValues.has(p));
+ candidates = patternViaFlag ? operands : operands.slice(1);
+ if (candidates.length === 0 && args.some(isRecursiveGrepFlag)) {
+ roots.add(SCAN_WHOLE_TREE);
+ }
+ break;
+ }
+ case 'find': {
+ const firstFlag = args.findIndex((a) => a.startsWith('-'));
+ const pathRoots = firstFlag === -1 ? args : args.slice(0, firstFlag);
+ const predicateValues =
+ firstFlag === -1
+ ? []
+ : args.slice(firstFlag).filter((a) => !a.startsWith('-') && !GLOB_RE.test(a));
+ candidates = [...pathRoots, ...predicateValues];
+ if (pathRoots.length === 0) roots.add(SCAN_WHOLE_TREE);
+ break;
+ }
+ case 'ls': {
+ candidates = positional;
+ if (positional.length === 0) roots.add(SCAN_WHOLE_TREE);
+ break;
+ }
+ default:
+ candidates = positional;
+ }
+ const attached = args
+ .filter((a) => a.startsWith('-') && a.includes('='))
+ .map((a) => a.slice(a.indexOf('=') + 1))
+ .filter((v) => v.length > 0 && !GLOB_RE.test(v));
+ for (const c of [...candidates, ...attached]) {
+ roots.add(GLOB_RE.test(c) ? literalDirPrefix(c) : c);
+ }
+ }
+ return roots.has(SCAN_WHOLE_TREE) ? [SCAN_WHOLE_TREE] : [...roots];
+}
+
+/**
+ * A root any of whose path segments is a skipped dir lies outside the
+ * sweep's coverage domain (the full-tree walk never descends into those),
+ * so scanning it would claim coverage the full scan never had.
+ */
+function hasSkippedSegment(rel: string): boolean {
+ return rel.split('/').some((seg) => SKIP_DIRS.has(seg));
+}
+
+/**
+ * Snapshot `(relPath, mtimeMs)` for files under the given roots (relative
+ * to `baseDir`; `SCAN_WHOLE_TREE` covers everything). Directory roots are
+ * walked recursively, file roots are statted directly, and missing roots
+ * contribute nothing — a file created there during exec shows up in the
+ * post snapshot and is reported by `diffMtimes` as a new path.
+ *
+ * Bounded at `cap` total entries across all roots; returns `truncated`
+ * when coverage is partial.
+ */
+export async function snapshotMtimesForRoots(
+ baseDir: string,
+ roots: readonly string[],
+ cap: number = SCAN_CAP,
+): Promise<SnapshotResult> {
+ const base = resolve(baseDir);
const snapshot: MtimeSnapshot = new Map();
- let count = 0;
- let truncated = false;
+ const state = { truncated: false };
+
+ function record(relPath: string, mtimeMs: number): void {
+ // Overlapping roots (a dir plus a file inside it) must not double-count.
+ if (snapshot.has(relPath)) return;
+ if (snapshot.size >= cap) {
+ state.truncated = true;
+ return;
+ }
+ snapshot.set(relPath, mtimeMs);
+ }
async function walk(dir: string): Promise<void> {
- if (truncated) return;
+ if (state.truncated) return;
let entries: Dirent[];
try {
entries = (await readdir(dir, { withFileTypes: true })) as Dirent[];
@@ -55,7 +211,7 @@ export async function snapshotMtimes(
return;
}
for (const entry of entries) {
- if (truncated) return;
+ if (state.truncated) return;
if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
const full = resolve(dir, entry.name);
if (entry.isDirectory()) {
@@ -63,22 +219,44 @@ export async function snapshotMtimes(
continue;
}
if (!entry.isFile()) continue;
- if (count >= SCAN_CAP) {
- truncated = true;
- return;
- }
try {
const s = await stat(full);
- snapshot.set(relative(root, full), s.mtimeMs);
- count++;
+ record(relative(base, full), s.mtimeMs);
} catch {
// ignore unreadable files
}
}
}
- await walk(root);
- return { snapshot, truncated };
+ const effectiveRoots = roots.includes(SCAN_WHOLE_TREE) ? [SCAN_WHOLE_TREE] : [...new Set(roots)];
+ for (const root of effectiveRoots) {
+ if (state.truncated) break;
+ if (root !== SCAN_WHOLE_TREE && hasSkippedSegment(root)) continue;
+ const abs = resolve(base, root);
+ let s: Awaited<ReturnType<typeof stat>>;
+ try {
+ s = await stat(abs);
+ } catch {
+ continue; // missing root: creation is caught by the post-exec snapshot
+ }
+ if (s.isDirectory()) {
+ await walk(abs);
+ } else if (s.isFile()) {
+ record(relative(base, abs), s.mtimeMs);
+ }
+ }
+ return { snapshot, truncated: state.truncated };
+}
+
+/**
+ * Snapshot the whole `projectDir` tree. Equivalent to
+ * `snapshotMtimesForRoots(projectDir, [SCAN_WHOLE_TREE])`.
+ */
+export async function snapshotMtimes(
+ projectDir: string,
+ cap: number = SCAN_CAP,
+): Promise<SnapshotResult> {
+ return snapshotMtimesForRoots(projectDir, [SCAN_WHOLE_TREE], cap);
}
interface MtimeDiff {
diff --git a/packages/server/src/bash/parse-command.ts b/packages/server/src/bash/parse-command.ts
index f29cd61a3..fe9e7671f 100644
--- a/packages/server/src/bash/parse-command.ts
+++ b/packages/server/src/bash/parse-command.ts
@@ -90,7 +90,7 @@ interface ExcludeStrategy {
insertionIndex(args: string[]): number;
}
-function isRecursiveGrepFlag(arg: string): boolean {
+export function isRecursiveGrepFlag(arg: string): boolean {
if (arg === '--recursive' || arg === '--dereference-recursive') return true;
if (arg.startsWith('--')) return false;
if (!arg.startsWith('-')) return false;
diff --git a/packages/server/src/mcp/tools/exec.test.ts b/packages/server/src/mcp/tools/exec.test.ts
index c0c67c867..90e5d932d 100644
--- a/packages/server/src/mcp/tools/exec.test.ts
+++ b/packages/server/src/mcp/tools/exec.test.ts
@@ -1023,3 +1023,80 @@ describe('formatFileEntry rendering', () => {
expect(line).toContain('forward links: 1 (https://example.com)');
});
});
+
+describe('exec — mutation-sweep scoping and honesty', () => {
+ const OVER_CAP = 1005;
+
+ function seedBulk(project: string): void {
+ const bulk = resolve(project, 'bulk');
+ mkdirSync(bulk, { recursive: true });
+ for (let i = 0; i < OVER_CAP; i++) {
+ writeFileSync(resolve(bulk, `f${i}.txt`), String(i));
+ }
+ }
+
+ function partialSweepWarnings(result: ExecResult): string[] {
+ return (structured(result).warnings ?? []).filter((w) => w.includes('sweep was partial'));
+ }
+
+ test('bare ls on an over-cap corpus discloses the partial sweep', async () => {
+ const project = await bootstrap();
+ seedBulk(project);
+
+ const result = (await buildExecResult(
+ { command: 'ls' },
+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },
+ )) as ExecResult;
+
+ expect(result.isError).toBeFalsy();
+ const warnings = partialSweepWarnings(result);
+ expect(warnings.length).toBe(1);
+ expect(warnings[0]).toContain('1000');
+ expect(result.content[0].text).toContain('sweep was partial');
+ });
+
+ test('listing an over-cap subdirectory discloses the partial sweep', async () => {
+ const project = await bootstrap();
+ seedBulk(project);
+
+ const result = (await buildExecResult(
+ { command: 'ls bulk/' },
+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },
+ )) as ExecResult;
+
+ expect(result.isError).toBeFalsy();
+ expect(partialSweepWarnings(result).length).toBe(1);
+ });
+
+ test('path-scoped commands avoid the corpus-wide sweep entirely', async () => {
+ const project = await bootstrap();
+ seedBulk(project);
+ const contentDir = resolve(project, 'content');
+ mkdirSync(contentDir, { recursive: true });
+ writeFileSync(resolve(contentDir, 'a.md'), '---\ntitle: A\n---\nBody\n');
+
+ const result = (await buildExecResult(
+ { command: 'cat content/a.md' },
+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },
+ )) as ExecResult;
+
+ expect(result.isError).toBeFalsy();
+ expect(partialSweepWarnings(result).length).toBe(0);
+ });
+
+ test('grep scoped to a small dir on an over-cap corpus stays fully swept', async () => {
+ const project = await bootstrap();
+ seedBulk(project);
+ const contentDir = resolve(project, 'articles');
+ mkdirSync(contentDir, { recursive: true });
+ writeFileSync(resolve(contentDir, 'a.md'), '---\ntitle: A\n---\noauth flow\n');
+
+ const result = (await buildExecResult(
+ { command: 'grep -rn oauth articles/' },
+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },
+ )) as ExecResult;
+
+ expect(result.isError).toBeFalsy();
+ expect(partialSweepWarnings(result).length).toBe(0);
+ });
+});
diff --git a/packages/server/src/mcp/tools/exec.ts b/packages/server/src/mcp/tools/exec.ts
index ee4f972ec..861f5417c 100644
--- a/packages/server/src/mcp/tools/exec.ts
+++ b/packages/server/src/mcp/tools/exec.ts
@@ -3,9 +3,11 @@
*
* Orchestrates:
* 1. parseCommand (shell-quote + allowlist) — primary security boundary
- * 2. snapshotMtimes (pre) — defense-in-depth baseline
+ * 2. snapshotMtimesForRoots (pre) — defense-in-depth baseline, scoped to
+ * the paths the command's tokens could touch (deriveScanRoots)
* 3. execBash via just-bash + ReadWriteFs (sandbox)
- * 4. snapshotMtimes (post) + diff — abort on any mutation
+ * 4. snapshotMtimesForRoots (post) + diff — abort on any mutation;
+ * a capped (partial) sweep is disclosed via a warning banner
* 5. extractReferencedPaths
* 6. enrichPath per path (slim shape for multi-path; rich for single-cat)
* 7. Format: raw stdout + markdown `### Referenced files` block +
@@ -22,7 +24,12 @@ import { relative, resolve } from 'node:path';
import { z } from 'zod';
import { argsOf, extractReferencedPaths, nonFlagArgs } from '../../bash/extract-paths.ts';
import { createBashInstance, execBash, StdoutOverflowError } from '../../bash/index.ts';
-import { diffMtimes, snapshotMtimes } from '../../bash/mtime-scan.ts';
+import {
+ deriveScanRoots,
+ diffMtimes,
+ SCAN_CAP,
+ snapshotMtimesForRoots,
+} from '../../bash/mtime-scan.ts';
import {
augmentStagesWithExcludes,
type ErrorCategory,
@@ -135,7 +142,8 @@ export interface ExecStructuredResult {
*/
cwd?: string;
/**
- * Tool-level warnings — head/tail truncation, binary-file detection, stderr.
+ * Tool-level warnings — head/tail truncation, binary-file detection,
+ * stderr, partial mutation-sweep coverage.
* Carried in `structuredContent` because Claude-class clients drop
* `content[].text` when `structuredContent` is present (claude-code#55677),
* so safety signals must live in structured content too or agents miss them.
@@ -528,11 +536,25 @@ export async function buildExecResult(
const stages = augmentStagesWithExcludes(parsed.stages);
const effectiveCommand = serializeStages(stages);
- // 2. Pre-exec mtime snapshot (baseline). Scoped to `executionCwd` — the
- // bash sandbox is rooted there (`ReadWriteFs` root), so a read-only command
- // can only mutate files inside it; scanning the whole project root would be
- // wasteful and would false-positive on concurrent writers elsewhere.
- const pre = await snapshotMtimes(executionCwd);
+ // 2. Pre-exec mtime snapshot (baseline). Scoped two ways: (a) to
+ // `executionCwd` — the bash sandbox is rooted there (`ReadWriteFs` root),
+ // so a read-only command can only mutate files inside it; and (b) to the
+ // scan roots derived from the command's own tokens — parseCommand
+ // tokenizes the whole command line, so any write target a parser bug
+ // could smuggle through must appear among those tokens. Roots are derived
+ // from the PRE-augmentation stages (the injected exclude filters are our
+ // own tokens, not attacker input) and containment-filtered like the
+ // enrichment paths: a token that escapes `executionCwd` can't be written
+ // by the sandbox either.
+ const scanRoots = [
+ ...new Set(
+ deriveScanRoots(parsed.stages)
+ .map((r) => resolveWithinRoot(executionCwd, r))
+ .filter((r) => r.ok)
+ .map((r) => r.rel),
+ ),
+ ];
+ const pre = await snapshotMtimesForRoots(executionCwd, scanRoots);
// 3. Execute via just-bash in the literal directory the caller passed.
const bash = createBashInstance(executionCwd);
@@ -555,8 +577,8 @@ export async function buildExecResult(
);
}
- // 4. Post-exec mtime check (backstop) — same scope as the pre snapshot.
- const post = await snapshotMtimes(executionCwd);
+ // 4. Post-exec mtime check (backstop) — same roots as the pre snapshot.
+ const post = await snapshotMtimesForRoots(executionCwd, scanRoots);
const mtimeDiff = diffMtimes(pre.snapshot, post.snapshot);
if (mtimeDiff.changed.length > 0) {
return errorCategoryResult(
@@ -564,6 +586,9 @@ export async function buildExecResult(
`Security invariant violated: file(s) in the content directory were modified during a read-only exec call: ${mtimeDiff.changed.join(', ')}. This indicates a parser bug; the command has been logged.`,
);
}
+ // A capped sweep covered only the first SCAN_CAP files — it must not be
+ // presented as a full safety net.
+ const sweepPartial = pre.truncated || post.truncated;
// 5. Apply soft cap to stdout
const capped = applySoftCap(stdout);
@@ -677,6 +702,11 @@ export async function buildExecResult(
if (stderr) {
banners.push(`stderr: ${stderr.trim()}`);
}
+ if (sweepPartial) {
+ banners.push(
+ `Read-only mutation sweep was partial: the files in scope exceed the ${SCAN_CAP}-file cap, so only the first ${SCAN_CAP} were checked for unexpected writes. Narrow the command to a subdirectory for full sweep coverage.`,
+ );
+ }
const bannerText = banners.length > 0 ? `${banners.join('\n')}\n\n` : '';
const provenance = buildStdoutProvenance(stages, dirByPath, fileByPath, rebaseToProject);
@@ -737,7 +767,9 @@ export function register(server: ServerInstance, deps: ExecDeps): void {
warnings: z
.array(z.string())
.optional()
- .describe('Tool-level warnings — head/tail truncation, binary detection, stderr.'),
+ .describe(
+ 'Tool-level warnings — head/tail truncation, binary detection, stderr, partial mutation-sweep coverage.',
+ ),
cwd: z.string().optional().describe('Absolute directory the command ran in.'),
error: z
.object({ category: z.string(), message: z.string() })