@banbolee/dsh-lsp-diagnostics 0.1.1 → 0.2.0

package/README.md

@@ -1,10 +1,13 @@
 # @banbolee/dsh-lsp-diagnostics
 
+**English** | [中文](./README.zh.md)
+
 Host-plane Cordis bundle plugin for DeepSeek Harness: after an official
 `write`/`edit`/`str_replace_editor` mutation lands inside the session
-workspace, the tool result still succeeds and the next model inference carries
-a single persistent LSP diagnostics plugin notice. It also registers the
-model-callable `lsp_diagnostics(file_path)` tool for explicit diagnosis.
+workspace, or inside a marker-rooted sibling worktree/project, the tool result
+still succeeds and the next model inference carries a single persistent LSP
+diagnostics plugin notice. It also registers the model-callable
+`lsp_diagnostics(file_path)` tool for explicit diagnosis.
 
 The plugin is a named namespace function plugin: it exports `name`, `inject`,
 `Config`, and `apply`, and has no default export. The real Loader reads the
@@ -16,7 +19,13 @@ monkey-patches official objects.
 
 ## Usage
 
-Install the bundle into any DSH profile from the repository root. The
+**Install from npm (recommended)** — no clone needed:
+
+```sh
+dsh plugin --profile <name> add @banbolee/dsh-lsp-diagnostics
+```
+
+For local development, install the bundle into any DSH profile from the repository root. The
 workspace-root flag `-w` is required: without it pnpm cannot resolve the local
 package inside the profile's generated workspace.
 
@@ -59,20 +68,22 @@ deviation from the closed extension route fail loud at load time.
 | `servers` | TypeScript + Go | Closed provider catalog; TypeScript and Go are enabled by default, while `clangd`, `rust`, and `python` are opt-in. |
 
 The extension route is closed: `.ts` → typescript/typescript, `.tsx` →
-typescript/typescriptreact, `.go` → go/go, `.c` → clangd/c,
-`.cc`/`.cpp`/`.cxx` → clangd/cpp, `.h`/`.hh`/`.hpp`/`.hxx` → clangd/cpp,
-`.rs` → rust/rust, and `.py`/`.pyi` → python/python; any other extension key,
-missing canonical provider entry, cross-provider collision, or rewritten
-language id fails loud at load time, while other extensions at runtime are
-silently ignored.
+typescript/typescriptreact, optional explicit `.js` → typescript/javascript,
+`.go` → go/go, `.c` → clangd/c, `.cc`/`.cpp`/`.cxx` → clangd/cpp,
+`.h`/`.hh`/`.hpp`/`.hxx` → clangd/cpp, `.rs` → rust/rust, and
+`.py`/`.pyi` → python/python; any other extension key, missing canonical
+provider entry, cross-provider collision, or rewritten language id fails loud at
+load time, while other extensions at runtime are silently ignored.
 
 The `servers` block is a provider-level partial overlay: omitting `servers` or
 supplying `servers: {}` keeps exactly the TypeScript and Go defaults, while
 supplying a known optional `clangd`, `rust`, or `python` key activates that
 provider. For example, `servers: { go: { command: '/path/trae-gopls' } }`
 changes only Go without requiring a TypeScript block. The legacy
-`extensionToLanguage` field is accepted only when it exactly equals that
-provider's canonical mapping; it never defines new routes.
+`extensionToLanguage` field is accepted only when it contains that provider's
+canonical mapping and only supported provider-owned extras. `.js` is accepted
+for compatibility with explicit TypeScript configs, but it is not enabled by
+default.
 
 Default commands are `typescript-language-server --stdio`, `gopls`, `clangd`,
 `rust-analyzer`, and `pyright-langserver --stdio`. clangd, rust-analyzer, and
@@ -81,13 +92,16 @@ gopls receive no default arguments. Per-server `env`, `configuration`, and
 
 ## Behavior
 
-Only a non-empty `session.header.cwd` that canonicalizes to a directory and
-contains the target is eligible; missing or empty cwd, non-directory
-canonicalization, and outside-workspace targets are ineligible and silently
-ignored — never a `workspace unavailable` or `outside workspace` notice.
-Workspace, cwd, and URI are always derived through the public `ctx.fs` API
-(`resolve`/`stat`/`contains`/`targetKey`/`processPath`/`fileUrl`), never from
-`displayPath` or the host `process.cwd()`.
+A non-empty `session.header.cwd` that canonicalizes to a directory is required.
+Automatic feedback first keeps the old behavior for targets contained by that
+workspace; targets outside it are eligible only when a target-local `.git` file
+or directory identifies their own git worktree root. Missing or empty cwd,
+non-directory canonicalization, and outside targets without a marker-rooted
+git worktree are silently ignored — never a `workspace unavailable` or
+`outside workspace` notice. Workspace, cwd, and URI are always
+derived through the public `ctx.fs` API (`resolve`/`stat`/`contains`/`targetKey`/
+`processPath`/`fileUrl`), never from raw `displayPath` or the host
+`process.cwd()`.
 
 Fail-open is plugin-owned post-processing failure only: after the downstream
 `await next()` decision succeeded, a diagnostics error, missing or crashed
@@ -187,13 +201,14 @@ natural-close wait → conditional `handle.terminate()` (only while still alive)
 existing file that `ctx.fs` permits the session to read. It accepts a
 workspace-relative or absolute path and uses every configured provider and the
 closed extension route documented above. It has the same path authority as the
-official `read` tool: the session cwd is only the LSP project root, so an
-explicit direct call may diagnose a readable file outside that root. It never
-creates, edits, or deletes a file. Invalid requests fail explicitly with
-`file_path must be a non-empty string`, `session workspace cwd`, `session
-workspace is not an existing directory`, `target does not exist`, `target is
-not a regular file`, `no configured diagnostics provider`, or `target changed
-during diagnosis`.
+official `read` tool: for files contained by `session.header.cwd`, that cwd
+remains the LSP project root; for a readable file outside the session cwd, the
+tool prefers the target's marker-rooted project/worktree root and then falls
+back to the session cwd. It never creates, edits, or deletes a file. Invalid
+requests fail explicitly with `file_path must be a non-empty string`, `session
+workspace cwd`, `session workspace is not an existing directory`, `target does
+not exist`, `target is not a regular file`, `no configured diagnostics
+provider`, or `target changed during diagnosis`.
 
 The direct tool has exactly three canonical outcomes: `diagnostics` with the
 normalized list sorted by the same comparator as automatic rendering and sliced
