@ran-sh/dsh-crew 0.5.0 → 0.5.2

package/README.md

@@ -1,112 +1,93 @@
-<p align="center"><img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" /></p>
-
-<h1 align="center">DSH Crew</h1>
-
-<p align="center"><strong>Workers and reviewers for Codex Desktop and Claude Code, shown inside the official DeepSeek Harness UI.</strong></p>
-
-<p align="center"><a href="./README.md"><b>English</b></a> · <a href="./README.zh.md">简体中文</a></p>
-
-## Quick start
-
-Requirements: Node.js; Git is required for worktree isolation.
-
-```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew install
-dsh-crew integrate
-```
-
-Start the official Harness on port 3080 as usual:
-
-```bash
-npx -y @deepseek-ai/dsh web --host 127.0.0.1 --port 3080
-```
-
-Open <http://127.0.0.1:3080> and go to the single **Settings → DSH Crew** entry. The official 3080 process is the daily console; Crew work stays in the isolated backend at `127.0.0.1:3210`. Use **Open 3210 Crew Harness →** only for low-level Provider and Harness Model settings.
-
-The shared client is surface-aware: 3080 renders the complete Crew control plane, host readiness, and task status; 3210 renders only a minimal Crew runtime panel while its native Harness menus continue to own Providers, Harness Models, Agent presets, and low-level settings. Detection uses the structured bridge/runtime endpoints, not a hard-coded browser port, and fails closed when evidence is missing. See [UI surface architecture](./docs/ui-surfaces.md).
-
-## Configure
-
-1. Click **Refresh Harness Models**.
-2. Set the model order for Worker and Reviewer.
-3. Keep Worker on **Auto** for automatic delegation.
-4. Reviewer defaults to **Manual**; enable automatic review only when wanted.
-5. Keep **worktree** isolation for coding tasks.
-
-With one configured model, both roles simply use that model. With several models, each role tries its ordered list and falls back to the next available model. Settings modules are collapsible and show their effective state while closed. The task section shows a compact Worker/Reviewer table plus process-local model call counts, sources, and last-call times; prompts, results, and credentials are not collected for this overview.
-
-## Use from Codex or Claude
-
-```text
-Use ds-worker to implement this change and run the tests.
-Use ds-reviewer to review the result.
-```
-
-Legacy `ds-flash` and `ds-pro` aliases remain compatible.
-
-## Results and reviews
-
-Crew returns a compact, machine-readable Result Contract by default: status,
-tests, changed files, review verdict, model-selection trace, artifact references,
-and canonical lifecycle events. Raw agent prose and full patches are not copied
-through every hand-off. An automatic Reviewer receives a bounded evidence
-capsule and inspects the isolated workspace directly.
-
-MCP callers can request `detail: "full"` on `dsh_run_worker` or
-`dsh_worker_result` for explicit debugging and recovery. Contract details are in
-[Job contracts and information flow](./docs/job-contracts.md).
-
-## Common commands
-
-```bash
-dsh-crew status       # installation and integration health
-dsh-crew inspect      # machine-readable capabilities and readiness
-dsh-crew jobs list    # machine-readable jobs
-dsh-crew jobs watch <job-id> --after 0
-dsh-crew update       # update and repair enabled integrations
-dsh-crew integrate    # connect official 3080 UI to isolated 3210 Crew
-dsh-crew detach       # remove only the 3080 bridge
-dsh-crew uninstall    # remove Crew, keep config and backups
-```
-
-`dsh-crew uninstall --purge` also removes Crew configuration and backups.
-
-If you prefer a completely separate UI, run `dsh-crew detach`, then start the isolated profile directly:
-
-```powershell
-$env:DSH_HOME = "$HOME\.config\dsh-crew\harness"
-& "$env:DSH_HOME\runtime\node_modules\.bin\dsh.cmd" --profile dsh-crew --host 127.0.0.1 --port 3210
-```
-
-The bridge backs up the official `web` profile before its first change and registers only a lightweight proxy/client package. The full Crew Hub, model execution, config, and credentials stay under:
-
-```text
-~/.config/dsh-crew/harness
-profile: dsh-crew
-```
-
-For launchers at `<= 0.3.3`, first refresh the launcher because the old updater cannot discover newer releases and cannot be retroactively fixed:
-
-```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew update
-```
-
-## Source development
-
-```bash
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-node scripts/setup.mjs install
-node --test test/*.test.mjs
-pnpm run build:client
-node scripts/setup.mjs uninstall
-```
-
-More detail: [Changelog](./CHANGELOG.md) · [UI surfaces](./docs/ui-surfaces.md) · [Readiness matrix](./docs/readiness-matrix.md) · [Job contracts](./docs/job-contracts.md)
-· [GPT-first extension](./docs/gpt-relay-extension.md)
-
-## License
-
-MIT
+<p align="center"><img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="112" /></p>
+
+# DSH Crew
+
+Workers and independent reviewers for Codex Desktop, Claude Code, and ZCode, with daily controls inside the official DeepSeek Harness UI.
+
+[English](./README.md) · [简体中文](./README.zh.md)
+
+## Quick start
+
+Requirements: Node.js; Git is also required for worktree isolation.
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
+dsh-crew integrate
+```
+
+On Windows, installation also creates a per-user login-start entry. It starts the isolated Crew backend on 3210 and the official UI on 3080 without opening a browser. Open <http://127.0.0.1:3080> when you need the console.
+
+```bash
+dsh-crew status
+dsh-crew inspect
+```
+
+- **3080**: daily console, Crew settings, Codex/Claude readiness, jobs.
+- **3210**: isolated Crew backend, Providers, Harness Models, low-level Harness settings.
+- **Codex / ZCode**: installation adds managed capability-aware policy blocks and dispatch roles. Existing user instructions remain untouched.
+- **ZCode**: uses `~/.zcode/cli/config.json` when native MCP servers exist, otherwise the compatible `~/.agents/mcp.json` source.
+
+## Configure and use
+
+In **Settings → DSH Crew**, refresh Harness Models and order the Worker and Reviewer model lists. One configured model is used directly; several models are tried in your chosen order. Worker can run automatically. Reviewer defaults to manual.
+
+Ask Codex or Claude naturally:
+
+```text
+Use ds-worker to implement this change and run its tests.
+Use ds-reviewer to review the result.
+```
+
+Codex first discovers the live Crew capability/readiness contract. If it selected Crew and Crew becomes unavailable, it pauses and asks whether to repair Crew or continue locally; it does not silently fall back.
+
+## Commands
+
+```bash
+dsh-crew status                    # installation and integration health
+dsh-crew inspect                   # live capabilities and readiness
+dsh-crew jobs list                 # jobs and Result Contracts
+dsh-crew jobs watch <id> --after 0
+dsh-crew update                    # update and repair enabled integrations
+dsh-crew integrate                 # add the official 3080 bridge
+dsh-crew detach                    # remove only the 3080 bridge
+dsh-crew uninstall                 # remove managed files; keep config/backups
+dsh-crew uninstall --purge         # also remove config/backups
+```
+
+The official `web` profile receives only a lightweight bridge. The Crew runtime, models, config, and credentials stay isolated under:
+
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
+```
+
+## Install from source
+
+Use this path to install the current GitHub `main` before it is published to npm:
+
+```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
+node scripts/setup.mjs install
+node scripts/setup.mjs status
+```
+
+Verify and remove it with:
+
+```bash
+node --test test/*.test.mjs
+pnpm run build:client
+node scripts/setup.mjs uninstall
+```
+
+For launchers at `<= 0.3.3`, refresh the launcher first. The old updater cannot discover newer releases and cannot be retroactively fixed:
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew update
+```
+
+Installation ownership and rollback details: [Installation plan](./docs/installation.md). Architecture contracts: [UI surfaces](./docs/ui-surfaces.md) · [Readiness](./docs/readiness-matrix.md) · [Jobs and information flow](./docs/job-contracts.md).
+
+MIT

package/README.zh.md

@@ -1,111 +1,93 @@
-<p align="center"><img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" /></p>
-
-<h1 align="center">DSH Crew</h1>
-
-<p align="center"><strong>让 Codex Desktop 和 Claude Code 使用 Worker / Reviewer，并统一显示在官方 DeepSeek Harness 界面中。</strong></p>
-
-<p align="center"><a href="./README.md">English</a> · <a href="./README.zh.md"><b>简体中文</b></a></p>
-
-## 快速开始
-
-需要 Node.js；使用 worktree 隔离还需要 Git。
-
-```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew install
-dsh-crew integrate
-```
-
-照常在 3080 端口启动官方 Harness：
-
-```bash
-npx -y @deepseek-ai/dsh web --host 127.0.0.1 --port 3080
-```
-
-打开 <http://127.0.0.1:3080>，进入唯一的 **设置 → DSH Crew**。3080 是日常控制台；Crew 的任务与模型执行继续隔离在 `127.0.0.1:3210`。只有配置底层 Provider 和 Harness Models 时才点击“打开 3210 Crew Harness →”。
-
-共享客户端会识别当前 surface：3080 显示完整 Crew 控制面、宿主就绪度和任务状态；3210 的 DSH Crew 入口只显示最小运行时诊断，Provider、Harness Models、Agent 预设和底层设置仍由 Harness 原生菜单管理。识别依赖结构化 bridge/runtime 接口，不硬编码浏览器端口；证据缺失时会保守隐藏控制面。详见 [UI surface 架构](./docs/ui-surfaces.md)。
-
-## 配置
-
-1. 点击“刷新 Harness 模型”。
-2. 分别设置 Worker 和 Reviewer 的模型顺序。
-3. Worker 保持 **Auto**，即可自动委派。
-4. Reviewer 默认 **Manual**；确实需要自动复审时再开启。
-5. 编码任务建议保持 **worktree** 隔离。
-
-只配置一个模型时，两个角色直接使用它。配置多个模型时，每个角色按自己的排序调用，失败后依次回退。设置模块可以展开/收起，收起后仍显示当前状态。任务区用紧凑表格显示 Worker/Reviewer，并聚合当前进程内的模型调用次数、来源和最近调用时间；不会为此采集提示词、结果或凭据。
-
-## 在 Codex 或 Claude 中使用
-
-```text
-使用 ds-worker 实现这个改动并运行测试。
-使用 ds-reviewer 审查结果。
-```
-
-旧的 `ds-flash`、`ds-pro` 别名仍可使用。
-
-## 结果与复审信息流
-
-Crew 默认返回紧凑、机器可读的 Result Contract：状态、测试、改动文件、
-Reviewer 结论、模型选择轨迹、候选引用和规范化生命周期事件。Worker 的
-整段原始回答和完整 patch 不会在每次交接时重复传递；自动 Reviewer 只接收
-有大小上限的证据胶囊，并直接检查隔离工作区。
-
-MCP 调用方如需排障或恢复，可以在 `dsh_run_worker` 或
-`dsh_worker_result` 中显式传入 `detail: "full"`。完整契约见
-[任务契约与信息流](./docs/job-contracts.md)。
-
-## 常用命令
-
-```bash
-dsh-crew status       # 查看安装与集成状态
-dsh-crew inspect      # 输出机器可读的能力与就绪度
-dsh-crew jobs list    # 输出机器可读的任务列表
-dsh-crew jobs watch <job-id> --after 0
-dsh-crew update       # 更新并自动修复已启用的集成
-dsh-crew integrate    # 将官方 3080 界面连接到隔离的 3210 Crew
-dsh-crew detach       # 只移除 3080 桥接
-dsh-crew uninstall    # 卸载 Crew，保留配置和备份
-```
-
-`dsh-crew uninstall --purge` 才会同时删除 Crew 配置和备份。
-
-如果想继续使用完全独立的界面，先运行 `dsh-crew detach`，再直接启动隔离 profile：
-
-```powershell
-$env:DSH_HOME = "$HOME\.config\dsh-crew\harness"
-& "$env:DSH_HOME\runtime\node_modules\.bin\dsh.cmd" --profile dsh-crew --host 127.0.0.1 --port 3210
-```
-
-桥接首次修改前会备份官方 `web` profile，并且只注册轻量代理/客户端包。完整 Crew Hub、模型执行、配置和凭据仍位于：
-
-```text
-~/.config/dsh-crew/harness
-profile: dsh-crew
-```
-
-对于 `<= 0.3.3` 的旧启动器，请先刷新启动器；旧 updater 无法发现新版本，也无法被追溯修复：
-
-```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew update
-```
-
-## 源码开发
-
-```bash
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-node scripts/setup.mjs install
-node --test test/*.test.mjs
-pnpm run build:client
-node scripts/setup.mjs uninstall
-```
-
-更多资料：[Changelog](./CHANGELOG.md) · [UI surfaces](./docs/ui-surfaces.md) · [Readiness Matrix](./docs/readiness-matrix.md) · [任务契约](./docs/job-contracts.md)
-· [GPT-first 扩展接入](./docs/gpt-relay-extension.md)
-
-## License
-
-MIT
+<p align="center"><img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="112" /></p>
+
+# DSH Crew
+
+让 Codex Desktop、Claude Code 和 ZCode 使用 Worker / Reviewer，并在官方 DeepSeek Harness 界面中完成日常控制。
+
+[English](./README.md) · [简体中文](./README.zh.md)
+
+## 快速开始
+
+需要 Node.js；使用 worktree 隔离还需要 Git。
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
+dsh-crew integrate
+```
+
+Windows 安装会同时创建当前用户的登录启动项：后台启动隔离的 3210 Crew 和官方 3080 界面服务，但不会自动弹出浏览器。需要时打开 <http://127.0.0.1:3080>。
+
+```bash
+dsh-crew status
+dsh-crew inspect
+```
+
+- **3080**：日常控制台、Crew 设置、Codex/Claude 就绪状态、任务列表。
+- **3210**：隔离 Crew 后端、Provider、Harness Models 和底层 Harness 设置。
+- **Codex / ZCode**：安装程序会加入可卸载的能力感知规则区块和 dispatch 角色，不改动已有个人规则。
+- **ZCode**：已有原生 MCP 服务时使用 `~/.zcode/cli/config.json`，否则兼容使用 `~/.agents/mcp.json`。
+
+## 配置与使用
+
+进入 **设置 → DSH Crew**，刷新 Harness Models，然后分别排列 Worker 和 Reviewer 的模型顺序。只配置一个模型时直接使用；配置多个模型时按你的排序依次尝试。Worker 可以自动调用，Reviewer 默认手动。
+
+直接告诉 Codex 或 Claude：
+
+```text
+使用 ds-worker 实现这个改动并运行测试。
+使用 ds-reviewer 审查结果。
+```
+
+Codex 会先读取 Crew 的实时能力与就绪合同。如果已经选择 Crew、但 Crew 变得不可调用，它会暂停并询问“修复 Crew 后继续”还是“由 Codex 本地继续”，不会静默降级。
+
+## 常用命令
+
+```bash
+dsh-crew status                    # 安装和集成状态
+dsh-crew inspect                   # 实时能力与就绪度
+dsh-crew jobs list                 # 任务与 Result Contract
+dsh-crew jobs watch <id> --after 0
+dsh-crew update                    # 更新并修复已启用集成
+dsh-crew integrate                 # 接入官方 3080
+dsh-crew detach                    # 只移除 3080 桥接
+dsh-crew uninstall                 # 移除受管文件，保留配置/备份
+dsh-crew uninstall --purge         # 同时移除配置/备份
+```
+
+官方 `web` profile 只安装轻量桥接。Crew 运行时、模型、配置与凭据隔离在：
+
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
+```
+
+## 从源码安装
+
+如果要在 npm 发布前安装 GitHub `main`：
+
+```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
+node scripts/setup.mjs install
+node scripts/setup.mjs status
+```
+
+验证与卸载：
+
+```bash
+node --test test/*.test.mjs
+pnpm run build:client
+node scripts/setup.mjs uninstall
+```
+
+对于 `<= 0.3.3` 的旧启动器，请先刷新启动器。旧 updater 无法发现更新，也无法被追溯修复：
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew update
+```
+
+安装归属与回滚细节见[安装方案](./docs/installation.md)。架构合同：[界面分工](./docs/ui-surfaces.md) · [就绪矩阵](./docs/readiness-matrix.md) · [任务与信息流](./docs/job-contracts.md)。
+
+MIT

package/codex/AGENTS.md

@@ -0,0 +1,92 @@
+# Global capability-aware delegation policy
+
+The main Codex agent owns the user's task from planning through final delivery.
+DSH Crew is an execution and review capability that Codex may use after
+discovering what the current environment actually supports.
+
+## Discover capabilities before delegation
+
+- Before delegating substantial work, query DSH Crew's authoritative live
+  configuration, capability, and readiness surfaces.
+- Discover capabilities dynamically from the returned contracts. Do not rely
+  on a hard-coded list of roles, models, providers, tools, modes, or optional
+  features; newly added capabilities should be considered automatically.
+- For every relevant capability, respect its reported availability, activation
+  state, invocation mode, constraints, dependencies, and readiness evidence.
+- Treat installed, configured, enabled, and callable as different states. Use a
+  capability only when the complete live execution path is ready.
+- Keep the capability snapshot for the current plan, and refresh it after a
+  relevant configuration change or an availability, routing, credential,
+  compatibility, or activation failure.
+- If discovery is unavailable or evidence is incomplete, fail closed: do not
+  invent capabilities or repeatedly dispatch blind retries. If DSH Crew was
+  selected for the task, apply the operator decision gate below.
+
+## Operator decision gate when DSH Crew is unavailable
+
+- Once Codex has selected DSH Crew for any work unit, any condition that makes
+  the required Crew capability unavailable or non-callable is a mandatory
+  pause point, regardless of cause.
+- At this pause point, do not continue implementation, silently fall back,
+  choose another execution path, or repair/reconfigure DSH Crew without new
+  operator direction. Perform only the read-only diagnosis needed to report
+  the blocker accurately.
+- Report the unavailable capability, bounded reason and evidence, and completed
+  work. Then wait for the operator to choose one direction:
+  1. Repair or restore DSH Crew, then continue through DSH Crew.
+  2. Do not repair DSH Crew; continue with the main Codex agent.
+- Resume only after the operator gives a new instruction. If repair is chosen,
+  verify live capability again before dispatch. If local execution is chosen,
+  state that the affected work is no longer independently delegated.
+- This gate applies only after DSH Crew has been selected or explicitly
+  requested. It does not force a pause when initial planning decides DSH Crew
+  provides no benefit and the task should remain with the main agent.
+
+## Decide what to delegate
+
+- Decompose the request into bounded work units before choosing an executor.
+- Match each unit against discovered capabilities. Use DSH Crew only where it
+  provides a clear execution, isolation, parallelism, specialization, or
+  independent-review benefit.
+- Delegate the smallest coherent unit that can be completed and verified
+  independently. Do not delegate an entire request merely because it is large.
+- Keep ambiguity, dependency ordering, cross-cutting decisions, conflict
+  resolution, external side effects, final integration, and user communication
+  in the main Codex agent.
+- Respect reported concurrency and isolation limits. Parallelize only
+  independent units with explicit, non-overlapping ownership.
+- Simple questions, explanations, small read-only inspections, and genuinely
+  trivial edits should normally remain in the main agent.
+- Explicit user instructions override default routing, but never safety or
+  capability boundaries.
+
+## Execute and verify
+
+- Give each delegated unit a concrete objective, owned scope, workspace
+  context, constraints, and required validation evidence.
+- Prefer isolated execution for code changes when supported. Review work must
+  remain read-only.
+- Consume compact structured results and canonical events. Do not move
+  unbounded transcripts, raw provider payloads, credentials, or unnecessary
+  patch content between agents.
+- The main agent must validate results, tests, changed scope, unresolved risks,
+  and completion state before accepting delegated work.
+
+## Review policy
+
+- Use available independent review for non-trivial code changes when its live
+  invocation policy permits automatic use or the user requests manual use.
+- Never bypass a manual, disabled, unavailable, or restricted review boundary.
+- Treat requested changes, incomplete structured results, or missing direct
+  evidence as not approved.
+- If selected DSH Crew review cannot run, apply the operator decision gate. The
+  main agent may review locally only after the operator selects that path.
+
+## Authority and completion
+
+- Delegation does not broaden authority. Publishing, pushing, messaging,
+  credential changes, account actions, destructive operations, and other
+  external effects still require authority from the user's request.
+- Do not present delegated work as complete until validation passes, structured
+  results are complete, integration is checked, and permitted review
+  requirements are satisfied or transparently reported as unavailable.

package/docs/installation.md

@@ -0,0 +1,63 @@
+# Installation plan
+
+DSH Crew uses an explicit installer. Merely installing the npm package does not mutate the host.
+
+## Recommended path
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
+dsh-crew integrate
+dsh-crew status
+```
+
+To test GitHub `main` before an npm release:
+
+```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
+node scripts/setup.mjs install
+node scripts/setup.mjs status
+```
+
+## Managed surfaces
+
+| Surface | Installed behavior | Uninstall behavior |
+| --- | --- | --- |
+| Crew runtime | Isolated in `~/.config/dsh-crew/harness`, profile: dsh-crew | Registration removed; config kept unless `--purge` |
+| Codex MCP and roles | Points Worker, Reviewer, and MCP to the installed release | Only DSH Crew entries are removed |
+| Global Codex policy | Managed block inside `~/.codex/AGENTS.md` | Only the managed block is removed |
+| ZCode MCP, agents and commands | Installs `~/.zcode/AGENTS.md`, `agents/{ds-worker,ds-reviewer}.md`, commands and a source-aware `dsh-crew` MCP entry | Only DSH Crew-owned files/entry are removed |
+| Windows login startup | `DSH Crew.vbs` plus a Crew-owned CMD launcher | Only those two managed files are removed |
+| Official 3080 UI | Optional lightweight bridge after `integrate` | `detach` removes the bridge; a backup is kept |
+
+The Windows login launcher starts the official UI on 3080 and the isolated Crew backend on 3210. It does not open a browser and does not store credentials.
+
+ZCode uses `~/.zcode/cli/config.json` when it already has native MCP servers. If
+that native list is empty, the installer uses `~/.agents/mcp.json`; unrelated
+servers are preserved and a conflicting unowned `dsh-crew` entry fails closed.
+
+## Verification
+
+```bash
+dsh-crew status
+dsh-crew inspect
+dsh-crew jobs list
+```
+
+Source checkout verification:
+
+```bash
+node --test test/*.test.mjs
+pnpm run build:client
+npm pack --dry-run
+```
+
+## Rollback
+
+```bash
+dsh-crew detach
+dsh-crew uninstall
+```
+
+Use `dsh-crew uninstall --purge` only when configuration and backups should also be deleted.

package/docs/ui-surfaces.md

@@ -12,7 +12,7 @@ management:
 - Worker and Reviewer policy
 - model priority, fallback, review, and adaptive routing
 - runtime and activation-boundary information
-- Codex and Claude installation actions and structured readiness
+- Codex, Claude, and ZCode installation actions and structured readiness
 - task status and bounded model-invocation summaries
 - the link to the underlying 3210 Crew Harness
 
@@ -44,4 +44,3 @@ the full control plane and never becomes `READY`.
 
 The split changes presentation only. Crew state, credentials, routing policy,
 and model execution remain isolated under the Crew-owned home and profile.
-