@gavinc-cn/touchstone-dsh 0.1.1 → 0.3.0

package/dsh-plugin/lib/pack-closure.mjs

@@ -0,0 +1,291 @@
+/**
+ * 发包闭包计算 —— 「npm 包里必须有哪些文件」的**唯一一份**算法（零依赖，只用 `node:`）。
+ *
+ * 为什么要有它：`package.json` 的 `files` 是**白名单**，漏一条就是「发出去的包起不来」，
+ * 而漏的形态是静默的 —— 2026-10-15 实测 `@gavinc-cn/touchstone-dsh@0.1.1` 的 105 个文件里
+ * **没有 `backend/routes/` 的 11 个文件**（白名单只写了 `backend/server.js` / `backend/lib` /
+ * `backend/schema`），解包后 `node backend/server.js` 当场
+ * `ERR_MODULE_NOT_FOUND: .../backend/routes/index.js`（`backend/server.js:61` 就 import 它）
+ * 并 exit 1。手写清单（`dsh-plugin/scripts/prepack-check.mjs` 的 `REQUIRED`）挡不住这种漏，
+ * 因为它只查「我记得的那些」；这里改成**从入口正推**：包内必需 = 两个入口的**静态 import
+ * 闭包** + 运行时时按路径读的数据根。新增一个 `backend/routes/xxx.js` 而忘了改白名单 ⇒
+ * 闭包自动长大 ⇒ 判据变红。
+ *
+ * 两个入口（`package.json` 的 `main` + Node 后端入口，见 `dsh-plugin/lib/index.js:117-118`）:
+ *   - `dsh-plugin/lib/index.js` —— dsh 插件壳，宿主 `require`/`import` 的就是它；
+ *   - `backend/server.js`      —— 薄壳 spawn 的 Node 后端进程。
+ * 只解析**相对说明符**（`./` / `../`）：`node:*` 内建与裸包名不是包内文件，一律记为
+ * `unresolved` 供人看（不参与判据 —— 把裸包名当必需会把判据搞成假红）。
+ *
+ * 数据根（`RUNTIME_RESOURCES`）是**手写的**，条目都带「谁在哪一行读它」的证据；递归 import
+ * 扫描器看不到这些「按路径拼出来的读」，所以只能人工登记 —— 但每条都写清理由，不写「大概
+ * 需要」。注意 `backend/schema/fixtures/*` **不在**闭包里：它只被 `backend/test/db.test.mjs`、
+ * `tools/parity/db-run.mjs`、`tools/export_schema.py` 读（测试/量具），运行时没人读
+ * （实测 `grep -rn fixtures backend/lib backend/routes` 无命中）—— 别凭印象往里塞。
+ *
+ * 白名单展开（`expandFilesEntries`）按 npm 的 `files` 语义实现最小规则，行为经实测校准
+ * （`npm pack --dry-run --json`，见下），不是照文档猜的：
+ *   - 条目相对包根；`*` 不跨 `/`（实测 `files:["*.py","*.md"]` 只收根级的 a.py/top.md，
+ *     子目录 `sub/b.py` 不收 ⇒ **没有** matchBase 语义），`**` 跨目录；
+ *   - 条目指到目录 ⇒ 递归含其内容（`backend/lib`、`webui/dist-plugin` 都是这个形态）；
+ *   - `package.json` / `README*` / `LICENSE*`（含 `LICENCE*`）恒含。
+ * 有意**不**建模 `.gitignore`：本仓 `.gitignore` 里有 `webui/dist-plugin/`，但它照进包
+ * （实测 3 个文件都在）—— 说明显式 `files` 条目压过忽略规则。副作用写在文件末尾「已知缺口」。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 包根（本文件在 `<包根>/dsh-plugin/lib/` 下, 上溯三级） */
+export const PKG_ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+/** 闭包的两个入口（相对包根，posix 分隔） */
+export const ENTRIES = Object.freeze([
+  'dsh-plugin/lib/index.js',
+  'backend/server.js',
+]);
+
+/**
+ * 运行时时**按路径读**的数据根（静态扫描看不到；每条都要有证据行号）。
+ * `files` 列出「精确文件」（测试夹具不算，别往里塞）；`dirs` 列出「整个目录都要」——
+ * 目录内容在判据里**当场递归枚举**，所以往里新增数据文件也自动进入闭包。
+ */
+export const RUNTIME_RESOURCES = Object.freeze({
+  files: Object.freeze([
+    { rel: 'backend/schema/schema.sql', why: 'backend/lib/db.js:59 initDb 启动即读（目标 DDL）' },
+    { rel: 'backend/schema/schema.json', why: 'backend/lib/db.js:60 收敛器按它补列/建索引' },
+    { rel: 'backend/schema/migrations.json', why: 'backend/lib/db.js:61 声明式迁移清单，启动即执行' },
+  ]),
+  dirs: Object.freeze([
+    { rel: 'builtin_prompts/free_style', why: 'backend/lib/prompts.js:237 _ASSET_DIR，运行时读流程文档与文件模板' },
+    { rel: 'extensions', why: 'backend/lib/builtin-assets.js:262 DEFAULT_EXT_DIR，资产清单扫描根（routes/assets.js 的端点）' },
+    { rel: 'webui/dist-plugin', why: 'server 静态服务目录（薄壳启动参数 --web-dir 传的就是它，dsh-plugin/lib/index.js）' },
+  ]),
+});
+
+/** 目录递归枚举时跳过的东西（不进包，也不需要进闭包） */
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.run', '__pycache__']);
+
+/** 相对说明符扫描（见文件头：锚在行首，避开注释里的散文；多行 import 靠 `[^'"]` 跨行） */
+const IMPORT_FROM_RE = /^[ \t]*import\s+[^'"]*?\bfrom\s*['"]([^'"]+)['"]/gm;
+const IMPORT_SIDE_EFFECT_RE = /^[ \t]*import\s*['"]([^'"]+)['"]/gm;
+const EXPORT_FROM_RE = /^[ \t]*export\s+(?:\*|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** posix 化（判据字符串一律用 `/`，Windows 上跑出来的也必须一样） */
+export function toPosix(rel) {
+  return rel.split(path.sep).join('/');
+}
+
+/** 目录清单缓存：同一进程内按 root 复用（判据是只读的静态检查，进程内不假设文件树会变） */
+const LIST_CACHE = new Map();
+
+/** 递归列出 root 下所有**文件**（相对包根，posix 分隔，排序）；结果按 root 缓存 */
+export function listFiles(root = PKG_ROOT) {
+  const cached = LIST_CACHE.get(root);
+  if (cached) return cached;
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;                       // 读不动就当不存在（判据自己会报缺）
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk(abs);
+      } else if (entry.isFile()) {
+        out.push(toPosix(path.relative(root, abs)));
+      }
+    }
+  };
+  walk(root);
+  out.sort();
+  LIST_CACHE.set(root, out);
+  return out;
+}
+
+/** 抽一个源文件里的相对说明符（去重、保持出现顺序） */
+export function scanRelativeSpecifiers(source) {
+  const found = [];
+  const add = (spec) => {
+    if (!spec) return;
+    if (!spec.startsWith('./') && !spec.startsWith('../')) return;
+    if (!found.includes(spec)) found.push(spec);
+  };
+  for (const re of [IMPORT_FROM_RE, IMPORT_SIDE_EFFECT_RE, EXPORT_FROM_RE, DYNAMIC_IMPORT_RE]) {
+    re.lastIndex = 0;
+    for (const m of source.matchAll(re)) add(m[1]);
+  }
+  return found;
+}
+
+/**
+ * 解析相对说明符 → 包内文件（posix 相对路径）；解析不到返回 null。
+ * 支持无扩展名（补 `.js`、`/index.js`），与 Node 的 ESM 解析口径近似（本仓无扩展名导入）。
+ */
+export function resolveSpecifier(fromRel, spec, root = PKG_ROOT) {
+  const baseDir = path.posix.dirname(fromRel);
+  const joined = path.posix.normalize(path.posix.join(baseDir, spec));
+  const candidates = [joined, `${joined}.js`, `${joined}.mjs`, path.posix.join(joined, 'index.js')];
+  for (const rel of candidates) {
+    if (rel.startsWith('..')) continue;              // 跑出包根：不是包内文件
+    const abs = path.join(root, rel);
+    try {
+      if (fs.statSync(abs).isFile()) return rel;
+    } catch { /* 不存在的候选，继续试下一个 */ }
+  }
+  return null;
+}
+
+/**
+ * 计算运行时闭包：两个入口的静态 import 闭包 + `RUNTIME_RESOURCES`。
+ * @returns {{files: string[], unresolved: Array<{from: string, spec: string}>,
+ *            entries: string[], resources: string[]}}
+ *   `files` 排序去重；`unresolved` 是相对说明符解析不到（或裸包名/`node:`）的清单，
+ *   只报不用（避免把裸包名当必需导致假红）。
+ */
+export function computeClosure(root = PKG_ROOT) {
+  const files = new Set();
+  const unresolved = [];
+  const queue = [...ENTRIES];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const rel = queue.shift();
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    let source;
+    try {
+      source = fs.readFileSync(abs, 'utf8');
+    } catch {
+      unresolved.push({ from: rel, spec: '(入口本身读不到)' });
+      continue;
+    }
+    files.add(rel);
+    for (const spec of scanRelativeSpecifiers(source)) {
+      const resolved = resolveSpecifier(rel, spec, root);
+      if (resolved === null) unresolved.push({ from: rel, spec });
+      else queue.push(resolved);
+    }
+  }
+  const resources = [];
+  for (const item of RUNTIME_RESOURCES.files) {
+    files.add(item.rel);
+    resources.push(item.rel);
+  }
+  for (const item of RUNTIME_RESOURCES.dirs) {
+    const abs = path.join(root, item.rel);
+    if (!fs.existsSync(abs)) { unresolved.push({ from: '(资源根)', spec: item.rel }); continue; }
+    for (const rel of listFiles(abs)) {
+      const full = `${item.rel}/${rel}`;
+      files.add(full);
+      resources.push(full);
+    }
+  }
+  return {
+    files: [...files].sort(),
+    unresolved,
+    entries: [...ENTRIES],
+    resources: resources.sort(),
+  };
+}
+
+/** glob → 正则（npm `files` 最小语义：`**` 跨 `/`，`*`/`?` 不跨 `/`） */
+function globToRegExp(pattern) {
+  let re = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i++;
+        if (pattern[i + 1] === '/') { i++; re += '(?:.*/)?'; }   // `**/` 也匹配零层
+        else re += '.*';
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(ch)) {
+      re += `\\${ch}`;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp(`${re}$`);
+}
+
+/**
+ * npm 恒含的文件（`files` 白名单管不着）—— **只在包根**，实测校准过：
+ * `files:["a.txt"]` 时 `sub/README.md` / `sub/deep/LICENSE` 都不进包，
+ * 而根级 `package.json` 恒在。别把这条写成「任意层级的 README/LICENSE」（会假绿：
+ * 例如 `tests/README.md` 会被误判成包内 —— 实测它不在 105 个文件里）。
+ */
+function isAlwaysIncluded(rel) {
+  if (rel === 'package.json') return true;
+  if (rel.includes('/')) return false;
+  return /^(README|LICENSE|LICENCE)(\..*)?$/i.test(rel);
+}
+
+/**
+ * 展开 `files` 白名单 → 包内文件集合（最小 npm 语义，见文件头）。
+ * @param {string[]} entries package.json 的 files 数组
+ * @param {{root?: string, allFiles?: string[]}} [opts] 便于测试注入（负对照就在内存里换 entries）
+ * @returns {Set<string>} posix 相对路径集合
+ */
+export function expandFilesEntries(entries, opts = {}) {
+  const root = opts.root || PKG_ROOT;
+  const all = opts.allFiles || listFiles(root);
+  const packed = new Set();
+  for (const rel of all) if (isAlwaysIncluded(rel)) packed.add(rel);
+  for (const raw of entries) {
+    const entry = path.posix.normalize(String(raw).replace(/^\.\//, '').replace(/\/+$/, ''));
+    if (!entry || entry.startsWith('..')) continue;
+    const abs = path.join(root, entry);
+    let stat = null;
+    try { stat = fs.statSync(abs); } catch { /* 不存在：当 glob 处理 */ }
+    if (stat && stat.isDirectory()) {
+      for (const rel of listFiles(abs)) packed.add(`${entry}/${rel}`);
+      continue;
+    }
+    if (stat && stat.isFile()) { packed.add(entry); continue; }
+    const re = globToRegExp(entry);
+    for (const rel of all) if (re.test(rel)) packed.add(rel);
+  }
+  return packed;
+}
+
+/**
+ * 判据本体：闭包里但包内没有的文件（空数组 = 过）。
+ * @param {string[]} closureFiles `computeClosure().files`
+ * @param {Iterable<string>} packedFiles `expandFilesEntries(...)`
+ */
+export function findUnpacked(closureFiles, packedFiles) {
+  const packed = packedFiles instanceof Set ? packedFiles : new Set(packedFiles);
+  return closureFiles.filter((rel) => !packed.has(rel));
+}
+
+/**
+ * 读仓库 `package.json` 的 `files` 并跑完整判据（`prepack-check.mjs` 与单测共用）。
+ * @returns {{ok: boolean, missing: string[], closure: object, packedCount: number, files: string[]}}
+ */
+export function checkPackClosure(root = PKG_ROOT) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const entries = Array.isArray(pkg.files) ? pkg.files : [];
+  const closure = computeClosure(root);
+  const packed = expandFilesEntries(entries, { root });
+  const missing = findUnpacked(closure.files, packed);
+  return { ok: missing.length === 0, missing, closure, packedCount: packed.size, files: entries };
+}
+
+/**
+ * 已知缺口（写在这里，不装作没有）:
+ *   ① `.gitignore` / `.npmignore` 未建模 —— 若将来某个运行时文件恰好落在被忽略的目录里、
+ *      而白名单**没有**显式列出它，本判据会假绿（今天不会：闭包里的路径全部由显式条目覆盖）。
+ *   ② npm 的 `files` 对**符号链接**、`.npmrc`、`bundledDependencies` 有额外规则，本判据不管。
+ *   ③ 运行时**动态拼**出来的路径（例如按用户输入拼文件名）静态看不到，只能靠人工登记进
+ *      `RUNTIME_RESOURCES`；登记漏了就是假绿。
+ */

package/dsh-plugin/scripts/prepack-check.mjs

@@ -1,13 +1,20 @@
 /**
  * 发包前自检 —— package.json 的 `prepack` 钩子（`npm pack` / `npm publish` 前自动执行）。
  *
- * 两道检查:
+ * 三道检查:
  *  ① **必需文件在不在**：本包是自包含的（插件壳 + Python 平台 + 预构建 webui/dist-plugin +
  *     内置提示词/内置资产），少任何一块装到 profile 里都跑不起来；
  *  ② **三处「包名」逐字一致**：包根 package.json 的 `name`、`dsh-plugin/cordis.patch.yml`
  *     里 insert 行的 `name`、`dsh-plugin/lib/client.bundle.js` 里 `__ModuleLoader__.load({id})`
  *     的 id —— dsh 宿主按注册行的包名给浏览器半预留模块槽，三者不一致时页面报
  *     "loaded without registering"（2026-10-07 改名 @gavinc-cn/touchstone-dsh 时踩过）。
+ *  ③ **闭包 ⊆ 白名单**（2026-10-15 新增）：从两个入口（`backend/server.js`、
+ *     `dsh-plugin/lib/index.js`）正推运行时闭包（静态 import 图 + 运行时按路径读的数据根），
+ *     与 `files` 展开结果比对。①的手写清单挡不住「新加了一个文件、忘了改白名单」——
+ *     实测 0.1.1 发出去的包里 `backend/routes/` 11 个文件全缺，解包后
+ *     `node backend/server.js` 直接 ERR_MODULE_NOT_FOUND（`backend/server.js:61` import 它）。
+ *     算法在 `dsh-plugin/lib/pack-closure.mjs`（与 `tools/parity/test/pack-closure.test.mjs`
+ *     **同一份**，不是一个抄一个）；这里只读文件、**绝不递归调用 `npm pack`**（会被自己再触发）。
  *
  * 任一项不过就非 0 退出，让 `npm pack` / `npm publish` 直接中断：宁可发不出去，不可发出坏包。
  * 用法: node dsh-plugin/scripts/prepack-check.mjs
@@ -16,6 +23,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { checkPackClosure } from '../lib/pack-closure.mjs';
+
 /** 包根（本脚本在 <包根>/dsh-plugin/scripts/ 下, 上溯三级） */
 const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
@@ -24,6 +33,15 @@ const REQUIRED = [
   'package.json',
   'server.py',
   'requirements.txt',
+  // Node 后端骨架（2026-10-11 M0）：profile 里配 `backend: node` 时薄壳拉起的就是它，
+  // 缺了等于「开关一打开就起不来」——必须在发包自检里挡住。
+  'backend/server.js',
+  'backend/lib',
+  // 数据层共享契约（2026-10-11 M1）：`backend/lib/db.js` 启动即读 schema.sql /
+  // schema.json / migrations.json，缺了就是「Node 后端起不来」——同样必须在发包自检里挡住。
+  'backend/schema/schema.sql',
+  'backend/schema/schema.json',
+  'backend/schema/migrations.json',
   'builtin_prompts',
   'extensions/dsh-autocommit/asset.json',
   'webui/dist-plugin/index.html',
@@ -53,9 +71,19 @@ if (!bundle.includes(`id: ${JSON.stringify(pkg.name)}`)) {
 }
 if (pkg.private === true) failures.push('package.json 里 private: true, 发不出去（发布前删掉）');
 
+// 闭包 ⊆ 白名单: 从入口正推运行时必需文件, 逐条要求在 files 展开结果里
+// （算法见 dsh-plugin/lib/pack-closure.mjs；只读文件, 不跑 npm pack ⇒ 可以安全地待在 prepack 里）
+const closure = checkPackClosure(PKG_ROOT);
+if (!closure.ok) {
+  failures.push(`files 白名单漏了 ${closure.missing.length} 个运行时必需文件`
+    + `（新增运行时文件/目录后忘了改 package.json 的 files 就会这样）:`);
+  for (const rel of closure.missing) failures.push(`files 缺: ${rel}`);
+}
+
 if (failures.length > 0) {
   console.error(`prepack 自检未通过（${failures.length} 项）:`);
   for (const line of failures) console.error(`  - ${line}`);
   process.exit(1);
 }
-console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致`);
+console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致, `
+  + `运行时闭包 ${closure.closure.files.length} 个文件全在白名单内`);

package/dsh-plugin/src/client.js

@@ -105,20 +105,103 @@ function toggleByKey(e) {
 /** 宿主页 keydown 监听体(capture 阶段; 函数引用稳定, 便于 dispose 时精确解绑)。 */
 function onHostKey(e) { toggleByKey(e); }
 
+// ── 侧栏入口按钮的配色与几何(2026-10-09 修) ──────────────────────────────────
+// 血案: 原先写 color:'var(--dsw-alias-text-l1, #e8e8e8)' —— dsh **没有** text-l1 这族
+// token(真实族是 --dsw-alias-label-primary/secondary/tertiary/caption/dimmed), var() 取不到
+// 就一直吃 fallback: 浅色档在 #f9fafb 的侧栏底上画 #e8e8e8 的字(实测对比度 1.17, 同排的
+// 「插件」「设置」是 18.08), 只有深色档碰巧能看。教训: 引用宿主 token 一律先核实名字。
+// 现行口径(明暗两档都跟宿主走):
+//   · 颜色**只取 dsh 语义 token 且不写死 fallback** —— token 缺席时该声明失效并回落到继承
+//     (侧栏根 .hHd-Xa_root 已设 label-primary), 而不是钉死一个只对某一档成立的灰;
+//   · 尺寸/圆角/gap/行高逐条对齐 dsh 自己的 .SidebarRoot_panelRow(min-height 36 / 内边距
+//     7px 8px / margin 0 2px / gap 8 / line-height 22 / --dsw-radius-md), 收起态对齐
+//     .hHd-Xa_collapsed .panelRow(36x36 居中);
+//   · 图标盒 16x16 —— 与 dsh 侧栏 SVG 图标同尺寸; 文字继承侧栏根的 14px。
+const ENTRY_TITLE = 'Touchstone 测试平台（Alt+T 开关）';
+const ENTRY_GLYPH_STYLE = {
+  flex: '0 0 16px', width: 16, height: 16, display: 'inline-flex',
+  alignItems: 'center', justifyContent: 'center', fontSize: 16, lineHeight: '16px',
+};
+const ENTRY_LABEL_STYLE = {
+  minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+};
+
+// 交互态样式(悬停/开合/键盘聚焦环): 伪类没法写在 inline style 里, 落一张最小样式表。
+// 取值逐条对齐 dsh 侧栏行(.hHd-Xa_panelRow:hover 与 :focus-visible)。
+const ENTRY_CSS = [
+  '.ts-sb-entry{background:transparent}',
+  '.ts-sb-entry:hover,.ts-sb-entry.ts-sb-on{background:'
+    + 'var(--dsw-alias-interactive-bg-hover,color-mix(in srgb,currentColor 8%,transparent))}',
+  '.ts-sb-entry:focus-visible{outline-width:var(--dsw-focus-ring-width,2px);outline-style:solid;'
+    + 'outline-color:var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));'
+    + 'outline-offset:-2px}',
+].join('');
+const ENTRY_CSS_ID = 'touchstone/sidebar-entry.css';
+
+/** 幂等挂上入口行交互态样式表(形态与 dsh 插件自身的注入方式一致)。
+ *  **失败一律吞掉**: 挂不上只是少了悬停/聚焦环的观感, 绝不能让侧栏入口或面板受影响
+ *  (桩 DOM 自检环境里 document 面本就不全, 真机异常同理)。
+ * @returns 摘除函数(插件卸载时调用; 已存在/挂不上时返回空操作)。 */
+function mountEntryStyle() {
+  try {
+    if (typeof document === 'undefined' || !document.head
+        || typeof document.createElement !== 'function'
+        || typeof document.querySelector !== 'function') {
+      return () => {};
+    }
+    if (document.querySelector('style[data-plugin-css=' + JSON.stringify(ENTRY_CSS_ID) + ']')) {
+      return () => {};
+    }
+    const tag = document.createElement('style');
+    tag.dataset.plugin = 'touchstone';
+    tag.dataset.pluginCss = ENTRY_CSS_ID;
+    tag.textContent = ENTRY_CSS;
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  } catch (error) {
+    console.warn('[touchstone] 侧栏入口样式注入失败（只影响悬停/聚焦观感）:', error);
+    return () => {};
+  }
+}
+
 // 侧栏入口按钮(footer.action 槽; wide=侧栏展开态显示文字)
 function Toggle(props) {
-  const wide = props && props.wide;
+  const wide = !!(props && props.wide);
   const isOpen = useOpen();
+  const style = {
+    boxSizing: 'border-box', display: 'flex', alignItems: 'center',
+    border: 'none', cursor: 'pointer', textAlign: 'left',
+    color: 'var(--dsw-alias-label-primary)', // 无 fallback: 取不到即回落继承(见上注)
+    borderRadius: 'var(--dsw-radius-md, 8px)',
+    fontSize: 'inherit', // 侧栏根是 14px, 不再自带 13px
+  };
+  if (wide) {
+    style.gap = 8;
+    style.margin = '0 2px';
+    style.padding = '7px 8px';
+    style.minHeight = 36;
+    style.lineHeight = '22px';
+    style.flex = '1 1 auto';
+    style.minWidth = 0;
+  } else {
+    style.width = 36;
+    style.height = 36;
+    style.margin = 0;
+    style.padding = 0;
+    style.flex = 'none';
+    style.justifyContent = 'center';
+  }
   return h('button', {
-    style: {
-      display: 'flex', alignItems: 'center', gap: 6, width: '100%', boxSizing: 'border-box',
-      padding: '6px 12px', margin: '2px 0', borderRadius: 8, cursor: 'pointer', border: 'none',
-      color: 'var(--dsw-alias-text-l1, #e8e8e8)', fontSize: 13, textAlign: 'left',
-      background: 'transparent',
-    },
-    title: 'Touchstone 测试平台（Alt+T 开关）',
+    type: 'button',
+    className: 'ts-sb-entry' + (isOpen ? ' ts-sb-on' : ''),
+    style,
+    title: ENTRY_TITLE,
+    'aria-label': ENTRY_TITLE,
+    'aria-expanded': isOpen,
     onClick: () => setOpen(!isOpen),
-  }, wide ? (isOpen ? '🧪 关闭 Touchstone' : '🧪 Touchstone') : '🧪');
+  },
+  h('span', { style: ENTRY_GLYPH_STYLE, 'aria-hidden': 'true' }, '🧪'),
+  wide ? h('span', { style: ENTRY_LABEL_STYLE }, isOpen ? '关闭 Touchstone' : 'Touchstone') : null);
 }
 
 // 关闭按钮自动隐藏(2026-10-03): 常显会盖住被嵌 SPA 侧栏底部的用户名, 所以平时完全隐藏,