@@ -231,13 +246,13 @@ unavailable`.
 - shell redirection, `sed -i`, scripts, formatters, generators, and external
   editors that bypass `ctx.fs`/`fs/observed` are out of scope for automatic
   feedback; the model may call `lsp_diagnostics(file_path)` afterward. There is no
-  filesystem watcher and no project-root probing — the session cwd is the
-  workspace root.
+  filesystem watcher; project-root probing is marker-based and only runs for
+  supported source files.
 - For automatic feedback, agentless tool execution, missing/empty or
-  non-directory cwd, and outside-workspace targets are silently out of scope
-  and never produce a notice. Direct calls use official `read`-equivalent path
-  authority instead: a readable file outside the session cwd is eligible, while
-  that cwd remains the LSP project root.
+  non-directory cwd, and outside targets without a marker-rooted git worktree are
+  silently out of scope and never produce a notice. Direct calls use official
+  `read`-equivalent path authority instead: a readable file outside the session
+  cwd is eligible, using its marker-rooted project/worktree root when available.
 - The plugin does not install or download `typescript-language-server`,
   `gopls`, `clangd`, `rust-analyzer`, or `pyright-langserver`; install requested
   executables yourself and configure their paths. A missing server fails open
@@ -245,9 +260,9 @@ unavailable`.
 - Portable deterministic tests use the repository fixture server and never use
   a real server or the network. The separate explicit real-server lane is
   opt-in, local-filesystem/process-only, and never installs or downloads tools.
