fix(fs-search): make glob sampling an explicit choice

.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.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 .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md
-2026-07-27-glob-sampling.md: b9dfc7fc89ff61824094ccd5297f766c665f4edb
-2026-07-27-glob-sampling.zh.md: 4f022467e461247c746e906b32f5ecffcb885d56
+2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d
+2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300

.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md

@@ -12,15 +12,17 @@ Three individually valid behaviors composed into the false impression. A glob wi
 
 ## Decision
 
-A result that fits within `globMaxResults` remains complete and byte-for-byte modification-time ordered. An over-cap result is sampled round-robin across the complete result's top-level entries: every entry receives one slot before any receives a second, exhausted groups drop out, and relative order remains stable within each group. Grouping is relative to the actual search root, including an explicit `path`.
+A result that fits within `globMaxResults` remains complete and byte-for-byte modification-time ordered. The required `sampleOverCapGlobResults` config has no fallback: `false` retains the modification-time head for an over-cap result, while `true` samples round-robin across the complete result's top-level entries. In sampling mode, every entry receives one slot before any receives a second, exhausted groups drop out, relative order remains stable within each group, and grouping is relative to the actual search root, including an explicit `path`.
 
-The footer states that the page is a cross-entry sample rather than the modification-time head, reports how many top-level entries it reaches when that fact adds information, and preserves the complete sorted list in the spill artifact. When more top-level entries exist than inline slots, it tells the model to narrow `path`.
+In sampling mode, the footer states that the page is a cross-entry sample rather than the modification-time head and reports how many top-level entries it reaches when that fact adds information. When more top-level entries exist than inline slots, it tells the model to narrow `path`. Head mode keeps the ordinary capped-result footer. When spill succeeds, both modes preserve the complete sorted list in the artifact.
 
-The prompt and schema also state that a pattern without `/` matches at any depth and that glob returns files, never directory entries. Directory orientation remains ordinary shell work in deployments that expose the model-facing bash tool: use `ls` for one directory, and glob for a named file-path pattern across the tree. `ctx.fs.listDir` remains an internal provider primitive used by skill discovery; this decision adds no model-facing `list` tool.
+The prompt and schema state the configured over-cap ordering, that a pattern without `/` matches at any depth, and that glob returns files, never directory entries. The shipped CLI composition explicitly selects head mode; deployments that want representative capped pages select sampling mode. Directory orientation remains ordinary shell work in deployments that expose the model-facing bash tool: use `ls` for one directory, and glob for a named file-path pattern across the tree. `ctx.fs.listDir` remains an internal provider primitive used by skill discovery; this decision adds no model-facing `list` tool.
 
 ## Alternatives considered
 
-**Keep the modification-time head and only warn about concentration.** Rejected after measuring the failure shape. A warning asks the model to distrust the only paths it received; representative data fixes the answer directly.
+**Keep the modification-time head as the only behavior.** Rejected after measuring the failure shape. Some deployments need the stable ordering, but a deployment that values workspace orientation can explicitly select representative data instead of asking the model to distrust the only paths it received.
+
+**Give the sampling choice a default.** Rejected. No product-wide evidence establishes either ordering as the implicit contract, so every composition selects one and misconfiguration fails at load.
 
 **Sample every result.** Rejected. A complete result loses nothing to truncation, so modification-time order remains useful for age-oriented questions. Sampling begins only when the head stops describing the whole.
 
@@ -36,10 +38,10 @@ The prompt and schema also state that a pattern without `/` matches at any depth
 
 ## Consequences
 
-An over-cap glob page no longer answers age-order questions from its inline paths; its footer says so, and the spill artifact retains the complete sorted view. Sampling balances only the first segment beneath the search root, so a deeper hot subtree can still dominate within one top-level entry.
+A sampling-mode over-cap page no longer answers age-order questions from its inline paths; its footer says so, and the spill artifact retains the complete sorted view. Sampling balances only the first segment beneath the search root, so a deeper hot subtree can still dominate within one top-level entry. Head mode retains the concentration risk as an explicit deployment trade-off.
 
-The tool surface does not grow. The fix changes glob's prompt, schema description, canonical output (`root` records the sampling basis), and over-cap Native rendering while leaving fitting results unchanged.
+The tool surface does not grow. Every composition must set `sampleOverCapGlobResults`; changing it alters glob's prompt, schema description, and over-cap Native rendering. The canonical output keeps `root` so sampling mode can recover its grouping basis, while fitting results remain unchanged.
 
 ## Testing
 
-Package tests pin concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario boots a minimal real Loader/app/local-bash composition and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head.
+Package tests pin the required config, both over-cap modes, their prompt and schema descriptions, concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario explicitly enables sampling, boots a minimal real Loader/app/local-bash composition, and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head.