@@ -330,6 +413,8 @@ function Panel() {
 
 // cordis 客户端插件入口: 等 slots 服务就位后注册两个 UI 槽, 再挂快捷键
 function apply(ctx) {
+  // 侧栏入口的交互态样式表(悬停/开合/聚焦环), 与本插件同生命周期
+  ctx.effect(() => mountEntryStyle(), 'touchstone: 侧栏入口样式');
   const slots = ctx.get('slots');
   if (!slots) return;
   slots.inject('sidebar.footer.action', () => slots.register(

package/dshdriver.py

@@ -143,9 +143,30 @@ def available(timeout=HEALTH_TIMEOUT):
         return False
 
 
+def live_snapshot(timeout=10):
+    """`/live` 的**原始响应**：`{sessions: [...], complete?: bool}`。
+
+    `complete`（A 批 2026-10-08 起真插件会上报）＝插件是否已枚举宿主已有会话：
+    只有它为 true，**空表**才具备「宿主里确实没有会话」的语义（见 dshevents._align）。
+    旧装机副本没有该字段 ⇒ `complete` 缺省按未声明处理（空表＝未知）。
+
+    为什么单列一个读口（2026-10-08 修正）：`live()` 返回的是**行表**（历史调用点
+    server.py 直接迭代），而中枢对齐需要「行表 + 完整性声明」两件东西。旧写法拿
+    `live()` 的返回值当 dict 取 `.get("sessions")` ⇒ `/live` 非空时必抛
+    AttributeError，被 `except` 吞掉后中枢**永久「未对齐」**（`aligned()` 恒 False ⇒
+    看板 recover 不搬列、调和器缺席归位不触发）。契约由
+    `tests/test_session_visibility.py::test_live_readers_contract` 钉死。
+    """
+    return _request("GET", "/live", timeout=timeout) or {}
+
+
 def live():
-    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。"""
-    return _request("GET", "/live", timeout=10).get("sessions", [])
+    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。
+
+    返回**行表 list**（历史契约：server.py 的外部会话汇总直接迭代）；需要「完整性
+    声明」的调用方（dshevents._align）用 `live_snapshot()`。
+    """
+    return list((live_snapshot() or {}).get("sessions") or [])
 
 
 def status(session_id):
@@ -245,9 +266,17 @@ def fork(session_id, at_seq=None):
     return _request("POST", "/fork", payload, timeout=60)
 
 
-def rename(session_id, title):
-    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title}`。"""
-    return _request("POST", "/rename", {"session_id": session_id, "title": title})
+def rename(session_id, title, timeout=REQUEST_TIMEOUT):
+    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title, [external]}`。
+
+    `title` 是**宿主接受值**（可能被 `normalizeSessionTitle` 规范化/按 UTF-8 字节预算
+    截断），调用方据此回写卡面可保证两侧逐字一致（见 board.rename_card_session）。
+
+    `timeout` 可缩短：卡面改名是 best-effort 的同步链路（`PATCH /board/cards/<cid>`），
+    不能让驱动侧僵死把 HTTP worker 拖满默认 120s。
+    """
+    return _request("POST", "/rename", {"session_id": session_id, "title": title},
+                    timeout=timeout)
 
 
 def set_model(session_id, model, provider="", reasoning_effort=""):
@@ -355,6 +384,46 @@ def unarchive(session_id, timeout=30):
     return archive(session_id, archived=False, timeout=timeout)
 
 
+# ---------- 看管声明（外部会话投递通道，C 批 T5 2026-10-10） ----------
+
+# 看管声明超时（秒）：`/watch` 是驱动侧**纯内存写**，正常毫秒级返回；而投递前置闸
+# （`chat._external_preflight`）是在 HTTP 请求线程上同步调用它的——不能沿用普通请求
+# 的 120s，否则驱动僵死会把用户的一次「发送」卡住两分钟。2s 与「声明不成功即拒投」
+# 的语义相称（设计 §5.1）。
+WATCH_TIMEOUT = 2
+
+# 旧插件没有 `/watch` 端点时的状态码（未知驱动端点，见插件 _serve 的兜底 404）。
+# 平台据此把「外部会话投递」降级为拒投并给「插件过旧」文案，池内一切功能不受影响。
+WATCH_UNSUPPORTED = 404
+
+
+def watch_session(session_id, on=True):
+    """声明 / 撤销「平台看管该会话」（驱动 `POST /watch`，幂等）。返回看管是否生效。
+
+    为什么需要（C 批设计 §3.1）：外部会话（用户在 dsh GUI 里直跑/接管、`/live` 里
+    `owned:false`）既不在驱动池、也没有平台持有者，驱动侧因此不可能靠「在不在池内」
+    推断平台是否有意投递——**范围必须由平台显式划定**（宿主里与 Touchstone 无关的
+    会话多得是，无差别放开等于允许平台向任意会话注入消息与答案）。平台只对**平台确实
+    要投递的**会话声明看管：有看板卡的会话由 `board._ensure_watch` 常态声明；任务侧
+    会话在宿主上报为外部态（`owned:false`）时，由消息前置闸 `chat._external_preflight`
+    与作答/审批送达前的 `board._watch_before_delivery` 补声明。驱动据此放行 `/prompt`·
+    `/steer`·`/answer`·`/approval` 的池外分支。
+
+    幂等：重复声明同一 sid 不报错，驱动回执给的是 `watched` 的**当前实际状态**
+    （而非「这次有没有改动」），故本函数返回 `bool(resp["watched"])`——调用方按
+    「True 才算声明成功」处置。`on=False` 撤销（卡删除/归档后的回收，见
+    `board._watch_prune`）。
+
+    失败语义：**异常照抛**（`DshDriverError`：旧插件 404 / 驱动不可达 / 令牌错），
+    「是否吞异常降级」由调用方决定——`board._ensure_watch` 选择留痕 + 返回 False
+    且不重试（看管失败 ⇒ 投递前置闸拒投，见 `chat._external_preflight`）。
+    """
+    resp = _request("POST", "/watch",
+                    {"session_id": session_id, "on": bool(on)},
+                    timeout=WATCH_TIMEOUT)
+    return bool((resp or {}).get("watched"))
+
+
 def apply_session_defaults(session_id, model="", provider="",
                            reasoning_effort="", permission_mode="", log=None):
     """把项目级默认（思考等级 / 权限档）应用到刚建或刚续的会话上（best-effort）。