context-mode 1.0.148 → 1.0.149

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.148"
+    "version": "1.0.149"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.148",
+      "version": "1.0.149",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/executor.d.ts

@@ -19,6 +19,15 @@ interface ExecuteOptions {
     timeout?: number;
     /** Keep process running after timeout instead of killing it. */
     background?: boolean;
+    /**
+     * Issue #45 — per-call cwd override for the shell language. When set,
+     * the shell script runs in this directory instead of `#projectRoot`.
+     * Non-shell languages keep their tmpDir sandbox cwd regardless (the
+     * script file lives there). Used by Codex MCP handlers to pin shell
+     * commands to a resolved project root when the spawning host inherited
+     * a non-project cwd (e.g. $HOME).
+     */
+    cwd?: string;
 }
 interface ExecuteFileOptions extends ExecuteOptions {
     path: string;

package/build/executor.js

@@ -130,7 +130,7 @@ export class PolyglotExecutor {
         this.#backgroundedPids.clear();
     }
     async execute(opts) {
-        const { language, code, timeout, background = false } = opts;
+        const { language, code, timeout, background = false, cwd: cwdOverride } = opts;
         const tmpDir = mkdtempSync(join(OS_TMPDIR, ".ctx-mode-"));
         try {
             const filePath = this.#writeScript(tmpDir, code, language);
@@ -142,7 +142,11 @@ export class PolyglotExecutor {
             // Shell commands run in the project directory so git, relative paths,
             // and other project-aware tools work naturally. Non-shell languages
             // run in the temp directory where their script file is written.
-            const cwd = language === "shell" ? this.#projectRoot : tmpDir;
+            // Issue #45 — `cwdOverride` lets per-call sites (Codex MCP handlers)
+            // pin shell cwd without mutating process-wide state.
+            const cwd = language === "shell"
+                ? (cwdOverride ?? this.#projectRoot)
+                : tmpDir;
             const result = await this.#spawn(cmd, cwd, tmpDir, timeout, background);
             // Skip tmpDir cleanup if process was backgrounded — it may still need files
             if (!result.backgrounded) {

package/build/server.d.ts

@@ -78,6 +78,18 @@ export declare function resolveSessionIdFromSessionDB(opts?: {
     sessionsDir?: string;
     bypassCache?: boolean;
 }): string | undefined;
+/**
+ * Project directory detection across supported platforms.
+ *
+ * Priority:
+ *   1. Platform-specific env var (set by host IDE before MCP server spawn)
+ *   2. CONTEXT_MODE_PROJECT_DIR (set by start.mjs for ALL platforms — universal)
+ *   3. process.cwd() (last resort)
+ *
+ * CONTEXT_MODE_PROJECT_DIR guarantees correct projectDir even for platforms
+ * that don't set their own env var (Cursor, OpenClaw, Codex, Kiro, Zed).
+ */
+export declare function getProjectDir(): string;
 /**
  * Parse FTS5 highlight markers to find match positions in the
  * original (marker-free) text. Returns character offsets into the

package/build/server.js

@@ -465,7 +465,7 @@ function getSessionDir() {
  * CONTEXT_MODE_PROJECT_DIR guarantees correct projectDir even for platforms
  * that don't set their own env var (Cursor, OpenClaw, Codex, Kiro, Zed).
  */
-function getProjectDir() {
+export function getProjectDir() {
     const override = projectDirOverride.getStore();
     if (override)
         return override.projectDir;
@@ -500,14 +500,22 @@ function getProjectDir() {
     // and the legacy literal cascade is preserved there for semver safety.
     let transcriptsRoot;
     let strictPlatform;
+    let codexHome;
     try {
         const detected = detectPlatform().platform;
         strictPlatform = detected;
         if (detected === "claude-code") {
             transcriptsRoot = join(homedir(), ".claude", "projects");
         }
+        // Issue #45 — Codex publishes no workspace env var, so the resolver
+        // reads `meta.cwd` from the most-recently-modified session.jsonl under
+        // `${codexHome}/sessions/`. Wire codexHome at the call site so the
+        // resolver can be exercised under test without process-level mutation.
+        if (detected === "codex") {
+            codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+        }
     }
-    catch { /* detection failure — leave both undefined, resolver uses legacy cascade */ }
+    catch { /* detection failure — leave undefined, resolver uses legacy cascade */ }
     return resolveProjectDir({
         env: process.env,
         cwd: process.cwd(),
@@ -515,6 +523,7 @@ function getProjectDir() {
         transcriptsRoot,
         transcriptMaxAgeMs: 5 * 60 * 1000,
         strictPlatform,
+        codexHome,
     });
 }
 /**
@@ -1731,13 +1740,20 @@ EXAMPLE: ctx_index(path: "/path/to/large-spec.md", source: "openapi-v2-spec")`,
         path: z
             .string()
             .optional()
-            .describe("File path to read and index (content never enters context). Provide this OR content."),
+            .describe("File OR directory path to read and index (content never enters context). Provide this OR content. Directory paths trigger a bounded recursive walk (#687)."),
         source: z
             .string()
             .optional()
             .describe("Label for the indexed content (e.g., 'Context7: React useEffect', 'Skill: frontend-design')"),
+        include: z.array(z.string()).optional().describe("Directory-only: glob patterns to include (default: all matching extensions)."),
+        exclude: z.array(z.string()).optional().describe("Directory-only: glob patterns to exclude. Merged with defaults (node_modules, .git, dist, build, .next, coverage, .venv, __pycache__, .DS_Store)."),
+        maxDepth: z.number().int().min(0).optional().describe("Directory-only: max recursion depth from root (default: 5)."),
+        maxFiles: z.number().int().min(1).optional().describe("Directory-only: hard cap on files indexed (default: 200) — FTS5 blow-up guard."),
+        extensions: z.array(z.string()).optional().describe("Directory-only: allowed file extensions (default: .md .mdx .txt .json .yaml .yml .ts .tsx .js .jsx .py .rs .go .sh)."),
+        respectGitignore: z.boolean().optional().describe("Directory-only: apply nearest .gitignore (default: true)."),
+        followSymlinks: z.boolean().optional().describe("Directory-only: follow directory symlinks (default: false — cycle hazard + escape risk)."),
     }),
-}, async ({ content, path, source }) => {
+}, async ({ content, path, source, include, exclude, maxDepth, maxFiles, extensions, respectGitignore, followSymlinks }) => {
     if (!content && !path) {
         return trackResponse("ctx_index", {
             content: [
@@ -1760,6 +1776,54 @@ EXAMPLE: ctx_index(path: "/path/to/large-spec.md", source: "openapi-v2-spec")`,
     }
     try {
         const resolvedPath = path ? resolveProjectPath(path) : undefined;
+        // Directory dispatch (#687, reported by @matiasduartee). When the
+        // resolved path is a directory, walk it bounded and re-enter `index()`
+        // per-file so the security gate at store.ts:845 (TOCTOU defense from
+        // #442 round-3) keeps running for every file.
+        if (resolvedPath && existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+            const store = getStore();
+            const projectDir = getProjectDir();
+            const denyGlobs = readToolDenyPatterns("Read", projectDir);
+            const isWin32 = process.platform === "win32";
+            const perFileDeny = (absPath) => {
+                try {
+                    return evaluateFilePath(absPath, denyGlobs, isWin32, projectDir).denied;
+                }
+                catch {
+                    return false; // fail-open consistent with checkFilePathDenyPolicy
+                }
+            };
+            const dirResult = store.indexDirectory({
+                path: resolvedPath,
+                source: source ?? resolvedPath,
+                attribution: currentAttribution(),
+                perFileDeny,
+                include,
+                exclude,
+                maxDepth,
+                maxFiles,
+                extensions,
+                respectGitignore,
+                followSymlinks,
+            });
+            const capNote = dirResult.capped
+                ? ` (cap reached — only first ${dirResult.filesIndexed} of ${dirResult.totalSeen}+ files; raise maxFiles to index more)`
+                : "";
+            const denyNote = dirResult.denied > 0
+                ? ` (${dirResult.denied} file${dirResult.denied === 1 ? "" : "s"} blocked by Read deny policy)`
+                : "";
+            const failNote = dirResult.failed > 0
+                ? ` (${dirResult.failed} file${dirResult.failed === 1 ? "" : "s"} failed to read)`
+                : "";
+            return trackResponse("ctx_index", {
+                content: [
+                    {
+                        type: "text",
+                        text: `Indexed ${dirResult.filesIndexed} file${dirResult.filesIndexed === 1 ? "" : "s"} (${dirResult.totalChunks} sections) from directory: ${dirResult.label}${capNote}${denyNote}${failNote}\nUse ctx_search(queries: ["..."]) to query this content.`,
+                    },
+                ],
+            });
+        }
         // Track the raw bytes being indexed (content or file)
         if (content)
             trackIndexed(Buffer.byteLength(content));

package/build/store-directory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * walkDirectory — bounded recursive directory walker for ctx_index (#687).
+ *
+ * Issue: ctx_index refused directory paths via the security gate at
+ * src/store.ts:845 ("refusing to index <path>: not a regular file"). The gate
+ * is a TOCTOU defense from #442 round-3 and MUST be preserved — directory
+ * support is layered as a separate concern here. Each file produced by
+ * walkDirectory is then read via the existing per-file
+ * `openSync + fstatSync.isFile()` invariant in `ContentStore.index()`.
+ *
+ * Reported by @matiasduartee across 4 clients × Windows 11.
+ * https://github.com/anthropic-experimental/context-mode/issues/687
+ *
+ * Design constraints:
+ *   - No new dependencies (avoid the `ignore` package — issue #687 Diagnose).
+ *   - Cross-OS: path.sep / path.join everywhere, never raw "/" string ops.
+ *   - Symlink cycle detection via a resolved-path Set.
+ *   - Symlink-escape rejection: refuse to follow symlinks that resolve outside
+ *     the rootPath (defense-in-depth alongside per-file checkFilePathDenyPolicy).
+ *   - FTS5-blowup guard: hard cap maxFiles (default 200, per Architect).
+ */
+export interface WalkOptions {
+    /** Glob-ish include patterns. Empty/undefined means include all (subject to extensions). */
+    include?: string[];
+    /** Glob-ish exclude patterns. Merged with sensible defaults. */
+    exclude?: string[];
+    /** Max recursion depth from rootPath (0 = root only). Default 5. */
+    maxDepth?: number;
+    /** Hard cap on total files. Default 200 — FTS5 blow-up guard. */
+    maxFiles?: number;
+    /** Allowed file extensions (with leading dot). Empty/undefined means default set. */
+    extensions?: string[];
+    /** Apply nearest .gitignore rules during walk. Default true. */
+    respectGitignore?: boolean;
+    /** Follow directory symlinks. Default false (cycle hazard + escape risk). */
+    followSymlinks?: boolean;
+}
+export interface WalkResult {
+    files: string[];
+    /** True when maxFiles cap was hit and traversal halted early. */
+    capped: boolean;
+    /** Total files discovered before cap (for reporting). */
+    totalSeen: number;
+}
+/**
+ * Walk `rootPath` recursively under the given bounds and return absolute file
+ * paths matching the filters. Pure synchronous traversal — no allocations
+ * beyond the result array. Symlink cycles are detected via a resolved-path
+ * Set; symlink escapes (resolving outside rootPath) are silently skipped.
+ */
+export declare function walkDirectory(rootPath: string, opts?: WalkOptions): string[];
+/**
+ * Same as walkDirectory but returns capped + totalSeen so callers can surface
+ * a "capped at N files" notice in their response.
+ */
+export declare function walkDirectoryDetailed(rootPath: string, opts?: WalkOptions): WalkResult;

package/build/store-directory.js

@@ -0,0 +1,254 @@
+/**
+ * walkDirectory — bounded recursive directory walker for ctx_index (#687).
+ *
+ * Issue: ctx_index refused directory paths via the security gate at
+ * src/store.ts:845 ("refusing to index <path>: not a regular file"). The gate
+ * is a TOCTOU defense from #442 round-3 and MUST be preserved — directory
+ * support is layered as a separate concern here. Each file produced by
+ * walkDirectory is then read via the existing per-file
+ * `openSync + fstatSync.isFile()` invariant in `ContentStore.index()`.
+ *
+ * Reported by @matiasduartee across 4 clients × Windows 11.
+ * https://github.com/anthropic-experimental/context-mode/issues/687
+ *
+ * Design constraints:
+ *   - No new dependencies (avoid the `ignore` package — issue #687 Diagnose).
+ *   - Cross-OS: path.sep / path.join everywhere, never raw "/" string ops.
+ *   - Symlink cycle detection via a resolved-path Set.
+ *   - Symlink-escape rejection: refuse to follow symlinks that resolve outside
+ *     the rootPath (defense-in-depth alongside per-file checkFilePathDenyPolicy).
+ *   - FTS5-blowup guard: hard cap maxFiles (default 200, per Architect).
+ */
+import { readdirSync, statSync, lstatSync, realpathSync, existsSync, readFileSync, } from "node:fs";
+import { join, extname, relative, sep, resolve } from "node:path";
+const DEFAULT_EXCLUDES = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    ".venv",
+    "__pycache__",
+    ".DS_Store",
+];
+const DEFAULT_EXTENSIONS = [
+    ".md",
+    ".mdx",
+    ".txt",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".py",
+    ".rs",
+    ".go",
+    ".sh",
+];
+const DEFAULT_MAX_DEPTH = 5;
+const DEFAULT_MAX_FILES = 200;
+/**
+ * Convert a simple glob pattern (`*`, `**`, `?`) to a RegExp. Anchors at
+ * boundaries so `node_modules` matches `node_modules` AND `node_modules/pkg`.
+ * Patterns are matched against POSIX-style relative paths (forward slashes)
+ * to give consistent behavior across macOS / Windows.
+ */
+function globToRegExp(pattern) {
+    // Escape regex metachars except glob ones.
+    let re = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                re += ".*";
+                i++;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else if ("\\^$.|+()[]{}".includes(c)) {
+            re += "\\" + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+/** Match a posix-style relative path against any of the patterns. */
+function matchesAny(relPosix, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const basename = relPosix.split("/").pop() ?? relPosix;
+    for (const p of patterns) {
+        // Bare names match basename OR any path segment.
+        if (!p.includes("/") && !p.includes("*")) {
+            if (basename === p)
+                return true;
+            if (relPosix.split("/").includes(p))
+                return true;
+            continue;
+        }
+        const re = globToRegExp(p);
+        if (re.test(relPosix))
+            return true;
+        if (re.test(basename))
+            return true;
+    }
+    return false;
+}
+/**
+ * Parse a .gitignore file into a list of patterns. Comments and blank lines
+ * are stripped. Negation (`!`) is not supported — kept conservative.
+ */
+function parseGitignore(rootPath) {
+    const giPath = join(rootPath, ".gitignore");
+    if (!existsSync(giPath))
+        return [];
+    try {
+        const text = readFileSync(giPath, "utf-8");
+        return text
+            .split(/\r?\n/)
+            .map(l => l.trim())
+            .filter(l => l.length > 0 && !l.startsWith("#") && !l.startsWith("!"))
+            .map(l => l.replace(/^\//, "").replace(/\/$/, ""));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Convert an absolute path under rootPath to a POSIX-style relative path
+ * so glob matching is identical across macOS/Linux/Windows.
+ */
+function toPosixRel(rootPath, absPath) {
+    const rel = relative(rootPath, absPath);
+    return rel.split(sep).join("/");
+}
+/**
+ * Walk `rootPath` recursively under the given bounds and return absolute file
+ * paths matching the filters. Pure synchronous traversal — no allocations
+ * beyond the result array. Symlink cycles are detected via a resolved-path
+ * Set; symlink escapes (resolving outside rootPath) are silently skipped.
+ */
+export function walkDirectory(rootPath, opts = {}) {
+    return walkDirectoryDetailed(rootPath, opts).files;
+}
+/**
+ * Same as walkDirectory but returns capped + totalSeen so callers can surface
+ * a "capped at N files" notice in their response.
+ */
+export function walkDirectoryDetailed(rootPath, opts = {}) {
+    const { include, exclude, maxDepth = DEFAULT_MAX_DEPTH, maxFiles = DEFAULT_MAX_FILES, extensions, respectGitignore = true, followSymlinks = false, } = opts;
+    // Normalize rootPath to its real path so symlink-escape detection is sound.
+    let rootReal;
+    try {
+        rootReal = realpathSync(rootPath);
+    }
+    catch {
+        return { files: [], capped: false, totalSeen: 0 };
+    }
+    const exts = (extensions && extensions.length > 0 ? extensions : DEFAULT_EXTENSIONS)
+        .map(e => (e.startsWith(".") ? e : "." + e).toLowerCase());
+    const excludes = [
+        ...DEFAULT_EXCLUDES,
+        ...(exclude ?? []),
+        ...(respectGitignore ? parseGitignore(rootReal) : []),
+    ];
+    const includes = include ?? [];
+    const out = [];
+    const visited = new Set([rootReal]);
+    let totalSeen = 0;
+    let capped = false;
+    function walk(absDir, depth) {
+        if (capped)
+            return;
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory — skip silently
+        }
+        for (const ent of entries) {
+            if (capped)
+                return;
+            const absChild = join(absDir, ent.name);
+            const relPosix = toPosixRel(rootReal, absChild);
+            // Exclude check applies to both files and dirs — early prune.
+            if (matchesAny(relPosix, excludes))
+                continue;
+            // Include filter applies to files only — see below.
+            // Resolve symlinks once; reject escapes; track for cycle detection.
+            let isDirChild = ent.isDirectory();
+            let isFileChild = ent.isFile();
+            let isSymlink = false;
+            try {
+                const lst = lstatSync(absChild);
+                isSymlink = lst.isSymbolicLink();
+            }
+            catch {
+                continue;
+            }
+            if (isSymlink) {
+                if (!followSymlinks)
+                    continue;
+                let resolved;
+                try {
+                    resolved = realpathSync(absChild);
+                }
+                catch {
+                    continue; // dangling
+                }
+                // Symlink-escape: refuse to follow if the resolved target leaves rootReal.
+                const escapeRel = relative(rootReal, resolved);
+                if (escapeRel.startsWith("..") || resolve(escapeRel) === resolved) {
+                    // resolve(absolute) === absolute → target is absolute outside root
+                    if (escapeRel.startsWith(".."))
+                        continue;
+                }
+                if (visited.has(resolved))
+                    continue;
+                visited.add(resolved);
+                try {
+                    const st = statSync(resolved);
+                    isDirChild = st.isDirectory();
+                    isFileChild = st.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirChild) {
+                walk(absChild, depth + 1);
+                continue;
+            }
+            if (!isFileChild)
+                continue;
+            // Extension filter.
+            const ext = extname(absChild).toLowerCase();
+            if (!exts.includes(ext))
+                continue;
+            // Include filter (if any): file must match at least one include pattern.
+            if (includes.length > 0 && !matchesAny(relPosix, includes))
+                continue;
+            totalSeen++;
+            if (out.length >= maxFiles) {
+                capped = true;
+                return;
+            }
+            out.push(absChild);
+        }
+    }
+    walk(rootReal, 0);
+    return { files: out, capped, totalSeen };
+}

package/build/store.d.ts

@@ -7,6 +7,7 @@
  * Use for documentation, API references, and any content where
  * you need EXACT text later — not summaries.
  */
+import { type WalkOptions } from "./store-directory.js";
 type SourceMatchMode = "like" | "exact";
 import type { IndexResult, SearchResult, StoreStats } from "./types.js";
 export type { IndexResult, SearchResult, StoreStats } from "./types.js";
@@ -51,6 +52,34 @@ export declare class ContentStore {
             eventId?: string;
         };
     }): IndexResult;
+    /**
+     * Index every file under a directory by walking it with `walkDirectory` and
+     * delegating each discovered file to `this.index({ path })`. The per-file
+     * `openSync + fstatSync.isFile()` security gate at line ~845 stays active
+     * for every file — directory support never bypasses the TOCTOU defense
+     * from #442 round-3.
+     *
+     * Reported by @matiasduartee in #687.
+     */
+    indexDirectory(opts: {
+        path: string;
+        source?: string;
+        attribution?: {
+            sessionId?: string;
+            eventId?: string;
+        };
+        /** Optional per-file deny check — runs INSIDE the walk loop so a denied
+         *  file does not even open a fd. Returns true to deny. */
+        perFileDeny?: (absPath: string) => boolean;
+    } & WalkOptions): {
+        filesIndexed: number;
+        totalChunks: number;
+        capped: boolean;
+        totalSeen: number;
+        denied: number;
+        failed: number;
+        label: string;
+    };
     /**
      * Index plain-text output (logs, build output, test results) by splitting
      * into fixed-size line groups. Unlike markdown indexing, this does not

package/build/store.js

@@ -13,6 +13,7 @@ import { readFileSync, readdirSync, unlinkSync, existsSync, statSync, openSync,
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { walkDirectoryDetailed } from "./store-directory.js";
 // ─────────────────────────────────────────────────────────
 // Constants
 // ─────────────────────────────────────────────────────────
@@ -756,6 +757,51 @@ export class ContentStore {
         const contentHash = filePath ? createHash("sha256").update(text).digest("hex") : undefined;
         return withRetry(() => this.#insertChunks(chunks, label, text, filePath, contentHash, attribution));
     }
+    // ── Index Directory (#687) ──
+    /**
+     * Index every file under a directory by walking it with `walkDirectory` and
+     * delegating each discovered file to `this.index({ path })`. The per-file
+     * `openSync + fstatSync.isFile()` security gate at line ~845 stays active
+     * for every file — directory support never bypasses the TOCTOU defense
+     * from #442 round-3.
+     *
+     * Reported by @matiasduartee in #687.
+     */
+    indexDirectory(opts) {
+        const { path: rootPath, source, attribution, perFileDeny, ...walkOpts } = opts;
+        const walked = walkDirectoryDetailed(rootPath, walkOpts);
+        let filesIndexed = 0;
+        let totalChunks = 0;
+        let denied = 0;
+        let failed = 0;
+        for (const file of walked.files) {
+            if (perFileDeny && perFileDeny(file)) {
+                denied++;
+                continue;
+            }
+            try {
+                // Per-file source label so ctx_search(source: "<file>") still works.
+                const fileSource = source ? `${source}:${file}` : file;
+                const r = this.index({ path: file, source: fileSource, attribution });
+                filesIndexed++;
+                totalChunks += r.totalChunks;
+            }
+            catch {
+                // Per-file failure (e.g. fd-bound fstat rejection of a non-regular
+                // file that races between walk and read) — count + continue.
+                failed++;
+            }
+        }
+        return {
+            filesIndexed,
+            totalChunks,
+            capped: walked.capped,
+            totalSeen: walked.totalSeen,
+            denied,
+            failed,
+            label: source ?? rootPath,
+        };
+    }
     // ── Index Plain Text ──
     /**
      * Index plain-text output (logs, build output, test results) by splitting