-- Implementation and tests use the `0.1.5-rc.1` dependency family; the peers
+- Implementation and tests use the `0.1.7-rc.2` dependency family; the peers
   `@deepseek-ai/dsh-fs`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-subprocess`,
-  and `@deepseek-ai/dsh-tools` are `^0.1.5-rc.1`.
+  and `@deepseek-ai/dsh-tools` are `^0.1.7-rc.2`.
 
 ## Verification
 

package/README.zh.md

@@ -0,0 +1,144 @@
+# @banbolee/dsh-lsp-diagnostics
+
+[English](./README.md) | **中文**
+
+DeepSeek Harness 的 host 面 Cordis bundle 插件：当一次官方 `write`/`edit`/`str_replace_editor` 变更落在 session workspace 内，或落在带 marker 根的兄弟 worktree/项目内时，工具结果仍然成功，而下一次模型推理会携带一条持久的 LSP diagnostics 插件 notice。它还注册了模型可调用的 `lsp_diagnostics(file_path)` 工具，用于显式诊断。
+
+本插件是具名 namespace 函数插件：导出 `name`、`inject`、`Config` 和 `apply`，没有 default export。真实 Loader 读取模块 namespace（`exports.default ?? exports`），Cordis 从插件对象读取 `inject`/`Config`，因此每个公开元数据字段都能在安装后存活。插件从不修改 `deepseek-harness`，从不扩展 `ctx.lsp`，从不 import `@deepseek-ai/*/src/*`，也从不 monkey-patch 官方对象。
+
+## 用法
+
+**从 npm 安装（推荐）** —— 无需 clone：
+
+```sh
+dsh plugin --profile <name> add @banbolee/dsh-lsp-diagnostics
+```
+
+本地开发时，可在仓库根目录把本 bundle 安装到任意 DSH profile。必须带上 workspace 根标志 `-w`：否则 pnpm 无法在 profile 生成的 workspace 内解析本地包。
+
+```bash
+dsh plugin --profile <profile> add -w ./plugins/dsh-lsp-diagnostics
+```
+
+若要用一条命令安装到隔离的 profile：
+
+```bash
+DSH_HOME="$(mktemp -d)" scripts/sync-lsp-diagnostics-to-profile.sh <profile>
+```
+
+sync 辅助脚本要求设置 `DSH_HOME`，这样测试与手工 QA 始终作用于隔离的 profile 状态，而绝不是用户的默认 Harness home。
+
+插件注册一个真正的三参数 `tools/post-execute` waterfall 监听器 `(exec, _result, next)`：它恰好调用一次 `await next()`，且在任何插件 catch 之外，也从不消费 `_result` 占位符。
+
+## 配置
+
+所有开关都经由插件的 `Config` schema 与严格校验器。未知 key、不是合法 JSON 可表示的值、非法 timer/cap，或对封闭扩展路由的任何偏离，都会在加载时 fail loud。
+
+| 配置项 | 默认值 | 含义 |
+| --- | --- | --- |
+| `enabled` | `true` | `enabled=false` 时插件不创建任何 collector、runtime、coordinator 或 tool，不注册任何 tools/listeners/effects，也不 spawn 任何进程。 |
+| `timeoutMs` | `5000` | 单个 post-execute 聚合的不可延长 deadline。 |
+| `settleMs` | `200` | 静默窗口；必须 `< timeoutMs`。 |
+| `shutdownTimeoutMs` | `1000` | 优雅 `shutdown`/`exit` 的预算。 |
+| `killGraceMs` | `500` | 进程树的 TERM→KILL 宽限期。 |
+| `maxDocumentBytes` | `2097152` | 经 `didOpen` 发送的文档的硬性 UTF-8 字节上限。 |
+| `maxMessageBytes` | `4194304` | LSP 消息体上限。 |
+| `maxStderrBytes` | `16384` | 有界的 stderr 尾部上限。 |
+| `maxDiagnostics` | `50` | 自动 diagnostic 行的全局上限，也是 canonical direct-tool diagnostics 数组的每次调用上限。 |
+| `maxResultChars` | `8000` | 最终聚合文本的 Unicode 码点上限。 |
+| `reportClean` | `true` | 显式空结果是否渲染为 `Status: clean`。 |
+| `servers` | TypeScript + Go | 封闭的 provider catalog；TypeScript 和 Go 默认启用，而 `clangd`、`rust` 和 `python` 需显式开启。 |
+
+扩展路由是封闭的：`.ts` → typescript/typescript，`.tsx` → typescript/typescriptreact，可选的显式 `.js` → typescript/javascript，`.go` → go/go，`.c` → clangd/c，`.cc`/`.cpp`/`.cxx` → clangd/cpp，`.h`/`.hh`/`.hpp`/`.hxx` → clangd/cpp，`.rs` → rust/rust，`.py`/`.pyi` → python/python；任何其他扩展名 key、缺失的 canonical provider 条目、跨 provider 冲突或被改写的 language id 都会在加载时 fail loud，而运行时的其他扩展名会被静默忽略。
+
+`servers` 块是 provider 级别的部分 overlay：省略 `servers` 或提供 `servers: {}` 会精确保留 TypeScript 和 Go 默认值，而提供已知的可选 key `clangd`、`rust` 或 `python` 会激活对应 provider。例如 `servers: { go: { command: '/path/trae-gopls' } }` 只改动 Go，无需提供 TypeScript 块。legacy 的 `extensionToLanguage` 字段仅当它包含该 provider 的 canonical 映射且只包含受支持的 provider 自有扩展时才被接受。`.js` 为兼容显式 TypeScript 配置而被接受，但默认不启用。
+
+默认命令为 `typescript-language-server --stdio`、`gopls`、`clangd`、`rust-analyzer` 和 `pyright-langserver --stdio`。clangd、rust-analyzer 和 gopls 不接受任何默认参数。per-server 的 `env`、`configuration` 和 `initializationOptions` 可以被覆盖，且必须是 JSON 可表示的。
+
+## 行为
+
+要求存在非空、且能 canonicalize 为目录的 `session.header.cwd`。自动反馈首先对该 workspace 包含的 target 保持旧行为；workspace 之外的 target 只有在 target 本地的 `.git` 文件或目录能标识其自身 git worktree 根时才符合条件。cwd 缺失或为空、canonicalize 结果不是目录，以及没有 marker 根 git worktree 的外部 target，都会被静默忽略 —— 永远不会出现 `workspace unavailable` 或 `outside workspace` notice。workspace、cwd 和 URI 始终通过公开的 `ctx.fs` API（`resolve`/`stat`/`contains`/`targetKey`/`processPath`/`fileUrl`）推导，绝不来自原始的 `displayPath` 或宿主的 `process.cwd()`。
+
+Fail-open 仅限插件自身的后处理失败：在下游 `await next()` 决策已经成功之后，diagnostics 错误、服务端缺失或崩溃、协议失败、读取错误或超时都不会改变该决策或结果，也永远不会返回 `kind: 'block'`。调用方 abort 由 ToolRuntime 和下游监听器决定；本插件从不吞掉、改写调用方 abort，也不承诺把它变成成功。
+
+新鲜度使用写入后的 `FsVersion`，加上一个独立的 per-target 单调 generation 计数器，其取值在一个插件生命周期内永不重用。`retireIfCurrent` 只移除匹配的 active marker（generation + version），从不触碰计数器。当 generation 计数器耗尽时，插件 fail safe，所有更旧的候选都保持 stale。
+
+符合条件的 target 由唯一的共享 comparator `(renderPath, String(targetKey), canonicalUri)` 按 Unicode 码点排序，同一顺序同时驱动诊断调度和渲染出的 section —— 绝不使用原始 `displayPath` 元组、`localeCompare` 或默认的 UTF-16 排序。
+
+一次 exec 最多产生一条聚合 notice，其中恰好有一个标题 `[LSP diagnostics after write]`，每个保留的文件一个 section，section 之间恰好一个空行，且没有开头或结尾换行。在全局 `maxDiagnostics` 数量上限之后，保留行为零的 diagnostics 文件会被整体省略，绝不留下空 section；clean 和 unavailable 的 section 不消耗该上限。仅当至少保留一行 diagnostic 时，才追加恰好一条全局 advisory，并以一个空行分隔。`maxResultChars` 上限只在完整的 canonical 聚合构建完成之后才应用：固定 marker `…(truncated)` 替换被截断的后缀，输出永不超过该上限。
+
+文档在 `stat.size` 预检之后用有界的 `ctx.fs.readBytes(target, signal, maxDocumentBytes)` 读取，并采用严格 UTF-8 解码；绝不使用无界的 `readText`。已知大小超过上限，或未知大小的读取抛出 `code === 'FS_TOO_LARGE'` 的 `FsError`，都映射为 `document too large`；任何其他读取错误映射为 `diagnostics unavailable`。公开接缝保证成功的 `readBytes` 是完整的，且 `bytes.length <= maxDocumentBytes`；插件从不依赖或返回超过上限的字节。
+
+`publishDiagnostics` 的关联顺序是精确 URI 优先，其次按文档 version；只有被消费的字段 `range`、`severity`、`code`、`source` 和 `message` 会被校验，而标准可选字段 `tags`、`relatedInformation`、`codeDescription`、`data` 以及未知扩展字段会被安全忽略，绝不进入规范化 schema 或 renderer。位置是基于 0 的 UTF-16，渲染为基于 1 的起止坐标。
+
+coordinator 同时持有 active augment-operation registry 和 `retiredIo` late-final-stat registry。Unload 按精确顺序静默：停止 direct-tool 准入 → 停止 coordinator 准入（同时关闭 runtime 准入）→ offTool → offPost → offObserved → abort coordinator 操作 → abort direct-tool 操作 → await 所有 active augment promise → await 所有 active direct-tool promise → await 所有 `retiredIo` → `runtime.dispose()`。清理在单个失败之后仍继续并聚合这些失败；因此没有任何直接调用能与 runtime disposal 竞争。每个操作最外层的 `finally` 会清除 deadline timer 并移除 caller/cleanup relay 监听器，不留任何残留。
+
+`stopAdmission()` 只关闭闸门和 runtime 自身的准入；它从不 abort 操作。Active 操作在更靠后的 abort 步骤被 abort，即在两个 listener disposer 都运行之后，与文档记载的顺序完全一致。已经进入但仍阻塞在下游 `next()` 中的监听器没有插件自有的取消接缝，因此清理会在 pending-invocation registry 中跟踪每一个这样的调用并等待其结算（它在下游结果或错误返回之前取走并 retire 该 exec 的候选，包括 `next()` 同步抛出的情况）。deadline 使用注入的单调时钟，绝不使用 `Date.now()`，因此墙钟回拨无法延长硬 deadline。
+
+Session teardown 还负责协议写入的静默：每个在途的 server-request handler 和序列化的写入尾部都在 cleanup 返回前结算，关闭期间不会启动新的 server-request handler —— 因此 cleanup 完成后不可能再写入任何排队的帧（responses、`shutdown`、`exit`）。与 `didOpen` 写入竞争的匹配 `publishDiagnostics` 会被缓冲，直到 open 写入成功；只有成功写入的 open generation 才接受通知，而失败的 `didOpen` 写入仍允许被允许的 fresh-instance 重试。共享 runtime 采用通用的 correctness-over-performance 策略：它仍会把一个 provider/workspace session 跨不同的 canonical URI 池化，但在该 session 已打开过的 URI 被再次诊断之前，它会驱逐并异步 retire 该 session，然后在一个全新进程中以 version 1 打开该 URI；这避免了 provider VFS 缓存返回同一 URI 的陈旧 diagnostics，而 retired teardown 在 unload 时仍被跟踪并排空。
+
+`timeoutMs` 是整个 post-execute 的单个不可延长 deadline；最后一轮 freshness 是一次性的 final stat/deadline/generation 闸门。direct tool 同样从其注入的单调时钟捕获一个绝对 deadline，并且当 `now() >= deadlineAt` 时每个闸门都转为 timeout，即使事件循环饥饿尚未运行已排定的 timer 回调。deadline/caller/cleanup 丢失时绝不等待迟到的 final stat：未结算的记录在决策返回前被 retire 进 `retiredIo`。Session teardown 是唯一顺序：`shutdown` 请求 → `exit` 通知/自然关闭等待 → 有条件的 `handle.terminate()`（仅当仍存活时）→ await `handle.done` 与 `waitForExit()` → `processLifetimeController.abort()`；`terminate()` 是唯一的硬停止。
+
+## 模型体验
+
+`lsp_diagnostics(file_path)` 是模型可调用的只读工具，作用于一个已存在、且 `ctx.fs` 允许该 session 读取的文件。它接受 workspace 相对路径或绝对路径，并使用所有已配置的 provider 以及上文记载的封闭扩展路由。它具有与官方 `read` 工具相同的路径权限：对于被 `session.header.cwd` 包含的文件，该 cwd 仍是 LSP 项目根；对于 session cwd 之外的可读文件，工具优先使用 target 的 marker 根项目/worktree 根，然后回退到 session cwd。它从不创建、编辑或删除文件。非法请求会显式失败，并给出 `file_path must be a non-empty string`、`session workspace cwd`、`session workspace is not an existing directory`、`target does not exist`、`target is not a regular file`、`no configured diagnostics provider` 或 `target changed during diagnosis`。
+
+direct tool 恰好有三种 canonical 结果：`diagnostics`，其规范化列表按与自动渲染相同的 comparator 排序，并在 ToolRuntime/PTC 收到之前被切片到 `maxDiagnostics`，外加一个始终存在的非负整数 `omitted_diagnostics`；`no_diagnostics`，渲染为 `No diagnostics reported for this file snapshot.`；以及 `unavailable`，带一个封闭 reason。renderer 会保留来自该 canonical 计数的省略 marker。当你需要显式诊断一个已存在的文件时调用它，尤其是在 shell 命令、formatter 或 generator 绕过了自动 `fs/observed` 反馈之后；当已有新鲜的自动反馈时，请避免冗余调用。在受支持的 write/edit 变更之后，自动的写入后反馈仍是默认行为，而 direct tool 是刻意调用的，并且会报告路径/workspace 错误，而不是把它们静默当作不符合条件。
+
+从模型的角度看，每个变更工具（`write`、`edit`、`str_replace_editor` 的 create/str_replace/insert）都原样返回其结果；插件为下一次推理向 `decision.additionalContexts` 追加一条有界聚合 notice。notice 包含：
+
+- 每个保留的文件一个 `File: <renderPath>` section —— diagnostics 为 `- <severity> <startLine>:<startCharacter>-<endLine>:<endCharacter> source=... code=... message` 行，或 `Status: clean`，或 `Status: diagnostics unavailable (<reason>)` —— 按共享的码点顺序排列；
+- 当至少保留一行 diagnostic 时，恰好一条全局 advisory；
+- 对不支持的扩展名、不符合条件的 workspace、`enabled=false` 或没有 workspace 的 session，则不产生任何内容。
+
+Unavailable reason 是封闭的：`server not found`、`server crashed`、`timeout`、`malformed response`、`document too large`、`diagnostics unavailable`。
+
+## 已知限制与待办工作
+
+- 绕过 `ctx.fs`/`fs/observed` 的 shell 重定向、`sed -i`、脚本、formatter、generator 以及外部编辑器不在自动反馈的范围内；模型可以随后调用 `lsp_diagnostics(file_path)`。没有 filesystem watcher；项目根探测基于 marker，且只对受支持的源文件运行。
+- 对于自动反馈，无 agent 的工具执行、cwd 缺失/为空或不是目录，以及没有 marker 根 git worktree 的外部 target，都被静默排除在范围之外，永不产生 notice。直接调用则改用与官方 `read` 等价的路径权限：session cwd 之外的可读文件符合条件，并在可用时使用其 marker 根项目/worktree 根。
+- 插件不安装也不下载 `typescript-language-server`、`gopls`、`clangd`、`rust-analyzer` 或 `pyright-langserver`；请自行安装所需可执行文件并配置其路径。服务端缺失时 fail open，给出 `diagnostics unavailable (server not found)`。
+- 可移植的确定性测试使用仓库内的 fixture 服务端，绝不使用真实服务端或网络。独立的显式 real-server lane 需显式开启，只使用本地文件系统/进程，且从不安装或下载工具。
+- 实现与测试使用 `0.1.7-rc.2` 依赖族；peer 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-subprocess` 和 `@deepseek-ai/dsh-tools` 为 `^0.1.7-rc.2`。
+
+## 验证
+
+确定性的包内测试（fixture 服务端、无网络、无真实 LSP 服务端、隔离的临时 workspace/profile）：
+
+```bash
+pnpm exec vitest run plugins/dsh-lsp-diagnostics tests/package-shape.spec.ts
+```
+
+文档形态测试（必需章节与契约字符串）：
+
+```bash
+pnpm exec vitest run tests/docs-shape-lsp-diagnostics.spec.ts
+```
+
+类型检查与 sync 脚本帮助：
+
+```bash
+pnpm dlx --package=typescript@6.0.3 tsc -p plugins/dsh-lsp-diagnostics/tsconfig.json --noEmit
+bash scripts/sync-lsp-diagnostics-to-profile.sh --help
+```
+
+显式的 real-server 验证与可移植覆盖是分开的。它要求 `RUN_REAL_LSP_SERVERS=1`、非空的 `REAL_LSP_PROVIDERS` 列表、每个被请求 provider 的显式可执行文件路径，以及一个证据路径：
+
+```bash
+RUN_REAL_LSP_SERVERS=1 \
+REAL_LSP_PROVIDERS=rust \
+REAL_LSP_RUST_COMMAND=/data00/home/lixingxin/.cargo/bin/rust-analyzer \
+REAL_LSP_EVIDENCE_PATH=/tmp/dsh-real-rust.json \
+pnpm exec vitest run tests/composition/lsp-real-servers.spec.ts
+```
+
+operator wrapper 执行同样的检查：
+
+```bash
+node scripts/qa/run-lsp-real-servers.mjs \
+  --providers rust \
+  --rust-command /data00/home/lixingxin/.cargo/bin/rust-analyzer \
+  --evidence /tmp/dsh-real-rust.json
+```
+
+每个被请求的 provider 都必须完成 bad → diagnostic → repair → clean。该 JSON 文件是机器可读的证据；被请求的可执行文件缺失时会记录 `status: "blocked"` 并以非零码退出，而不是跳过或通过。

package/coordinator.js

@@ -15,15 +15,17 @@
  * @module @banbolee/dsh-lsp-diagnostics/coordinator
  */
 
