super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/specs/model-picker-ios-blur/spec.md

@@ -1,168 +0,0 @@
-# model-picker-ios-blur Specification
-
-## Status
-
-**OPEN — 不修，仅记录。** 2026-10-01 user 裁决：按奥卡姆剃刀，production 没问题就不引入非必要的兜底；当时写好的页面级兜底**已 revert**（源码、单测、mobile leg 接线全部移除）。本文是该问题的**调查记录**，不含任何生效的代码变更。
-
----
-
-## Purpose
-
-记录一个**未坐实的 iOS 触摸缺陷**的完整证据链，使得：
-
-1. 日后任何人不必从零重查——已知的事实、已证伪的假设、以及仍未知的部分都在这里；
-2. 当时那段**已删除**的兜底实现（要点 + 判据）可被重建；
-3. 「什么时候该重新研究」有明确触发条件。
-
----
-
-## 现象（user 报告，2026-10-01）
-
-iPhone Safari / 加到主屏的 Web App，composer 的 model seat：
-
-- 第一次点触发按钮 → 弹出**一级菜单**（两行：`Model │ <当前模型>`、`Effort │ <当前等级>`）—— 正常。
-- 再点一级菜单里的 **`Model` 那一行**（期望进入二级的 provider 分组模型清单）→ **整个 menu 直接关掉**，清单不出现。
-- 换模型、resume 会话等后续流程在能进入二级菜单时一切正常。
-
-发生实例：**4999 rig**（DSH 0.1.7-rc.1 checkout 构建 + better-dsh 0.2.4-d）。
-未发生实例：**3080 production**（DSH 0.1.7-rc.2 全局安装 + better-dsh 0.2.4-c），同一台 iPhone。
-
-> user 补充的历史：更早 **test.pc 的 PC 端**也出现过同样行为，后来某次更新/调整后**自愈**了。这条是「上游版本差异」这一方向的重要旁证。
-
----
-
-## Why not fixed (Occam 裁决)
-
-| 事实 | 含义 |
-|---|---|
-| prod（rc.2）在同机型同模式下**没有**这个问题 | 现役稳定版本不需要兜底 |
-| user 推测更早的 beta 也没有 | 不是「新版本引入的回归」 |
-| 曾经的 test.pc PC 端**自愈** | 更像上游某次改动带进来的差异，而非我们的插件 |
-| 两端**都是**加到主屏的 Web App（PWA） | PWA/浏览器模式差异这条最省事的解释被**排除** |
-
-结论：**不引入页面级兜底**；把证据留下，等有更强的复现条件（或上游版本对齐）再研究。
-
----
-
-## 已确证的事实（证据）
-
-**E1 — 不是数据/凭据问题。** 4999 活体驱动该组件：根菜单正常；二级清单完整加载 `DeepSeek`（V4.1-Flash、V4-Pro）+ `zai`（GLM-4.7、GLM-5-Turbo、GLM-5.2、GLM-5.2 Highspeed、GLM-5.3、GLM-5.3-Flash、GLM-5.3 Highspeed），**无 error strip / warning 行**。host 侧 `agent-default-model: zai/glm-5.3-flash`，`ZAI_API_KEY` 在凭据库。
-
-**E2 — 上游的关闭逻辑在两版之间字节一致。** `@deepseek-ai/dsh-client-ui-model-selection` 的 `ModelSelect.onBlur`：
-
-```js
-const onBlur = (event) => {
-  if (event.relatedTarget instanceof Node && (rootRef.current?.contains(event.relatedTarget) === true
-      || menuRef.current?.contains(event.relatedTarget) === true)) return;
-  close();   // 任何「没落在卡片里」的 blur 都关菜单
-};
-```
-
-prod 的 rc.2 与 rig 的 rc.1 逐字符相同 ⇒ 组件本身在两个实例上**同样脆弱**。
-
-**E3 — 机制可达（本地复现，无需 iOS）。** 菜单开着、触发器持焦时，制造一个 `relatedTarget === null` 的 `focusout`：
-
-```
-before: menuOpen=1, active=Select model, current …
-after:  menuOpen=0        ← 菜单被 onBlur 关掉
-```
-
-即：**只要 iOS 在 tap 的触摸相位把焦点抹到"没有地方"，菜单就会在 click 之前被 unmount，tap 被吃掉。** 这也解释了 user 观察到的「按完直接关回去」。
-
-**E4 — prod 并不免疫（对照实验，决定性）。** 用 prod 自己的 cookie 在真实浏览器里对 **3080 活体页面**施加同一个事件：
-
-| | 菜单开 | 施加 `focusout(relatedTarget=null)` | 点 Model 行 |
-|---|---|---|---|
-| **PROD 3080** | ✓ | **菜单被关掉** ❌ | — |
-| **RIG 4999**（当时带兜底） | ✓ | 存活 ✓ | 9 行清单 ✓ |
-
-⇒ 「prod 的代码里没有这个缺陷」被**证伪**。差异不在组件逻辑。
-
-**E5 — 两个实例服务的组件实现并不"几乎一样"。** 抓取**实际被浏览器加载**的 client bundle 比对（rc.1 vs rc.2），差异是实质性的（非仅 CSS）：
-
-- 菜单容器：裸 `<div>` → primitives 的 **`MenuSurface`**（多一层 `material` + 一个 `position:fixed` 的 backing portal）；
-- `show()`：rc.2 在「没有当前选择」时**直接开二级清单**（`setPane(state.current === null ? 'model' : 'root')`），rc.1 永远先开一级；
-- 新增 `pending` / `StateDot` 转圈、`retainedEffort`、`deepseek-account` provider 分组与文案；
-- 删除 composer-block（`blocked.composer`）；
-- `busy` 语义：`status === 'selecting'` → `pending !== null`；
-- 目录同步整段重写：catalog 未就绪时 **rc.1 把 `current` 清成 null / `groups` 清空**（除非 `resolved`），**rc.2 保留**。
-
-**E6 — 我们的插件不碰焦点/指针默认。** `better-dsh/src/mobile/client/index.ts` 的滑动手势只在 `document` 上**记录** pointerdown/move 的起点与位移，**既不 `preventDefault()` 也不 `stopPropagation()`**；zoom guard 只在 iOS 窄视口下改 viewport meta / 注入字号地板，不触碰焦点。⇒ 没有「我们的插件把 tap 吃掉」的通路。
-
----
-
-## 已证伪的假设
-
-| # | 假设 | 证伪方式 |
-|---|---|---|
-| H1 | 没有 GLM-5.3 的 key / catalog 两边对不上 → listing 报错后静默弹回 | **E1**（清单完整、无报错） |
-| H2 | 我们某个插件开发不到位（手势/zoom guard 吞掉了 tap） | **E6** |
-| H3 | prod 是 PWA、rig 是浏览器标签页，模式差异 | user 确认**两端都是加到主屏的 Web App** |
-| H4 | prod 的组件代码免疫，所以只有 rig 坏 | **E4**（prod 活体同样被关掉） |
-| H5 | 「两个实例几乎一样，只是版本落后一点点」 | **E5**（该组件实现有实质差异） |
-
----
-
-## 仍然未知（open question）
-
-> 同一台 iPhone、同为 PWA：为什么 **rc.2 的页面不发**那个杀死菜单的 blur，而 **rc.1 的页面发**？
-
-按可疑度排序的候选方向（**均未验证**）：
-
-- **D1（最可疑）** rc.1 → rc.2 之间**该组件自身**的行为差异（E5 那一串），特别是菜单容器从裸 `div` 换成 `MenuSurface`、以及 `show()` 开窗策略/目录同步重写。这条与 user 的「更新后自愈」时间线吻合。
-- **D2** 壳层（shell / kernel / composer / `ui-conversation`）在 rc.1→rc.2 的焦点处理差异。
-- **D3（低）** better-dsh 0.2.4-c（prod）vs 0.2.4-d（rig）的差异 —— 但 c→d 只多了 web-password gate 与本次已 revert 的 fix，两者都不参与焦点。
-- **D4** 其它环境项：iOS 版本、键盘是否弹起、PWA 安装时间与缓存态、tap 时 `document.activeElement` 究竟是谁。
-
-**重新研究的触发条件**：把 rig 对齐到 rc.2 后现象**仍在** ⇒ 推翻 D1/D2，转 D4，此时才值得上真机探针。
-
----
-
-## 复现与取证
-
-### R1 本地机制复现（Chromium，无需 iOS）
-
-```js
-// 菜单开着、触发器持焦时执行
-document.activeElement.blur()          // → menuOpen 1 → 0，菜单消失
-```
-
-或者用完整对照脚本：用 cookie 打开 3080 / 4999，`click` 触发器 → `document.activeElement.blur()` → 看 `[role="menu"]` 是否还在 → 若在，点 `[role="menuitem"]` 里含 `Model` 的那行，数 `[role="menuitemradio"]`。当时的脚本（已随 revert 删除）用的是 `puppeteer-core`（`better-dsh/node_modules`）+ playwright 缓存的 Chromium（`~/.cache/ms-playwright/chromium-1228/chrome-linux64/chrome`），cookie 从 curl 的 Netscape jar 解析（**注意 `#HttpOnly_` 前缀不是注释**）。
-
-### R2 真机取证（建议的下一步，尚未做）
-
-在页面注入探针，记录并**悬浮显示**最近 N 条 `touchstart / touchend / mousedown / focusin / focusout(relatedTarget) / click` + 每步的 `document.activeElement`，在 iPhone 上点一次、截图。这是唯一能看到「iOS 到底发了什么事件」的手段——本机没有可用真 WebKit（Playwright 不支持 Ubuntu 26.04，系统只有 snap epiphany）。
-
----
-
-## 当时的兜底实现（已 revert，存档备查）
-
-若将来 R2 证明「iOS 确实发了那个 blur」，可按此重建（`better-dsh` 的 `dashr-mobile` boot-script 腿，纯函数 + `Function.prototype.toString` 内联，与 `zoom-guard.ts` 同一约束：ES5、自包含）：
-
-```js
-export function isSpuriousMenuBlur(target, relatedTarget) {
-  if (relatedTarget !== null && relatedTarget !== undefined) return false
-  if (target === null || typeof target !== 'object') return false
-  var el = target
-  if (typeof el.closest === 'function') {
-    var owner = el.closest('[role="menu"]')
-    if (owner !== null && owner !== undefined) return true
-  }
-  if (typeof el.getAttribute !== 'function') return false
-  return el.getAttribute('aria-haspopup') === 'menu'
-    && el.getAttribute('aria-expanded') === 'true'
-}
-```
-
-接线：`document.addEventListener('focusout', e => { if (isSpuriousMenuBlur(e.target, e.relatedTarget)) e.stopPropagation() }, true)` —— **capture 相位在 React 的 root container 监听器之前跑**，所以 React 的 `onBlur` 收不到该事件。
-
-验证过的安全性：菜单外 `mousedown`（不依赖焦点）、`Escape`、`Tab`、以及任何 `relatedTarget` 是真实元素的 blur，全部照旧关闭；只有「从打开的菜单里 blur 到没有地方」这一种被压掉。段落需自带分号定界（相邻的 zoom 段以 `})()` 结尾、靠 ASI，裸语句会拼成 `})()var …` = SyntaxError）。
-
----
-
-## 参考锚点
-
-- 上游组件：`packages/client/ui-model-selection/src/client/ModelSelect.tsx`（`onBlur` / `show` / `drill` / `close`）
-- 上游 WebKit 相关的两笔提交（**只修了鼠标路径**，rig 与 prod 都已包含）：`6613660223`（keep model picker focus during mouse selection）、`06ef26a80f`（preserve focus when toggling the model picker），分支 `fix/webkit-model-picker`
-- 上游 e2e：`apps/web/tests/declared-reasoning.e2e.ts`（Chromium + WebKit 双引擎，含 `pointer-menu` 快照）；其 WebKit 用例走的是 `page.mouse.down()`（**鼠标**），因此覆盖不到触摸相位
-- 相关实现：`packages/client/ui-primitives/src/client/MenuSurface.tsx`（rc.2 新增的菜单容器）

