Merge latest master into worktree-llm-dynamic-config

2026-07-30 23:55:50 +08:00
parent 9ebf7424f7 c017481618
commit 2a9a5ff412
12 changed files with 199 additions and 12 deletions
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/process/2026-07-30-cordis-config-source-plane-resolution-gate.md
+2026-07-30-cordis-config-source-plane-resolution-gate.md: f9070d39559948ef27f96df5afccd7c4e076f131
+2026-07-30-cordis-config-source-plane-resolution-gate.zh.md: fac6c4047d334d7dd0685aa270234fee3d15dba8
@@ -0,0 +1,27 @@
+# Agent Note: verify-cordis-config gates source-plane resolution of configured plugins
+
+Status: implemented
+
+English | [中文](2026-07-30-cordis-config-source-plane-resolution-gate.zh.md)
+
+## Problem
+
+`apps/cli/config/tui.cordis.yml` gained the `@deepseek-ai/dsh-tui/prompt` entry without a matching tsconfig `paths` mapping. The generic `@deepseek-ai/dsh-*` wildcard substitutes `tui/prompt` whole into its `<group>/*/src` candidates, none of which exist, so the [tsx source launch](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md) fell back to package `exports` and resolved `lib/prompt.js` — an artifact-plane file. Every environment with a built `lib/` (developer trees after `pnpm build`) booted fine, and the e2e workflow runs the keyless TUI PTY smoke in `lib` mode (`DSH_EXAMPLE_MODE=lib`, built bin under plain Node) so CI never exercises the source vector at all — while every clean checkout failed `pnpm dsh` at startup with `plugin(s) failed to load: @deepseek-ai/dsh-tui/prompt`. No gate checked the source plane, so the breakage shipped silently and surfaced only in fresh worktrees.
+
+## Decision
+
+`scripts/verify-cordis-config.ts` (`validateSourcePlaneResolution`) requires every configured specifier of a local workspace package — harness packages and vendored Cordis alike — to resolve through the `tsconfig.base.json` `paths` facade to a `.ts`/`.tsx` source file, using `ts.resolveModuleName` from the repository root. A failed resolution or a `.d.ts` hit (the `exports` fallback into built `lib/types`) fails `verify-cordis-config`, naming the config files and the specifier. The missing `@deepseek-ai/dsh-tui/prompt` mapping is added next to the other explicit subpath entries; removing it reproduces the gate failure.
+
+## Alternatives considered
+
+**Rely on the keyless TUI PTY smoke.** In default source mode it boots the real tree through the source vector and does catch the failure — but only on a clean tree. CI's e2e workflow runs it exclusively in `lib` mode (the built bin resolving real package `exports`), so no CI line runs the source vector, and developer trees with a stale `lib/` stay masked locally. Adding a source-mode CI smoke proves one composition per run; the static gate covers every shipped and example config.
+
+**Broaden the `dsh-source-launch-smoke` compat test to full boot.** The node-compat smoke asserts only the TTY refusal, which happens before plugin loading. A full keyless boot per matrix line duplicates the PTY smoke at higher cost and, like it, proves one composition rather than every shipped and example config.
+
+**A `@deepseek-ai/dsh-*/prompt`-style wildcard mapping.** Fixes this one subpath but not the class; the next single-file subpath export (`/surface`, `/message`, …) regresses identically. The static gate covers all current and future configured specifiers.
+
+## Consequences
+
+- A configured workspace specifier that resolves only through built `lib/` is now a red `verify-cordis-config` (in `hygiene` and CI) instead of a clean-tree-only startup crash.
+- New single-file subpath exports referenced from a cordis.yml need an explicit `tsconfig.base.json` `paths` entry at introduction time; the gate message says so.
+- The gate resolves with `tsconfig.base.json` options only; a specifier needing client-only compiler options to resolve would fail it, which matches the facade's role as the single resolution surface for tsx and vitest.
@@ -0,0 +1,27 @@
+# Agent Note: verify-cordis-config 对配置中插件的源码面解析实施门禁
+
+Status: implemented
+
+[English](2026-07-30-cordis-config-source-plane-resolution-gate.md) | 中文
+
+## 问题
+
+`apps/cli/config/tui.cordis.yml` 新增了 `@deepseek-ai/dsh-tui/prompt` 配置项，却没有对应的 tsconfig `paths` 映射。通用的 `@deepseek-ai/dsh-*` 通配符会把 `tui/prompt` 整体代入其 `<group>/*/src` 候选路径，而这些路径全都不存在，因此 [tsx 源码启动](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)会回退到包（package）的 `exports`，解析出产物面文件 `lib/prompt.js`。任何带有已构建 `lib/` 的环境（开发者目录树运行 `pnpm build` 后）都能正常启动，而 e2e 工作流以 `lib` 模式（`DSH_EXAMPLE_MODE=lib`，构建产物 bin 在普通 Node 下运行）执行无密钥 TUI PTY 冒烟测试，因此 CI 根本不会经过源码启动向量——与此同时，所有干净检出环境中的 `pnpm dsh` 都会在启动时失败，并报错 `plugin(s) failed to load: @deepseek-ai/dsh-tui/prompt`。当时没有门禁检查源码面，因此该故障未被发现便进入发布版本，仅在新的 worktree 中暴露。
+
+## 决策
+
+`scripts/verify-cordis-config.ts`（`validateSourcePlaneResolution`）要求配置中凡是引用本地 workspace 包的模块说明符（包括 harness 包与纳入 vendor 的 Cordis）都必须通过 `tsconfig.base.json` 的 `paths` 外观层（facade）解析到 `.ts`/`.tsx` 源文件；解析以仓库根目录为起点，调用 `ts.resolveModuleName` 完成。解析失败或命中 `.d.ts`（即经 `exports` 回退到构建出的 `lib/types`）都会使 `verify-cordis-config` 失败，并列出配置文件与模块说明符。缺失的 `@deepseek-ai/dsh-tui/prompt` 映射已添加在其他显式子路径条目旁；删除该映射即可复现门禁失败。
+
+## 备选方案
+
+**依赖无密钥 TUI PTY 冒烟测试。** 在默认源码模式下，该测试通过源码向量启动真实目录树，确实能捕获这个故障，但仅限干净目录树。CI 的 e2e 工作流只以 `lib` 模式运行它（构建产物 bin 通过真实的包 `exports` 解析），因此没有任何 CI 环节执行源码向量，而带有过期 `lib/` 的开发者目录树在本地也仍被掩盖。为 CI 增加一个源码模式冒烟测试，每次也只能证明一种组合；静态门禁则覆盖所有随产品发布的配置与示例配置。
+
+**将 `dsh-source-launch-smoke` 兼容性测试扩展为完整启动。** node-compat 冒烟测试只断言 TTY 拒绝，而该拒绝发生在插件加载之前。每条矩阵版本线都执行一次完整的无密钥启动，会以更高成本重复 PTY 冒烟测试，而且同样只能验证一种组合，无法覆盖所有随产品发布的配置与示例配置。
+
+**使用类似 `@deepseek-ai/dsh-*/prompt` 的通配符映射。** 这能修复当前子路径，却不能杜绝这一类问题；下一个单文件子路径导出（`/surface`、`/message` 等）仍会以同样方式复发。静态门禁覆盖当前及未来配置中引用的所有模块说明符。
+
+## 结果
+
+- 配置中的 workspace 模块说明符若只能通过构建后的 `lib/` 解析，现在会导致 `verify-cordis-config` 门禁失败（在 `hygiene` 和 CI 中执行），而不再成为只在干净目录树中出现的启动崩溃。
+- cordis.yml 中引用新的单文件子路径导出时，必须同步为 `tsconfig.base.json` 添加显式 `paths` 条目；门禁消息会明确提示这一要求。
+- 门禁只使用 `tsconfig.base.json` 的选项执行解析；如果某个模块说明符需要仅客户端可用的编译器选项才能解析，门禁就会失败。这符合该外观层作为 tsx 与 vitest 唯一解析入口的定位。
@@ -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/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: 898b8b5fe1b8d65b108b4afa95b782a1ce1e5c71
-2026-07-24-web-gui-browser-e2e-lane.zh.md: 966a9854aee8f3b63b2ae8f1362f91a40b9ba894
+2026-07-24-web-gui-browser-e2e-lane.md: 107dbddbfde8ad29e22d9cba04ce2b83c1d01383
+2026-07-24-web-gui-browser-e2e-lane.zh.md: e4132b2ebb3f30a9d540f47cf9416a13bc4aa9f3
@@ -16,7 +16,7 @@ The web GUI ships as a real assembled chain — chromium page → client plugin

 A plain shared-fixture module (the [testing-policy sanctioned shape](../../../../docs/testing.md)), not a package: the gate-worthy logic — replay derivation, session parsing, log scrubbing, persistence — lives in the gated packages `dsh-llm-replay`, `dsh-acp-snapshot`, and `dsh-session-persistence-jsonl`; what remains is boot wiring and browser glue, and chromium-driving code cannot hold per-file 100% coverage on the browserless coverage runners.

