@ran-sh/dsh-crew 0.3.0 → 0.3.1

package/README.md

@@ -5,356 +5,136 @@
 <h1 align="center">DSH Crew</h1>
 
 <p align="center">
-  <strong>Use Codex Desktop or Claude Code as the orchestrator, and dispatch coding work to DeepSeek Harness workers (with an independent reviewer role) over configurable Worker Model Policies.</strong>
+  <strong>Use Codex Desktop or Claude Code as the orchestrator, and dispatch coding work to isolated DeepSeek Harness workers and reviewers.</strong>
 </p>
 
 <p align="center">
   <a href="./README.md"><b>English</b></a> · <a href="./README.zh.md">简体中文</a>
 </p>
 
-## Features
+## What it does
 
-- Codex Desktop / Claude Code as the main orchestrator
-- **Roles**: worker (implementation / fixes / tests / search) and reviewer (independent review + verdict)
-- **Model Policy**: each role resolves its own ordered provider/model candidates (preferred → priority → escalation → Harness Default)
-- Legacy Flash Only · Pro Only · Balanced · Review Pipeline modes migrate onto the role model automatically
-- Follow DSH Provider
-- First-class DSH Hub sessions (visible in the Web UI, async jobs with progress)
-- Optional Vision / Image Generation (independently switchable)
+DSH Crew adds a small orchestration layer between your coding host and DeepSeek Harness:
 
-## How it works
+- **worker** — implements, fixes, tests, searches, and analyzes;
+- **reviewer** — independently reviews the worker result and returns a verdict;
+- **model policy** — resolves provider/model priorities per role and can escalate on evidence;
+- **isolated execution** — coding workers run in temporary git worktrees by default;
+- **live jobs** — Hub sessions expose progress, results, cancellation, routing trace, and readiness data.
 
-```
+```text
 Codex Desktop / Claude Code
-          │
-          ▼
-       dsh-crew
-          │
-     Workflow (run + spawn share one state machine)
-          │
-     ┌────┴────┐
-     │         │
-   worker    reviewer
-     │         │
-  Model Policy  │  (each role resolves its own provider/model candidates;
-  cheap→strong  │   escalation steps on evidence: FAIL tests, missing
-     │          │   delivery, blocked tasks)
-     └────┬────┘
-          │
-          ▼
-   DeepSeek Harness
-          │
-          ▼
-   DSH selected provider/model
+            │
+            ▼
+         DSH Crew
+       ┌────┴────┐
+       │         │
+    worker    reviewer
+       │         │
+       └────┬────┘
+            ▼
+     DeepSeek Harness
 ```
 
-The orchestrator picks **what** to do and decides accept / reject / revise.
-The workflow decides **when / state**. **Roles** decide **who** (worker executes,
-reviewer reviews). **Model Policy** decides **which model** (never fixed to a
-role). Workspace isolation decides **where** (each coding worker runs in its
-own temporary git worktree, so parallel workers never write the same working
-tree). Verification / reviewer decide **whether to accept**.
-
 ## Install
 
-Prerequisites: Node.js with npm/npx, Git, and pnpm. The source setup installer is
-the safe cross-platform path because it controls the Crew DSH home and profile.
-
-> **Official Harness isolation** — dsh-crew installs into its own dedicated DSH
-> home (`~/.config/dsh-crew/harness`) and profile (`dsh-crew`), never into the
-> official DSH home (`~/.dsh`) or the official `web` profile. Your normal
-> DeepSeek Harness installation is never modified.
+Prerequisites: **Node.js**, **Git**, and **pnpm**.
 
-From a clone of this repository, cross-platform:
+Recommended source setup:
 
 ```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
 node scripts/setup.mjs install
 ```
 
-or on Windows:
+Windows can use:
 
 ```bat
 install.cmd
 ```
 
-Then open **Settings → DSH Crew** and click **Install** for Codex. Claude Code
-integration is optional and has its own Install button.
+DSH Crew uses its own Harness home and profile:
 
-The installer links this local checkout as `@ran-sh/dsh-crew` in the dedicated
-`dsh-crew` profile, points the Crew Hub at its own port, and does not touch the
-official DSH web profile or any official credential store. Crew is not published
-to the npm registry.
-
-### Update
-
-Re-run the source installer after pulling:
-
-```bash
-git pull
-node scripts/setup.mjs install
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
 ```
 
-Restart DSH after updating.
-
-### Migrating an older fork install
-
-Legacy releases installed Crew into the official DSH `web` profile. Those
-installs are outside the supported path. Uninstall any legacy Crew (see
-Uninstall), then run the source installer above, which installs into the
-dedicated Crew home/profile.
+Supported Crew tooling does **not** modify the normal `~/.dsh` home, the official `web` profile, or official DSH credential stores.
 
-### Legacy web-profile commands (unsupported — reference only)
+## Quick start
 
-Older releases and tooling used direct `--profile web` commands that put Crew
-inside the official DSH `web` profile. Those commands are **not supported** and
-must not be used for new installs, updates, or uninstalls — the official web
-profile is never modified by supported Crew tooling:
+1. Start DeepSeek Harness normally.
+2. Open **Settings → DSH Crew**.
+3. Install the Codex integration; Claude Code integration is optional.
+4. Refresh Harness models and choose role priorities if needed.
+5. Restart the coding host after integration changes.
 
-```bash
-npx -y @deepseek-ai/dsh plugin --profile web add github:Ran-sh/dsh-crew
-npx -y @deepseek-ai/dsh plugin --profile web remove @ran-sh/dsh-crew
-npx -y @deepseek-ai/dsh plugin --profile web remove @zseven-w/dsh-crew
-```
+Then ask the host naturally, for example:
 
-`ZSeven-W/dsh-crew` is the upstream project identity; this fork is
-`Ran-sh/dsh-crew`. Use the source installer/uninstaller
-(`node scripts/setup.mjs install|uninstall`) instead.
-
-### Migrating from Flash / Pro (v0.1 → v0.2 roles)
-
-v0.2 keeps every old configuration field working. `collaboration_mode`,
-`tier_policy`, `flash_state` / `pro_state`, `flash_model_priority` /
-`pro_model_priority`, `escalate_on_failure` and `pro_reviews_flash` are all
-still read, and a centralized migration rebuilds the role model from them:
-
-- `flash-only` → worker auto, reviewer disabled, `economy` strategy.
-- `pro-only` → worker auto (strong model class), reviewer disabled.
-- `balanced` → worker auto, reviewer manual (available on request).
-- `review-pipeline` → worker auto + reviewer auto (`auto_review` on);
-  reviewer uses the old Pro priority.
-- `escalate_on_failure` → worker escalation policy `enabled`.
-- `pro_reviews_flash` → automatic review after a successful worker run.
-
-The old `ds-flash` / `ds-pro` subagents remain as **deprecated aliases**: they
-map to the worker role with a legacy model-class hint, so existing prompts
-keep working, but new prompts should use `ds-worker` / `ds-reviewer`. A
-request that names both a role and a contradicting legacy tier is rejected
-with a clear `ROLE_TIER_CONFLICT` error — never silently guessed.
-
-### Troubleshooting: `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`
-
-pnpm 11 enforces a default supply-chain policy (`minimum-release-age`, 24h):
-a lockfile entry published within the last day is rejected unless listed under
-`minimumReleaseAgeExclude`. Installing Crew into a fresh dedicated `dsh-crew`
-profile is unaffected, but if the Crew profile already contains a just-published
-DSH-plugin (for example the optional `dsh-plugin-image-mind`), the install fails
-with this error.
-
-Unblock it by adding the package (bare name, no version) under
-`minimumReleaseAgeExclude` in the **Crew profile's** `pnpm-workspace.yaml`, then
-re-run the installer:
-
-```yaml
-# ~/.config/dsh-crew/harness/profiles/dsh-crew/pnpm-workspace.yaml
-minimumReleaseAgeExclude:
-  - dsh-plugin-image-mind
-  - '@ran-sh/dsh-vision@0.1.0'
+```text
+Use ds-worker to implement this change.
+Use ds-reviewer to review the implementation.
 ```
 
