dsh-plugin-upgrade 0.1.0

package/README.zh.md

@@ -0,0 +1,172 @@
+<div align="center">
+
+# ⬆️ dsh-plugin-upgrade
+- **1024 商店通道**：先 `npm i -g dsh1024`，再执行 `dsh1024 plugin --profile web add dsh-plugin-upgrade`（计入 [deepseek1024.com](https://deepseek1024.com) 安装排行）。
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-upgrade)
+
+**DeepSeek Harness 插件升级技能（版本锁定）——`0.1.3-alpha.1` → `0.1.5-alpha.1`。**
+
+*一张版本卡 + 一个零依赖接缝扫描器，让「typecheck 绿了」不再被误当成「插件还能跑」。*
+
+> **官方仓库。** 这是 dsh-plugin-upgrade 唯一的官方仓库，由 PerryLink 维护。其他账号下的同名仓库与本项目无关。
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![dsh-doctor](https://raw.githubusercontent.com/PerryLink/dsh-plugin-doctor/main/badges/PerryLink__dsh-plugin-upgrade.svg)](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-upgrade/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-plugin-upgrade/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-plugin-upgrade?label=version)](https://github.com/PerryLink/dsh-plugin-upgrade/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-upgrade)](https://www.npmjs.com/package/dsh-plugin-upgrade)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-upgrade)](https://www.npmjs.com/package/dsh-plugin-upgrade)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## 兼容性
+
+| 面 | 状态 |
+|---|---|
+| 宿主 | DeepSeek Harness `0.1.5-alpha.1`（checkout `19d2e38480`，tag `dsh-v0.1.5-alpha.1` = `5dda764ed3`）。peer 区间 `@deepseek-ai/dsh-skill >=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0`、`@deepseek-ai/cordis ^4.0.2`、`@deepseek-ai/schemastery ^3.18.2`。 |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| 平台 | 有 Node 即可；扫描器只读文件系统，与平台无关 |
+| 模型 | 纯文本模型完全支持；技能就是一段 Markdown，不要求工具或视觉能力 |
+| 范围 | **只覆盖一条走廊**：`0.1.3-alpha.1` → `0.1.5-alpha.1`。它不是通用迁移框架。 |
+
+## 你得到什么
+
+两半，一套接缝目录：
+
+- **一个随包发布的 agent 技能（`plugin-upgrade-015`）** —— 版本卡 + 「修-验」循环。只有任务真正需要时模型才会加载它；本包不贡献任何系统提示词段落，也不注册工具。
+- **一个零依赖 CLI（`dsh-plugin-upgrade-scan`）** —— 按 `file:line` 报告十类接缝；这些接缝来自 2026-09-09 那轮对 40 个真实插件仓的实测。命中 error 级即退出码 `1`，可直接接进 CI。
+
+它要消灭的失效模式是：**本地门禁绿了，不等于适配完成。** 有两类破坏能穿过 `typecheck` + `test`：
+
+1. 已发布的类型线把接缝藏住，仓库对着旧类型编译（接缝 `M1`）；
+2. 测试是按旧形状 mock 的，于是测试通过而宿主拒收。
+
+十类接缝中的 `S3`、`S8`、`S9`、`M1` 在本包成文时仍未被任何社区升级 PR 覆盖；其余六类已与该轮证据交叉核对。
+
+## 快速开始
+
+```sh
+# 1. 把 bundle 装进 profile
+dsh plugin --profile web add dsh-plugin-upgrade
+
+# 2. 确认这一行挂上了
+dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-upgrade'
+
+# 3. 扫描你正在升级的插件
+npx dsh-plugin-upgrade-scan --repo ../my-plugin
+```
+
+然后让 agent 使用 `plugin-upgrade-015` 技能，或者自己照着版本卡走：
+`skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md`。
+
+## 安装与卸载
+
+```sh
+dsh plugin --profile web add dsh-plugin-upgrade            # 从 npm 安装
+dsh plugin --profile web add "github:PerryLink/dsh-plugin-upgrade#main"   # 从源码安装
+dsh plugin --profile web remove dsh-plugin-upgrade         # 卸载（可逆）
+```
+
+装 bundle 只是注册一个技能；删掉那一行就删掉技能。CLI 是普通的 `npx` 目标，完全不需要 profile。
+
+## 配置
+
+所有键都可选，写在 profile patch 里：
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 是否注册随包技能。设为 `false` 可保留依赖但不生效。 |
+| `skillName` | `plugin-upgrade-015` | `skillsRoot` 下要注册的目录名，也是目录里显示的名字。 |
+| `skillsRoot` | 包自带的 `./skills` | `<skillName>/SKILL.md` 所在目录。指向你自己的卡即可复用整套管线。 |
+| `userInvocable` | `true` | 除模型外，是否允许人按名字调用该技能。 |
+
+```yaml
+- insert:
+    - id: dsh-plugin-upgrade
+      name: dsh-plugin-upgrade
+      config:
+        skillName: plugin-upgrade-015
+```
+
+挂载是「大声失败」的：`SKILL.md` 缺失、正文为空、或 frontmatter 没有 `name`，都会让挂载失败，而不是注册一个空技能。
+
+## 暴露面
+
+**技能** —— `plugin-upgrade-015`（默认模型可调用、人也可调用）。正文：6 步循环。引用：版本卡。脚本：扫描器，随技能目录一起发布，因此相对路径可解析。
+
+**CLI** —— `dsh-plugin-upgrade-scan`：
+
+```sh
+dsh-plugin-upgrade-scan [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]
+```
+
+| 参数 | 含义 |
+|---|---|
+| `--repo <path>` | 要扫描的仓库（默认：当前目录）。 |
+| `--json <out.json>` | 同时写出机器可读报告（`repo`、`scannedAt`、`files`、`hits[]`、`bySeam`）。 |
+| `--seams S3,S8,M1` | 只扫指定接缝。 |
+| `--quiet` | 不打印人类可读渲染（与 `--json` 搭配）。 |
+
+退出码：`0` 无 error 级命中 · `1` 至少一个 error 级命中 · `2` 用法或扫描失败。扫描干净是必要条件而非充分条件 —— 卡上的出口标准是在临时 `DSH_HOME` 上做一次真机冒烟。
+
+## 十类接缝
+
+| Id | 级别 | `0.1.5-alpha.1` 线里变了什么 |
+|---|---|---|
+| `S1` | warn | 会话格式为 V3，日志文件名带世代（`session.v3.jsonl.zstd`）。硬编码 `session.jsonl.zstd` 会静默失效。 |
+| `S2` | warn | `EpochHeader.system` 已移除；系统提示词是 surface 节点 0 的 `system/message`。读取方需要结构式回退。 |
+| `S3` | error | `assistant/message` 必须带 `stream`；缺了会话能导入但无法续聊（`Session.fromRestore` 拒绝非法 settlement 字段）。 |
+| `S4` | error | `tool/code-dispatch` 改名为 `tool/ptc-dispatch`。 |
+| `S5` | error | `ctx.agent` 已移除；调用方改为显式接收 `Agent`。 |
+| `S6` | error | `Inbox` 变成类型接口，不再可构造；请用 `agent.inbox` 与官方夹具形状。 |
+| `S7` | warn | `SubprocessHandle.pid` 已移除（只有 `SubprocessTerminalHandle` 保留 `pid`）。 |
+| `S8` | error | `SessionHandle.read()` 现在返回 `SessionHandleReadResult` —— 要解包 `.events`。 |
+| `S9` | error | `SystemPrompt` 配置的 `persona` 改为 `personaPrefix` / `personaSuffix`。 |
+| `M1` | error | `tsconfig` 的 `paths` 指向不存在的 checkout 目录时，TypeScript 会静默回退到已发布类型 —— 本地门禁变成**假绿**。 |
+
+`S7`、`S1`、`S2`、`S10` 刻意保持「提示」级别：它们有合法命中（Node 自带的 `pid`、旧世代读取器、插件自建的自适应事件门），所以扫描器把它们报成待人工复核的线索，而不是失败。
+
+## 本包不覆盖什么
+
+- **其他走廊。** `0.1.1` → `0.1.2` 以及未来版本线不在范围内；版本卡刻意锁死版本 —— 会漂移的卡比没有卡更糟。
+- **DSH 面向用户的升级路径。** 本包升级的是**插件源码**，不是用户的 harness 安装。
+- **客户端/浏览器行为。** 扫描器是静态的；client 半边仍需真实浏览器断言。
+- **证明。** 扫描干净只是假设。出口标准是真机冒烟（临时 `DSH_HOME`、目标 CLI、`plugin add <tarball>`、`--dump-config`，会话日志写入方还要加一次 resume 往返）。
+
+## 安全边界
+
+- **只读扫描。** CLI 绝不往被扫仓库里写文件；`--json` 只写你指定的路径。
+- **无网络、无 shell。** 扫描器除 Node 标准库外不引入任何依赖，也从不创建进程。
+- **不碰密钥。** 本包不读取凭据、环境令牌或会话数据。
+- **沙箱化冒烟配方。** 卡上的真机检查使用 `mkdtemp` 出来的 `DSH_HOME`，绝不碰你真实的 `~/.dsh`。
+
+## 开发
+
+```sh
+pnpm install
+pnpm test                          # node --test（真实 Cordis + 真实 SkillRegistry）
+pnpm run verify:self-contained     # 所有 import 都在包内解析
+pnpm run verify:artifacts          # 打包产物带齐技能、CLI 与 patch
+pnpm run check:readmes             # 五语 README 一致性
+pnpm pack
+```
+
+扫描器自带合成的 `fixtures/bad-repo` 与 `fixtures/good-repo`，外加一个针对已适配仓库的 live negative —— 目录回归会让测试套件失败，而不是让下游用户踩坑。
+
+## 主题标签
+
+`dsh`、`dsh-plugin`、`deepseek-harness`、`deepseek`、`cordis`、`plugin-upgrade`、`migration`、`skill`、`version-card`、`scanner`（与 `package.json` 的 keywords 一致；`dsh-plugin` 是生态的曝光通道）。
+
+## PerryLink DSH 插件家族
+
+属于 PerryLink DSH 插件家族 —— 40 个仓库，覆盖会话、记忆、权限、交付、可观测性与开发者工具。目录见 [perrylink-dsh-catalog.perrylink.workers.dev](https://perrylink-dsh-catalog.perrylink.workers.dev) 或 [`dsh-plugin` 主题](https://github.com/topics/dsh-plugin)。
+
+## 许可证
+
+Apache-2.0 —— 见 [LICENSE](LICENSE)。安装期依赖及其许可证列在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)；本包不打包任何第三方代码。

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report privately through GitHub's [private vulnerability reporting](https://github.com/PerryLink/dsh-plugin-upgrade/security/advisories/new)
+(Security → Advisories → Report a vulnerability). Please do not open a public issue for a
+suspected vulnerability.
+
+Include the version, the exact command or plugin config, the observed behavior and, when
+possible, a minimal reproduction. You can expect an acknowledgement within a few days.
+
+## Scope
+
+`dsh-plugin-upgrade` is a **read-only developer tool**:
+
+- The scanner reads files under `--repo` and never writes inside the scanned repository.
+  `--json` writes only to the path you pass.
+- It imports nothing beyond Node's standard library, opens no socket and spawns no process.
+- It reads no credentials, no environment tokens and no session data.
+- The bundled skill is a Markdown body plus a version card; it contributes no system-prompt
+  paragraph and registers no tool.
+
+In scope:
+
+- a crafted repository that makes the scanner write outside the requested paths, escape the
+  scanned root, or execute code;
+- a path-traversal or symlink escape in `--repo` / `--json` handling;
+- a plugin config that mounts the skill from outside the intended root, or that silently
+  registers a skill different from the packaged one;
+- a published artifact that differs from this repository's source.
+
+Out of scope:
+
+- findings in the DeepSeek Harness itself (report those upstream);
+- the *content* of the upgrade card being incomplete for a repository the maintainer has
+  never seen — that is a bug report, not a vulnerability;
+- anything that requires the attacker to already control the machine or the repository
+  being scanned.
+
+## Supported versions
+
+The latest published `0.1.x` line receives fixes. Prerelease versions of the harness are
+supported as declared in `package.json` peer ranges.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,21 @@
+# Third-party notices
+
+`dsh-plugin-upgrade` ships **no bundled third-party code**. The published tarball contains
+only this repository's source, the packaged skill and its version card.
+
+The dependencies below are declared as `peerDependencies` (the host provides them at
+runtime) and as `devDependencies` (used only to run the test suite in this repository). None
+of them is copied into the published artifact.
+
+| Package | Range | Role | License |
+|---|---|---|---|
+| `@deepseek-ai/cordis` | `^4.0.2` (peer) | Plugin runtime (Context, effect, inject) | Apache-2.0 |
+| `@deepseek-ai/dsh-skill` | `>=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0` (peer) | `skills` service and `SkillRegistry` used by the tests | Apache-2.0 |
+| `@deepseek-ai/schemastery` | `^3.18.2` (peer) | `Config` schema | Apache-2.0 |
+| `@deepseek-ai/dsh-skill` | `0.1.5-alpha.1` (dev) | Real-registry mount test | Apache-2.0 |
+
+The scanner (`lib/scan.mjs`) and the CLI import only Node.js built-ins (`node:fs`,
+`node:path`) and therefore add no transitive install-time dependency of their own.
+
+License texts for the peer packages are distributed by those packages. This repository's own
+code is Apache-2.0 — see [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+# dsh-plugin-upgrade bundle patch layer.
+#
+# A loader patch file is a top-level YAML array; each entry inserts (or removes)
+# composition rows. This bundle mounts one row and registers one bundled agent
+# skill (`plugin-upgrade-015`) through the `skills` service. It contributes no
+# system-prompt paragraph and no tool: the model sees the skill only when a task
+# needs it, and the CLI (`dsh-plugin-upgrade-scan`) stays an explicit developer
+# action. Every key below is a Config field (Schemastery schema); invalid values
+# fail the profile load loudly. See README.md "Configuration".
+- insert:
+    - id: dsh-plugin-upgrade
+      name: dsh-plugin-upgrade
+      config:
+        # Register the packaged skill. Default true.
+        enabled: true
+        # Skill name published to the model catalog. Default 'plugin-upgrade-015'.
+        skillName: plugin-upgrade-015
+        # Skill root inside the package; must contain <skillName>/SKILL.md.
+        # Default: the package's own ./skills directory.
+        # skillsRoot: /absolute/path/to/skills
+        # Mark the skill user-invocable in addition to model-invocable. Default true.
+        userInvocable: true

package/index.mjs

@@ -0,0 +1,105 @@
+// dsh-plugin-upgrade bundle entry point.
+//
+// Publishes the packaged 0.1.3-alpha.1 -> 0.1.5-alpha.1 plugin-upgrade skill as an
+// on-demand agent skill named `plugin-upgrade-015`. The skill body is this
+// package's `skills/plugin-upgrade-015/SKILL.md`; its relative references
+// (`./references/...`) and scripts (`./scripts/...`) resolve against the packaged
+// skills directory through the directory resourceBase, so the agent loads the
+// version card and the scanner only when a task needs them.
+//
+// The package imports nothing from the harness beyond the injected `skills`
+// service, so the cordis peer stays metadata-only.
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-plugin-upgrade'
+export const inject = ['skills']
+
+/** Package root, used as the resourceBase for relative skill references. */
+const packageRoot = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Plugin configuration (Schemastery). Every knob is a deployment choice and is
+ * documented in cordis.patch.yml; there are no hardcoded tunables.
+ */
+export const Config = Schema.object({
+  /** Register the packaged skill (default true). */
+  enabled: Schema.boolean().default(true),
+  /** Skill name published to the model catalog. Defaults to the packaged corridor name. */
+  skillName: Schema.string().default('plugin-upgrade-015'),
+  /** Skill root inside the package; must contain `<skillName>/SKILL.md`. */
+  skillsRoot: Schema.string().default(join(packageRoot, 'skills')),
+  /** Mark the skill user-invocable in addition to model-invocable (default true). */
+  userInvocable: Schema.boolean().default(true),
+})
+
+/**
+ * Strip the YAML frontmatter block from SKILL.md and return its routing fields
+ * and body. A missing block falls back to the full text as the body.
+ * @param text - raw SKILL.md content.
+ * @returns the parsed description/whenToUse (when present) and the instruction body.
+ */
+export function splitFrontmatter(text) {
+  if (!text.startsWith('---\n')) return { description: undefined, whenToUse: undefined, body: text }
+  const end = text.indexOf('\n---', 4)
+  if (end < 0) return { description: undefined, whenToUse: undefined, body: text }
+  const meta = text.slice(4, end)
+  const body = text.slice(end + 4).replace(/^\n+/, '')
+  const scalar = (key) => new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(meta)?.[1]?.trim()
+  return { description: scalar('description'), whenToUse: scalar('whenToUse'), body }
+}
+
+/**
+ * Read and validate the packaged skill bundle. Fails loud: a missing SKILL.md,
+ * an empty body, or a missing frontmatter `name` aborts the mount instead of
+ * registering an empty skill.
+ * @param skillsRoot - root directory holding `<skillName>/SKILL.md`.
+ * @param skillName - expected skill directory name.
+ * @returns the frontmatter name, routing fields, body, and the skill directory.
+ */
+export function readSkillBundle(skillsRoot, skillName) {
+  const skillPath = join(skillsRoot, skillName, 'SKILL.md')
+  let text
+  try {
+    text = readFileSync(skillPath, 'utf8')
+  } catch (error) {
+    throw new Error(`dsh-plugin-upgrade: cannot read skill bundle at ${skillPath}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  const { description, whenToUse, body } = splitFrontmatter(text)
+  if (body.trim() === '') throw new Error(`dsh-plugin-upgrade: skill body is empty at ${skillPath}`)
+  const frontmatterName = /^name:\s*(\S+)\s*$/m.exec(text.slice(0, text.indexOf('\n---', 4) + 1))?.[1]
+  if (frontmatterName === undefined) throw new Error(`dsh-plugin-upgrade: skill frontmatter is missing a name at ${skillPath}`)
+  return { frontmatterName, description, whenToUse, body, skillDir: join(skillsRoot, skillName) }
+}
+
+/**
+ * Register the packaged skill. Registration is an effect: the disposer returned
+ * by `ctx.skills.register()` removes the contribution on unload.
+ * @param ctx - Cordis context with the injected `skills` service.
+ * @param config - validated plugin configuration.
+ */
+export function apply(ctx, config = {}) {
+  const resolved = {
+    enabled: config.enabled ?? true,
+    skillName: config.skillName ?? 'plugin-upgrade-015',
+    skillsRoot: config.skillsRoot ?? join(packageRoot, 'skills'),
+    userInvocable: config.userInvocable ?? true,
+  }
+  if (!resolved.enabled) return
+  const { frontmatterName, description, whenToUse, body, skillDir } = readSkillBundle(resolved.skillsRoot, resolved.skillName)
+  ctx.effect(() =>
+    ctx.skills.register({
+      name: frontmatterName,
+      source: 'bundled',
+      description: description ?? 'DSH plugin upgrade · 0.1.3-alpha.1 -> 0.1.5-alpha.1: seam scanner and version card.',
+      ...whenToUse !== undefined ? { whenToUse } : {},
+      content: body,
+      // The base is the skill's own directory, so `./references/...` and
+      // `./scripts/...` in the body resolve inside the published tarball.
+      resourceBase: { kind: 'directory', path: skillDir },
+      invocation: { modelInvocable: true, userInvocable: resolved.userInvocable },
+    }),
+  )
+}

package/lib/scan.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * scan-0.1.5.mjs — zero-dependency detector for the DSH `0.1.3-alpha.1 → 0.1.5-alpha.1`
+ * plugin-adaptation seams.
+ *
+ * Why this exists: typecheck passing is NOT evidence of adaptation. Two classes of
+ * failure survive a green local gate — (a) seams the published type line hides
+ * because the repo compiles against stale types, and (b) seams whose tests are
+ * mocked against the old shape. This scanner reports `file:line` facts for ten
+ * seams measured against 40 real plugin repos during the 2026-09-09 wave, and
+ * treats the "tsconfig silently resolves to the wrong types" case (M1) as a
+ * first-class defect, not a warning.
+ *
+ * Usage:
+ *   node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]
+ *
+ * Exit codes: 0 = no error-severity hit, 1 = at least one error-severity hit,
+ *             2 = usage/scan failure.
+ *
+ * Provenance: evidence for every seam lives in the 2026-09-09 batch report
+ * (40 plugin repos) and the per-repo cards produced by that wave. The scanner
+ * ships in this package so a plugin author can re-measure their own repo; it
+ * imports nothing outside Node's standard library.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const SKIP_DIRS = new Set(['node_modules', 'lib', 'dist', '.git', '.tmp', 'coverage', '_scratch', '_archive', 'downloads', 'upstream', 'dev'])
+const SCAN_EXT = /\.(ts|tsx|mts|cts|mjs|cjs|js|jsx|json|yml|yaml)$/
+
+/** @typedef {{ id: string, title: string, severity: 'error'|'warn'|'info', action: string, test: RegExp }} Seam */
+
+/** @type {Seam[]} */
+export const SEAMS = [
+  {
+    id: 'S3',
+    title: 'assistant/message 缺 stream（V3 必填）',
+    severity: 'error',
+    action: '写入会话日志的 assistant/message 必须带 `stream: []`（或真实分片）；缺了导入成功但会话不可续聊（Session.fromRestore 抛 invalid settlement fields）。',
+    test: /assistant\/message/,
+    // Only object construction / append calls, never comparisons or prose.
+    lineFilter: line => /type\s*:\s*['"]assistant\/message['"]|append\(\s*['"]assistant\/message['"]|['"]assistant\/message['"]\s*,/.test(line),
+    // Only production code that actually writes session logs, and only when the file
+    // never mentions `stream` (comments excluded).
+    fileCheck: (text, file) => !/(^|[\\/])(tests?|__tests__)[\\/]/.test(file) &&
+      /(\.append\(|writeFileSync|writeFile\(|writeSync|persist)/.test(text) &&
+      /assistant\/message/.test(text) && !/\bstream\b/.test(stripComments(text)),
+  },
+  {
+    id: 'S8',
+    title: 'SessionHandle.read() 返回形状（{eventState,events}）',
+    severity: 'error',
+    action: 'handle.read() 现在返回 SessionHandleReadResult；数组操作要改成 `(await handle.read()).events`。',
+    test: /\.read\s*\([^)]*\)\s*\.\s*(filter|find|findLast|map|some|every|forEach|slice|length)\b|await\s+[\w.$]+\s*\.\s*read\s*\(/,
+    // Only session-persistence handles are in scope (Web Streams readers also expose read()).
+    fileCheck: text => /sessionPersistence|SessionHandle|session-persistence|handle\.read\b/.test(text),
+    // A file that unwraps `.events` (property, destructuring, or a shared normalizer) is adapted.
+    fileCheck2: text => {
+      const awaitsRead = /await\s+[\w.$]+\s*\.\s*read\s*\(/.test(text)
+      if (!awaitsRead) return true
+      return !(/\.events\b/.test(text) || /\{[^}]*\bevents\b[^}]*\}\s*=\s*await/.test(text) || /normalizeReadResult/.test(text))
+    },
+  },
+  {
+    id: 'S9',
+    title: 'SystemPrompt Config.persona 已改名',
+    severity: 'error',
+    action: '`persona` 改为 `personaPrefix` / `personaSuffix`（`includeHarnessIdentity: false` 不等价，会删 harness identity 段）。',
+    test: /\{\s*persona\s*:|\bpersona\s*:\s*['"`]/,
+    // `persona:` is only the SystemPrompt seam when the call site is a SystemPrompt mount.
+    windowFilter: (lines, i) => lines.slice(Math.max(0, i - 3), i + 1).join('\n').includes('SystemPrompt'),
+  },
+  {
+    id: 'M1',
+    title: 'tsconfig 的 checkout 路径解析失败 → typecheck 静默回退',
+    severity: 'error',
+    action: 'tsconfig `paths` 指向不存在的目录时 TypeScript 会静默回退到 node_modules 的已发布类型，本地门禁变成假绿。路径应为 `../../../../deepseek-harness/packages/...`（相对仓库根）。',
+    test: /__tsconfig_paths_probe__/,
+  },
+  {
+    id: 'S4',
+    title: 'tool/code-dispatch 已改名 tool/ptc-dispatch',
+    severity: 'error',
+    action: '事件名改为 `tool/ptc-dispatch`；旧标签在 V3 会话里不再被识别（保留双标签需归一化器）。',
+    test: /tool\/code-dispatch/,
+    // A file that also names `tool/ptc-dispatch` is handling the legacy alias on purpose.
+    downgradeIf: text => /tool\/ptc-dispatch/.test(text),
+  },
+  {
+    id: 'S5',
+    title: 'ctx.agent 已移除',
+    severity: 'error',
+    action: '调用方必须显式传 Agent（如 `setup(agentCtx, agent)` 的第 2 参），不要读 `ctx.agent`。',
+    test: /ctx\.agent\b|ctx\['agent'\]|ctx\.get\(\s*['"]agent['"]\s*\)/,
+    // Deliberate back-compat fallbacks are legitimate while the old peer band is supported.
+    downgradeIf: text => /legacy|0\.1\.4|backward|back-compat|compat/i.test(text),
+  },
+  {
+    id: 'S6',
+    title: 'Inbox 已改为类型接口',
+    severity: 'error',
+    action: '`Inbox` 不再可构造；夹具改用官方 unsupportedInbox() 形状，运行时用 `agent.inbox`。',
+    test: /\bnew\s+Inbox\s*\(|import\s*\{[^}]*\bInbox\b[^}]*\}\s*from\s*['"]@deepseek-ai\/dsh-agent['"]/,
+    // A harness pinned to a pre-0.1.5 ruler may still construct Inbox on purpose.
+    downgradeIf: text => /0\.1\.3|0\.1\.2|pinned|legacy/i.test(text),
+  },
+  {
+    id: 'S7',
+    title: 'SubprocessHandle.pid 已移除',
+    severity: 'warn',
+    action: 'handle 不再有 `pid`（只剩 SubprocessTerminalHandle.pid）；测试夹具删掉该字段。',
+    test: /\bpid\s*:\s*\d+|\.pid\b/,
+    // Node ChildProcess.pid and plugin-owned process info also match: keep this advisory.
+    downgradeIf: () => true,
+  },
+  {
+    id: 'S2',
+    title: 'EpochHeader.system 已移除（系统提示词进消息历史）',
+    severity: 'warn',
+    action: '系统提示词现在是 surface node 0 的 `system/message`；`request/header.system` 只在旧线存在，读取方需要结构式回退。',
+    test: /header\.system\b|EpochHeader/,
+  },
+  {
+    id: 'S1',
+    title: '会话格式 V3 / 日志文件名世代化',
+    severity: 'warn',
+    action: '当前世代是 `session.v3.jsonl.zstd`；硬编码 `session.jsonl.zstd` 的读写脚本会静默失效（建议从新到旧枚举 vN）。',
+    test: /SESSION_FORMAT_VERSION|session\.jsonl(?!\.v\d)/,
+  },
+  {
+    id: 'S10',
+    title: '插件自建会话事件必须走自适应门',
+    severity: 'warn',
+    action: '宿主事件词表 fail-closed 且 `Session.append` 无 `ignorable` 写入通道；无条件 append 会让会话不可读，请保留"探测后降级"的写法。',
+    test: /SessionEventMap|\.append\(/,
+  },
+]
+
+function* walk(dir, depth = 0) {
+  if (depth > 8) return
+  let ents
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of ents) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue
+      yield* walk(path.join(dir, e.name), depth + 1)
+    } else if (SCAN_EXT.test(e.name)) {
+      yield path.join(dir, e.name)
+    }
+  }
+}
+
+/** Strip comment-only lines so prose never satisfies a code-level check. */
+function stripComments(text) {
+  return text.split(/\r?\n/).filter(l => !/^\s*(?:\/\/|\/\*|\*|#)/.test(l)).join('\n')
+}
+
+/** M1: resolve every `paths` entry; a missing target means silent fallback. */
+function checkTsconfigPaths(repoDir, imports) {
+  const hits = []
+  const files = fs.readdirSync(repoDir).filter(f => /^tsconfig.*\.json$/.test(f))
+  for (const f of files) {
+    const full = path.join(repoDir, f)
+    let json
+    try { json = JSON.parse(fs.readFileSync(full, 'utf8')) } catch { continue }
+    const opts = json.compilerOptions || {}
+    const paths = opts.paths
+    if (!paths || typeof paths !== 'object') continue
+    const base = path.resolve(repoDir, opts.baseUrl || '.')
+    for (const [alias, targets] of Object.entries(paths)) {
+      if (!Array.isArray(targets)) continue
+      for (const t of targets) {
+        if (typeof t !== 'string') continue
+        // Only checkout-style aliases are in scope: they must point at the harness tree.
+        const looksCheckout = /(?:^|\/)(?:packages|vendor)\//.test(t) || t.includes('deepseek-harness')
+        if (!looksCheckout) continue
+        // An alias the repo never imports cannot cause a false green: skip it.
+        const aliasBase = alias.replace(/\/\*$/, '')
+        if (imports && imports.size && !imports.has(aliasBase)) continue
+        // Wildcard aliases (`.../lib/types/*`) are checked at their static prefix.
+        const probe = t.includes('*') ? t.slice(0, t.indexOf('*')) : t
+        const resolved = path.resolve(base, probe)
+        if (!fs.existsSync(resolved)) {
+          hits.push({
+            seam: 'M1', severity: 'error', file: path.join(repoDir, f), line: 1,
+            snippet: `"${alias}": ["${t}"]`,
+            detail: `resolves to ${resolved} which does not exist → TypeScript silently falls back to node_modules (green gate is fake)`,
+          })
+        }
+      }
+    }
+  }
+  return hits
+}
+
+/**
+ * Scan one repo.
+ * @param {string} repoDir
+ * @param {{ seams?: string[] }} [options]
+ * @returns {{ repo: string, scannedAt: string, files: number, hits: any[], bySeam: Record<string, number> }}
+ */
+export function scanRepo(repoDir, options = {}) {
+  const wanted = options.seams && options.seams.length ? new Set(options.seams) : null
+  const hits = []
+  const imports = new Set()
+  let files = 0
+  for (const file of walk(repoDir)) {
+    files++
+    let text
+    try { text = fs.readFileSync(file, 'utf8') } catch { continue }
+    for (const m of text.matchAll(/(?:from|require\()\s*['"](@deepseek-ai\/[^'"]+)['"]/g)) imports.add(m[1])
+    const lines = text.split(/\r?\n/)
+    for (const seam of SEAMS) {
+      if (wanted && !wanted.has(seam.id)) continue
+      if (seam.id === 'M1') continue // handled separately (structured, not regex)
+      if (seam.fileCheck && !seam.fileCheck(text, file)) continue
+      if (seam.fileCheck2 && !seam.fileCheck2(text, file)) continue
+      for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim()
+        // Comment-only lines carry prose, not code: never a seam hit.
+        if (/^(?:\/\/|\/\*|\*|#)/.test(trimmed)) continue
+        if (!seam.test.test(lines[i])) continue
+        if (seam.lineFilter && !seam.lineFilter(lines[i])) continue
+        if (seam.windowFilter && !seam.windowFilter(lines, i)) continue
+        // S7 is noisy: only report when the file is about subprocess handles.
+        if (seam.id === 'S7' && !/Subprocess|subprocess/.test(text)) continue
+        // S6 only for value imports / constructor calls, never type-only.
+        if (seam.id === 'S6' && /import\s+type\s*\{/.test(lines[i])) continue
+        // S9 only in a SystemPrompt-ish context or a test harness.
+        if (seam.id === 'S9' && !/SystemPrompt|system-prompt|systemPrompt/.test(text)) continue
+        const downgraded = seam.downgradeIf ? seam.downgradeIf(text) : false
+        hits.push({
+          seam: seam.id, severity: downgraded ? 'warn' : seam.severity, file, line: i + 1,
+          snippet: lines[i].trim().slice(0, 200),
+          detail: downgraded ? `${seam.title} (legacy alias handling — verify it is intentional)` : seam.title,
+        })
+      }
+    }
+  }
+  if (!wanted || wanted.has('M1')) hits.push(...checkTsconfigPaths(repoDir, imports))
+  const bySeam = {}
+  for (const h of hits) bySeam[h.seam] = (bySeam[h.seam] || 0) + 1
+  return { repo: repoDir, scannedAt: new Date().toISOString(), files, hits, bySeam }
+}
+
+/** Human-readable rendering. */
+export function render(report) {
+  const L = []
+  L.push(`# scan-0.1.5 · ${report.repo}`)
+  L.push(`files scanned: ${report.files} · hits: ${report.hits.length}`)
+  if (!report.hits.length) { L.push('no seam hits — still verify with real-host smoke (this scanner is necessary, not sufficient)'); return L.join('\n') }
+  const order = ['S3', 'S8', 'S9', 'M1', 'S4', 'S5', 'S6', 'S7', 'S2', 'S1', 'S10']
+  for (const id of order) {
+    const group = report.hits.filter(h => h.seam === id)
+    if (!group.length) continue
+    const seam = SEAMS.find(s => s.id === id)
+    L.push('')
+    L.push(`## ${id} [${seam.severity}] ${seam.title} — ${group.length} hit(s)`)
+    L.push(`   action: ${seam.action}`)
+    for (const h of group.slice(0, 12)) L.push(`   ${path.relative(process.cwd(), h.file)}:${h.line}  ${h.snippet}`)
+    if (group.length > 12) L.push(`   ... ${group.length - 12} more`)
+  }
+  return L.join('\n')
+}
+
+export function main(argv) {
+  const args = { repo: process.cwd(), json: null, seams: null, quiet: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--repo') args.repo = argv[++i]
+    else if (a === '--json') args.json = argv[++i]
+    else if (a === '--seams') args.seams = String(argv[++i]).split(',').map(s => s.trim()).filter(Boolean)
+    else if (a === '--quiet') args.quiet = true
+    else if (a === '--help' || a === '-h') { console.log('usage: node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]'); return 0 }
+    else { console.error(`unknown argument: ${a}`); return 2 }
+  }
+  const repoDir = path.resolve(args.repo)
+  if (!fs.existsSync(repoDir)) { console.error(`repo not found: ${repoDir}`); return 2 }
+  const report = scanRepo(repoDir, { seams: args.seams })
+  if (!args.quiet) console.log(render(report))
+  if (args.json) fs.writeFileSync(path.resolve(args.json), JSON.stringify(report, null, 1), 'utf8')
+  return report.hits.some(h => h.severity === 'error') ? 1 : 0
+}
+
+if (process.argv[1]?.endsWith('scan.mjs') || process.argv[1]?.endsWith('scan-0.1.5.mjs')) {
+  process.exit(main(process.argv.slice(2)))
+}