package/node_modules/better-dsh/docs/specs/plugins-page-components/spec.md

@@ -1,79 +0,0 @@
-# plugins-page-components Specification
-
-## Purpose
-
-让 better-dsh 在原生 Plugins 页（`dsh-client-ui-plugin-manager`）上呈现与官方 bundle 同等的两件事：
-
-1. **卡片描述**：页面的 `BundleInfo.description` 直接取自包 manifest 的 `description` 字段；better-dsh 的 package.json 缺该字段导致卡片无描述。补齐为 awesome-dsh-plugins listing 的同款文案（单一事实源，两表面一致）。
-2. **组件化**：页面只把 bundle patch 的 **`insert` 行**列为可开关组件（每行一个 toggle，写 profile 用户层 `cordis.patch.yml` 的 `{id, disabled}` 覆盖行，HMR 即时生效）；非 insert 行只进 `overrides`（本页不显示）。现状 better-dsh 只有一条 insert（`dashr-repl`），整个插件是"一个组件"。本变更把 bundle patch 拆成 **6 条 insert**，每条 = 一个可独立开关的功能组件，映射原生 Agent Teams 的双组件形态。
-
-## Requirements
-
-### Requirement: 六组件行结构
-
-bundle patch（`cordis.patch.yml`）SHALL 恰好声明 6 条 insert 行，全部指向同一 npm 包 `better-dsh` 的子路径导出：
-
-| row id | module | 内容 |
-|---|---|---|
-| `dashr-repl` | `better-dsh` | 核心：kernel runtime + spin-up 供给检查 + `eval` + 三委派桥 + `llm_completion` + wire mask + escalation guidance |
-| `dashr-url-schemes` | `better-dsh/url-schemes` | URL 感知 I/O + hashline + devices（原 `DshUrlSchemes`，行配置载 `urlSchemes`/`hashline` gates） |
-| `dashr-failover` | `better-dsh/failover` | LLM failover 瀑布（settings 驱动，行配置 = 两个 fallback 槽） |
-| `dashr-compaction-tuning` | `better-dsh/compaction-tuning` | 自动压缩阈值偏好（settings 驱动） |
-| `dashr-web-trust` | `better-dsh/web-trust` | `webserver/index-inject` **authorities 腿**（`__DSH_TRANSPORT__.ownsHost`）；行配置 `trustedPageAuthorities`（schema 默认派生自 `DSH_TRUSTED_HOSTS`） |
-| `dashr-mobile` | `better-dsh/mobile` | `webserver/index-inject` **mobile 腿**（`__DASHR_MOBILE__` + zoomGuard 段）；行配置 = 原 `MOBILE_CONFIG` |
-
-#### Scenario: 页面呈现
-
-- **WHEN** 用户打开 Plugins 页的 better-dsh 卡片
-- **THEN** 卡片显示 listing 文案描述与 6 个组件行，每行可独立开关
-
-#### Scenario: 行开关落盘
-
-- **WHEN** 用户关闭任一组件行
-- **THEN** profile 用户层 patch 追加该 id 的 `{disabled: true}` 覆盖行，HMR 即时卸载该组件；重新打开则移除覆盖
-
-### Requirement: 配置键迁移（行 = 配置归属）
-
-`urlSchemes`、`hashline`、`trustedPageAuthorities`、`mobile` SHALL 从 `dashr-repl` 的 Config schema 移除，改由所属行的 schema 承载（schema 级默认逐键填充，跨 patch 覆盖层存活——v0.2.2a 裁决的延续）。config-file 用户改以行 id 为目标。
-
-#### Scenario: 行级 gates
-
-- **WHEN** `dashr-url-schemes` 行配置 `hashline: false`
-- **THEN** hashline read 锚点与 edit/undo 家族不安装，captured 原生 read 独立站立（既有 gate 语义不变，只是配置位置从核心行移到本行）
-
-### Requirement: 行间无注入边，排序无关
-
-任何组件行 SHALL NOT inject 另一组件行提供的服务；行为正确的唯一跨行约束——**capture-before-mask**（url-schemes 的继承面快照必须在 wire mask `restrict({deny})` 之前完成，快照保存被 mask 的委派工具定义）——SHALL 由 mask 监听器自身保证：mask 监听器第一步调用共享模块 `native-capture`（单例 chunk）的 `captureAllTools(agent)`（幂等，WeakMap 缓存），随后才 restrict。两个入口行（entry）的激活顺序因此无关紧要。
-
-#### Scenario: 顺序反转仍正确
-
-- **WHEN** cordis 激活顺序使 mask 监听器先于 url-schemes 的 session-start 监听器运行
-- **THEN** mask 先经 `captureAllTools` 固化 pre-mask 全量快照再 restrict；url-schemes 随后的 `captureNativeTools` 命中同一缓存，wrappers 照常安装（own-layer 注册不受已落限制过滤）
-
-#### Scenario: url-schemes 行关闭时桥不断
-
-- **WHEN** `dashr-url-schemes` 行关闭、`dashr-repl` 行开启
-- **THEN** mask 监听器的 capture 步骤照常固化快照，captured 委派工具定义仍可供读取；eval 与委派桥正常工作
-
-### Requirement: 双腿 boot script
-
-`buildBootScript` SHALL 拆为两个纯函数腿构建器：`buildTrustScript`（authorities 段）与 `buildMobileScript`（`__DASHR_MOBILE__` + zoomGuard 段），各自为空即注入 nothing；两行各自注册 `webserver/index-inject` 监听器（list 事件，`table.push` 天然可组合）。
-
-#### Scenario: 单腿开关
-
-- **WHEN** `dashr-mobile` 行关闭而 `dashr-web-trust` 行开启
-- **THEN** 页面仍注入 authorities 腿脚本，`__DASHR_MOBILE__` 缺席，client 移动手势/zoomGuard 保持惰性（client 半无改动，读页面全局缺席即休眠）
-
-### Requirement: override 行保持原样
-
-compaction 再启用三条（`compaction-basic`/`command-compact`/`tool-result-pruner`）与 `connection` fence 行 SHALL 保持 override 行形态。原生页面不列出 override 行（把再启用做成 insert 需 fork 上游插件模块，不采纳）。
-
-### Requirement: 描述单源
-
-package.json `description` SHALL 逐字采用 awesome-dsh-plugins listing 的 en 文案，使 Plugins 卡片与市场 listing 单源一致。
-
-## Out of Scope
-
-- npm publish（另行裁决，按发布红线走两道闸）。
-- `plugins.row.config` / `plugins.bundle.config` 配置表单（本变更只要求原生行开关；行配置仍走 config file）。
-- client half 改动（页面全局缺席即休眠的既有形态已满足）。