-`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`, `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md), `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor), the webserver row pinned to port 0 with the built dist, and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.
+`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`; every host-level `skill-local` root (`dshHome`, `agentsHome`, and `bundledSkillDir`) pinned beneath the temp workspace with watching disabled, because ambient skill catalogs are model-visible input; `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md); `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor); the webserver row pinned to port 0 with the built dist; and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.

 Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the open seam on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the seam empty, so a stray stream fails loud with NO_ADAPTER.

@@ -76,7 +76,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot

 ## Testing

-`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position.
+`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. The scaffold hermeticity scenario populates distinct entries in all three ambient skill roots and requires none to enter the assembled catalog. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position.

 ## Deferred

@@ -16,7 +16,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu

 一个普通的共享 fixture 模块（[测试政策认可的形态](../../../../docs/testing.md)），不是包：值得门禁把守的逻辑——回放推导、会话解析、日志脱敏、持久化——都在已受门禁的包 `dsh-llm-replay`、`dsh-acp-snapshot`、`dsh-session-persistence-jsonl` 中；剩下的只是启动接线和浏览器胶水，而驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100% 覆盖率。

-`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
+`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。

 无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。

@@ -76,7 +76,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu

 ## Testing

-`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。
+`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。

 ## 暂缓

@@ -0,0 +1,57 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import type {} from '@deepseek-ai/dsh-skill'
+import { launchWebScaffold, type WebScaffold } from './scaffold.ts'
+
+async function writeSkill(root: string, name: string): Promise<void> {
+  const bundle = join(root, name)
+  await mkdir(bundle, { recursive: true })
+  await writeFile(join(bundle, 'SKILL.md'), `---
+name: ${name}
+description: Must not enter the Web replay scaffold
+---
+
+Ambient host state.
+`)
+}
+
+it('isolates replay skill discovery from every ambient host root', async () => {
+  const ambient = await mkdtemp(join(tmpdir(), 'dsh-web-ambient-skills-'))
+  const dshHome = join(ambient, 'dsh-home')
+  const agentsHome = join(ambient, 'agents-home')
+  const bundled = join(ambient, 'bundled')
+  await Promise.all([
+    writeSkill(join(dshHome, 'skills'), 'ambient-dsh'),
+    writeSkill(join(agentsHome, 'skills'), 'ambient-agents'),
+    writeSkill(bundled, 'ambient-bundled'),
+  ])
+
+  const originalDshHome = process.env.DSH_HOME
+  const originalAgentsHome = process.env.DSH_AGENTS_HOME
+  const originalBundled = process.env.DSH_BUNDLED_SKILL_DIR
+  process.env.DSH_HOME = dshHome
+  process.env.DSH_AGENTS_HOME = agentsHome
+  process.env.DSH_BUNDLED_SKILL_DIR = bundled
+  let scaffold: WebScaffold | undefined
+  try {
+    scaffold = await launchWebScaffold()
+    const names = (await scaffold.ctx.skills.list({ cwd: scaffold.workspaceCwd })).map(skill => skill.name)
+    expect(names).not.toContain('ambient-dsh')
+    expect(names).not.toContain('ambient-agents')
+    expect(names).not.toContain('ambient-bundled')
+  } finally {
+    try {
+      await scaffold?.close()
+    } finally {
+      if (originalDshHome === undefined) delete process.env.DSH_HOME
+      else process.env.DSH_HOME = originalDshHome
+      if (originalAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
+      else process.env.DSH_AGENTS_HOME = originalAgentsHome
+      if (originalBundled === undefined) delete process.env.DSH_BUNDLED_SKILL_DIR
+      else process.env.DSH_BUNDLED_SKILL_DIR = originalBundled
+      await rm(ambient, { recursive: true, force: true })
+    }
+  }
+})
@@ -9,12 +9,13 @@
 // from live session memory), refresh (keyless replay that rewrites goldens).
 //
 // Composition divergences from `dsh web`, all deliberate, all via include
-// patches after the shipped surface overlay: temp persistenceRoot;
-// workspace-context disabled (recorded fixtures must not embed this repo's
-// AGENTS.md); session-title-llm disabled (its fire-and-forget title call
-// would race the loop for the session's replay cursor); webserver pinned to
-// port 0 with the built dist; keyless modes disable llm-deepseek and fill
-// the open llm seam post-boot with installLlmReplay on the settled root ctx
+// patches after the shipped surface overlay: temp persistenceRoot; local skill
+// roots confined to the temp workspace; workspace-context disabled (recorded
+// fixtures must not embed this repo's AGENTS.md); session-title-llm disabled
+// (its fire-and-forget title call would race the loop for the session's replay
+// cursor); webserver pinned to port 0 with the built dist; keyless modes
+// disable llm-deepseek and fill the open llm seam post-boot with
+// installLlmReplay on the settled root ctx
 // (the plugin-row path discards the ReplayHandle; the direct install keeps
 // assertConsumed for the teardown fixture-consumption check).
 import { existsSync } from 'node:fs'
@@ -172,6 +173,19 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
    // per write; the scaffold restores the original cwd after boot, so the
    // row gets an absolute temp root (removed with the workspace at close).
    { id: 'storage-json', config: { root: join(workspaceCwd, '.dsh-storages') } },
+    // Skill discovery is model-visible input. Pin every host-level root inside
+    // the owned temp world so ~/.dsh, ~/.agents, and a bundled-root env setting
+    // cannot change replay requests or conversation goldens. Project roots stay
+    // enabled against the same empty temp workspace, preserving the real seam.
+    {
+      id: 'skill-local',
+      config: {
+        dshHome: join(workspaceCwd, '.dsh-home'),
+        agentsHome: join(workspaceCwd, '.agents-home'),
+        bundledSkillDir: join(workspaceCwd, '.bundled-skills'),
+        watch: false,
+      },
+    },
    // fs/bash cwd default to process.cwd(); the gateway injects the same
    // value into session.cwd — chdir below anchors all three to the temp
    // workspace, keeping the composition untouched.
@@ -23,6 +23,7 @@
  // cannot see both sides of the cordis Context merges).
  "exclude": [
    "tests/scaffold.ts",
+    "tests/scaffold-hermetic.e2e.ts",
    "tests/live-interactions.e2e.ts",
    "tests/question-composer.e2e.ts",
    "tests/steering.e2e.ts",
@@ -74,6 +74,7 @@ for (const file of files) {

 errors.push(...validateExampleResolution())
 errors.push(...validateAppResolution())
+errors.push(...validateSourcePlaneResolution())

 if (errors.length > 0) {
  console.error('verify-cordis-config: invalid Loader metadata or plugin package resolution:')
@@ -152,6 +153,57 @@ function validateAppResolution(): string[] {
  return missingPluginDependencies(references, dependencies, 'apps/cli/package.json')
 }

+/**
+ * Every configured specifier of a local workspace package must resolve through
+ * the tsconfig `paths` facade to a `.ts`/`.tsx` source file. The `dsh` source
+ * launch (tsx) and vitest resolve in the source plane; without a `paths` match
+ * they fall back to package `exports`, which reach built `lib/` — present on a
+ * built dev tree, absent on a clean one — so a missing mapping boots locally
+ * yet breaks every clean checkout. Anything but a `.ts`/`.tsx` hit (a `.d.ts`
+ * or `.js` under built `lib/`) is that artifact-plane fallback, not source.
+ */
+function validateSourcePlaneResolution(): string[] {
+  const violations: string[] = []
+  const localPackages = localPackageDirectories()
+  const config = ts.readConfigFile(resolve(root, 'tsconfig.base.json'), path => ts.sys.readFile(path))
+  if (config.error !== undefined) {
+    throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  }
+  const { options, errors: optionErrors } = ts.convertCompilerOptionsFromJson(
+    (config.config as { compilerOptions?: unknown }).compilerOptions,
+    root,
+    'tsconfig.base.json',
+  )
+  if (optionErrors.length > 0) {
+    throw new Error(optionErrors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'))
+  }
+  // convertCompilerOptionsFromJson leaves `pathsBasePath` unset, so relative
+  // `paths` targets resolve against the host's current directory; anchor it to
+  // the repository root to keep the gate cwd-independent.
+  const host: ts.ModuleResolutionHost = {
+    fileExists: path => ts.sys.fileExists(path),
+    readFile: path => ts.sys.readFile(path),
+    directoryExists: path => ts.sys.directoryExists(path),
+    getCurrentDirectory: () => root,
+  }
+  const sourceExtensions = new Set<string>([ts.Extension.Ts, ts.Extension.Tsx])
+  const containingFile = resolve(root, 'scripts/verify-cordis-config.ts')
+  const locationsBySpecifier = new Map<string, Set<string>>()
+  for (const reference of pluginReferences) {
+    const packageName = packageNameFromSpecifier(reference.name)
+    if (packageName === undefined || !localPackages.has(packageName)) continue
+    const locations = locationsBySpecifier.get(reference.name) ?? new Set<string>()
+    locations.add(reference.file)
+    locationsBySpecifier.set(reference.name, locations)
+  }
+  for (const [specifier, locations] of locationsBySpecifier) {
+    const resolved = ts.resolveModuleName(specifier, containingFile, options, host).resolvedModule
+    if (resolved !== undefined && sourceExtensions.has(resolved.extension)) continue
+    violations.push(`${[...locations].join(', ')}: ${specifier} does not resolve to workspace source through tsconfig.base.json paths (add a mapping so the tsx source launch does not depend on built lib/)`)
+  }
+  return violations
+}
+
 function missingPluginDependencies(
  references: readonly PluginReference[],
  dependencies: Readonly<Record<string, string>>,
@@ -58,6 +58,7 @@
      "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"],
      "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"],
      "@deepseek-ai/dsh-commands/brand": ["./packages/ui/commands/src/brand.ts"],
+      "@deepseek-ai/dsh-tui/prompt": ["./packages/ui/tui/src/prompt.ts"],
      "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
      "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"],
      "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"],
@@ -121,6 +122,7 @@
      "@deepseek-ai/dsh-host-apiproxy": ["./packages/host/apiproxy/src"],
      "@deepseek-ai/dsh-host-directory-picker": ["./packages/host/directory-picker/src"],
      "@deepseek-ai/dsh-host-directory-picker/*": ["./packages/host/directory-picker/src/*"],
+      "@deepseek-ai/dsh-host-directory-picker-auto": ["./packages/host/directory-picker-auto/src"],
      "@deepseek-ai/dsh-host-directory-picker-browse": ["./packages/host/directory-picker-browse/src"],
      "@deepseek-ai/dsh-host-directory-picker-browse/*": ["./packages/host/directory-picker-browse/src/*"],
      "@deepseek-ai/dsh-host-directory-picker-native": ["./packages/host/directory-picker-native/src"],
@@ -10,6 +10,7 @@
  "include": [
    "apps/web/tests/scaffold.ts",
    "apps/web/tests/support.ts",
+    "apps/web/tests/scaffold-hermetic.e2e.ts",
    "apps/web/tests/live-interactions.e2e.ts",
    "apps/web/tests/question-composer.e2e.ts",
    "apps/web/tests/steering.e2e.ts",