+/// <reference path="./message-source.d.ts" />
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { compareEligibleTargets, renderDiagnostics, sanitizeDisplayPath } from './render.js'
+import { resolveWorkspaceRoot } from './workspace-root.js'
 
 /**
  * Loose structural seams, mirroring the runtime's own public shapes. The
  * coordinator only consumes the documented surface (`take/isCurrent/
  * retireIfCurrent`, `diagnose/stopAdmission/dispose`, `resolve/stat/
- * contains/fileUrl`); keeping these structural keeps both the real services
- * and the deterministic test fakes assignable.
+ * contains/fileUrl/processPath`); keeping these structural keeps both the real
+ * services and the deterministic test fakes assignable.
  * @typedef {object} CollectorSeam
  * @property {(exec: any, target: any, observation: any) => void} observe
  * @property {(exec: any) => import('./collector.js').MutationCandidate[]} take
@@ -44,6 +46,7 @@ import { compareEligibleTargets, renderDiagnostics, sanitizeDisplayPath } from '
  * @property {(target: any, signal?: AbortSignal) => Promise<{ version: string, type: string, size?: number } | undefined>} stat
  * @property {(parent: any, child: any) => boolean} contains
  * @property {(target: any) => string} fileUrl
+ * @property {(target: any) => string} processPath
  */
 
 /**
@@ -382,10 +385,12 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         retireAll()
         return decision
       }
-      // 2. Workspace root from the session header; missing/empty is ineligible.
+      // 2. Canonicalize the session workspace once. Files inside it keep the
+      // original behavior; files outside it may still resolve to their own
+      // project/worktree root.
       const execRecord = /** @type {{ agent?: { session?: { header?: { cwd?: unknown } } } }} */ (exec)
