@deepseek-ai/dsh-file-reference-local 0.1.1-rc.2 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/file-reference-local/README.md
-README.md: 67b07eef4b59fdcc5e21104cac4628feb1c15f4e
-README.zh.md: beded13250daf041294e4e2656d0e1374407ff94
+README.md: da5db0882e9f4538bdd901a970eca98aac10bbde
+README.zh.md: cea38d335c8b29ddc3c875782cb62df1d0ae6e0d

package/README.md

@@ -1,24 +1,102 @@
-# `@deepseek-ai/dsh-file-reference-local`
+---
+description: "Local-workspace @file completion provider for users and maintainers enabling, sizing, or debugging ctx.fileReferences discovery."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-file-reference-local
 
 English | [中文](README.zh.md)
 
-Local-filesystem implementation of `ctx.fileReferences`. It maintains one bounded `WorkspaceFileSearch` per agent, rooted at that session's `cwd` and falling back to the host process cwd. The index ranks direct directory listings for queries containing `/`, otherwise fuzzy-ranks a bounded recursive index; it never follows directory symlinks.
+## Summary
+
+Agents and their host UIs get ranked path candidates for `@file` mentions, scoped to each agent's workspace and bounded so even large repositories stay responsive. `dsh-file-reference-local` implements `ctx.fileReferences` for the local filesystem: it keeps one reusable search index per agent, rebuilds it in the background after tool results so completion reflects workspace changes without stalling, and never follows directory symlinks. When the addressed agent can call `read`, it also installs a stable one-sentence guidance into the system prompt. Choose it when the agent's `read` tool operates on the Harness host filesystem; remote or virtual namespaces need a provider whose discovery matches the tool.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this provider when `@file` completion should discover the Harness host's own filesystem — the namespace the shipped `read` tool operates on. Each agent's workspace is indexed from its session working directory, falling back to the host process directory when the session has none.
+
+### Enabling the provider
+
+The defaults suit a typical workspace, so the minimal mount needs no configuration:
+
+```yaml
+- name: '@deepseek-ai/dsh-file-reference-local'
+  config:
+    maxResults: 20
+```
+
+### What you get
+
+Typing `@` in a host UI returns up to `maxResults` ranked path candidates for the addressed agent. A query containing `/` lists the matching directory's entries directly; a bare query fuzzy-ranks the bounded recursive index. Directory candidates keep the mention open with a trailing slash. After any tool result the agent's index is marked stale: the next query still answers from it and its replacement builds in the background, so a rebuild never sits in front of the caret.
+
+### Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxResults` | `20` | Maximum ranked candidates returned for one query |
+| `maxEntries` | `50000` | Maximum files and directories indexed per agent workspace |
+| `excludedDirectories` | `['.git', 'node_modules', 'dist', 'build', 'out', 'coverage', 'target', '.next', '.nuxt', '.turbo', '.venv', '__pycache__', '.pytest_cache', '.mypy_cache', '.gradle']` | Directory basenames omitted from traversal and candidates |
+
+Every numeric value must be a positive safe integer, and every excluded name must be a non-empty basename without `/` or `\`.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
 
-Tool-result events invalidate the addressed agent's reusable index so later completion observes likely workspace mutations. Agent disposal releases that index and its scoped prompt contribution; plugin disposal awaits every prompt fiber and releases all cached searches.
+<details>
+<summary>Implementation internals — click to expand</summary>
 
-## Configuration
+This section explains the design of the provider; the observable behavior is covered in [Use this package](#use-this-package).
 
-| Key | Default | Contract |
-|---|---:|---|
-| `maxResults` | `20` | Maximum ranked candidates returned for one query. |
-| `maxEntries` | `10000` | Maximum files and directories indexed per agent workspace. |
-| `excludedDirectories` | `[".git", "node_modules"]` | Directory basenames omitted from traversal and candidates. |
+### Design concept
 
-Every numeric value must be a positive safe integer. Excluded names must be non-empty basenames without `/` or `\`.
+The provider maintains one reusable `WorkspaceFileSearch` per agent, rooted at that session's `cwd`. Directory-scoped queries (`a/b/...`) list live directory state, while bare fuzzy queries share one bounded recursive traversal. Only a workspace's first bare query waits for that traversal; a `tool/result` event marks the settled entries stale, and the next bare query serves them while the replacement builds. The model guidance is a per-agent prompt section contributed only while the addressed agent has a `read` tool; agent disposal releases both the index and the prompt fiber.
 
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `LocalFileReferenceService`: config validation, per-agent searches, prompt install |
+| [`src/search.ts`](src/search.ts) | `WorkspaceFileSearch`: traversal, ranking, exclusion, staleness and background rebuild |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion for the discovery contract |
+
+### Main flow
+
+A `list(agent, query, signal)` call either lists one directory's entries or reads the shared bounded index, ranks the candidates (exact, prefix, substring, then subsequence scores with directory bonuses), and returns at most `maxResults` in deterministic order. `tool/result` events mark the addressed agent's index stale so a later bare query observes a fresh tree. An unreadable or excluded subtree contributes no candidates, while an unreadable root fails its traversal instead: a transient failure must not replace still-good entries with an empty index.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the seam this provider implements to the tools its candidates point at.
+
+- [File-reference seam](../file-reference/README.md) — the service contract and `@file` grammar this provider implements.
+- [Session-reference subsystem](../../../docs/subsystems/session-reference.md) — the shared file-reference contract behind host UIs.
+- [Filesystem tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs) — the `read` tool whose namespace discovery must match.
+- [Context group map](../README.md) — sibling request-context packages.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-### File-reference guidance when `read` is available
+### File-reference guidance when read is available
 
 #### What the model sees
 
@@ -27,7 +105,7 @@ When the addressed agent has an effective `read` tool, the provider contributes
 ##### File-reference instruction
 
 ```markdown
-Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
+Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 ```
 
 #### Token effect
@@ -36,10 +114,26 @@ Conditional and fixed: the one sentence is present while `read` is visible to th
 
 #### KV Cache effect
 
-The stable sentence joins the system-prompt prefix. Mounting or removing this provider, or changing whether `read` is visible, changes that prefix; queries, candidates, and index invalidations do not.
+The stable sentence joins the system-prompt prefix. Mounting or removing this provider, or changing whether `read` is visible, changes that prefix; queries, candidates, and index staleness do not.
 
 ## Known Limitations and Deferred Work
 
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is a poor fit. They are current package constraints.
+
 - **Host-local namespace** — the provider scans the Harness host filesystem, so remote or virtual `read` implementations require a provider whose namespace matches the tool.
-- **Bounded advisory index** — very large workspaces may omit paths after `maxEntries`, and excluded or unreadable directories do not appear.
+- **Bounded advisory index** — very large workspaces may omit paths after `maxEntries`, and excluded or unreadable directories do not appear. The default exclusions name only build outputs no ecosystem also uses for sources; `lib` is deliberately absent, so a workspace that builds into it adds that name through `excludedDirectories`.
+- **One invalidation of staleness** — a bare query answered right after a tool result reflects the tree as of the previous traversal; the following query sees the rebuild.
 - **No ignore-file semantics** — `.gitignore` and other project ignore files do not influence discovery; only configured directory basenames are excluded.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,45 +1,139 @@
-# `@deepseek-ai/dsh-file-reference-local`
+---
+description: "面向用户与维护者的本地工作区 @file 补全提供方，用于启用、设置大小或排查 ctx.fileReferences 的发现能力。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-file-reference-local
 
 [English](README.md) | 中文
 
-`ctx.fileReferences` 的本地文件系统实现。它为每个 agent（智能体）维护一个有界的 `WorkspaceFileSearch`，以该会话的 `cwd` 为根目录；缺少该值时回退到宿主进程的 cwd。查询包含 `/` 时，索引会对直接列出的目录项排序；否则会对有界递归索引进行模糊排序。索引永远不会跟随目录符号链接。
+## 概述
+
+agent（智能体）及其宿主 UI 获得 `@file` mention 的排序路径候选，范围限定在各自 agent 的工作区，并有界以保证大型仓库依然响应迅速。`dsh-file-reference-local` 在本地文件系统上实现 `ctx.fileReferences`：它为每个 agent 维护一个可复用的搜索索引，在工具结果后于后台重建索引，让补全反映工作区变化而不发生停顿，且从不跟随目录符号链接。当指定 agent 可以调用 `read` 时，它还会向系统提示词安装一句稳定指引。当 agent 的 `read` 工具作用于 Harness 宿主文件系统时选择它；远程或虚拟命名空间需要发现能力与工具一致的提供方。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当 `@file` 补全应发现 Harness 宿主自身的文件系统——即随附 `read` 工具所操作的命名空间——时，挂载此提供方。每个 agent 的工作区从该会话的工作目录开始建立索引；会话没有工作目录时回退到宿主进程目录。
+
+### 启用提供方
+
+默认设置适合典型工作区，因此最小挂载无需任何配置：
+
+```yaml
+- name: '@deepseek-ai/dsh-file-reference-local'
+  config:
+    maxResults: 20
+```
+
+### 你能得到什么
+
+在宿主 UI 中输入 `@` 会为指定 agent 返回至多 `maxResults` 个排序路径候选。包含 `/` 的查询直接列出匹配目录的条目；裸查询对有界递归索引做模糊排序。目录候选以尾斜杠保持 mention 开放。任何工具结果之后，该 agent 的索引会被标记为陈旧：下一次查询仍由它作答，其替代品在后台构建，因此重建不会挡在光标前面。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxResults` | `20` | 单次查询返回的排序候选最大数量 |
+| `maxEntries` | `50000` | 每个 agent 工作区建立索引的文件与目录最大数量 |
+| `excludedDirectories` | `['.git', 'node_modules', 'dist', 'build', 'out', 'coverage', 'target', '.next', '.nuxt', '.turbo', '.venv', '__pycache__', '.pytest_cache', '.mypy_cache', '.gradle']` | 遍历与候选中排除的目录基名 |
+
+所有数值都必须是正的安全整数，所有排除名都必须是不含 `/` 或 `\` 的非空基名。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
 
-工具结果事件会使指定 agent 的可复用索引失效，使后续补全能够反映工作区中可能发生的变更。agent 的 dispose（资源释放）会释放该索引及其作用域内的提示词贡献；插件 dispose 会等待所有提示词 fiber，并释放全部缓存的搜索器。
+<details>
+<summary>实现细节——点击展开</summary>
 
-## 配置
+本节解释提供方的设计；可观察行为见[使用本包](#use-this-package)。
 
-| 配置键 | 默认值 | 契约 |
-|---|---:|---|
-| `maxResults` | `20` | 单次查询返回的候选项最大数量。 |
-| `maxEntries` | `10000` | 每个 agent 工作区建立索引的文件和目录最大数量。 |
-| `excludedDirectories` | `[".git", "node_modules"]` | 遍历和候选项中排除的目录基名。 |
+### 设计理念
 
-所有数值都必须是正的安全整数。排除名称必须是非空基名，且不能包含 `/` 或 `\`。
+提供方为每个 agent 维护一个可复用的 `WorkspaceFileSearch`，以该会话的 `cwd` 为根。目录范围查询（`a/b/...`）列出实时目录状态，裸模糊查询共享一次有界递归遍历。只有一个工作区的首次裸查询会等待该遍历；`tool/result` 事件把已完成的条目标记为陈旧，下一次裸查询在替代品构建期间继续由它作答。模型指引是按 agent 的提示词段，仅在指定 agent 拥有 `read` 工具时贡献；agent 释放时会同时释放索引与提示词 fiber。
 
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `LocalFileReferenceService`：配置校验、按 agent 搜索、提示词安装 |
+| [`src/search.ts`](src/search.ts) | `WorkspaceFileSearch`：遍历、排序、排除、陈旧标记与后台重建 |
+| [`src/invariant.ts`](src/invariant.ts) | 发现约定的不变式伴生插件 |
+
+### 主要流程
+
+`list(agent, query, signal)` 要么列出某个目录的条目，要么读取共享的有界索引，对候选排序（精确、前缀、子串，再到子序列得分，目录有加成），并按确定性顺序返回至多 `maxResults` 个。`tool/result` 事件把指定 agent 的索引标记为陈旧，之后的裸查询因此观察到全新目录树。不可读或已排除的子目录不贡献候选，而不可读的根目录则让该次遍历失败：一次瞬时故障不得用空索引覆盖仍然有效的条目。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+包级约定不够用时阅读以下页面。它们从本提供方所实现的 seam 进入其候选所指向的工具。
+
+- [文件引用 seam](../file-reference/README.zh.md)——本提供方所实现的服务约定与 `@file` 语法。
+- [会话引用子系统](../../../docs/subsystems/session-reference.zh.md)——宿主 UI 背后的共享文件引用约定。
+- [文件系统工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-fs)——发现能力必须匹配其命名空间的 `read` 工具。
+- [context 组地图](../README.zh.md)——相邻的请求上下文包。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
 ### `read` 可用时的文件引用指引
 
-#### 模型看到什么
+#### 模型看到的内容
 
 当指定 agent 有实际生效的 `read` 工具时，提供方会贡献以下稳定的系统提示词段：
 
 ##### 文件引用指令
 
 ```markdown
-Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
+Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 ```
 
 #### Token 影响
 
 该影响有条件且固定：只要 `read` 对指定 agent 可见，这一句就会存在；候选查询本身不增加 token，所选路径只会贡献普通用户消息中的对应字符。
 
-#### KV 缓存影响
+#### KV Cache 影响
+
+该稳定句子会加入系统提示词前缀。挂载或移除此提供方，或者改变 `read` 是否可见，都会改变该前缀；查询、候选项和索引陈旧标记不会改变前缀。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
 
-该稳定句子会加入系统提示词前缀。挂载或移除此提供方，或者改变 `read` 是否可见，都会改变该前缀；查询、候选项和索引失效不会改变前缀。
 
-## 已知限制与暂缓事项
+这些限制说明该提供方何时不合适。它们是当前包约束。
 
 - **宿主本地命名空间**：提供方扫描 Harness 宿主的文件系统，因此远程或虚拟 `read` 实现需要使用命名空间与该工具一致的提供方。
-- **有界的提示性索引**：超大型工作区可能省略 `maxEntries` 之后的路径；被排除或无法读取的目录不会出现。
+- **有界的提示性索引**：超大型工作区可能省略 `maxEntries` 之后的路径；被排除或无法读取的目录不会出现。默认排除项只列没有任何生态用作源码目录的构建产物；`lib` 被刻意排除在外，因此构建进 `lib` 的工作区需通过 `excludedDirectories` 自行加上。
+- **一次失效的陈旧窗口**：紧接工具结果之后的模糊查询反映的是上一次遍历时的目录树；下一次查询才看到重建结果。
 - **没有忽略文件语义**：`.gitignore` 和其他项目忽略文件不会影响发现；系统只排除已配置的目录基名。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -14,19 +14,51 @@ import { activeAtToken, formatFileMention } from "@deepseek-ai/dsh-file-referenc
 /** Default maximum file and directory candidates rendered for one query. */
 const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
 /** Default maximum entries retained in one workspace search index. */
-const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 1e4;
-/** Directory basenames omitted from traversal unless the deployment overrides them. */
-const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = [".git", "node_modules"];
+const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 5e4;
+/**
+* Directory basenames omitted from traversal unless the deployment overrides
+* them: version-control and dependency stores plus build-output names that no
+* ecosystem also uses for sources. Generated files carry the basenames of the
+* sources that produced them, so an unfiltered tree both spends the entry
+* budget twice and ranks `dist/x.js` beside `src/x.ts` for every query.
+*
+* `lib` is deliberately absent: Ruby gems and many npm packages keep their
+* sources there, and excluding it would make `@` miss those sources entirely
+* and silently. A workspace that builds into `lib` adds it through
+* `excludedDirectories`.
+*/
+const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = [
+	".git",
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	"target",
+	".next",
+	".nuxt",
+	".turbo",
+	".venv",
+	"__pycache__",
+	".pytest_cache",
+	".mypy_cache",
+	".gradle"
+];
 /**
 * Cancellable, reusable fuzzy index rooted at one agent working directory.
 * Directory-scoped queries list live state; bare fuzzy queries share one
-* bounded traversal until the `@` interaction ends or a tool result invalidates it.
+* bounded traversal. Only the first query of a workspace waits for that
+* traversal — an invalidated index keeps answering while its replacement
+* builds behind the caret.
 */
 var WorkspaceFileSearch = class {
 	root;
 	config;
 	excludedDirectories;
+	settled;
 	generation;
+	/** Monotonic invalidation counter; a settled index below it is stale. */
+	invalidations = 0;
 	disposed = false;
 	constructor(root, config) {
 		this.root = root;
@@ -52,28 +84,61 @@ var WorkspaceFileSearch = class {
 			const fragment = slash < 0 ? "" : query.slice(slash + 1);
 			return this.listDirectory(directory, fragment, signal);
 		}
-		return rankCandidates((await waitForPromise(this.ensureIndex(), signal)).filter((candidate) => visibleForGlobalQuery(candidate.path, query)), query, this.config.maxResults);
+		return rankCandidates((await this.indexFor(signal)).filter((candidate) => visibleForGlobalQuery(candidate.path, query)), query, this.config.maxResults);
 	}
-	/** Discard the current index so the next bare query observes a fresh tree. */
+	/**
+	* Mark the index stale so a later bare query observes a fresh tree.
+	*
+	* The stale entries are kept and keep answering: a rebuild costs one
+	* traversal of the whole workspace, and putting that in front of the caret
+	* is what a caller invalidating on every tool result would otherwise pay.
+	*/
 	invalidate() {
-		this.generation?.controller.abort(/* @__PURE__ */ new Error("file search index invalidated"));
-		this.generation = void 0;
+		this.invalidations += 1;
 	}
 	/** Abort traversal and make later queries return no candidates. */
 	dispose() {
 		if (this.disposed) return;
 		this.disposed = true;
-		this.invalidate();
+		this.generation?.controller.abort(/* @__PURE__ */ new Error("file search index disposed"));
+		this.generation = void 0;
+		this.settled = void 0;
+	}
+	/**
+	* The entries a bare fuzzy query ranks. Only the first query of a workspace
+	* waits for a traversal; afterwards a stale index answers immediately and
+	* its replacement builds in the background.
+	* @param signal - cancels this caller's wait without killing a shared traversal.
+	* @returns indexed paths, at most one invalidation behind the tree.
+	*/
+	async indexFor(signal) {
+		const settled = this.settled;
+		if (settled === void 0) return waitForPromise(this.ensureIndex(), signal);
+		if (settled.startedAt < this.invalidations) this.ensureIndex().catch(() => {});
+		return settled.entries;
 	}
 	ensureIndex() {
 		if (this.generation !== void 0) return this.generation.promise;
 		const controller = new AbortController();
+		const startedAt = this.invalidations;
 		const generation = {
 			controller,
 			promise: Promise.resolve([])
 		};
-		generation.promise = this.scanWorkspace(controller.signal).catch((error) => {
-			/* v8 ignore next -- every owned abort clears `generation` synchronously; this only protects an unexpected scan failure */
+		generation.promise = this.scanWorkspace(controller.signal).then((entries) => {
+			/* v8 ignore next -- disposal aborts this traversal, so it reaches the
+			* rejection handler instead; the guard only covers a scan that finished
+			* its last directory in the instant before the abort landed, and must
+			* not hand a disposed index its entries back. */
+			if (this.disposed) return entries;
+			this.generation = void 0;
+			this.settled = {
+				entries,
+				startedAt
+			};
+			return entries;
+		}, (error) => {
+			/* v8 ignore next -- dispose clears `generation` synchronously; this only protects an unexpected scan failure */
 			if (this.generation === generation) this.generation = void 0;
 			throw error;
 		});
@@ -91,7 +156,7 @@ var WorkspaceFileSearch = class {
 			const directory = directories[cursor];
 			/* v8 ignore next 3 -- cursor is bounded by this exact queue's length. */
 			if (directory === void 0) throw new Error("file search selected a missing directory");
-			const entries = await readDirectory(directory.absolute, signal);
+			const entries = cursor === 0 ? await readWorkspaceRoot(directory.absolute, signal) : await readDirectory(directory.absolute, signal);
 			for (const entry of entries) {
 				signal.throwIfAborted();
 				const path = directory.relative === "" ? entry.name : `${directory.relative}/${entry.name}`;
@@ -158,6 +223,12 @@ async function resolveDisplayDirectory(root, displayDirectory, signal) {
 	}
 	return absolute;
 }
+async function readWorkspaceRoot(absolute, signal) {
+	signal.throwIfAborted();
+	const entries = await readdir(absolute, { withFileTypes: true });
+	signal.throwIfAborted();
+	return entries.sort((left, right) => compareText(left.name, right.name));
+}
 async function readDirectory(absolute, signal) {
 	signal.throwIfAborted();
 	try {
@@ -260,7 +331,7 @@ var LocalFileReferenceService = class extends FileReferenceService {
 		super(ctx);
 		this.config = {
 			maxResults: config.maxResults ?? 20,
-			maxEntries: config.maxEntries ?? 1e4,
+			maxEntries: config.maxEntries ?? 5e4,
 			excludedDirectories: config.excludedDirectories ?? DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES
 		};
 		validateConfig(this.config);
@@ -269,7 +340,7 @@ var LocalFileReferenceService = class extends FileReferenceService {
 			const fiber = agent.ctx.inject(["systemPrompt", "tools"], (scope) => {
 				scope.systemPrompt.section({
 					name: "context:file-reference",
-					order: 99,
+					order: scope.systemPrompt.getSectionOrder("FILE_REFERENCE"),
 					text: () => agent.ctx.tools.get("read", agent) === void 0 ? "" : FILE_REFERENCE_PROMPT$1
 				});
 			});

package/lib/types/index.js

@@ -35,7 +35,7 @@ export class LocalFileReferenceService extends FileReferenceService {
             const fiber = agent.ctx.inject(['systemPrompt', 'tools'], (scope) => {
                 scope.systemPrompt.section({
                     name: 'context:file-reference',
-                    order: 99,
+                    order: scope.systemPrompt.getSectionOrder('FILE_REFERENCE'),
                     text: () => agent.ctx.tools.get('read', agent) === undefined ? '' : FILE_REFERENCE_PROMPT,
                 });
             });

package/lib/types/search.d.ts

@@ -10,9 +10,20 @@ export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-referenc
 /** Default maximum file and directory candidates rendered for one query. */
 export declare const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
 /** Default maximum entries retained in one workspace search index. */
-export declare const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 10000;
-/** Directory basenames omitted from traversal unless the deployment overrides them. */
-export declare const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES: readonly [".git", "node_modules"];
+export declare const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 50000;
+/**
+ * Directory basenames omitted from traversal unless the deployment overrides
+ * them: version-control and dependency stores plus build-output names that no
+ * ecosystem also uses for sources. Generated files carry the basenames of the
+ * sources that produced them, so an unfiltered tree both spends the entry
+ * budget twice and ranks `dist/x.js` beside `src/x.ts` for every query.
+ *
+ * `lib` is deliberately absent: Ruby gems and many npm packages keep their
+ * sources there, and excluding it would make `@` miss those sources entirely
+ * and silently. A workspace that builds into `lib` adds it through
+ * `excludedDirectories`.
+ */
+export declare const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES: readonly [".git", "node_modules", "dist", "build", "out", "coverage", "target", ".next", ".nuxt", ".turbo", ".venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".gradle"];
 /** Resolved limits and exclusions for one workspace index. */
 export interface FileSearchConfig {
     /** Maximum ranked candidates returned for one query. */
@@ -25,13 +36,18 @@ export interface FileSearchConfig {
 /**
  * Cancellable, reusable fuzzy index rooted at one agent working directory.
  * Directory-scoped queries list live state; bare fuzzy queries share one
- * bounded traversal until the `@` interaction ends or a tool result invalidates it.
+ * bounded traversal. Only the first query of a workspace waits for that
+ * traversal — an invalidated index keeps answering while its replacement
+ * builds behind the caret.
  */
 export declare class WorkspaceFileSearch {
     private readonly root;
     private readonly config;
     private readonly excludedDirectories;
+    private settled;
     private generation;
+    /** Monotonic invalidation counter; a settled index below it is stale. */
+    private invalidations;
     private disposed;
     constructor(root: string, config: FileSearchConfig);
     /**
@@ -41,10 +57,24 @@ export declare class WorkspaceFileSearch {
      * @returns at most `maxResults` deterministic candidates.
      */
     list(rawQuery: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
-    /** Discard the current index so the next bare query observes a fresh tree. */
+    /**
+     * Mark the index stale so a later bare query observes a fresh tree.
+     *
+     * The stale entries are kept and keep answering: a rebuild costs one
+     * traversal of the whole workspace, and putting that in front of the caret
+     * is what a caller invalidating on every tool result would otherwise pay.
+     */
     invalidate(): void;
     /** Abort traversal and make later queries return no candidates. */
     dispose(): void;
+    /**
+     * The entries a bare fuzzy query ranks. Only the first query of a workspace
+     * waits for a traversal; afterwards a stale index answers immediately and
+     * its replacement builds in the background.
+     * @param signal - cancels this caller's wait without killing a shared traversal.
+     * @returns indexed paths, at most one invalidation behind the tree.
+     */
+    private indexFor;
     private ensureIndex;
     private scanWorkspace;
     private listDirectory;

package/lib/types/search.js

@@ -11,19 +11,51 @@ export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-referenc
 /** Default maximum file and directory candidates rendered for one query. */
 export const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
 /** Default maximum entries retained in one workspace search index. */
-export const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 10_000;
-/** Directory basenames omitted from traversal unless the deployment overrides them. */
-export const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = ['.git', 'node_modules'];
+export const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 50_000;
+/**
+ * Directory basenames omitted from traversal unless the deployment overrides
+ * them: version-control and dependency stores plus build-output names that no
+ * ecosystem also uses for sources. Generated files carry the basenames of the
+ * sources that produced them, so an unfiltered tree both spends the entry
+ * budget twice and ranks `dist/x.js` beside `src/x.ts` for every query.
+ *
+ * `lib` is deliberately absent: Ruby gems and many npm packages keep their
+ * sources there, and excluding it would make `@` miss those sources entirely
+ * and silently. A workspace that builds into `lib` adds it through
+ * `excludedDirectories`.
+ */
+export const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = [
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'target',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    '.venv',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.gradle',
+];
 /**
  * Cancellable, reusable fuzzy index rooted at one agent working directory.
  * Directory-scoped queries list live state; bare fuzzy queries share one
- * bounded traversal until the `@` interaction ends or a tool result invalidates it.
+ * bounded traversal. Only the first query of a workspace waits for that
+ * traversal — an invalidated index keeps answering while its replacement
+ * builds behind the caret.
  */
 export class WorkspaceFileSearch {
     root;
     config;
     excludedDirectories;
+    settled;
     generation;
+    /** Monotonic invalidation counter; a settled index below it is stale. */
+    invalidations = 0;
     disposed = false;
     constructor(root, config) {
         this.root = root;
@@ -56,31 +88,69 @@ export class WorkspaceFileSearch {
             const fragment = slash < 0 ? '' : query.slice(slash + 1);
             return this.listDirectory(directory, fragment, signal);
         }
-        const indexed = await waitForPromise(this.ensureIndex(), signal);
+        const indexed = await this.indexFor(signal);
         return rankCandidates(indexed.filter(candidate => visibleForGlobalQuery(candidate.path, query)), query, this.config.maxResults);
     }
-    /** Discard the current index so the next bare query observes a fresh tree. */
+    /**
+     * Mark the index stale so a later bare query observes a fresh tree.
+     *
+     * The stale entries are kept and keep answering: a rebuild costs one
+     * traversal of the whole workspace, and putting that in front of the caret
+     * is what a caller invalidating on every tool result would otherwise pay.
+     */
     invalidate() {
-        this.generation?.controller.abort(new Error('file search index invalidated'));
-        this.generation = undefined;
+        this.invalidations += 1;
     }
     /** Abort traversal and make later queries return no candidates. */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.invalidate();
+        this.generation?.controller.abort(new Error('file search index disposed'));
+        this.generation = undefined;
+        this.settled = undefined;
+    }
+    /**
+     * The entries a bare fuzzy query ranks. Only the first query of a workspace
+     * waits for a traversal; afterwards a stale index answers immediately and
+     * its replacement builds in the background.
+     * @param signal - cancels this caller's wait without killing a shared traversal.
+     * @returns indexed paths, at most one invalidation behind the tree.
+     */
+    async indexFor(signal) {
+        const settled = this.settled;
+        if (settled === undefined)
+            return waitForPromise(this.ensureIndex(), signal);
+        if (settled.startedAt < this.invalidations) {
+            void this.ensureIndex().catch(() => {
+                // A background refresh failure is not this caller's error: the stale
+                // entries still answer and `settled.startedAt` stays behind, so the
+                // next bare query starts a fresh attempt.
+            });
+        }
+        return settled.entries;
     }
     ensureIndex() {
         if (this.generation !== undefined)
             return this.generation.promise;
         const controller = new AbortController();
+        const startedAt = this.invalidations;
         const generation = {
             controller,
             promise: Promise.resolve([]),
         };
-        generation.promise = this.scanWorkspace(controller.signal).catch((error) => {
-            /* v8 ignore next -- every owned abort clears `generation` synchronously; this only protects an unexpected scan failure */
+        generation.promise = this.scanWorkspace(controller.signal).then((entries) => {
+            /* v8 ignore next -- disposal aborts this traversal, so it reaches the
+             * rejection handler instead; the guard only covers a scan that finished
+             * its last directory in the instant before the abort landed, and must
+             * not hand a disposed index its entries back. */
+            if (this.disposed)
+                return entries;
+            this.generation = undefined;
+            this.settled = { entries, startedAt };
+            return entries;
+        }, (error) => {
+            /* v8 ignore next -- dispose clears `generation` synchronously; this only protects an unexpected scan failure */
             if (this.generation === generation)
                 this.generation = undefined;
             throw error;
@@ -98,7 +168,13 @@ export class WorkspaceFileSearch {
             if (directory === undefined) {
                 throw new Error('file search selected a missing directory');
             }
-            const entries = await readDirectory(directory.absolute, signal);
+            // The root is not a subtree: an unreadable branch costs its own
+            // candidates, but an unreadable root means the traversal learned
+            // nothing. Letting that settle would publish an empty index over
+            // entries that are still good and leave no invalidation to retry from.
+            const entries = cursor === 0
+                ? await readWorkspaceRoot(directory.absolute, signal)
+                : await readDirectory(directory.absolute, signal);
             for (const entry of entries) {
                 signal.throwIfAborted();
                 const path = directory.relative === '' ? entry.name : `${directory.relative}/${entry.name}`;
@@ -166,6 +242,12 @@ async function resolveDisplayDirectory(root, displayDirectory, signal) {
     }
     return absolute;
 }
+async function readWorkspaceRoot(absolute, signal) {
+    signal.throwIfAborted();
+    const entries = await readdir(absolute, { withFileTypes: true });
+    signal.throwIfAborted();
+    return entries.sort((left, right) => compareText(left.name, right.name));
+}
 async function readDirectory(absolute, signal) {
     signal.throwIfAborted();
     try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-file-reference-local",
   "description": "Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -37,22 +37,22 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-file-reference": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-file-reference": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }