fix: preserve mutation outcomes and bound reference replies

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 0.15.0 (unreleased)
 
+- Preserve completed/partial trash outcomes and actual file locations when the request deadline expires during metadata finalization. Propagate cancellation before the move and keep interruption accounting; client cancellation or disconnection still does not guarantee delivery of a final response.
+- Add optional Roslyn reference `limit` (1–1000, default 100, requires `symbolLocation`). Impact reports retain `totalReferences` and `referencesTruncated` alongside the existing returned `referencesCount`; unknown totals remain null and semantic risk/coverage rules stay unchanged.
+- Bound reference-tool replies by final formatted JSON size with `maxOutputChars` (2048–32768, default 8000). Preserve known totals and exact identities, report returned counts and omitted lists, and reject budgets that cannot hold required metadata. The output limit covers both providers and does not bound Roslyn search work or change internal impact aggregation.
 - Add bounded literal text search and file outlines with executable source follow-ups, exclusive/deduplicated scopes and file-level lexical/scan diagnostics. Retain local-text evidence boundaries and existing filesystem/cancellation/byte limits.
 - Add final-output context summaries and observed EOF correction requests without claiming the original range was covered. File-head excerpts now support bounded continuation as well as symbol excerpts.
 - Return an independent STDIO launch recipe on WORKSPACE_MISMATCH and via `--print-connection --workspace <absolute-path>`, without registration, project startup or rebinding. Add opt-in compact UI responses with unchanged snapshot IDs/images, shared C# candidates and live-control expansion requests; default full output remains compatible.

README.md

@@ -181,10 +181,10 @@ The 2026-09-08 check of the current Codex connection against TavernDesk source p
 | `wincode_analyze_workspace` | Parse solution structure and declared `.sln`/`.csproj` project references. |
 | `wincode_prepare_context` | Return code excerpts with file paths and line ranges within a character-based output limit. |
 | `wincode_find_code_symbol` | Search symbols and report the provider and completeness of the results. |
-| `wincode_find_references` | Find references using a returned symbol location; report ambiguous or incomplete results and provider limitations. |
+| `wincode_find_references` | Find references using a returned symbol location; optional Roslyn `limit` is 1–1000 (default 100, requires `symbolLocation`). Both providers accept `maxOutputChars` (2048–32768, default 8000) for the final JSON text. Preserve known totals and report returned counts, truncation and output omissions. |
 | `analyze_change_impact` | Estimate which code a change may affect. Return `riskLevel: "UNKNOWN"` and `confidence: "UNCERTAIN"` for ambiguous symbols, incomplete results or no references. |
 | `wincode_plan_refactoring` | Suggest pre-edit checks and verification steps based on change impact. |
-| `wincode_safe_move_to_trash` | Validate paths, move files to `trash/` and record metadata. |
+| `wincode_safe_move_to_trash` | Validate paths, move files to `trash/` and record metadata. Cancellation before the move stops it; finalization preserves the actual completed/partial outcome even after a deadline. |
 | `wincode_ui_list_windows` | Enumerate visible top-level windows with title/process filters and count limits. |
 | `wincode_ui_inspect` | Inspect UI control subtrees, interactive states, and optional numbered screenshots. |
 | `wincode_ui_review` | Return explicit XAML/C# source candidates, lines, hashes and scoped next requests from one UI snapshot. |
@@ -436,10 +436,10 @@ Skill 安装和客户端配置方法见 [Skill 与 MCP 配置指南](WinCode-Ski
 | `wincode_analyze_workspace` | 解析解决方案结构及 `.sln`/`.csproj` 中声明的项目引用。 |
 | `wincode_prepare_context` | 按文件、符号或行号读取代码片段，返回文件路径和行号，并限制输出字符数。 |
 | `wincode_find_code_symbol` | 检索代码符号，说明结果来自哪个分析服务，以及查询是否完整。 |
-| `wincode_find_references` | 使用返回的符号位置查找引用，报告匹配不唯一、查询不完整或分析服务能力受限的情况。 |
+| `wincode_find_references` | 使用返回的符号位置查找引用；Roslyn 可选 `limit` 为 1–1000，默认 100，必须同时提供 `symbolLocation`。两种提供方均支持最终 JSON 字符预算 `maxOutputChars`（2048–32768，默认 8000），保留已知总数，报告实际返回数、截断状态和输出省略项。 |
 | `analyze_change_impact` | 评估代码改动可能影响的范围。符号不唯一、查询不完整或未找到引用时，返回 `riskLevel: "UNKNOWN"` 和 `confidence: "UNCERTAIN"`。 |
 | `wincode_plan_refactoring` | 根据改动影响，建议修改前需要检查的内容和修改后的验证步骤。 |
-| `wincode_safe_move_to_trash` | 校验路径后将文件移入 `trash/`，并记录元数据。 |
+| `wincode_safe_move_to_trash` | 校验路径后移入 `trash/` 并记录元数据；移动前取消会停止操作，移动后的收尾即使超时也保留实际 completed/partial 结果。 |
 | `wincode_ui_list_windows` | 列出可见顶层窗口，支持按标题或进程名筛选，并限制返回数量。 |
 | `wincode_ui_inspect` | 读取控件子树、状态和可选的编号截图。 |
 | `wincode_ui_review` | 根据一次 UI 检查结果，返回可能相关的 XAML/C# 代码、行号、哈希及后续读取参数。 |

WinCode-架构与数据流说明.md

@@ -104,7 +104,7 @@ sequenceDiagram
 
 **有界受理和实际执行分开。** 每实例最多 32 个未完成业务请求（含 workspace_open），hello/tools/list 共享 4 个轻量槽。既有 Roslyn/UI/恢复互斥决定 FIFO 等待；其他已有并行能力继续并行。满额在执行前返回 SERVER_BUSY，不驱逐先来者或自动重放。恢复占用业务容量，但不计入它自己等待排空的 inFlight；关闭和手动释放同时考虑未完成受理与实际清理。
 
-原始参数含未知字段，在归一化前按 UTF-8 JSON 限制为 64 KiB。外层预算包含排队，Router/Adapter 使用剩余 deadline。Router 与准入租约使用同一截止时复用计时器；独立更短的预算保留自己的计时器，异常路径按实际操作上下文保留 REQUEST_TIMEOUT。MCP 在工具执行返回后再次检查截止，不返回已过期的成功结果；租约收尾同时读取实际失败和取消原因，使同步截止检查或更短的适配器预算也计入 timedOut，实际清理完成后才归还容量。health.admission 给出计数和等待/执行耗时；hello 仅读取缓存磁盘观察，诊断才刷新统计。这些限制不能消除 SDK 解析帧的瞬时内存，也不提供挂起 OS I/O 的强制终止保证。
+原始参数含未知字段，在归一化前按 UTF-8 JSON 限制为 64 KiB。外层预算包含排队，Router/Adapter 使用剩余 deadline。Router 与准入租约使用同一截止时复用计时器；独立更短的预算保留自己的计时器，异常路径按实际操作上下文保留 REQUEST_TIMEOUT。MCP 在工具执行返回后再次检查截止，只读工具不返回已过期的成功结果；回收站工具保留已确定的 completed/partial 及实际路径，移动前仍检查取消，移动后完成元数据收尾。租约收尾同时读取实际失败和取消原因，使同步截止检查或更短的适配器预算也计入 timedOut，实际清理完成后才归还容量。客户端取消/断连仍不保证最终响应送达，也不表示副作用回滚。health.admission 给出计数和等待/执行耗时；hello 仅读取缓存磁盘观察，诊断才刷新统计。这些限制不能消除 SDK 解析帧的瞬时内存，也不提供挂起 OS I/O 的强制终止保证。
 
 ## 3. 代码证据的数据流
 
@@ -143,10 +143,14 @@ flowchart LR
 
 0.13.0 退役外部 Serena 配置、连接及旧 source；local-text 与 roslyn 均不能仅凭来源证明完整性。ImpactAnalyzer 对身份不唯一或查询不完整保留 UNKNOWN；零引用不构成可安全删除的证明。
 
+公开引用接口可在 symbolLocation 上指定 Roslyn `limit`（1–1000，默认 100），复用 Host 原有限制，不提供分页。影响报告的 `referencesCount` 为实际聚合条数，`totalReferences` 为查询范围内已知总数（未知为 null），`referencesTruncated` 表示引用返回是否被裁剪（未知为 null）。这些字段不把局部引用扩展成全仓覆盖，也不改变 UNKNOWN 规则。
+
 ### 3.3 输出预算位于最后一公里
 
 普通代码导航由 CodeNavigation 复用 LocalTextScanner：字面量搜索在排他目录/文件范围内进行，文件概览读取实际行数、字节数及文本声明，均返回 prepare_context 续读请求。路径范围先整体校验，实际读取再检查真实路径；扫描预算与最终 JSON 预算分别生效。LocalTextScanner 保留具名文件问题和省略计数，不把词法不确定性隐藏成完整结果。导航不启动语义 Host，也不改变所配置的提供方。
 
+引用工具由 ReferenceResponse 对最终格式化 JSON 执行 `maxOutputChars` 预算（默认 8000，范围 2048–32768，UTF-16 字符），包含缩进、转义和元数据；与 Roslyn 条数 limit 同时生效。按完整条目裁剪引用、候选和文件问题，返回 `returnedReferences`、`outputOmissions` 和实际预算，保留已知总数及精确身份；输出省略时标记 truncated/queryComplete，必要元数据超预算则明确返回 OUTPUT_BUDGET_EXCEEDED。裁剪不修改原始查询对象，因此不会缩小影响分析内部采用的引用集合，也不约束 Host 查找阶段的计算量。
+
 `maxTokens` 当前按 UTF-16 字符数 / 4 估算，最终 MCP 文本块的 JSON 转义、元数据及 legacy 附加文本共同占预算。它不是模型 tokenizer 的精确结果。
 
 ContextResponse 在最终裁剪后重新计算范围覆盖，区分读取阶段不足和响应预算不足，并给出缺失区间或后续请求。符号窗口没有解析方法结束边界，`symbolCoverage=unknown` 不能被显示的几行正文替代。

docs/codex_worklog.md

@@ -1373,3 +1373,13 @@
 - 原报告确认 9 个受管进程全部退出，`survivors=[]`、场景成功；随后 finally 仍逐个启动 PowerShell 做兜底终止，其中一次 `spawnSync powershell.exe ETIMEDOUT`。这是测试收尾失败，不是本次报告中观察到进程泄漏。尚未确定该 PowerShell 调用为何超过 8 秒；Node 22 文档说明 spawnSync 的 timeout 限制子进程运行时间：https://nodejs.org/download/release/v22.23.2/docs/api/child_process.html#child_processspawnsynccommand-args-options。
 - 仅调整默认 owner-death 脚本：验收已确认全部退出后不再兜底终止；失败路径保留原有 PID/创建时间核验及清理。没有放宽超时、忽略清理错误或修改生产代码。
 - 真实正常路径通过，报告 `test-tmp/owner-death/run-HzZLg9/report.json`。另以临时脚本副本故意保留 Gateway，验证残留仍使验收失败、兜底清理实际执行、随后同身份进程全部消失；故障注入验证通过，报告 `test-tmp/owner-death/run-LTW9Qh/report.json`。未重复无关全量测试；新提交的远端检查尚待运行。
+
+## 2026-09-11 — 保留文件移动结果与引用计数，约束引用最终输出
+
+- 用户批准实现架构审查中的前两项修复，并同意增加引用输出字符预算；随后要求提交 PR 并合并。基于 main `4720bf8`，本轮只修改相关源码、测试和现有文档，没有增加依赖。
+- 修复 trash 已移动或元数据写入失败后，Gateway 的请求期限检查覆盖实际结果的问题。移动前传递取消并再次检查期限；移动后完成元数据收尾，保留 completed/partial、实际位置及中断计数。客户端取消或断线仍不能保证最终回复送达，没有增加事务日志或自动回滚。
+- 公开 Host 已有的 Roslyn limit（1–1000，默认 100，要求 symbolLocation）；影响报告保留已知 totalReferences、referencesTruncated 和实际聚合条数，未知总数仍为 null，UNKNOWN 规则不变。
+- 引用工具最终格式化 JSON 增加 maxOutputChars（2048–32768，默认 8000），两种提供方均适用，计入 UTF-16 字符、缩进、转义及元数据。保留实际返回数、输出省略项、候选和文件问题计数；必要身份及覆盖元数据放不下时明确返回 OUTPUT_BUDGET_EXCEEDED。输出裁剪不修改内部查询对象，不限制 Roslyn 查找阶段的计算成本。
+- 回归先确认旧实现会丢失移动结果/取消信号/引用总数，以及最终 JSON 超预算。实现后定向验证通过：真实临时文件移动与取消、真实 Roslyn Host 的 120 处引用、长路径和转义预览、候选身份及必要元数据边界。本轮累计新增 5 个测试，分属两次授权的局部任务（3 个及 2 个）；没有放宽原有超时或断言。
+- 最终完整 `npm run check` 460/460、0 失败、0 跳过，类型检查、Gateway/原生构建、生产 stdio 和交付核验通过。报告：`test-tmp/check/2026-09-11T13-13-40-686Z-core/report.json`；交付 contentId=`7d04eb319ef210868f25ece81496aaaad184e456a2ec3d302a8593e8923537f3`。错误契约 17/17：`test-tmp/error-contracts/run-bAbdGe/report.json`。
+- 自查及本地验证不等同于独立审查；最新 PR 提交仍须通过 Node 22/24 和三项 CodeQL 后再合并。未重新执行无关桌面验收，也未同步已安装 Skill 或重连当前 Codex MCP；本地构建完成不证明活动客户端已更新。