-      const workspaceRoot = execRecord?.agent?.session?.header?.cwd
-      if (typeof workspaceRoot !== 'string' || workspaceRoot.length === 0) {
+      const sessionRoot = execRecord?.agent?.session?.header?.cwd
+      if (typeof sessionRoot !== 'string' || sessionRoot.length === 0) {
         retireAll()
         return decision
       }
@@ -393,10 +398,9 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         retireAll()
         return decision
       }
-      // 3. Canonicalize the workspace exactly once.
-      let workspaceTarget
+      let sessionWorkspace
       try {
-        workspaceTarget = await fs.resolve(workspaceRoot, { signal })
+        sessionWorkspace = await fs.resolve(sessionRoot, { signal })
       } catch {
         retireAll()
         return decision
@@ -405,9 +409,9 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         retireAll()
         return decision
       }
-      let workspaceInfo
+      let sessionWorkspaceInfo
       try {
-        workspaceInfo = await fs.stat(workspaceTarget, signal)
+        sessionWorkspaceInfo = await fs.stat(sessionWorkspace, signal)
       } catch {
         retireAll()
         return decision
@@ -416,26 +420,43 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         retireAll()
         return decision
       }
-      if (workspaceInfo === undefined || workspaceInfo.type !== 'directory') {
+      if (sessionWorkspaceInfo === undefined || sessionWorkspaceInfo.type !== 'directory') {
         retireAll()
         return decision
       }
-      // 4. Per-target eligibility: contains with pre/post abort checks, then
-      // freeze renderPath + canonicalUri exactly once. Every early exit and
-      // abort break retires the remaining taken candidates.
-      /** @type {{ candidate: import('./collector.js').MutationCandidate, renderPath: string, targetKey: string, canonicalUri: string }[]} */
+      // 3. Per-target eligibility: use session cwd when it contains the target;
+      // otherwise resolve the LSP workspace from target-local markers
+      // (go.mod/.git/package markers). Then freeze renderPath + canonicalUri.
+      /** @type {{ candidate: import('./collector.js').MutationCandidate, workspaceTarget: any, renderPath: string, targetKey: string, canonicalUri: string }[]} */
       const eligible = []
       for (const route of routed) {
         const { candidate, canonicalUri } = route
         if (signal.aborted) break
         let contained = false
         try {
-          contained = fs.contains(workspaceTarget, candidate.target) === true
+          contained = fs.contains(sessionWorkspace, candidate.target) === true
         } catch {
           contained = false
         }
         if (signal.aborted) break
-        if (!contained) {
+        let workspaceTarget = contained ? sessionWorkspace : undefined
+        if (workspaceTarget === undefined) {
+          try {
+            workspaceTarget = await resolveWorkspaceRoot({
+              fs,
+              target: candidate.target,
+              extension: extensionOf(canonicalUri),
+              sessionRoot,
+              signal,
+              sessionFallback: 'never',
+              markerMode: 'git',
+            })
+          } catch {
+            workspaceTarget = undefined
+          }
+        }
+        if (signal.aborted) break
+        if (workspaceTarget === undefined) {
           collector.retireIfCurrent(candidate)
           continue
         }
@@ -448,6 +469,7 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         }
         eligible.push({
           candidate,
+          workspaceTarget,
           renderPath,
           targetKey: String(candidate.target.targetKey ?? ''),
           canonicalUri,
@@ -470,7 +492,7 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         /** @type {import('./runtime.js').DiagnosisOutcome} */
         let outcome
         try {
-          outcome = await runtime.diagnose(target.candidate, workspaceTarget, target.canonicalUri, signal)
+          outcome = await runtime.diagnose(target.candidate, target.workspaceTarget, target.canonicalUri, signal)
         } catch (error) {
           if (signal.aborted) break
           // Plugin-owned failure after eligibility: bounded unavailable with
@@ -609,9 +631,12 @@ export function createDiagnosticsCoordinator({ collector, runtime, config, fs, n
         if (rendered.text !== null) {
           const message = createUserMessage({
             content: [{ type: 'text', text: rendered.text }],
+            // 0.1.7-rc.2 vocabulary: the producer declares its own
+            // `MessageSourceMap` kind (message-source.d.ts) and owns its bounded
+            // one-line `notice` account; there is no shared catch-all `plugin`
+            // kind and no producer-name field.
             source: {
-              kind: 'plugin',
-              plugin: '@banbolee/dsh-lsp-diagnostics',
+              kind: 'lsp-diagnostics',
               form: 'notice',
               summary: boundContextSummary(rendered.text),
             },

package/index.js

@@ -90,6 +90,7 @@ const DEFAULT_ENABLED_PROVIDERS = Object.freeze(['typescript', 'go'])
  * @type {Readonly<Record<string, Readonly<{ provider: ProviderId, language: string }>>>}
  */
 const CANONICAL_ROUTE = Object.freeze({
+  '.js': Object.freeze({ provider: 'typescript', language: 'javascript' }),
   '.ts': Object.freeze({ provider: 'typescript', language: 'typescript' }),
   '.tsx': Object.freeze({ provider: 'typescript', language: 'typescriptreact' }),
   '.go': Object.freeze({ provider: 'go', language: 'go' }),
@@ -290,11 +291,8 @@ function assertExtensionToLanguage(map, provider) {
   if (defaults === undefined) fail(`provider ${provider} has no catalog defaults`)
   const expected = defaults.extensionToLanguage
   const expectedExtensions = Object.keys(expected)
-  if (
-    routes.size !== expectedExtensions.length
-    || !expectedExtensions.every((extension) => routes.get(extension) === expected[extension])
-  ) {
-    fail(`servers.${provider}.extensionToLanguage must equal the canonical provider mapping`)
+  if (!expectedExtensions.every((extension) => routes.get(extension) === expected[extension])) {
+    fail(`servers.${provider}.extensionToLanguage must include the canonical provider mapping`)
   }
   return Object.fromEntries(routes)
 }

package/message-source.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The plugin-owned `MessageSourceMap` entry this plugin's aggregate diagnostics
+ * notice needs.
+ *
+ * `@deepseek-ai/dsh-llm` 0.1.7-rc.2 removed the shared catch-all
+ * `MessageSourceMap['plugin']` kind: the map is merge-extensible, so every
+ * producer declares its own `kind` in its own module (as `dsh-agent` does for
+ * `model-selection` and `dsh-tools` for `tool-registry`). A `declare module`
+ * augmentation cannot live in a checked JavaScript file (TS8006), so it lives
+ * here and `coordinator.js` pulls it into the program with
+ * `/// <reference path="./message-source.d.ts" />`.
+ *
+ * @module @banbolee/dsh-lsp-diagnostics/message-source
+ */
+
+import type { ContextFormed } from '@deepseek-ai/dsh-llm'
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    /** One aggregate post-write diagnostics notice produced by this plugin. */
+    'lsp-diagnostics': { kind: 'lsp-diagnostics' } & ContextFormed
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banbolee/dsh-lsp-diagnostics",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Automatic post-write and model-callable read-only LSP diagnostics for existing files in DeepSeek Harness.",
   "type": "module",
   "main": "index.js",
@@ -16,8 +16,11 @@
     "tool.js",
     "render.js",
     "coordinator.js",
+    "message-source.d.ts",
+    "workspace-root.js",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "README.zh.md"
   ],
   "dsh": {
     "bundle": {
@@ -25,33 +28,31 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-fs": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-attachment": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-code-runtime": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-fs-local": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-tool-fs": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-tool-str-replace-editor": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.1"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tool-str-replace-editor": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.7-rc.2"
   },
   "keywords": [
     "dsh",

package/runtime.js

@@ -473,7 +473,27 @@ export class DiagnosticsRuntime {
     for (const session of sessions) this.startSessionTeardown(session)
     /** @type {unknown[]} */
     const errors = []
-    const queueResults = await Promise.allSettled(queues)
+    // Bounded for the same reason every wait inside `teardown` is: these are the
+    // serialized write queues, and a queue whose peer is gone never settles. The
+    // sessions' own teardowns are already bounded, but this await is a SECOND,
+    // independent one on the same tails — bounding it inside `teardown` does not
+    // reach it, and an unbounded await here keeps `dispose()` from ever
+    // resolving, which is what leaves the fiber alive and the plugin never
+    // reporting itself disposed.
+    const queues$ = new AbortController()
+    const queuesTimer = setTimeout(() => queues$.abort(), this.config.shutdownTimeoutMs)
+    /** @type {PromiseSettledResult<unknown>[]} */
+    let queueResults = []
+    try {
+      queueResults = await /** @type {Promise<PromiseSettledResult<unknown>[]>} */ (
+        abortable(Promise.allSettled(queues), queues$.signal)
+      )
+    } catch (error) {
+      if (!(error instanceof Error && error.name === 'AbortError')) errors.push(error)
+      queueResults = []
+    } finally {
+      clearTimeout(queuesTimer)
+    }
     for (const result of queueResults) {
       if (result.status === 'rejected') errors.push(result.reason)
     }
@@ -1505,17 +1525,37 @@ class LspSession {
   }
 
   /**
-   * The unique teardown sequence: shutdown request within an independent
-   * graceful budget, exit notification plus natural-close wait, whole-process-
-   * tree liveness probe (bounded by the same budget), conditional
-   * `terminate()` (the only hard-stop, exactly once, tree-scoped), then
-   * `handle.done` and `waitForExit()`, and only then the process-lifetime
-   * controller abort. Terminate is decided by whole-tree liveness, never by
-   * direct-process `done` alone, so a root that exits while a helper remains
-   * alive still escalates and the teardown cannot wait forever.
+   * The unique teardown sequence: own the session's startup, then shutdown
+   * request within an independent graceful budget, exit notification plus
+   * natural-close wait, whole-process-tree liveness probe (bounded by the same
+   * budget), conditional `terminate()` (the only hard-stop, exactly once,
+   * tree-scoped), then `handle.done` and `waitForExit()`, and only then the
+   * process-lifetime controller abort. Terminate is decided by whole-tree
+   * liveness, never by direct-process `done` alone, so a root that exits while
+   * a helper remains alive still escalates and the teardown cannot wait forever.
    * @returns {Promise<void>}
    */
   async teardown() {
+    // A session can be retired while its bootstrap is still running: the pool
+    // publishes the session before its process exists. Acting on the process
+    // now would find no stdin and no handle, so the sequence below would
+    // complete as a no-op while the process the bootstrap spawns afterwards
+    // stays owned by nobody — never sent shutdown/exit and never terminated —
+    // and dispose() would have reported a finished teardown. Own the startup
+    // first, so the single transaction always runs against the process this
+    // session actually has. This wait is deliberately not charged to the
+    // graceful budget, which bounds the shutdown handshake against a live but
+    // hung server: the bootstrap cannot outlive the admitted operation's signal
+    // (cleanup aborts it before disposing) and its pending initialize request
+    // was already rejected by `startTeardown`, so it settles without a process
+    // or with the one the sequence must tear down.
+    if (this.handle === undefined && this.ready !== undefined) {
+      try {
+        await this.ready
+      } catch {
+        // the bootstrap failed without spawning; the transaction continues
+      }
+    }
     /** @type {unknown[]} */
     const errors = []
     const budget = new AbortController()
@@ -1565,31 +1605,65 @@ class LspSession {
         errors.push(error)
       }
     }
-if (this.handle !== undefined) {
-      try {
-        await this.handle.done
-      } catch (error) {
-        errors.push(error)
-      }
+    if (this.handle !== undefined) {
+      // These two waits must be BOUNDED. `terminate()` above is the hard stop —
+      // once it has been issued there is nothing left to decide, only a process
+      // tree to observe going away. On a platform whose containment never
+      // reports the tree as exited (a systemd scope whose direct runner dies
+      // while the scope lives, say), `waitForExit()` never resolves, and an
+      // unbounded await here deadlocks the teardown BEFORE the lifetime abort at
+      // the end of this method — the one action that would actually tear the
+      // subprocess down. The method's own contract says it "cannot wait
+      // forever"; this is where that promise is kept.
+      //
+      // A fresh graceful budget is used rather than the one above: that one
+      // bounded the shutdown handshake, which is a different question from how
+      // long to wait for a killed tree to disappear.
+      const settle = new AbortController()
+      const settleTimer = setTimeout(() => settle.abort(), this.config.shutdownTimeoutMs)
       try {
-        await this.handle.waitForExit()
-      } catch (error) {
-        errors.push(error)
+        try {
+          await abortable(this.handle.done, settle.signal)
+        } catch (error) {
+          if (!(error instanceof Error && error.name === 'AbortError')) errors.push(error)
+        }
+        try {
+          await this.handle.waitForExit(settle.signal)
+        } catch (error) {
+          if (!(error instanceof Error && error.name === 'AbortError')) errors.push(error)
+        }
+      } finally {
+        clearTimeout(settleTimer)
       }
     }
     // Own the protocol write quiescence: every server-request handler and the
     // serialized write tail must settle before cleanup returns, so no queued
     // frame (responses, shutdown, exit) can be written after dispose resolves.
-    // No new server-request handlers start while closing, so this terminates.
-for (;;) {
-      while (this.serverRequests.size > 0) {
-        await Promise.allSettled([...this.serverRequests])
+    // No new server-request handlers start while closing, so this terminates —
+    // EXCEPT when the peer is gone and a write never settles, which is precisely
+    // the case teardown exists to survive. The loop is therefore bounded by the
+    // same graceful budget as the waits above: quiescence is a cleanliness
+    // guarantee, not something worth hanging the whole teardown for. An expired
+    // budget is not an error — the lifetime abort below is the lever.
+    const quiesce = new AbortController()
+    const quiesceTimer = setTimeout(() => quiesce.abort(), this.config.shutdownTimeoutMs)
+    try {
+      for (;;) {
+        while (this.serverRequests.size > 0) {
+          await Promise.allSettled([...this.serverRequests])
+          if (quiesce.signal.aborted) break
+        }
+        const tail = this.writeTail
+        await abortable(tail, quiesce.signal).catch((error) => {
+          if (!(error instanceof Error && error.name === 'AbortError')) errors.push(error)
+        })
+        if (quiesce.signal.aborted) break
+        if (this.writeTail === tail && this.serverRequests.size === 0) break
       }
-  const tail = this.writeTail
-      await tail
-      if (this.writeTail === tail && this.serverRequests.size === 0) break
+    } finally {
+      clearTimeout(quiesceTimer)
     }
-this.lifetimeController.abort()
+    this.lifetimeController.abort()
     this.detachStreams()
     if (errors.length === 1) throw errors[0]
     if (errors.length > 1) {

package/tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { compareDiagnostics, sanitizeDisplayPath } from './render.js'
+import { resolveWorkspaceRoot } from './workspace-root.js'
 
 /** Closed runtime reasons exposed by the canonical tool output. */
 const UNAVAILABLE_REASONS = /** @type {const} */ ([
@@ -105,7 +106,9 @@ const OUTPUT_SCHEMA = /** @type {const} */ ({
  * @typedef {object} FsSeam
  * @property {(path: string, opts?: { cwd?: string, signal?: AbortSignal }) => Promise<import('@deepseek-ai/dsh-fs').FsTarget>} resolve
  * @property {(target: import('@deepseek-ai/dsh-fs').FsTarget, signal?: AbortSignal) => Promise<import('@deepseek-ai/dsh-fs').FsInfo | undefined>} stat
+ * @property {(parent: import('@deepseek-ai/dsh-fs').FsTarget, child: import('@deepseek-ai/dsh-fs').FsTarget) => boolean} contains
  * @property {(target: import('@deepseek-ai/dsh-fs').FsTarget) => string} fileUrl
+ * @property {(target: import('@deepseek-ai/dsh-fs').FsTarget) => string} processPath
  */
 
 /**
@@ -351,13 +354,13 @@ export function createDiagnosticsTool({ fs, runtime, config, now = () => perform
       let early = abortOutcome(operation)
       if (early !== undefined) return early
       const signal = operation.controller.signal
-      const workspace = await fs.resolve(workspaceRoot, { signal })
+      const sessionWorkspace = await fs.resolve(workspaceRoot, { signal })
       early = abortOutcome(operation)
       if (early !== undefined) return early
-      const workspaceInfo = await fs.stat(workspace, signal)
+      const sessionWorkspaceInfo = await fs.stat(sessionWorkspace, signal)
       early = abortOutcome(operation)
       if (early !== undefined) return early
-      if (workspaceInfo === undefined || workspaceInfo.type !== 'directory') {
+      if (sessionWorkspaceInfo === undefined || sessionWorkspaceInfo.type !== 'directory') {
         throw new Error('lsp_diagnostics: session workspace is not an existing directory')
       }
 
@@ -379,6 +382,28 @@ export function createDiagnosticsTool({ fs, runtime, config, now = () => perform
         const label = extension.length === 0 ? '(none)' : extension
         throw new Error(`lsp_diagnostics: no configured diagnostics provider for extension ${label}`)
       }
+      /** @type {import('@deepseek-ai/dsh-fs').FsTarget | undefined} */
+      let workspace = sessionWorkspace
+      try {
+        if (fs.contains(sessionWorkspace, target) !== true) workspace = undefined
+      } catch {
+        workspace = undefined
+      }
+      if (workspace === undefined) {
+        workspace = await resolveWorkspaceRoot({
+          fs,
+          target,
+          extension,
+          sessionRoot: workspaceRoot,
+          signal,
+          sessionFallback: 'always',
+        })
+      }
+      early = abortOutcome(operation)
+      if (early !== undefined) return early
+      if (workspace === undefined) {
+        throw new Error('lsp_diagnostics: workspace root could not be resolved')
+      }
 
       const outcome = await runtime.diagnoseTarget(
         target,

package/workspace-root.js

@@ -0,0 +1,155 @@
+import { dirname, isAbsolute, join } from 'node:path'
+
+/** @typedef {'always' | 'if-contained' | 'never'} SessionFallback */
+
+/**
+ * @typedef {object} FsSeam
+ * @property {(path: string, opts?: { cwd?: string, signal?: AbortSignal }) => Promise<any>} resolve
+ * @property {(statTarget: any, signal?: AbortSignal) => Promise<{ version: string, type: string, size?: number } | undefined>} stat
+ * @property {(parentTarget: any, childTarget: any) => boolean} contains
+ * @property {(processTarget: any) => string} processPath
+ */
+
+const GO_MARKERS = /** @type {const} */ (['go.work', 'go.mod', '.git'])
+const TYPESCRIPT_MARKERS = /** @type {const} */ (['tsconfig.json', 'jsconfig.json', 'package.json', '.git'])
+const DEFAULT_MARKERS = /** @type {const} */ (['.git'])
+
+/**
+ * Return project markers for the already-routed source extension.
+ * @param {string} extension
+ * @returns {readonly string[]}
+ */
+function markersForExtension(extension) {
+  if (extension === '.go') return GO_MARKERS
+  if (extension === '.ts' || extension === '.tsx') return TYPESCRIPT_MARKERS
+  return DEFAULT_MARKERS
+}
+
+/**
+ * Stat one marker path. Missing or inaccessible markers are simply not roots.
+ * @param {FsSeam} fs
+ * @param {string} markerPath
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<boolean>}
+ */
+async function markerExists(fs, markerPath, signal) {
+  try {
+    if (signal?.aborted) return false
+    const marker = await fs.resolve(markerPath, { signal })
+    if (signal?.aborted) return false
+    const info = await fs.stat(marker, signal)
+    if (signal?.aborted) return false
+    return info?.type === 'file' || info?.type === 'directory'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve an existing directory root candidate.
+ * @param {FsSeam} fs
+ * @param {string} directory
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<any | undefined>}
+ */
+async function resolveDirectory(fs, directory, signal) {
+  try {
+    if (signal?.aborted) return undefined
+    const root = await fs.resolve(directory, { signal })
+    if (signal?.aborted) return undefined
+    const info = await fs.stat(root, signal)
+    if (signal?.aborted) return undefined
+    return info?.type === 'directory' ? root : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Walk from the target's directory to the filesystem root looking for project markers.
+ * @param {FsSeam} fs
+ * @param {string} startDirectory
+ * @param {readonly string[]} markers
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<any | undefined>}
+ */
+async function nearestMarkedDirectory(fs, startDirectory, markers, signal) {
+  let directory = startDirectory
+  for (;;) {
+    for (const marker of markers) {
+      if (await markerExists(fs, join(directory, marker), signal)) {
+        return resolveDirectory(fs, directory, signal)
+      }
+    }
+    const parent = dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/**
+ * Resolve the session root fallback and optionally require it to contain target.
+ * @param {FsSeam} fs
+ * @param {string} sessionRoot
+ * @param {any} target
+ * @param {SessionFallback} fallback
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<any | undefined>}
+ */
+async function resolveSessionFallback(fs, sessionRoot, target, fallback, signal) {
+  if (fallback === 'never') return undefined
+  if (typeof sessionRoot !== 'string' || sessionRoot.trim().length === 0) return undefined
+  const workspace = await resolveDirectory(fs, sessionRoot, signal)
+  if (workspace === undefined) return undefined
+  if (fallback === 'always') return workspace
+  try {
+    return fs.contains(workspace, target) === true ? workspace : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Resolve the LSP workspace for a target. Prefer a project marker rooted at the
+ * target itself (so sibling git worktrees work), then fall back to the session
+ * workspace according to the caller's policy.
+ *
+ * @param {object} input
+ * @param {FsSeam} input.fs
+ * @param {any} input.target
+ * @param {string} input.extension
+ * @param {string} input.sessionRoot
+ * @param {AbortSignal} [input.signal]
+ * @param {SessionFallback} [input.sessionFallback]
+ * @param {'language' | 'git'} [input.markerMode]
+ * @returns {Promise<any | undefined>}
+ */
+export async function resolveWorkspaceRoot({
+  fs,
+  target,
+  extension,
+  sessionRoot,
+  signal,
+  sessionFallback = 'if-contained',
+  markerMode = 'language',
+}) {
+  if (sessionFallback === 'if-contained') {
+    const sessionWorkspace = await resolveSessionFallback(fs, sessionRoot, target, sessionFallback, signal)
+    if (sessionWorkspace !== undefined) return sessionWorkspace
+  }
+
+  try {
+    if (signal?.aborted) return undefined
+    const targetPath = fs.processPath(target)
+    if (typeof targetPath === 'string' && isAbsolute(targetPath)) {
+      const markers = markerMode === 'git' ? DEFAULT_MARKERS : markersForExtension(extension)
+      const marked = await nearestMarkedDirectory(fs, dirname(targetPath), markers, signal)
+      if (marked !== undefined) return marked
+    }
+  } catch {
+    // Fall through to the configured session fallback.
+  }
+
+  if (sessionFallback === 'if-contained') return undefined
+  return resolveSessionFallback(fs, sessionRoot, target, sessionFallback, signal)
+}