@nanmicoder/dsh-agent-teams 0.1.15-alpha.1 → 0.1.16-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanmicoder/dsh-agent-teams",
-  "version": "0.1.15-alpha.1",
+  "version": "0.1.16-rc.1",
   "description": "AgentTeams for DeepSeek Harness: multi-agent team collaboration (captain, members, tasks with dependencies, messaging) driven by natural language, with a tree monitor in the web GUI",
   "type": "module",
   "main": "lib/index.js",
@@ -25,7 +25,10 @@
     "cordis.patch.yml",
     "release-notes",
     "README.md",
-    "README_ZH.md"
+    "README_ZH.md",
+    "compatibility.json",
+    "scripts/doctor.mjs",
+    "scripts/compatibility.mjs"
   ],
   "license": "MIT",
   "author": {
@@ -56,7 +59,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "alpha",
+    "tag": "next",
     "registry": "https://registry.npmjs.org/"
   },
   "dsh": {
@@ -76,39 +79,29 @@
       "platform": "web"
     }
   },
-  "scripts": {
-    "build": "node scripts/clean-build.mjs && tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "sync:skill": "node scripts/sync-skill.mjs",
-    "verify:skill": "node scripts/sync-skill.mjs --check",
-    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/quality-gates-tdd.mjs && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && pnpm verify:web-routes && pnpm verify:release && pnpm verify:skill",
-    "prepublishOnly": "pnpm build && pnpm verify",
-    "verify:web-routes": "node scripts/web-routes-verify.mjs",
-    "verify:release": "node --test scripts/release-metadata.test.mjs"
-  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-chat": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-model-selection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-connection": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-chat": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-model-selection": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-commands": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.2-rc.1 || 0.1.2-alpha.5 || 0.1.2-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0"
   },
@@ -188,29 +181,30 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-api-session-controller": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-connection": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-store": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-chat": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-layout": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-model-selection": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-session": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-commands": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-workspace": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-connection": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-model-selection": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-util-values": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-workspace": "0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "@types/node": "^24.13.3",
     "@types/react": "~18.3.1",
@@ -220,5 +214,21 @@
     "react-dom": "^18.2.0",
     "tsdown": "0.22.2",
     "typescript": "^5.9.3"
+  },
+  "bin": {
+    "dsh-agent-teams-doctor": "scripts/doctor.mjs"
+  },
+  "scripts": {
+    "build": "node scripts/clean-build.mjs && tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "sync:skill": "node scripts/sync-skill.mjs",
+    "verify:skill": "node scripts/sync-skill.mjs --check",
+    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/member-failure-tdd.mjs && node scripts/quality-gates-tdd.mjs && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && pnpm verify:web-routes && pnpm verify:release && pnpm verify:skill && pnpm verify:harness-contract && pnpm verify:http-body && pnpm verify:compatibility",
+    "verify:web-routes": "node scripts/web-routes-verify.mjs",
+    "verify:release": "node --test scripts/release-metadata.test.mjs",
+    "verify:harness-contract": "node scripts/harness-compat-tdd.mjs && node scripts/lifecycle-verify.mjs --modern-harness && node scripts/member-failure-tdd.mjs --modern-harness",
+    "verify:compatibility": "node scripts/compatibility.mjs && node --test scripts/compatibility.test.mjs && node scripts/doctor.mjs",
+    "verify:http-body": "node --test scripts/http-body.test.mjs",
+    "doctor": "node scripts/doctor.mjs"
   }
-}
+}

package/release-notes/v0.1.11.md

@@ -7,7 +7,7 @@ This release restores AgentTeams activity and member history after a DeepSeek Ha
 - **Cold-start activity recovery**: selecting a captain session now performs a lightweight live and archived team discovery pass, so older sessions without an AgentTeams conversation card restore their activity panel after restart.
 - **Reliable member activity**: live `running / idle / ready` state is resolved from the durable team roster and Agent registry instead of depending on the versioned `listChildren()` projection shape.
 - **Persistent member history**: retired AgentTeams members remain discoverable in the Harness subagent catalog for transcript review while direct follow-up remains blocked.
-- **rc.8 transcript navigation**: activity-panel and conversation-card member links refresh the parent catalog and use addressed `openSubagent()` navigation, with a fallback for older Harness runtimes.
+- **rc.8 transcript navigation**: activity-panel and conversation-card member links refresh the parent catalog and use `openSubagent()` navigation with parent-child addressing, with a fallback for older Harness runtimes.
 
 ## Verification
 