package/node_modules/better-dsh/docs/specs/preact-ui-shell/spec.md

@@ -1,22 +0,0 @@
-# preact-ui-shell Specification
-
-## Purpose
-为测试线（test-line）的 `apps/web` shell 提供构建期 React 家族到 `preact/compat` 的 vite alias patch：上游 ui-* 插件 bundle 的 `require("react")` 零改动获得 Preact 实例，shell 体积随之显著缩减。该 patch 仅限测试线 checkout，随 tag 切换重放；是否随插件包发布 dist 由 ship 决策另行裁决、暂缓。
-
-### Requirement: Preact-shell build for the web UI
-The test-line harness build SHALL support building the web shell (`apps/web`) with the React family aliased to `preact/compat` (including `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`, `react-dom/client` subpaths) via a build-time vite alias, so the platform module seed materializes Preact instances and every upstream client plugin bundle's `require("react")` receives Preact with zero upstream component edits. The alias SHALL be a monorepo-local build patch (documented, re-applied on tag switches), never an upstream source fork.
-
-#### Scenario: Shell serves the UI with Preact
-- **WHEN** the test-line instance is rebuilt with the alias patch and a browser loads the served UI
-- **THEN** the full upstream UI corpus mounts (sidebar/workspace/settings/chat), the session reports zero `pageerror` and zero `console.error`, and the shell bundle contains no `react-dom` production banner while carrying `preact` identity
-
-#### Scenario: Size regression is measured, not assumed
-- **WHEN** the alias build completes
-- **THEN** the shell `index` chunk (where the React family rides) is measured against the stock build and the delta recorded in the change report
-
-### Requirement: Test-line-only scope pending a ship decision
-The alias patch lives in the harness checkout only. The published plugin package (`@pgmi-builds/better-dsh`) SHALL NOT silently fork the web-UI serve surface: shipping a Preact-built frontend dist through the plugin (web-runtime override rows) is a separate decision gated on the prod host version upgrade, because a shipped dist freezes the UI corpus at the fork point.
-
-#### Scenario: Plugin publish content unchanged by this change
-- **WHEN** the next plugin alpha is published after this change
-- **THEN** the Preact enhancement is not part of the published artifact; the report records the ship-in-plugin option (dist + override rows) and its corpus-freeze trade-off as a pending decision tied to the prod host upgrade