-Notes: the official DSH home (`~/.dsh`) and its `web` profile are never edited
-by Crew tooling. Use a bare package name — listing multiple `pkg@version`
-entries for the same name only honors the first (first-match-wins), which can
-leave newer versions blocked. Keep the entries in `pnpm-workspace.yaml`; the
-verifier does not read `.npmrc`. The policy only applies to registry packages
-younger than one day (git-hosted installs like Crew itself are never
-age-checked), so the failure is transient and self-heals within 24 hours.
+## Roles and routing
 
-## Uninstall
-
-DSH Crew and its Codex / Claude Code integrations are separate layers:
-
-1. In **Settings → DSH Crew**, click **Restore** for Codex and Claude Code integrations that you installed.
-2. Uninstall the Crew plugin from the dedicated Crew profile:
-
-```bash
-node scripts/setup.mjs uninstall
-```
+| Role | Purpose |
+|---|---|
+| `worker` | Implementation, fixes, tests, search, analysis |
+| `reviewer` | Independent review and verdict |
 
-Legacy Crew installs that were previously placed into the official DSH `web`
-profile must be removed for that profile using the DSH CLI against the official
-home, without changing anything else there. Removing the Crew plugin does not
-implicitly edit `~/.codex` or `~/.claude`. Crew configuration, backups,
-credentials, and other DSH bundles are preserved.
+Each role resolves its own ordered provider/model candidates. Explicit user priorities remain authoritative; automatic escalation only happens when the workflow has evidence that stronger execution or review is needed.
 
-## Development / Source install
+Legacy `ds-flash` / `ds-pro` aliases remain for compatibility, but new prompts should use `ds-worker` / `ds-reviewer`.
 
-The source installer remains available for contributors and local checkout development.
+## Isolation
 
-Windows:
+`execution.isolation` defaults to `worktree`.
 
-```bat
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-install.cmd
-```
+A coding worker receives a temporary git worktree at the requested revision, so parallel workers do not write into the same working tree. The worker returns an auditable change candidate for the orchestrator to accept, reject, or revise; Crew does not silently merge changes into your primary workspace.
 
-To update later:
+## Update / uninstall
 
-```bat
-git pull
-install.cmd
-```
-
-Cross-platform:
+Update a source install:
 
 ```bash
+git pull --ff-only
 node scripts/setup.mjs install
 ```
 
-The source installer:
-
-- links this local checkout into the dedicated Crew profile (`dsh-crew`) under
-  the Crew-owned DSH home (`~/.config/dsh-crew/harness`), never the official
-  `web` profile (`link:<repo>`)
-- installs the Codex Desktop integration (no `codex` CLI required)
-- installs the Claude Code integration automatically when the `claude` CLI is detected (optional)
-- is idempotent — safe to re-run
-
-Source uninstall on Windows:
-
-```bat
-uninstall.cmd
-```
-
-Source uninstall cross-platform:
+Uninstall Crew and its integrations:
 
 ```bash
 node scripts/setup.mjs uninstall
 ```
 