package/release-notes/v0.1.15.md

@@ -0,0 +1,57 @@
+# AgentTeams v0.1.15
+
+**The default install now supports DeepSeek Harness 0.1.2-alpha.2.**
+This release publishes to npm **latest** and is the latest GitHub release.
+It replaces the opt-in-only release policy of 0.1.15-alpha.1, with no plugin
+runtime changes.
+
+## Install / upgrade
+
+Use the current supported Harness developer preview and the latest plugin:
+
+```sh
+npm install --global @deepseek-ai/dsh@0.1.2-alpha.2
+dsh --version
+dsh plugin --profile web add @nanmicoder/dsh-agent-teams@latest
+```
+
+Use `@0.1.15` instead of `@latest` to pin this release. Restart Harness and
+refresh the browser after updating. The host's Alpha.2 version does not
+require a separate Alpha plugin channel.
+
+## Older hosts
+
+If Harness must stay on **0.1.0-rc.8**, install the historical plugin explicitly:
+
+```sh
+dsh plugin --profile web add @nanmicoder/dsh-agent-teams@0.1.14
+```
+
+Other older hosts should likewise pin their known-working plugin version;
+they must not follow `@latest`. There is no dual-version adapter. Updating
+the plugin does not update the running host, including a source-built host.
+See the README for source-build and rollback instructions.
+
+## Included fixes and validation
+
+- Alpha.2 Web client activation using current conversation, session and store APIs.
+- Host authentication and Host/Origin checks on raw state, plan, halt and artwork routes.
+- The same runtime previously exercised with real DeepSeek API calls, three-member
+  order-settlement delivery, and human UI review in `/tmp`.
+- Rebuild, full automated verification and runtime-payload comparison for this
+  release. This publication-policy change does not claim a second full business run.
+
+See the [real API / UI acceptance record](https://github.com/NanmiCoder/dsh-agent-teams/blob/v0.1.15/docs/alpha2-release-acceptance.md)
+for the recovered model mistakes, screenshots methodology and environment limits.
+
+## 中文说明
+
+**默认最新插件 0.1.15 适配 Harness 0.1.2-alpha.2，发布到 `latest`。**
+Harness 本身处于开发者预览阶段，插件默认发行跟进当前已适配的新宿主；
+不再因为宿主带 Alpha 名称，就把适配放到必须主动选择的插件 Alpha 渠道。
+
+新宿主使用插件 `@latest`（当前为 0.1.15）；旧宿主应安装明确兼容的固定版本，
+例如 Harness 0.1.0-rc.8 使用插件 `@0.1.14`。没有更新 Harness 源码或安装版本的用户，
+不要只把插件更新到 latest。中英文 README 已给出完整操作方法。
+
+本次调整版本、发行渠道和文档，运行时代码与此前真实业务 / UI 验收的 Alpha.2 适配一致。

package/release-notes/v0.1.16-rc.1.md

@@ -0,0 +1,33 @@
+# AgentTeams v0.1.16-rc.1 — release candidate
+
+This candidate restores team execution across the exact Harness targets `0.1.2-rc.1`, `0.1.2-alpha.5`, and `0.1.2-alpha.2`. Its release channel is npm `next`; install the exact plugin version with `dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.16-rc.1` after checking that the running host is one of those targets. This is a prerelease, and older Desktop cores require their own compatible pair.
+
+## Compatibility and correctness
+
+- Centralize old and new host contracts: receiver-bound legacy setup, synchronous modern session setup, own session events, FIFO continuation, and retired-member delivery guards. Preserve model selection, reasoning effort, fallback, failure notification, and cleanup on both host generations.
+- Persist fallback settings when adding members manually; restore the active fallback route after a cold restart. Real-host testing exposed the missing persisted setting even when mocked tests passed.
+- Require the captain to use safe reassignment instead of claiming tasks on behalf of members. Preserve idempotent reads of an already active captain takeover.
+- Align the status tool and captain instructions around member notifications, removing the instruction to repeatedly poll for progress.
+- Bound both plan and halt JSON requests by bytes, reject malformed/non-object bodies, and keep the host Connection authentication gate.
+
+## Contributions
+
+The host adapter incorporates the migration analysis and reproduction cases from [Adol1111's #119](https://github.com/NanmiCoder/dsh-agent-teams/pull/119), [Zn-Dk's #124](https://github.com/NanmiCoder/dsh-agent-teams/pull/124), and [chenkai2's #130](https://github.com/NanmiCoder/dsh-agent-teams/pull/130). Their proposals were integrated at one compatibility boundary, with additional receiver, lifecycle, FIFO and failure coverage.
+
+Separately merged contributions retain their original authors and commits: [#26](https://github.com/NanmiCoder/dsh-agent-teams/pull/26), [#63](https://github.com/NanmiCoder/dsh-agent-teams/pull/63), [#74](https://github.com/NanmiCoder/dsh-agent-teams/pull/74), [#82](https://github.com/NanmiCoder/dsh-agent-teams/pull/82), [#83](https://github.com/NanmiCoder/dsh-agent-teams/pull/83), [#84](https://github.com/NanmiCoder/dsh-agent-teams/pull/84), [#86](https://github.com/NanmiCoder/dsh-agent-teams/pull/86), [#90](https://github.com/NanmiCoder/dsh-agent-teams/pull/90), and [#93](https://github.com/NanmiCoder/dsh-agent-teams/pull/93). These cover argument validation, wording, parked-attempt recovery, panel resizing, working indicators, model badges, Windows build paths, and client service declarations.
+
+## Maintenance and release policy
+
+- Use `compatibility.json` for exact support targets, development dependency validation and the CI matrix. Freeze the complete DSH development dependency cohort; an exact CLI version alone does not freeze its transitive packages.
+- Add a read-only installation doctor for version mixing, missing packages, duplicate runtime identities and profile/plugin mismatches.
+- Vendor the community upgrade, audit, benchmark, testing and release skills with a pinned source revision and license. Keep local rules separate from upstream guidance.
+- Require Ubuntu and Windows static checks plus real packaged-plugin execution on all three hosts before publication. Every host verifies the same tgz, and the publish job verifies its digest before publishing that artifact.
+- Use `next` for plugin prereleases. A stable `latest` requires the recommended host and complete matrix; Alpha-only validation is insufficient.
+
+## Verification scope
+
+The runtime runner installs actual npm host packages and the candidate artifact in isolated directories, then exercises the CLI, profile, plugin tools, member sessions, messages, reasoning, fallback, failure handling and cold restoration. The external model adapter supplies deterministic responses so the suite can run without credentials. It is not a real-provider benchmark or a claim about every Desktop/OS/version combination.
+
+Separate real DeepSeek API acceptance using `deepseek-v4-flash` passed on all three hosts from `/tmp`, plus a real-model rc.1 Web workflow. Ubuntu/Windows typecheck, build and full verify, and the three Ubuntu host cohorts passed in CI. These checks do not establish native Desktop compatibility or resolve the independent OOM investigation.
+
+See the repository's [maintenance workflow](../docs/maintenance-workflow.md) and the dated implementation/acceptance record for the exact outcomes and remaining limits. Older `0.1.0-*` and `0.1.1-*` hosts are outside this candidate's support matrix; retain a known compatible exact pair or migrate both sides.

package/scripts/compatibility.mjs

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+export const policy = JSON.parse(readFileSync(new URL('../compatibility.json', import.meta.url), 'utf8'))
+
+// Contract consumed by the published server entry and client module table.
+// Keeping this independent from package.json catches accidentally deleted peers.
+export const requiredHostPeers = [
+  '@deepseek-ai/cordis', '@deepseek-ai/schemastery', 'react',
+  ...[
+    'agent', 'api-session-controller', 'client-connection', 'client-locale',
+    'client-store', 'client-ui-chat', 'client-ui-conversation', 'client-ui-layout',
+    'client-ui-model-selection', 'client-ui-primitives', 'client-ui-renderer',
+    'client-ui-session', 'client-ui-slots', 'commands', 'llm', 'session',
+    'session-projection', 'subagent', 'system-prompt', 'tools', 'util-values',
+  ].map(name => `@deepseek-ai/dsh-${name}`),
+]
+
+// These are value imports of the server entry, so optional-peer metadata does
+// not make an unresolved installation executable. Client services can instead
+// be supplied by the host's browser module table.
+export const serverRuntimePeers = [
+  '@deepseek-ai/schemastery', '@deepseek-ai/dsh-agent', '@deepseek-ai/dsh-llm',
+  '@deepseek-ai/dsh-session', '@deepseek-ai/dsh-subagent', '@deepseek-ai/dsh-tools',
+]
+
+export function validatePolicy(input) {
+  if (input.schemaVersion !== 1 || input.previewTag !== 'next') throw new Error('Unsupported compatibility policy')
+  const hosts = input.supportedHosts
+  if (!Array.isArray(hosts) || hosts.length === 0) throw new Error('supportedHosts must list exact tested host targets')
+  const versions = new Set()
+  for (const host of hosts) {
+    if (typeof host.version !== 'string' || !/^\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?$/.test(host.version)
+        || host.version.trim() !== host.version || versions.has(host.version)
+        || !['recommended', 'preview', 'legacy'].includes(host.track)) {
+      throw new Error('Host targets must be unique exact versions with an explicit track')
+    }
+    versions.add(host.version)
+  }
+  const recommended = hosts.filter(host => host.track === 'recommended')
+  if (recommended.length !== 1 || recommended[0].version !== input.recommendedHost) throw new Error('Exactly one recommended host is required')
+  if (/-(alpha|beta)\./.test(input.recommendedHost)) throw new Error('Alpha/beta hosts cannot be the ordinary-user recommendation')
+  return hosts.map(host => host.version)
+}
+
+export function validatePackageCompatibility(pkg, input = policy) {
+  const versions = validatePolicy(input)
+  for (const name of requiredHostPeers) {
+    if (typeof pkg.peerDependencies?.[name] !== 'string' || pkg.peerDependencies[name].trim() === '') {
+      throw new Error(`Missing required host peer declaration: ${name}`)
+    }
+  }
+  const baseline = pkg.devDependencies?.['@deepseek-ai/dsh']
+  if (!versions.includes(baseline)) throw new Error('Development host must be an exact supported target')
+  for (const [name, version] of Object.entries(pkg.devDependencies ?? {})) {
+    if (name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-')) {
+      if (version !== baseline) throw new Error(`${name} must match the exact development host ${baseline}`)
+    }
+  }
+  const overrides = pkg.pnpm?.overrides ?? {}
+  const dshNames = Object.keys(pkg.devDependencies ?? {}).filter(name => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+  for (const name of dshNames) {
+    if (overrides[name] !== baseline) throw new Error(`${name} requires an exact pnpm override to ${baseline}`)
+  }
+  for (const [name, version] of Object.entries(overrides)) {
+    if (name.includes('@deepseek-ai/dsh')) {
+      if (!/^@deepseek-ai\/dsh(?:-[a-z0-9-]+)?$/.test(name)) {
+        throw new Error(`${name} override must use a bare DSH package name, without ranges or parent selectors`)
+      }
+      if (version !== baseline) throw new Error(`${name} override must match the development host ${baseline}`)
+    }
+  }
+  for (const [name, range] of Object.entries(pkg.peerDependencies ?? {})) {
+    if (name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-')) {
+      const declared = range.split('||').map(value => value.trim())
+      if (declared.length !== versions.length || versions.some(version => !declared.includes(version))) {
+        throw new Error(`${name} peer range must enumerate the supported host targets`)
+      }
+    }
+  }
+  return versions
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  const hosts = validatePackageCompatibility(pkg)
+  if (process.argv[2] === '--github-output') console.log(`hosts=${JSON.stringify(hosts)}`)
+  else if (process.argv.length === 2) console.log(`Compatibility targets: ${hosts.join(', ')}`)
+  else throw new Error('Usage: node scripts/compatibility.mjs [--github-output]')
+}

package/scripts/doctor.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { policy, serverRuntimePeers, validatePolicy } from './compatibility.mjs'
+
+function manifest(path) {
+  return JSON.parse(readFileSync(path, 'utf8'))
+}
+
+function locatePackage(name, from) {
+  let directory = resolve(from)
+  for (;;) {
+    const candidate = join(directory, 'node_modules', name, 'package.json')
+    if (existsSync(candidate)) return realpathSync(candidate)
+    const parent = dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/** Inspect manifests only; never execute packages or read credentials/configuration. */
+export function inspectInstallation(hostRoot, profileRoot) {
+  const allowed = validatePolicy(policy)
+  const root = resolve(hostRoot)
+  const own = join(root, 'package.json')
+  const hostPath = existsSync(own) && manifest(own).name === '@deepseek-ai/dsh'
+    ? realpathSync(own) : locatePackage('@deepseek-ai/dsh', root)
+  if (!hostPath) throw new Error('Cannot locate @deepseek-ai/dsh; pass --host-root for the actual CLI or embedded Desktop package directory')
+  const host = manifest(hostPath)
+  const visited = new Set()
+  const packages = []
+  const sharedRuntimes = []
+  const missing = []
+  function walk(path) {
+    path = realpathSync(path)
+    if (visited.has(path)) return
+    visited.add(path)
+    const pkg = manifest(path)
+    if (pkg.name === '@deepseek-ai/dsh' || pkg.name?.startsWith('@deepseek-ai/dsh-')) {
+      packages.push({ name: pkg.name, version: pkg.version, path: dirname(path) })
+    }
+    if (pkg.name === '@deepseek-ai/cordis') sharedRuntimes.push({ name: pkg.name, path: dirname(path) })
+    for (const name of Object.keys({ ...pkg.dependencies, ...pkg.optionalDependencies, ...pkg.peerDependencies })) {
+      const dependency = locatePackage(name, dirname(path))
+      if (dependency) walk(dependency)
+      else if ((name.startsWith('@deepseek-ai/dsh-') || name === '@deepseek-ai/cordis') && !(name in (pkg.optionalDependencies ?? {}))
+          && pkg.peerDependenciesMeta?.[name]?.optional !== true) missing.push(name)
+    }
+  }
+  walk(hostPath)
+  let plugin
+  if (profileRoot) {
+    const path = locatePackage('@nanmicoder/dsh-agent-teams', resolve(profileRoot))
+    if (!path) missing.push('@nanmicoder/dsh-agent-teams (profile)')
+    else {
+      const pkg = manifest(path)
+      plugin = { version: pkg.version, path: dirname(path) }
+      // Follow normal transitive requirements and optional resolved peers, then
+      // check the server's actual value imports even when marked optional.
+      walk(path)
+      for (const name of serverRuntimePeers) {
+        const dependency = locatePackage(name, dirname(path))
+        if (dependency) walk(dependency)
+        else missing.push(`${name} (plugin runtime)`)
+      }
+    }
+  }
+  const mixed = packages.filter(pkg => pkg.version !== host.version)
+  const problems = []
+  const policyPackage = manifest(new URL('../package.json', import.meta.url))
+  if (plugin && plugin.version !== policyPackage.version) {
+    problems.push(`Installed plugin ${plugin.version} differs from this policy's plugin ${policyPackage.version}; verify its own host compatibility`)
+  }
+  if (!allowed.includes(host.version)) problems.push(`Unsupported host ${host.version}; recommended target is ${policy.recommendedHost}`)
+  if (mixed.length) problems.push(`${mixed.length} resolved DSH packages differ from host ${host.version}`)
+  if (missing.length) problems.push(`Missing packages: ${[...new Set(missing)].join(', ')}`)
+  const identities = new Map()
+  for (const pkg of [...packages, ...sharedRuntimes]) {
+    const paths = identities.get(pkg.name) ?? new Set()
+    paths.add(pkg.path)
+    identities.set(pkg.name, paths)
+  }
+  const duplicates = [...identities].filter(([, paths]) => paths.size > 1).map(([name]) => name)
+  if (duplicates.length) problems.push(`Multiple resolved identities: ${duplicates.join(', ')}`)
+  return {
+    ok: problems.length === 0,
+    host: { version: host.version, path: dirname(hostPath) },
+    ...(plugin ? { plugin } : {}),
+    checkedPackages: packages.length, supportedHosts: allowed,
+    problems, packages,
+    limits: ['Checks files resolved from the supplied roots; does not identify the running process or prove plugin behavior.'],
+  }
+}
+
+// npm bin entries and macOS temporary directories may reach this module via
+// symlinks; Node canonicalizes import.meta.url but preserves argv[1].
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    let hostRoot = process.cwd()
+    let profileRoot
+    let json = false
+    for (let index = 2; index < process.argv.length; index++) {
+      const arg = process.argv[index]
+      if (arg === '--json') json = true
+      else if (arg === '--host-root' || arg === '--profile-root') {
+        const value = process.argv[++index]
+        if (!value || value.startsWith('--')) throw new Error(`${arg} requires a directory`)
+        if (arg === '--host-root') hostRoot = value
+        else profileRoot = value
+      } else throw new Error('Usage: dsh-agent-teams-doctor [--host-root dir] [--profile-root dir] [--json]')
+    }
+    const result = inspectInstallation(hostRoot, profileRoot)
+    console.log(json ? JSON.stringify(result, null, 2) : [
+      `Harness: ${result.host.version} (${result.host.path})`,
+      `DSH package identities checked: ${result.checkedPackages}`,
+      ...result.problems.map(problem => `FAIL: ${problem}`),
+      result.ok ? 'Dependency inspection passed.' : 'Use one supported host version and a matching locked profile.',
+      ...result.limits,
+    ].join('\n'))
+    if (!result.ok) process.exitCode = 1
+  } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}