package/node_modules/better-dsh/docs/specs/remote-pty-label/spec.md

@@ -1,126 +0,0 @@
-# remote-pty-label Specification
-
-## Purpose
-
-`remote` 工具的持久化 BYO-PTY 通道从「`spawn` 命令原文即会话键」改为「`target` 选择器寻址的具名会话」。旧实现的池键就是整条 spawn 文本，于是「同一条命令」与「同一个会话」被绑死：改一个 token 就**静默**新开一个 shell（cwd/env 全丢、零提示），roster 又拿整整一条 shell 命令当会话名。本规格固定新契约——`byop:<label>` 是唯一入口、label 由调用方（模型）自选并因此成为复用入口、`spawn` 降格为该 label 首次创建时的伴生参数——并据此定义创建/复用/冲突三分支、失败面，以及裸名候选表的末位新增项。
-
-## Requirements
-
-### Requirement: 单入口寻址
-
-`target` SHALL 是 `remote` 工具的唯一分流入口。以 `byop:` 开头的 target SHALL 被解析为 PTY 选择器，冒号之后的全部内容为 label。`spawn` SHALL 仅在与 `byop:<label>` target 同时出现时合法——它不再是独立入口。
-
-#### Scenario: spawn 不能独立成调用
-
-- **WHEN** 调用只给 `spawn`（无 target，或 target 不是 `byop:` 选择器）
-- **THEN** 系统返回 `[E_PARAMS]` 并在消息内给出正确形状 `{ target: "byop:<label>", spawn: "…", cmd: "…" }`，且不创建、不触碰任何会话
-
-#### Scenario: label 字符集
-
-- **WHEN** label 不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（空 label、含空白、含 `:` 等）
-- **THEN** 系统返回 `[E_BAD_LABEL]` 并在消息内给出合法形状，且不触碰会话池
-
-#### Scenario: PTY 选择器锁定 mode
-
-- **WHEN** `byop:<label>` target 与显式 `mode:"oneshot"` 同时出现
-- **THEN** 系统返回 `[E_BAD_MODE]`，而不是静默降级或静默改写 mode
-
-### Requirement: label 即复用入口，命名空间按 agent 隔离
-
-PTY 会话 SHALL 以 `` `${agentSessionKey}|p:${label}` `` 为池键。`spawn` 原文 SHALL 作为创建来源（origin）随会话保存，仅用于同 label 重复给 spawn 时的比对。label 首次创建之后，仅给 `{ target: "byop:<label>", cmd }` SHALL 复用该会话，cwd/env 存活。
-
-#### Scenario: 创建后仅凭 label 复用
-
-- **WHEN** 先调用 `{target:"byop:dev3", spawn:"bash", cmd:"cd /tmp && export MARK=live"}`，再调用 `{target:"byop:dev3", cmd:'echo "$MARK" && pwd'}`
-- **THEN** 第二次调用在**同一个** shell 内执行，输出含 `live`、cwd 为 `/tmp`，且结果带 `session: "byop:dev3"`
-
-#### Scenario: 两个 agent 的同名 label 互不可见
-
-- **WHEN** agent A 创建了 `byop:dev3`，agent B 以同一 label 且不给 spawn 调用
-- **THEN** B 得到 `[E_NO_SESSION]`，A 的会话不受任何影响
-
-### Requirement: 同 label 重复 spawn 的三分支
-
-对已存在的 label 再次给 `spawn` 时，系统 SHALL 将其与创建来源比对：相同即复用并在结果内附教学提示；不同即拒绝，且 SHALL NOT 执行任何命令。
-
-#### Scenario: 同一 spawn → 复用 + 提示
-
-- **WHEN** 对活着的 `byop:dev3` 再次传入与创建时逐字相同的 `spawn`
-- **THEN** 调用在既有会话内执行，结果的 `notice` 说明该 PTY 是持久化的、后续可省略 `spawn`（只写 label）
-
-#### Scenario: 不同 spawn → 冲突，什么都不跑
-
-- **WHEN** 对活着的 `byop:dev3` 传入与创建时不同的 `spawn`
-- **THEN** 系统返回 `[E_LABEL_CONFLICT]`，消息内含既有 spawn 原文与「丢掉 spawn 复用它 / 换一个 label 新建」两条出路，**cmd 不执行**，既有会话状态不变
-
-### Requirement: 无会话面 fail-loud 且不保留 spawn
-
-label 从未创建、或已被 idle TTL（默认 600s）回收时，不带 `spawn` 的调用 SHALL 返回 `[E_NO_SESSION]`。spawn 命令 SHALL NOT 被跨会话保留（无墓碑、无自动重建）。
-
-#### Scenario: 回收后必须重贴 spawn
-
-- **WHEN** `byop:dev3` 因 idle TTL 出池后调用 `{target:"byop:dev3", cmd:"echo hi"}`
-- **THEN** 系统返回 `[E_NO_SESSION]`，消息内给出带 `spawn` 的重建形状，并说明 spawn 未被保留
-
-### Requirement: 初始化失败不留任何东西
-
-首建命令未能初始化（`[E_SESSION_DIED]` / `[E_SESSION_START]`）时，该 PTY 会话 SHALL 出池：label 与 TTY SHALL NOT 被建立——这里从来没有过一个可用会话。**已 ready 过**的会话死亡 SHALL 留在池内（那是 reconnect 语义），不受本需求约束。
-
-#### Scenario: 失败的 spawn 之后 label 仍然自由
-
-- **WHEN** `{target:"byop:x", spawn:"…", cmd:"…"}` 的首建命令未能初始化
-- **THEN** 随后不带 spawn 的复用得到 `[E_NO_SESSION]`（而非重跑冻结的 argv 再失败一次），且带**任意** spawn 的调用 SHALL 正常新建——不得被创建来源比对拦成 `[E_LABEL_CONFLICT]`
-
-#### Scenario: 已 ready 的会话死亡仍可重连
-
-- **WHEN** 一个曾经初始化成功的 `byop:<label>` shell 死亡后被复用
-- **THEN** 该会话留在池内、按原创建命令重连并附 reconnect 提示
-### Requirement: 状态面与 roster 以 label 呈现
-
-`{target:"byop:<label>"}`（无 cmd）SHALL 只读池内状态、零拨号。roster SHALL 以 `byop:<label>` 命名会话，SHALL NOT 泄露 spawn 命令。
-
-#### Scenario: 探测不存在的 label
-
-- **WHEN** 对无会话的 `byop:<label>` 做 status 调用
-- **THEN** 返回 `session: none — no live PTY under this label`（不是 transport target 的 "dials on first exec"，也不报错）
-
-#### Scenario: roster 只给 label
-
-- **WHEN** 调用方自己以 `UNIQUESPAWNMARKER bash` 创建了 `byop:dev3`
-- **THEN** roster 包含 `live pty sessions: byop:dev3`，且文本中不出现 `UNIQUESPAWNMARKER`
-
-### Requirement: roster 的活性面按 agent session 作用域
-
-「live pty sessions」段 SHALL 只列调用方 agent session 自己的会话（池键前缀 = 调用方 sessionKey）。`ssh hosts` / `docker containers` / `incus containers` 三段名字候选 SHALL 保持全局可见。理由：名字候选是**静态公共配置**（谁都能 `ssh dev4`），活会话却是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，而两个 agent 各开一条线的代价可忽略。BYO-PTY 天然是活的，因此自然落进这个 scope，无需另立规则。
-
-#### Scenario: 两个 agent 各自只看见自己的活会话
-
-- **WHEN** agent `a1` 建了 `byop:mine`、agent `a2` 建了 `byop:theirs`，随后各自调 `{}`
-- **THEN** `a1` 的 roster 含 `byop:mine` 且不含 `byop:theirs`（反之亦然），而两边 `ssh hosts` / `docker containers` / `incus containers` 三段内容相同
-### Requirement: 模型面不得泄露池内部键
-
-面向模型的文本（roster、status、错误消息）SHALL 只出现模型面名字（`byop:<label>`、裸 transport target），SHALL NOT 出现池键（`` `${agentSessionKey}|p:<label>` `` / `|t:<target>`）。key→名字 SHALL 是单一定义（`displayKey`），roster 与错误面共用同一条规则。
-
-#### Scenario: 初始化失败的错误消息
-
-- **WHEN** agent `sess-abc` 的 `byop:x` 初始化失败
-- **THEN** 错误消息含 `'byop:x'`，且不含 `sess-abc`、不含 `|p:`
-
-### Requirement: 裸名候选表末位新增 PTY label
-
-裸名解析顺序 SHALL 保持 ssh config 字面 host → docker → incus **一位不挪**，并在这三段之后、ssh 兜底之前追加「池内活 PTY label」候选。该候选 SHALL 仅在调用面未显式指定 `mode:"oneshot"` 时参与匹配。命中顺序即优先级：同名冲突时更靠前的来源胜出。
-
-#### Scenario: 无重名时裸 label 可达（懒复用）
-
-- **WHEN** 池内有 `byop:lab`，ssh config / docker / incus 均无 `lab`，且调用 `{target:"lab", cmd:"…"}`（未指定 mode）
-- **THEN** 调用落在该 PTY 会话上（mode 为 `pty`），结果 `session` 为 `"byop:lab"`
-
-#### Scenario: 重名时 ssh host 优先
-
-- **WHEN** ssh config 存在 `Host lab`，同时池内有 `byop:lab`
-- **THEN** 裸名 `lab` 仍解析为 ssh transport（现有优先级逐位不变）；要进 PTY 通道必须显式写 `byop:lab`
-
-#### Scenario: 显式 oneshot 不吃 PTY 候选
-
-- **WHEN** 调用显式带 `mode:"oneshot"` 且 target 为裸名
-- **THEN** 该调用不走 PTY 末位候选，裸名在 `mode:"oneshot"` 下的旧行为逐位保留