-It removes:
-
-- DSH Crew from the dedicated Crew profile (official web profile is never touched)
-- Codex Desktop integration
-- Claude Code integration
-
-It keeps:
-
-- the repository
-- Crew config (`~/.config/dsh-crew`)
-- backups and credentials
-
-## Quick Start
-
-1. Start the official DeepSeek Harness as usual (its home and `web` profile are
-   never modified by Crew).
-2. Open **Settings → DSH Crew** (the Crew Settings surface is served by the
-   Crew-owned Hub).
-3. Keep the fresh default workflow: Codex → **worker** role → Codex (reviewer off).
-4. Use **Refresh Harness Models** to choose ordered per-role model priorities when needed.
-5. Restart Codex Desktop / Claude Code.
-
-Then just say:
-
-- “Use ds-worker to implement this change.”
-- “Use ds-reviewer to review this implementation.”
-
-## Roles
-
-- **worker** — the executing role: implementation, fixes, tests, search, analysis. The default role for any coding request. It is a thin dispatcher; which model backs it is the Worker Model Policy's job.
-- **reviewer** — the independent review role: inspects the implementation outcome, the workspace diff, tests and risks, and returns a verdict. Review-only by default; it does not re-implement.
-- **ds-flash / ds-pro** remain as deprecated aliases for compatibility (see migration above).
-
-A role's state is `disabled | manual | auto`: a disabled role refuses every
-request, a manual role runs only when explicitly named, an auto role may be
-chosen by the orchestrator. The effective state comes from the legacy
-collaboration mode until you adopt the canonical config.
-
-## Model Policy
-
-Each role resolves its own ordered provider/model candidates through the live
-Harness catalog:
-
-- attempt 0 → the role's primary (cheap/fast) priority;
-- attempt ≥ 1 → the escalation (strong) priority — escalation happens on
-  *evidence* (FAIL tests, incomplete delivery, blocked/incomplete task,
-  workspace diff that disagrees with the worker's report), not on failure
-  alone, and never beyond `max_attempts` (0..max-1, total attempts);
-- otherwise → Harness Default.
-
-Infrastructure failures (missing API key, unreachable hub, non-git workspace
-under worktree isolation) are **never** "fixed" by a stronger model — they
-fail with a stable error code instead. Flash / Pro survive only as legacy
-model-class hints (`deepseek-v4-flash` / `deepseek-v4-pro`); they are not
-roles.
-
-## Workflow
-
-Every dispatch — `dsh_run_worker` (blocking) and `dsh_spawn_worker` (async),
-Hub or Standalone — runs the **same** workflow runtime:
+Windows shortcuts:
 
+```bat
+install.cmd
+uninstall.cmd
 ```
-CREATED -> (QUEUED when busy) -> RUNNING -> VERIFYING
-  -> ESCALATING (evidence) -> RUNNING -> VERIFYING
-  -> REVIEWING (automatic reviewer) -> READY -> COMPLETED
-  (or FAILED / CANCELLED)
-```
-
-The only difference between blocking and async is whether the caller awaits.
-A coding worker runs in its own temporary git worktree (isolated execution);
-a `change candidate` (base revision, committed + uncommitted + new-file
-changes, bounded redacted patch, fingerprint) is returned for the orchestrator
-to accept / reject / revise — the runtime never auto-merges into your working
-tree.
 
-### Isolation
-
-`execution.isolation` is `worktree` by default: a worker role converges on a
-fresh detached worktree at HEAD and the primary workspace is never modified
-(even while it is dirty; uncommitted primary changes are not folded in). If
-the requested workspace is **not** a git repository, worktree-isolated jobs
-fail closed (`NOT_GIT_REPOSITORY`) instead of silently sharing — set
-`execution.isolation: "shared"` to allow the legacy in-place behavior.
-
-## Modes
-
-| Mode | Mapped role behavior |
-|---|---|
-| Flash Only | worker auto, reviewer disabled, economy model strategy |
-| Pro Only | worker auto on the strong model class, reviewer disabled |
-| Balanced | worker auto, reviewer manual (available on request) |
-| Review Pipeline | worker auto + reviewer auto (`auto_review` on) |
+Crew config and backups under `~/.config/dsh-crew` are preserved unless you remove them yourself.
 
-Custom mode configures worker / reviewer states directly.
+## Development
 
-## Provider
-
-Crew reads every provider and model currently registered in DeepSeek Harness. Each role resolves its own candidates: the **worker** uses a primary (cheap) priority with an escalation (strong) pool, and the **reviewer** has an independent review priority — the legacy fresh preferences are `deepseek-v4-flash` / `deepseek-v4-pro`, with Harness Default as fallback.
-
-- **Follow DSH Provider** — resolve the role's provider/model priority from the Harness catalog (fresh default).
-- **DeepSeek Official** — use the legacy built-in fixed route for compatibility.
-
-Credentials stay in the DSH provider configuration only. Tested with an OpenAI-compatible OpenCode Go gateway. Standalone mode (no DSH running) always uses DeepSeek Official + `DEEPSEEK_API_KEY`.
-
-## Hosts
-
-- **Codex Desktop** is directly supported through the shared `~/.codex` configuration. The Codex CLI is **not required**; it is an optional extra host / management interface.
-- **Claude Code** is optional; the one-click setup installs its integration automatically when the Claude CLI is detected.
-
-## Notes
+```bash
+pnpm install --frozen-lockfile
+node --test test/*.test.mjs
+pnpm run build:client
+pnpm run verify:npm-install
+```
 
-- Main Agent Mode is routing guidance, not a hard sandbox for the host's tools.
-- Standalone uses DeepSeek Official only.
-- Crew Vision registration changes may require a DSH restart.
-- Restart Codex Desktop after integration changes.
-- Every worker returns an auditable Delivery Report (`## Diff` / `## Tests` / `## Risks`) and the isolated candidate captures a bounded, redacted patch so you can verify what changed before accepting.
-- Blocking and async jobs execute the same workflow (evidence-driven escalation + automatic reviewer pass); async just returns a workflow id immediately and continues in the background.
-- `dsh_worker_status` / `dsh_worker_result` / `dsh_worker_cancel` operate on workflow ids (`wf-…`); legacy `hub-…` / `job-…` ids are still accepted.
-- Standalone launches the worker as `node <dsh-sdk-jsonrpc-demo/lib/bin.js>` (Windows-safe; the pnpm `.bin` sh shim is not spawnable). Standalone defaults to the DeepSeek Official provider + `DEEPSEEK_API_KEY`, but honors `DEEPSEEK_BASE_URL` so an OpenAI-compatible gateway (e.g. an `opencode-*` gateway already configured in `~/.dsh`) can back standalone workers by setting both env vars.
-- The Settings UI still presents the legacy Flash/Pro compatibility controls in this transition build; the new worker/reviewer role policy and `execution.isolation` write-through is a follow-up.
+Useful docs:
 
-## Credits & License
+- [Architecture roadmap](./docs/v0.3-architecture-roadmap.md)
+- [Readiness matrix](./docs/readiness-matrix.md)
+- [Agent Workflow](./docs/agent-workflow.md)
+- [Changelog](./CHANGELOG.md)
 
-This fork is based on the original DSH Crew by [ZSeven-W](https://github.com/ZSeven-W/dsh-crew) and retains the original MIT license and attribution. It adds configurable Harness-backed model priorities, worker/reviewer roles, unified job workflows, git-worktree isolation, auditable delivery, and related workflow changes.
+## License
 
-MIT License — see [LICENSE](LICENSE).
+MIT

package/README.zh.md

@@ -5,301 +5,136 @@
 <h1 align="center">DSH Crew</h1>
 
 <p align="center">
-  <strong>让 Codex Desktop / Claude Code 负责统筹，把编码任务交给 DeepSeek Harness 中的 worker 角色（另有独立的 reviewer 角色），由可配置的 Worker Model Policy 决定用哪个模型。</strong>
+  <strong>让 Codex Desktop 或 Claude Code 做总控，把编码任务分发给隔离运行的 DeepSeek Harness worker 与 reviewer。</strong>
 </p>
 
 <p align="center">
   <a href="./README.md">English</a> · <a href="./README.zh.md"><b>简体中文</b></a>
 </p>
 
-## 功能
+## 它做什么
 
-- Codex Desktop / Claude Code 作为主统筹 Agent
-- **角色（Role）**：worker（实现 / 修复 / 测试 / 搜索）与 reviewer（独立审查 + 结论）
-- **模型策略（Model Policy）**：每个角色独立解析有序 provider/model 候选（首选 → 优先级 → 升级 → Harness Default）
-- 旧版 Flash Only · Pro Only · Balanced · Review Pipeline 自动迁移到角色模型
-- Follow DSH Provider
-- DSH Hub 一等公民会话（Web UI 可见、异步任务带进度）
-- 可选的视觉 / 生图（独立开关）
+DSH Crew 在你的编码宿主和 DeepSeek Harness 之间增加一层轻量编排：
 
-## 工作方式
+- **worker** — 实现、修复、测试、搜索、分析；
+- **reviewer** — 独立审查 worker 的结果并给出结论；
+- **模型策略** — 每个角色独立解析 provider / model 优先级，并可按证据升级；
+- **隔离执行** — 编码 worker 默认运行在临时 git worktree；
+- **实时任务** — Hub 可查看进度、结果、取消、路由轨迹和 readiness 信息。
 
-```
+```text
 Codex Desktop / Claude Code
-          │
-          ▼
-       dsh-crew
-          │
-     Workflow（run 与 spawn 共用同一套状态机）
-          │
-     ┌────┴────┐
-     │         │
-   worker    reviewer
-     │         │
-  Model Policy  │  （各角色独立解析 provider/model；
-  cheap→strong  │   升级基于证据：FAIL 测试、缺失交付、阻塞任务）
-     │          │
-     └────┬────┘
-          │
-          ▼
-   DeepSeek Harness
-          │
-          ▼
-   DSH 当前选择的 provider/model
+            │
+            ▼
+         DSH Crew
+       ┌────┴────┐
+       │         │
+    worker    reviewer
+       │         │
+       └────┬────┘
+            ▼
+     DeepSeek Harness
 ```
 
-主 Agent 决定**做什么**并负责接受 / 拒绝 / 要求修改；Workflow 决定**何时 / 状态**；
-**角色**决定**谁来做**（worker 执行、reviewer 审查）；**模型策略**决定**用哪个模型**
-（永不与角色绑定）；工作区隔离决定**在哪里做**（每个 coding worker 跑在独立临时
-git worktree，并行 worker 不会互相踩 working tree）；验证 / reviewer 决定**是否接受**。
-
 ## 安装
 
-前置条件：带 npm/npx 的 Node.js、Git 和 pnpm。
-
-> **官方 Harness 隔离** — dsh-crew 安装到它自己的专用 DSH home
-> （`~/.config/dsh-crew/harness`）和专用 profile（`dsh-crew`），永远不会安装
-> 到官方 DSH home（`~/.dsh`）或官方 `web` profile。你的正常 DeepSeek Harness
-> 安装不会被修改。
+需要：**Node.js、Git、pnpm**。
 
-从本仓库克隆后，跨平台安装：
+推荐从源码安装：
 
 ```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
 node scripts/setup.mjs install
 ```
 
-Windows：
+Windows 也可以直接运行：
 
 ```bat
 install.cmd
 ```
 
-然后打开 **设置 → DSH Crew**，在 Codex 一行点击 **安装**。Claude Code 集成是可选项，有独立的安装按钮。
-
-安装器会把本检出以 `@ran-sh/dsh-crew` 方式链接到专用 `dsh-crew` profile，并把 Crew Hub 指向自己的端口；不会改动官方 web profile 或任何官方凭据存储。本 fork 不发布到 npm registry。
-
-### 更新
+DSH Crew 使用自己独立的 Harness home 和 profile：
 
-重新执行源码安装器：
-
-```bash
-git pull
-node scripts/setup.mjs install
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
 ```
 
-更新后重启 DSH。
-
-### 迁移旧版 fork 安装
+受支持的 Crew 工具不会修改正常的 `~/.dsh`、官方 `web` profile 或官方 DSH 凭据存储。
 
-旧版发布把 Crew 安装进官方 DSH `web` profile，这些安装不在受支持路径内。请先用源码卸载器卸载旧版 Crew（见“卸载”），再执行上述源码安装器，它会安装到专用 Crew home/profile。
+## 30 秒上手
 
-### 旧版 web-profile 命令（不支持 — 仅作参考）
+1. 正常启动 DeepSeek Harness。
+2. 打开 **Settings → DSH Crew**。
+3. 安装 Codex 集成；Claude Code 集成为可选项。
+4. 需要时刷新 Harness 模型，并设置各角色优先级。
+5. 集成变更后重启编码宿主。
 
-旧版发布和工具曾使用直接 `--profile web` 命令把 Crew 安装进官方 DSH `web` profile。这些命令**不受支持**，不得用于新的安装、更新或卸载 — 受支持的 Crew 工具绝不会修改官方 web profile：
+然后直接说：
 
-```bash
-npx -y @deepseek-ai/dsh plugin --profile web add github:Ran-sh/dsh-crew
-npx -y @deepseek-ai/dsh plugin --profile web remove @ran-sh/dsh-crew
-npx -y @deepseek-ai/dsh plugin --profile web remove @zseven-w/dsh-crew
+```text
+Use ds-worker to implement this change.
+Use ds-reviewer to review the implementation.
 ```
 
-`ZSeven-W/dsh-crew` 是上游项目标识；本 fork 是 `Ran-sh/dsh-crew`。请改用源码安装/卸载器（`node scripts/setup.mjs install|uninstall`）。
-
-### 从 Flash / Pro 迁移（v0.1 → v0.2 角色）
+## 角色与路由
 
-v0.2 保留所有旧配置字段继续生效。`collaboration_mode`、`tier_policy`、
-`flash_state` / `pro_state`、`flash_model_priority` / `pro_model_priority`、
-`escalate_on_failure`、`pro_reviews_flash` 都会被读取，迁移逻辑集中重建角色模型：
-
-- `flash-only` → worker auto、reviewer disabled、`economy` 策略。
-- `pro-only` → worker auto（强模型类）、reviewer disabled。
-- `balanced` → worker auto、reviewer manual（点名时可用）。
-- `review-pipeline` → worker auto + reviewer auto（`auto_review` 开启）；
-  reviewer 使用旧 Pro priority。
-- `escalate_on_failure` → worker 升级策略 `enabled`。
-- `pro_reviews_flash` → worker 成功后自动追加一次复查。
-
-旧的 `ds-flash` / `ds-pro` 子代理保留为**弃用别名**：它们映射到 worker 角色并带上
-历史模型类提示，旧 prompt 照常可用；新 prompt 请改用 `ds-worker` / `ds-reviewer`。
-同时传 role 与冲突的 legacy tier 会被明确拒绝（`ROLE_TIER_CONFLICT`），绝不静默猜测。
-
-### 故障排查：`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`
+| 角色 | 用途 |
+|---|---|
+| `worker` | 实现、修复、测试、搜索、分析 |
+| `reviewer` | 独立审查与 verdict |
 
-pnpm 11 有默认供应链策略（`minimum-release-age`，24 小时）：最近一天内发布的
-lockfile 条目会被拒绝，除非列入 `minimumReleaseAgeExclude`。全新 profile 安装
-dsh-crew 不受影响；但如果你 profile 里已带刚发布的 DSH 插件（例如可选的
-`dsh-plugin-image-mind`），安装会报此错。
+每个角色都有自己的 provider / model 候选顺序。用户显式配置始终优先；只有工作流拿到明确证据时才会自动升级到更强模型。
 
-解除方法：在 profile 的 `pnpm-workspace.yaml` 里加**不带版本号**的包名排除，然后重跑 add：
+旧的 `ds-flash` / `ds-pro` 仍保留兼容，但新提示词建议使用 `ds-worker` / `ds-reviewer`。
 
-```yaml
-# ~/.dsh/profiles/web/pnpm-workspace.yaml
-minimumReleaseAgeExclude:
-  - dsh-plugin-image-mind
-  - '@ran-sh/dsh-vision@0.1.0'
-```
+## 隔离
 
-注意：用不带版本的裸包名——同名多条 `pkg@version` 只认第一条（先命中先赢），可能把
-新版本漏掉。排除项要放在 `pnpm-workspace.yaml`，校验器不读 `.npmrc`。该策略只针对
-发布不到一天的 registry 包（git 托管的 dsh-crew 本身从不做 age 校验），所以问题通常
-在 24 小时内自动消失。
+`execution.isolation` 默认是 `worktree`。
 
-## 卸载
+编码 worker 会在目标 revision 上创建临时 git worktree，因此并行 worker 不会写入同一个工作目录。worker 返回可审计的 change candidate，由总控决定接受、拒绝或继续修改；Crew 不会偷偷把改动合进主工作区。
 
-DSH Crew 与 Codex / Claude Code 宿主集成是两层：
+## 更新 / 卸载
 
-1. 在 **设置 → DSH Crew** 中，对已安装的 Codex / Claude Code 集成点击 **还原**。
-2. 移除 profile plugin：
+更新源码安装：
 
 ```bash
-node scripts/setup.mjs uninstall   # Safe uninstall: see the canonical Uninstall section of README.md (official web profile is never modified).
-```
-
-只移除 profile plugin 不会隐式修改 `~/.codex` 或 `~/.claude`。Crew 配置、备份、凭据和其他 DSH bundle 都会保留。
-
-## 开发 / 源码安装
-
-源码安装器继续保留，供贡献者与本地 checkout 开发使用。
-
-Windows：
-
-```bat
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-install.cmd
-```
-
-以后更新：
-
-```bat
-git pull
-install.cmd
+git pull --ff-only
+node scripts/setup.mjs install
 ```
 
-跨平台：
+卸载 Crew 与集成：
 
 ```bash
-node scripts/setup.mjs install
+node scripts/setup.mjs uninstall
 ```
 
-源码安装器会：
-
-- 把本仓库以 link 方式装进 DSH web profile（`link:<repo>`）
-- 安装 Codex Desktop 集成（**不需要** `codex` CLI）
-- 检测到 `claude` CLI 时自动安装 Claude Code 集成（可选）
-- 幂等，可安全重复执行
-
-Windows 源码卸载：
+Windows：
 
 ```bat
+install.cmd
 uninstall.cmd
 ```
 
-跨平台源码卸载：
-
-```bash
-node scripts/setup.mjs uninstall
-```
-
-它会移除：
-
-- DSH web profile 中的 DSH Crew
-- Codex Desktop 集成
-- Claude Code 集成
-
-它会保留：
-
-- 仓库
-- Crew 配置（`~/.config/dsh-crew`）
-- 备份与凭据
-
-## 快速开始
-
-1. 照常启动 DSH：`npx -y @deepseek-ai/dsh web`
-2. 打开 **设置 → DSH Crew**。
-3. 保持新安装默认工作流：Codex → **worker** 角色 → Codex（reviewer 关闭）。
-4. 需要时用 **刷新 Harness 模型** 为各角色分别设置有序模型优先级。
-5. 重启 Codex Desktop / Claude Code。
-
-然后直接说：
-
-- “用 ds-worker 实现这个改动。”
-- “用 ds-reviewer 审查这个实现。”
-
-## 角色
-
-- **worker** — 执行角色：实现、修复、测试、搜索、分析。任意编码请求的默认角色。它是薄派发器；后台用哪个模型由 Worker Model Policy 决定。
-- **reviewer** — 独立审查角色：检查实现结果、工作区 diff、测试与风险，给出结论。默认只读，不做二次实现。
-- **ds-flash / ds-pro** 保留为弃用别名（见上面的迁移说明）。
-
-角色状态为 `disabled | manual | auto`：disabled 拒绝一切请求；manual 只在显式点名时运行；auto 可被 orchestrator 自动选择。未采用 canonical 配置时，生效状态来自旧协作模式。
-
-## 模型策略
+`~/.config/dsh-crew` 下的 Crew 配置和备份默认保留。
 
-各角色通过实时 Harness 目录独立解析有序候选：
+## 开发
 
-- attempt 0 → 角色首选（便宜 / 快）优先级；
-- attempt ≥ 1 → 升级（强）优先级——升级基于**证据**（FAIL 测试、交付缺失、阻塞 / 未完成任务、工作区 diff 与 worker 报告不一致），并非只看失败，且不超 `max_attempts`（0..max-1，总尝试次数）；
-- 否则 → Harness Default。
-
-基础设施失败（缺 API key、Hub 不可达、worktree 隔离下非 Git 工作区）**不会**靠“换更强模型”解决，而是以稳定错误码失败。Flash / Pro 只作为历史模型类提示存在，不再是角色。
-
-## 工作流
-
-每次派发——`dsh_run_worker`（阻塞）与 `dsh_spawn_worker`（异步）、Hub 或 Standalone——都走**同一套** workflow runtime：
-
-```
-CREATED -> (繁忙时 QUEUED) -> RUNNING -> VERIFYING
-  -> ESCALATING（证据驱动）-> RUNNING -> VERIFYING
-  -> REVIEWING（自动审查）-> READY -> COMPLETED
-  （或 FAILED / CANCELLED）
+```bash
+pnpm install --frozen-lockfile
+node --test test/*.test.mjs
+pnpm run build:client
+pnpm run verify:npm-install
 ```
 
-阻塞与异步的唯一区别是调用方是否等待。coding worker 默认在独立临时 git worktree 中执行；返回 `change candidate`（base revision、committed + 未提交 + 新增文件、有界脱敏 patch、指纹）供 orchestrator 接受 / 拒绝 / 要求修改——runtime 绝不自动合并进你的 working tree。
-
-### 隔离
-
-`execution.isolation` 默认为 `worktree`：worker 角色在 HEAD 的分离 worktree 上工作，主工作区永不被动（即使它是 dirty 的；未提交的主工作区改动不会混入 candidate）。如果目标工作区**不是** git 仓库，worktree 隔离任务会 **fail closed**（`NOT_GIT_REPOSITORY`）而不是静默共享——需要旧的就地行为请显式设 `execution.isolation: "shared"`。
-
-## 模式
-
-| 模式 | 迁移后的角色行为 |
-|---|---|
-| Flash Only | worker auto、reviewer disabled、economy 模型策略 |
-| Pro Only | worker auto（强模型类）、reviewer disabled |
-| Balanced | worker auto、reviewer manual（点名时可用） |
-| Review Pipeline | worker auto + reviewer auto（`auto_review` 开启） |
-
-Custom 模式可分别配置 worker / reviewer 状态。
-
-## Provider
-
-Crew 会读取 DeepSeek Harness 当前注册的全部 provider 与模型。各角色独立解析候选：**worker** 使用首选（便宜）优先级 + 升级（强）模型池，**reviewer** 有独立审查优先级——旧版新鲜偏好为 `deepseek-v4-flash` / `deepseek-v4-pro`，以 Harness Default 兜底。
-
-- **Follow DSH Provider** — 从 Harness 目录解析角色的 provider/model 优先级（新配置默认值）。
-- **DeepSeek Official** — 为兼容旧配置保留内置固定路由。
-
-凭据始终由 DSH 的 provider 配置管理。已在 OpenAI 兼容的 OpenCode Go 网关实测。Standalone 模式（无 DSH 运行）始终使用 DeepSeek Official + `DEEPSEEK_API_KEY`。
-
-## 宿主
-
-- **Codex Desktop** 通过共享的 `~/.codex` 配置直接受支持，**不要求** `codex` CLI；CLI 只是可选的补充宿主 / 管理接口。
-- **Claude Code** 为可选；一键安装检测到 Claude CLI 时自动安装其集成。
-
-## 备注
-
-- Main Agent Mode 是路由指引，不是对宿主工具的硬沙箱。
-- Standalone 只使用 DeepSeek Official。
-- Crew Vision 的工具注册改动可能需要重启 DSH。
-- 集成内容改动后请重启 Codex Desktop。
-- 每个 worker 都会返回可审查的交付报告（`## Diff` / `## Tests` / `## Risks`），隔离候选捕获有界、脱敏的 patch，方便在接受前核对改动。
-- 阻塞与异步任务执行**同一套** workflow（证据驱动升级 + 自动审查）；异步只是立刻返回 workflow id 并在后台继续。
-- `dsh_worker_status` / `dsh_worker_result` / `dsh_worker_cancel` 以 workflow id（`wf-…`）为主；旧的 `hub-…` / `job-…` id 仍兼容。
-- Standalone 以 `node <dsh-sdk-jsonrpc-demo/lib/bin.js>` 启动 worker（Windows 安全；pnpm 的 `.bin` sh shim 无法被 Node spawn）。Standalone 默认 DeepSeek Official + `DEEPSEEK_API_KEY`，但支持 `DEEPSEEK_BASE_URL`——已配置在 `~/.dsh` 的 OpenAI 兼容网关（如 `opencode-*`）可通过同时设置这两个环境变量来支撑 Standalone worker。
-- 设置 UI 在本过渡构建里仍展示旧的 Flash/Pro 兼容控件；新 worker/reviewer 角色策略与 `execution.isolation` 的写回是后续项。
+更多文档：
 
-## 版权与许可
+- [架构路线图](./docs/v0.3-architecture-roadmap.md)
+- [Readiness Matrix](./docs/readiness-matrix.md)
+- [Agent Workflow](./docs/agent-workflow.md)
+- [Changelog](./CHANGELOG.md)
 
-本 fork 基于 [ZSeven-W](https://github.com/ZSeven-W/dsh-crew) 的原始 DSH Crew，保留原 MIT 许可与署名，并增加可配置的 Harness 模型优先级、worker/reviewer 角色、统一任务工作流、git worktree 隔离、可审计交付等工作流能力。
+## License
 
-MIT License —— 见 [LICENSE](LICENSE)。
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "description": "DeepSeek Harness plugin: dispatch work to DSH agents from Claude Code / Codex, as native subagents with live progress",
@@ -20,7 +20,9 @@
   },
   "scripts": {
     "mcp": "node src/server.mjs",
-    "build:client": "tsdown src/client/entry.tsx --format cjs --platform browser --target es2022 --tsconfig tsconfig.client.json --deps.never-bundle react --deps.never-bundle react/jsx-runtime --deps.never-bundle react-dom --deps.never-bundle react-dom/client --out-dir .client-build --clean --logLevel warn && node scripts/build-client.mjs"
+    "build:client": "tsdown src/client/entry.tsx --format cjs --platform browser --target es2022 --tsconfig tsconfig.client.json --deps.never-bundle react --deps.never-bundle react/jsx-runtime --deps.never-bundle react-dom --deps.never-bundle react-dom/client --out-dir .client-build --clean --logLevel warn && node scripts/build-client.mjs",
+    "verify:npm-install": "node scripts/verify-npm-install.mjs",
+    "verify:npm-install:official": "node scripts/verify-npm-install.mjs --with-official-dsh"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.5",
@@ -34,26 +36,26 @@
   "peerDependencies": {
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-spine-demo": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-bash-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-compaction-basic": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-fs-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-fs-observation-policy": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm-deepseek": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sandbox-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sandbox-policy": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sdk-client": "^0.1.0-rc.5",
-    "@deepseek-ai/dsh-sdk-jsonrpc-demo": "^0.1.0-rc.5",
-    "@deepseek-ai/dsh-sdk-jsonrpc-server": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-token-meter": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tool-fs": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tool-todo": "0.1.0-rc.6"
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-spine-demo": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-bash-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-client": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-jsonrpc-demo": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-jsonrpc-server": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-todo": "0.1.1-rc.2"
   },
   "devDependencies": {
     "react": "^18.3.1",
@@ -61,26 +63,26 @@
     "tsdown": "^0.12.0",
     "typescript": "^5.6.0",
     "@types/react": "^18.3.0",
-    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-spine-demo": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-bash-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-compaction-basic": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-fs-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-fs-observation-policy": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm-deepseek": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sandbox-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sandbox-policy": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-sdk-client": "^0.1.0-rc.5",
-    "@deepseek-ai/dsh-sdk-jsonrpc-demo": "^0.1.0-rc.5",
-    "@deepseek-ai/dsh-sdk-jsonrpc-server": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-token-meter": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tool-fs": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tool-todo": "0.1.0-rc.6"
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-spine-demo": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-bash-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-client": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-jsonrpc-demo": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-sdk-jsonrpc-server": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tool-todo": "0.1.1-rc.2"
   },
   "license": "MIT",
   "repository": {

package/scripts/verify-npm-install.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+// Regression gate for the published-package peer contract.
+// This intentionally uses npm's default resolver for the candidate install:
+// no peer-resolution bypass or equivalent override is permitted here.
+//
+// The official DSH check is deliberately bounded. It audits authoritative
+// public registry manifests and cross-cohort ranges instead of materializing
+// or fully resolving the very large official DSH dependency graph.
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const registry = process.env.NPM_REGISTRY ?? 'https://registry.npmjs.org/';
+export const candidateVersion = '0.3.1';
+export const supportedDshVersion = '0.1.1-rc.2';
+const verifyOfficialDsh = process.argv.includes('--with-official-dsh');
+const DSH_PACKAGE = '@deepseek-ai/dsh';
+const DSH_PREFIX = '@deepseek-ai/dsh-';
+const MAX_DIRECT_PEERS = 64;
+
+function isDshPackage(name) {
+  return name === DSH_PACKAGE || name.startsWith(DSH_PREFIX);
+}
+
+function parseVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+function compareVersions(left, right) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
+  }
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+  if (left.prerelease.length === 0) return 1;
+  if (right.prerelease.length === 0) return -1;
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const a = left.prerelease[index];
+    const b = right.prerelease[index];
+    if (a === undefined) return -1;
+    if (b === undefined) return 1;
+    if (a === b) continue;
+    const aNumber = /^\d+$/.test(a);
+    const bNumber = /^\d+$/.test(b);
+    if (aNumber && bNumber) return Number(a) > Number(b) ? 1 : -1;
+    if (aNumber !== bNumber) return aNumber ? -1 : 1;
+    return a > b ? 1 : -1;
+  }
+  return 0;
+}
+
+function upperBoundForCaret(version) {
+  if (version.major > 0) return { major: version.major + 1, minor: 0, patch: 0, prerelease: [] };
+  if (version.minor > 0) return { major: 0, minor: version.minor + 1, patch: 0, prerelease: [] };
+  return { major: 0, minor: 0, patch: version.patch + 1, prerelease: [] };
+}
+
+function upperBoundForTilde(version) {
+  return { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
+}
+
+function satisfiesComparator(version, operator, expected) {
+  const comparison = compareVersions(version, expected);
+  if (operator === '>') return comparison > 0;
+  if (operator === '>=') return comparison >= 0;
+  if (operator === '<') return comparison < 0;
+  if (operator === '<=') return comparison <= 0;
+  return comparison === 0;
+}
+
+function satisfiesAlternative(version, alternative) {
+  const normalized = alternative.trim();
+  if (!normalized || /[*xX]|workspace:|^npm:|^file:|^git:/.test(normalized)) return false;
+  const tokens = normalized.replace(/,/g, ' ').split(/\s+/).filter(Boolean);
+  return tokens.every((token) => {
+    const prefix = /^(\^|~|>=|<=|>|<|=)/.exec(token)?.[1] ?? '';
+    const raw = prefix ? token.slice(prefix.length) : token;
+    const expected = parseVersion(raw);
+    if (!expected) return false;
+    if (prefix === '^') {
+      return compareVersions(version, expected) >= 0 && compareVersions(version, upperBoundForCaret(expected)) < 0;
+    }
+    if (prefix === '~') {
+      return compareVersions(version, expected) >= 0 && compareVersions(version, upperBoundForTilde(expected)) < 0;
+    }
+    return satisfiesComparator(version, prefix, expected);
+  });
+}
+
+export function satisfiesCohortRange(versionString, range) {
+  const version = parseVersion(versionString);
+  if (!version || typeof range !== 'string') return false;
+  return range.split(/\s*\|\|\s*/).some((alternative) => satisfiesAlternative(version, alternative));
+}
+
+function assertManifest(manifest, expectedName, expectedVersion) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error(`invalid registry manifest for ${expectedName}@${expectedVersion}`);
+  }
+  if (manifest.name !== expectedName || manifest.version !== expectedVersion) {
+    throw new Error(`registry manifest identity mismatch for ${expectedName}@${expectedVersion}`);
+  }
+  return manifest;
+}
+
+function manifestUrl(registryUrl, name, version) {
+  const encodedName = name.startsWith('@') ? name.replace('/', '%2f') : encodeURIComponent(name);
+  return `${registryUrl.replace(/\/+$/, '')}/${encodedName}/${encodeURIComponent(version)}`;
+}
+
+export async function fetchPublicManifest(name, version, {
+  registryUrl = registry,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('global fetch is unavailable');
+  const response = await fetchImpl(manifestUrl(registryUrl, name, version), {
+    headers: { accept: 'application/json', 'user-agent': 'dsh-crew-v031-cohort-audit' },
+  });
+  if (!response?.ok) throw new Error(`public manifest unavailable for ${name}@${version} (HTTP ${response?.status ?? 'unknown'})`);
+  let manifest;
+  try {
+    manifest = await response.json();
+  } catch {
+    throw new Error(`public manifest was not valid JSON for ${name}@${version}`);
+  }
+  return assertManifest(manifest, name, version);
+}
+
+function dshReferences(manifest) {
+  return [
+    ...Object.entries(manifest.dependencies ?? {}),
+    ...Object.entries(manifest.optionalDependencies ?? {}),
+    ...Object.entries(manifest.peerDependencies ?? {}),
+  ].filter(([name]) => isDshPackage(name));
+}
+
+function assertCrossCohortRanges(manifest, label) {
+  const references = dshReferences(manifest);
+  for (const [name, range] of references) {
+    if (!satisfiesCohortRange(supportedDshVersion, range)) {
+      throw new Error(`${label} has incompatible ${name} range ${JSON.stringify(range)} for ${supportedDshVersion}`);
+    }
+  }
+  return references.length;
+}
+
+export async function auditOfficialDshCohort({
+  candidateManifest,
+  registryUrl = registry,
+  fetchManifest = (name, version) => fetchPublicManifest(name, version, { registryUrl }),
+} = {}) {
+  if (!candidateManifest || typeof candidateManifest !== 'object') throw new Error('candidate package manifest is missing');
+  if (candidateManifest.version !== candidateVersion) throw new Error(`package.json must be ${candidateVersion}`);
+
+  const directPeers = Object.entries(candidateManifest.peerDependencies ?? {})
+    .filter(([name]) => isDshPackage(name));
+  if (directPeers.length === 0 || directPeers.length > MAX_DIRECT_PEERS) {
+    throw new Error(`candidate DSH peer count is outside the bounded audit limit: ${directPeers.length}`);
+  }
+  for (const [name, range] of directPeers) {
+    if (range !== supportedDshVersion) {
+      throw new Error(`candidate peer ${name} must pin exact cohort ${supportedDshVersion}, got ${JSON.stringify(range)}`);
+    }
+  }
+
+  const officialManifest = assertManifest(
+    await fetchManifest(DSH_PACKAGE, supportedDshVersion),
+    DSH_PACKAGE,
+    supportedDshVersion,
+  );
+  const manifests = [officialManifest];
+  let crossCohortChecks = assertCrossCohortRanges(officialManifest, `${DSH_PACKAGE}@${supportedDshVersion}`);
+
+  for (const [name] of directPeers) {
+    const manifest = assertManifest(await fetchManifest(name, supportedDshVersion), name, supportedDshVersion);
+    manifests.push(manifest);
+    crossCohortChecks += assertCrossCohortRanges(manifest, `${name}@${supportedDshVersion}`);
+  }
+
+  return {
+    marker: 'PASS',
+    candidate: candidateVersion,
+    officialDsh: supportedDshVersion,
+    directPeerCount: directPeers.length,
+    manifestCount: manifests.length,
+    crossCohortChecks,
+  };
+}
+
+function run(args, cwd = root) {
+  const result = spawnSync(npmCommand, args, {
+    cwd,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function fail(label, result) {
+  const detail = `${result.stdout}\n${result.stderr}`.trim().replace(/\s+/g, ' ').slice(0, 800);
+  throw new Error(`${label} failed (exit ${result.status}): ${detail}`);
+}
+
+async function assertInstalled(prefix, label) {
+  const packageRoot = path.join(prefix, 'node_modules', '@ran-sh', 'dsh-crew');
+  const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  const runtimeSource = await readFile(path.join(packageRoot, 'src', 'runtime-identity.mjs'), 'utf8');
+  const runtimeVersion = runtimeSource.match(/RUNTIME_VERSION\s*=\s*'([^']+)'/)?.[1];
+  const entryExists = await readFile(path.join(packageRoot, 'src', 'hub', 'entry.mjs')).then(() => true, () => false);
+  const clientExists = await readFile(path.join(packageRoot, 'lib', 'client.js')).then(() => true, () => false);
+  if (packageJson.version !== candidateVersion || runtimeVersion !== candidateVersion || !entryExists || !clientExists) {
+    throw new Error(`${label} did not install the expected ${candidateVersion} package/runtime entries`);
+  }
+}
+
+async function main() {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'dsh-crew-v031-install-'));
+  const paths = {
+    pack: await mkdtemp(path.join(tempRoot, 'pack-')),
+    standalone: await mkdtemp(path.join(tempRoot, 'standalone-')),
+  };
+
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+    if (packageJson.version !== candidateVersion) throw new Error(`package.json must be ${candidateVersion}`);
+
+    const packed = run(['pack', '--json', '--pack-destination', paths.pack]);
+    if (packed.status !== 0) fail('npm pack', packed);
+    const packInfo = JSON.parse(packed.stdout)[0];
+    const tarball = path.join(paths.pack, packInfo.filename);
+
+    const standalone = run([
+      'install', '--prefix', paths.standalone, '--no-save', '--package-lock=false', '--ignore-scripts', '--no-audit', '--no-fund',
+      '--registry', registry, tarball,
+    ]);
+    if (standalone.status !== 0) fail('plain npm candidate install', standalone);
+    await assertInstalled(paths.standalone, 'standalone candidate');
+
+    let officialMarker = 'not-run';
+    if (verifyOfficialDsh) {
+      const audit = await auditOfficialDshCohort({ candidateManifest: packageJson, registryUrl: registry });
+      officialMarker = `${supportedDshVersion}:manifest-audit`;
+      console.log(`DSH_COHORT_AUDIT=PASS official_dsh=${audit.officialDsh} direct_peers=${audit.directPeerCount} manifests=${audit.manifestCount} cross_cohort_checks=${audit.crossCohortChecks}`);
+    }
+
+    console.log(`NPM_INSTALL_CONTRACT=PASS candidate=${candidateVersion} official_dsh=${officialMarker}`);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/src/runtime-identity.mjs

@@ -8,7 +8,7 @@
 // Keep this module pure and dependency-free so Hub, MCP and tests all use the
 // exact same compatibility rules.
 
-export const RUNTIME_VERSION = '0.3.0';
+export const RUNTIME_VERSION = '0.3.1';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([