.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md

@@ -12,15 +12,17 @@ Status: implemented
 
 ## 决策
 
-未超过 `globMaxResults` 的结果仍保持完整，且按修改时间排序的内容逐字节不变。超过上限时，系统会在完整结果的顶层条目之间按轮转方式采样：每个条目都先获得一个位置，之后才有条目获得第二个位置；已经用尽的分组会退出轮转；各组内部的相对顺序保持稳定。分组始终以实际搜索根为基准，显式指定 `path` 时也如此。
+未超过 `globMaxResults` 的结果仍保持完整，且按修改时间排序的内容逐字节不变。必填的 `sampleOverCapGlobResults` 配置没有回退值：`false` 会为超过上限的结果保留按修改时间排序的前部，`true` 则会在完整结果的顶层条目之间按轮转方式采样。采样模式下，每个条目都先获得一个位置，之后才有条目获得第二个位置；已经用尽的分组会退出轮转；各组内部的相对顺序保持稳定；分组以实际搜索根为基准，显式指定 `path` 时也如此。
 
-footer 会说明当前页面是跨条目的样本，而不是按修改时间排序的前部；当顶层条目覆盖数能提供额外信息时，还会报告该数量；完整排序列表仍保存在 spill 产物中。若顶层条目数量超过内联位置数，footer 会要求模型缩小 `path`。
+采样模式下，footer 会说明当前页面是跨条目的样本，而不是按修改时间排序的前部；当触达的顶层条目数能提供额外信息时，还会报告该数量。若顶层条目数量超过内联位置数，footer 会要求模型缩小 `path`。保留前部的模式沿用达到上限时的普通 footer。spill 成功时，两种模式都会在该产物中保留完整排序列表。
 
-提示词与 schema 还会说明：不含 `/` 的模式会匹配任意深度，glob 只返回文件，绝不返回目录条目。在向模型暴露 bash 工具的部署中，目录定位仍由普通 shell 操作完成：查看一个目录使用 `ls`，跨目录树按指定文件路径模式查找则使用 glob。skill（技能）发现流程仍将 `ctx.fs.listDir` 作为内部提供方原语使用；本决策不会新增面向模型的 `list` 工具。
+提示词与 schema 会说明配置所指定的超限结果排序方式、不含 `/` 的模式会匹配任意深度，以及 glob 只返回文件而绝不返回目录条目。随产品交付的 CLI（命令行界面）组合显式选择保留前部的模式；希望达到上限的页面具有代表性的部署则选择采样模式。在向模型暴露 bash 工具的部署中，目录定位仍由普通 shell 操作完成：查看一个目录使用 `ls`，跨目录树按指定文件路径模式查找则使用 glob。skill（技能）发现流程仍将 `ctx.fs.listDir` 作为内部提供方原语使用；本决策不会新增面向模型的 `list` 工具。
 
 ## 考虑过的替代方案
 
-**保留按修改时间排序的前部，只警告结果过于集中。** 测量实际故障形态后否决。警告只会要求模型怀疑自己拿到的唯一一批路径；具有代表性的数据能直接修正答案。
+**只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
+
+**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。
 
 **对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
 
@@ -36,10 +38,10 @@ footer 会说明当前页面是跨条目的样本，而不是按修改时间排
 
 ## 影响
 
-超过上限的 glob 页面无法再根据内联路径回答按时间判断新旧的问题；footer 会明确说明这一点，spill 产物仍保留完整的排序视图。采样只平衡搜索根下的第一路径段，因此某个顶层条目内部较深处、结果密集的子树仍可能占据主导。
+采样模式下，超过上限的 glob 页面无法再根据内联路径回答按时间判断新旧的问题；footer 会明确说明这一点，spill 产物仍保留完整的排序视图。采样只平衡搜索根下的第一路径段，因此某个顶层条目内部较深处、结果密集的子树仍可能占据主导。保留前部的模式则把集中风险作为显式部署取舍保留下来。
 
-工具接口不会扩大。此修复会更改 glob 的提示词、schema 描述、规范输出（`root` 记录采样基准）以及超过上限时的 Native 渲染，未超过上限的结果保持不变。
+工具接口不会扩大。每个组合都必须设置 `sampleOverCapGlobResults`；更改该值会改变 glob 的提示词、schema 描述以及超过上限时的 Native 渲染。规范输出保留 `root`，以便采样模式恢复其分组基准；未超过上限的结果保持不变。
 
 ## 测试
 
-包测试锁定了结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会启动最小化的真实 Loader/app/local-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。
+包测试锁定了必填配置、两种超过上限模式及其提示词和 schema 描述、结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会显式启用采样，启动最小化的真实 Loader/app/local-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。