package/node_modules/better-dsh/docs/specs/repl-dispatch-resilience/spec.md

@@ -1,21 +0,0 @@
-# repl-dispatch-resilience Specification
-
-## Purpose
-REPL（`eval` cell）子分派的韧性契约：分派层的任何错误——调度器缺失、工具体抛错、取消——都必须 settle 为 cell 可见的 `ToolCallError` 结果，绝不外泄为 unhandled rejection 或使宿主进程崩溃。生产组合必须把带 `TOOL_RUNTIME_SCHEDULER` symbol 的原生 `ToolRuntime` 实例解析给插件，测试组合与生产组合之间不得存在环境差异导致的静默行为分裂。
-
-## Requirements
-
-### Requirement: Dispatch errors settle as visible ToolCallError
-The system SHALL resolve the plugin's tools service to the native `ToolRuntime` instance carrying the `TOOL_RUNTIME_SCHEDULER` symbol in the production composition, so REPL sub-dispatches execute through the same staged scheduler as the agent loop and return real tool results to the cell. The symbol this plugin imports SHALL be identical (`===`) to the one keying the mounted instance — a second dsh-tools module copy reachable from the deployed plugin (e.g. stray nested `@deepseek-ai` symlinks) breaks that identity and is a deployment defect (2026-09-02 corrected root cause; the plain `runtimeCtx.tools` read is the sanctioned resolution path). A mount whose tools service genuinely lacks the symbol SHALL be treated as a loud, diagnosable configuration failure — the error names the plugin's own `dsh-tools` resolution path — rather than a silent runtime crash, and that loud failure SHALL be the abnormal fallback, not the normal production state.
-
-#### Scenario: Production mount carries the scheduler symbol
-- **WHEN** the DASHR plugin mounts in the production composition and a cell dispatches a real tool call
-- **THEN** the dispatch executes through `registry[TOOL_RUNTIME_SCHEDULER]` and returns the tool result to the cell without crashing the daemon
-
-#### Scenario: Legitimate cell tool call returns its real result
-- **WHEN** a cell dispatches a legitimate tool call (e.g. `tool.read({ path })`) in a live session after the fix
-- **THEN** the cell receives the tool's actual result, not the `TOOL_RUNTIME_SCHEDULER` loud error
-
-#### Scenario: Regression probes pass after the fix
-- **WHEN** the four probe cells from the diagnosis matrix (`tool.subagent` background:false, `tool.subagent` background:true, `tool.bash` background:true, `tool.read`) run in a live session after the fix
-- **THEN** all four return a real result (or a visible `ToolCallError` where the call is legitimately invalid) instead of truncating, and the journal contains no new daemon crash

package/node_modules/better-dsh/docs/specs/skill/spec.md

@@ -1,58 +0,0 @@
-# skill Specification
-
-## Purpose
-
-Let the model address skill bodies and internal skill resources via `skill://` URLs, with discovery tied to the same workspace source that advertises skills, and replace the skill tool's body-loading role on the REPL surface.
-
-## Requirements
-
-### Requirement: Skill body addressing
-The system SHALL let read accept `skill://<name>` and return that skill's SKILL.md body in full text (no default truncation; only explicit selectors page).
-
-#### Scenario: Reading an existing skill
-- **WHEN** the model reads `skill://<registered skill name>`
-- **THEN** the system returns the skill's body text in full
-
-#### Scenario: Reading an unknown skill
-- **WHEN** the model reads `skill://<unregistered name>`
-- **THEN** the system returns the structured `URL_SKILL_NOT_FOUND` error ("unknown or no longer available")
-
-### Requirement: Skill internal resource addressing
-The system SHALL let read accept `skill://<name>/<path>` and return the named file inside the skill's resource directory, loaded through the sandboxed filesystem (same containment/audit rules as host reads). A skill without a filesystem resource directory returns `URL_SKILL_NO_RESOURCE_BASE`; a subpath escaping the directory returns `URL_SKILL_RESOURCE_ESCAPE`.
-
-#### Scenario: Reading a referenced skill file
-- **WHEN** the model reads `skill://foo/references/x.md`
-- **THEN** the system returns the content of `references/x.md` inside foo's resource directory
-
-#### Scenario: Resource path escapes the skill directory
-- **WHEN** the model reads `skill://foo/../../etc/passwd`
-- **THEN** the system returns the structured `URL_SKILL_RESOURCE_ESCAPE` error and reads nothing
-
-### Requirement: Workspace-cwd-sensitive discovery
-The system SHALL pass the calling agent's session cwd (`{cwd: agent.session.header.cwd}`) to every skill-registry lookup — the same source `dsh-tool-skill` uses to render `<available_skills>` — so `skill://` can address exactly the skills the catalog advertises for the current workspace.
-
-#### Scenario: Skill visible in the current workspace
-- **WHEN** the model reads `skill://foo` from a session whose cwd is inside a project root that provides foo
-- **THEN** the lookup succeeds and the body resolves
-
-#### Scenario: Skill outside the workspace is unknown
-- **WHEN** a skill's project roots do not cover the session cwd
-- **THEN** the lookup misses and the system returns `URL_SKILL_NOT_FOUND`, matching what `<available_skills>` advertised
-
-### Requirement: Path-backed search view
-The system SHALL expose the handler's `resolvePath`: `skill://<name>` maps to the skill's resource-directory root and `skill://<name>/<subpath>` to the joined file (same escape guard), letting grep/glob search the real files; unmappable URLs (unknown skill, non-directory resource base, escaping subpath) resolve to `undefined` so callers fall back to text resolution with its structured error.
-
-#### Scenario: grep searches the skill's real directory
-- **WHEN** the model greps a `skill://foo` URL
-- **THEN** the search runs natively over foo's on-disk resource directory
-
-### Requirement: Skill tool masked on the REPL surface only
-The system SHALL mask the upstream `skill` tool presentation-only (ADR-0002): it disappears from the REPL `tool.*` binding names and the dashr tool-catalog section, while the host-layer native `skill` tool stays registered and executable and the `<available_skills>` discovery catalog is retained.
-
-#### Scenario: Skill absent from the REPL surface
-- **WHEN** the model inspects the kernel tool bindings or the tool-catalog text
-- **THEN** neither contains `skill`, and `skill://` URLs remain the addressing path for skill content
-
-#### Scenario: Host-native skill tool survives
-- **WHEN** any host-plane consumer dispatches the native `skill` tool directly
-- **THEN** the tool remains registered and executable — the mask touched only presentation surfaces