@ran-sh/dsh-crew 0.3.7 → 0.4.0

package/README.md

@@ -1,124 +1,109 @@
-<p align="center">
-  <img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
-</p>
+<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>Let Codex Desktop or Claude Code coordinate isolated DeepSeek Harness workers and reviewers.</strong></p>
+<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>
 
-## What you get
-
-- A `worker` for implementation, fixes, tests, and repository inspection.
-- A read-only `reviewer` with its own model priority.
-- Ordered provider/model routing for both roles.
-- Temporary Git worktrees by default, so workers do not edit your main workspace directly.
-- A live settings and jobs panel inside DeepSeek Harness.
-
-## Install
+## 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
 ```
 
-Use the global launcher. Transient `npx` execution is not the supported install path on npm versions affected by npm/cli#9870.
-
-## Start Harness
-
-Windows PowerShell:
-
-```powershell
-$env:DSH_HOME = "$HOME\.config\dsh-crew\harness"
-& "$env:DSH_HOME\runtime\node_modules\.bin\dsh.cmd" --profile dsh-crew --port 3210
-```
-
-macOS / Linux:
+Start the official Harness on port 3080 as usual:
 
 ```bash
-DSH_HOME="$HOME/.config/dsh-crew/harness" \
-  "$HOME/.config/dsh-crew/harness/runtime/node_modules/.bin/dsh" \
-  --profile dsh-crew --port 3210
+npx -y @deepseek-ai/dsh web --host 127.0.0.1 --port 3080
 ```
 
-Open <http://127.0.0.1:3210>, then go to **Settings → DSH Crew**.
+Open <http://127.0.0.1:3080> and go to **Settings → DSH Crew**. The official 3080 process displays the UI; Crew work stays in an isolated backend on `127.0.0.1:3210`, which the bridge starts in the background when needed.
 
 ## Configure
 
-1. Install the Codex and/or Claude Code integration.
-2. Click **Refresh Harness Models**.
-3. Order the models used by Flash and Pro.
-4. Keep `worker` on Auto for automatic delegation; keep `reviewer` on Manual unless you want automatic review.
-5. Use `worktree` isolation for coding tasks.
+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.
 
-The settings page is split into collapsible modules. Each closed module still shows its effective state and first-priority model.
+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.
 
-## Use
-
-Ask your coding host naturally:
+## 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 available, but new workflows should use `ds-worker` and `ds-reviewer`.
+Legacy `ds-flash` and `ds-pro` aliases remain compatible.
 
-## Check, update, remove
+## Results and reviews
 
-```bash
-dsh-crew status
-dsh-crew update
-dsh-crew uninstall
-```
+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.
 
-`uninstall` preserves configuration and backups. Add `--purge` only when you also want those removed.
+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).
 
-For launchers at `<= 0.3.3`, the old updater cannot discover newer releases and cannot be retroactively fixed. Refresh the launcher first, then update the managed payload:
+## Common commands
 
 ```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew update
+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
 ```
 
-## Isolation and source installs
+`dsh-crew uninstall --purge` also removes Crew configuration and backups.
 
-Crew owns a dedicated Harness home and profile:
+If you prefer a completely separate UI, run `dsh-crew detach`, then start the isolated profile directly:
 
-```text
-~/.config/dsh-crew/harness
-profile: dsh-crew
+```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
 ```
 
-Normal Crew operations do not modify `~/.dsh`, the official `web` profile, or official Harness credential stores.
-
-Developer install:
+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:
 
-```bash
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-node scripts/setup.mjs install
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
 ```
 
-Developer uninstall:
+For launchers at `<= 0.3.3`, first refresh the launcher because the old updater cannot discover newer releases and cannot be retroactively fixed:
 
 ```bash
-node scripts/setup.mjs uninstall
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew update
 ```
 
-## Development
+## Source development
 
 ```bash
-pnpm install --frozen-lockfile
+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
-pnpm run verify:npm-install
+node scripts/setup.mjs uninstall
 ```
 
-More detail: [Changelog](./CHANGELOG.md) · [Readiness matrix](./docs/readiness-matrix.md) · [Architecture](./docs/v0.3-architecture-roadmap.md)
+More detail: [Changelog](./CHANGELOG.md) · [Readiness matrix](./docs/readiness-matrix.md) · [Job contracts](./docs/job-contracts.md)
+· [GPT-first extension](./docs/gpt-relay-extension.md)
 
 ## License
 

package/README.zh.md

@@ -1,124 +1,108 @@
-<p align="center">
-  <img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
-</p>
+<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 统一调度隔离运行的 DeepSeek Harness Worker 与 Reviewer。</strong></p>
+<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>
 
-## 能做什么
+## 快速开始
 
-- `worker`：实现、修复、测试和仓库检查。
-- `reviewer`：使用独立模型顺序进行只读审查。
-- 为两个角色分别设置 Provider / Model 优先级。
-- 默认使用临时 Git worktree，不直接修改主工作区。
-- 在 DeepSeek Harness 中查看设置、进度和结果。
-
-## 安装
-
-需要 Node.js；worktree 隔离还需要 Git。
+需要 Node.js；使用 worktree 隔离还需要 Git。
 
 ```bash
 npm install -g @ran-sh/dsh-crew@latest
 dsh-crew install
+dsh-crew integrate
 ```
 
-请使用全局启动器。对于受 npm/cli#9870 影响的 npm 版本，临时 `npx` 不是受支持的安装方式。
-
-## 启动 Harness
-
-Windows PowerShell：
-
-```powershell
-$env:DSH_HOME = "$HOME\.config\dsh-crew\harness"
-& "$env:DSH_HOME\runtime\node_modules\.bin\dsh.cmd" --profile dsh-crew --port 3210
-```
-
-macOS / Linux：
+照常在 3080 端口启动官方 Harness：
 
 ```bash
-DSH_HOME="$HOME/.config/dsh-crew/harness" \
-  "$HOME/.config/dsh-crew/harness/runtime/node_modules/.bin/dsh" \
-  --profile dsh-crew --port 3210
+npx -y @deepseek-ai/dsh web --host 127.0.0.1 --port 3080
 ```
 
-打开 <http://127.0.0.1:3210>，进入 **Settings → DSH Crew**。
+打开 <http://127.0.0.1:3080>，进入 **设置 → DSH Crew**。3080 只显示官方界面；Crew 的任务与模型执行继续隔离在 `127.0.0.1:3210`，需要时由桥接在后台自动启动。
 
 ## 配置
 
-1. 安装 Codex 和/或 Claude Code 集成。
-2. 点击“刷新 Harness 模型”。
-3. 分别排列 Flash 与 Pro 的模型调用顺序。
-4. Worker 保持 Auto 即可自动委派；Reviewer 建议默认 Manual，需要自动复审时再开启。
-5. 编码任务建议使用 `worktree` 隔离。
+1. 点击“刷新 Harness 模型”。
+2. 分别设置 Worker 和 Reviewer 的模型顺序。
+3. Worker 保持 **Auto**，即可自动委派。
+4. Reviewer 默认 **Manual**；确实需要自动复审时再开启。
+5. 编码任务建议保持 **worktree** 隔离。
 
-设置页已按模块折叠；关闭后仍会显示当前状态和第一优先模型。
+只配置一个模型时，两个角色直接使用它。配置多个模型时，每个角色按自己的排序调用，失败后依次回退。设置模块可以展开/收起，收起后仍显示当前状态。
 
-## 使用
-
-直接告诉编码宿主：
+## 在 Codex 或 Claude 中使用
 
 ```text
 使用 ds-worker 实现这个改动并运行测试。
 使用 ds-reviewer 审查结果。
 ```
 
-旧的 `ds-flash`、`ds-pro` 别名仍兼容，但新工作流建议使用 `ds-worker`、`ds-reviewer`。
+旧的 `ds-flash`、`ds-pro` 别名仍可使用。
 
-## 检查、更新、卸载
+## 结果与复审信息流
 
-```bash
-dsh-crew status
-dsh-crew update
-dsh-crew uninstall
-```
+Crew 默认返回紧凑、机器可读的 Result Contract：状态、测试、改动文件、
+Reviewer 结论、模型选择轨迹、候选引用和规范化生命周期事件。Worker 的
+整段原始回答和完整 patch 不会在每次交接时重复传递；自动 Reviewer 只接收
+有大小上限的证据胶囊，并直接检查隔离工作区。
 
-普通卸载会保留配置和备份；只有确实要一起删除时才加 `--purge`。
+MCP 调用方如需排障或恢复，可以在 `dsh_run_worker` 或
+`dsh_worker_result` 中显式传入 `detail: "full"`。完整契约见
+[任务契约与信息流](./docs/job-contracts.md)。
 
-对于 `<= 0.3.3` 的旧启动器，旧 updater 无法发现更新版本，也无法被追溯修复。先刷新启动器，再更新托管载荷：
+## 常用命令
 
 ```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew update
+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 配置和备份。
 
-Crew 使用独立的 Harness home 和 profile：
+如果想继续使用完全独立的界面，先运行 `dsh-crew detach`，再直接启动隔离 profile：
 
-```text
-~/.config/dsh-crew/harness
-profile: dsh-crew
+```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
 ```
 
-正常操作不会修改 `~/.dsh`、官方 `web` profile 或官方 Harness 凭据存储。
-
-开发者安装：
+桥接首次修改前会备份官方 `web` profile，并且只注册轻量代理/客户端包。完整 Crew Hub、模型执行、配置和凭据仍位于：
 
-```bash
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-node scripts/setup.mjs install
+```text
+~/.config/dsh-crew/harness
+profile: dsh-crew
 ```
 
-开发者卸载：
+对于 `<= 0.3.3` 的旧启动器，请先刷新启动器；旧 updater 无法发现新版本，也无法被追溯修复：
 
 ```bash
-node scripts/setup.mjs uninstall
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew update
 ```
 
-## 开发
+## 源码开发
 
 ```bash
-pnpm install --frozen-lockfile
+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
-pnpm run verify:npm-install
+node scripts/setup.mjs uninstall
 ```
 
-详细资料：[Changelog](./CHANGELOG.md) · [Readiness Matrix](./docs/readiness-matrix.md) · [架构](./docs/v0.3-architecture-roadmap.md)
+更多资料：[Changelog](./CHANGELOG.md) · [Readiness Matrix](./docs/readiness-matrix.md) · [任务契约](./docs/job-contracts.md)
+· [GPT-first 扩展接入](./docs/gpt-relay-extension.md)
 
 ## License
 

package/docs/gpt-relay-extension.md

@@ -0,0 +1,103 @@
+# GPT-first extension integration
+
+DSH Crew is an optional DeepSeek Harness capability extension for Codex,
+Claude Code, ZCode, or another top-level executor. It is not itself a top-level
+executor and does not choose the next project-wide step.
+
+## Discover
+
+With the isolated Hub running on 3210:
+
+```bash
+dsh-crew inspect
+```
+
+The same versioned JSON is available at:
+
+```text
+GET http://127.0.0.1:3210/_dsh/dsh-crew/extension
+```
+
+An orchestrator should check `capabilities.deepseek.worker` or
+`capabilities.deepseek.reviewer`, then inspect `readiness.status` and its
+components. `DEGRADED` is not `READY`; a model catalog proves discoverability,
+not successful authentication or execution.
+
+## Dispatch and observe
+
+Codex and Claude normally call the six MCP tools. `dsh_run_worker` and
+`dsh_spawn_worker` accept the backward-compatible fields plus:
+
+- `job_id`: optional caller id, echoed separately from Crew's internal id.
+- `profile`: a Worker/Reviewer profile id.
+- `workspace`: per-job `repo_root`, `branch`, and `worktree` policy.
+- `constraints`: per-job timeout and fallback override.
+- `workspace_id`: a registered Workspace Context id.
+- `context_refs`: extra workspace-relative instruction references.
+
+Poll `dsh_worker_result` with `after_sequence` to receive only newer canonical
+events. HTTP consumers can use:
+
+```text
+POST /_dsh/dsh-crew/jobs
+GET /_dsh/dsh-crew/jobs/:id/contract?after=0
+GET /_dsh/dsh-crew/jobs/:id/events?after=0
+```
+
+CLI consumers use `dsh-crew jobs list|get|watch|cancel|submit`; `submit`
+accepts a versioned JSON Job Request through `--request`.
+
+The compact Contract is the automation surface. Full prose and patches require
+an explicit `detail=full` recovery/debug request.
+
+## Profiles
+
+Profiles live in `~/.config/dsh-crew/profiles.json`:
+
+```json
+{
+  "schema_version": 1,
+  "profiles": {
+    "worker-fast": {
+      "role": "worker",
+      "routing": "priority",
+      "isolation": "worktree",
+      "fallback": false,
+      "timeout_seconds": 300,
+      "review_strictness": "standard"
+    }
+  }
+}
+```
+
+The built-ins are `worker-default` and `reviewer-default`. The registry can be
+read or atomically replaced through loopback-only `GET/POST
+/_dsh/dsh-crew/profiles`. Invalid documents are rejected before replacement.
+
+## Workspace Context
+
+Workspace facts live in `~/.config/dsh-crew/workspaces.json`:
+
+```json
+{
+  "schema_version": 1,
+  "workspaces": {
+    "dsh-crew": {
+      "repo_root": "D:/work/dsh-crew",
+      "default_branch": "main",
+      "instruction_files": ["AGENTS.md"],
+      "validation_hints": ["node --test test/*.test.mjs", "pnpm run build:client"]
+    }
+  }
+}
+```
+
+Only bounded path references and hints cross the hand-off. Crew never copies
+instruction-file contents into the registry. Use loopback-only `GET/POST
+/_dsh/dsh-crew/workspaces` to read or atomically replace it.
+
+## Failure handling
+
+Every structured failure includes a `family` and `disposition`. Dispositions
+are `retry`, `fallback`, `human`, or `terminal` (`none` for success), allowing
+the GPT-first controller to decide the next step without parsing logs.

package/docs/job-contracts.md

@@ -0,0 +1,107 @@
+# Job contracts and information flow
+
+DSH Crew is a narrow bridge and scheduler. Codex or Claude owns the main task;
+Crew owns one delegated Worker/Reviewer workflow and reports auditable evidence
+back to the caller.
+
+## Information flow
+
+```text
+caller objective
+  -> Worker in isolated workspace
+  -> structured outcome + candidate reference
+  -> optional Reviewer inspects the workspace directly
+  -> compact Result Contract + canonical job events
+  -> caller
+```
+
+The Worker receives the complete delegated objective. After it finishes, Crew
+does not copy the Worker's raw prose or full patch into the Reviewer prompt.
+The Reviewer receives a bounded capsule containing the objective, reported
+changes/tests/risks, changed-file names, base revision, and candidate
+fingerprint. It opens the relevant files and runs `git diff` in the isolated
+workspace when deeper inspection is needed.
+
+The Hub keeps only the latest assistant message needed as the final Delivery
+Report. It does not retain an ever-growing list of intermediate assistant
+messages.
+
+## Canonical events
+
+Every workflow result can expose a versioned, ordered `canonical_events` list.
+Each event has `schema_version`, `event_id`, `job_id`, `sequence`, `type`, `at`,
+`role`, `attempt`, and bounded structured `data`.
+
+Supported event types (the allow-list is versioned; `approval.required` is
+reserved for a future approval broker and is not emitted by the current
+runtime):
+
+- `job.created`, `job.started`
+- `model.selected`, `model.fallback`
+- `worker.started`, `worker.completed`
+- `review.started`, `review.completed`
+- `approval.required`
+- `job.completed`, `job.failed`, `job.cancelled`
+
+Events never carry a candidate patch, raw provider payload, credential, or full
+assistant response. `event_cursor` identifies the latest event in status views.
+
+## Result Contract
+
+`dsh_run_worker` and `dsh_worker_result` default to `detail: "compact"`. Their
+`evidence` object contains:
+
+- `status`: `PASS`, `FAIL`, `PARTIAL`, or `BLOCKED`
+- structured execution/test/delivery/review summary
+- bounded model-selection trace
+- changed files, reported changes, tests, risks, and unverified checks
+- reviewer verdict and evidence when review ran
+- candidate fingerprint/base revision and workspace recovery state
+- bounded machine error code/message when execution failed
+
+Raw worker prose and candidate patch text are excluded. For an explicit debug
+or recovery operation, pass `detail: "full"`; this preserves the previous rich
+workflow view and adds the same evidence envelope.
+
+## Profiles, Workspace Context, and watch
+
+Both blocking and asynchronous MCP dispatch accept optional `job_id`, `profile`,
+`workspace`, `constraints`, `workspace_id`, and `context_refs` fields. The
+caller id is echoed as `client_job_id`; it never replaces Crew's internal id.
+Profiles control role-compatible
+routing, isolation, timeout, fallback, and review strictness. Workspace Context
+adds bounded project facts by reference; instruction file contents are opened by
+the Agent in the workspace rather than copied through the hand-off.
+
+`dsh_worker_result` accepts `after_sequence`. The response includes only newer
+`canonical_events` plus the current numeric `event_cursor`, so callers can watch
+long jobs without replaying the entire event history.
+
+The isolated Hub also exposes `/extension`, `/profiles`, `/workspaces`,
+`/jobs/:id/contract`, and `/jobs/:id/events`. All remain loopback-only.
+
+Per-job precedence is request `constraints` > Profile > session defaults.
+`workspace.branch` pins the isolated base revision; `workspace.worktree` accepts
+`auto`, `existing`, or `none`. Workspace preflight reports `READY`, `CONFLICT`,
+`READ_ONLY`, or `UNAVAILABLE` before dispatch.
+
+The CLI is a JSON projection of the same local HTTP surface:
+
+```text
+dsh-crew jobs list
+dsh-crew jobs get <job-id> --detail compact
+dsh-crew jobs watch <job-id> --after <sequence>
+dsh-crew jobs cancel <job-id>
+dsh-crew jobs submit --request job.json
+```
+
+## Compatibility boundary
+
+The internal legacy phase events remain in the explicit full view for current
+debug consumers. Canonical events and the compact Result Contract are the
+stable integration surface for new Codex, Claude, CLI, and HTTP consumers.
+
+This design borrows the useful boundary from
+[OpenMausBot](https://github.com/milind-soni/OpenMausBot)—a small provider
+contract and one normalized event stream—without adopting its desktop chat,
+bot roster, persona, connector, or general-purpose agent-platform scope.

package/docs/readiness-matrix.md

@@ -0,0 +1,73 @@
+# DSH Crew Readiness Matrix
+
+The readiness matrix is a conservative diagnostic surface for release and environment confidence. Its primary rule is simple:
+
+> Missing evidence is never PASS.
+
+The matrix is emitted by `hubStatus()` and is therefore visible inside the existing `dsh_worker_config` response under `hub_compatibility.readiness_matrix`.
+
+## Statuses
+
+- `PASS` — direct evidence confirms the row.
+- `FAIL` — a check actually ran and produced an incompatible or failed result.
+- `BLOCKED` — the check could not run because required infrastructure or authorization was unavailable.
+- `SKIP` — the row is intentionally not applicable for the active policy/path.
+- `NOT_RUN` — no trusted evidence has been supplied for the row.
+
+`BLOCKED` and `SKIP` are not failures. `NOT_RUN` is not success.
+
+## Evidence classes
+
+The matrix separates three kinds of evidence:
+
+1. `live-runtime` — facts the current process can directly observe, such as Hub reachability and protocol compatibility.
+2. `ci` — platform validation such as Linux deterministic, Windows regressions, and future macOS smoke.
+3. `real-execution` — provider/model and workflow behavior that requires a genuine DSH execution.
+
+Only live checks are populated automatically by the current runtime. CI and real-execution rows remain `NOT_RUN` until a trusted higher layer supplies explicit evidence.
+
+## Target rows
+
+- `linux_deterministic`
+- `windows_regressions`
+- `macos_smoke`
+- `hub_compatibility`
+- `provider_catalog`
+- `deepseek_flash`
+- `deepseek_pro`
+- `opencode_go_mimo_qwen`
+- `reviewer_pipeline`
+- `cancellation_timeout_escalation`
+- `standalone_official`
+
+## Provider/catalog rule
+
+The Hub client does not know the active worker provider mode, so its embedded matrix leaves `provider_catalog` as `NOT_RUN` with `PROVIDER_MODE_UNKNOWN` rather than guessing.
+
+When a higher layer knows the provider mode and has actually read the Harness catalog, it may build a more specific matrix:
+
+- DeepSeek Official strict mode: catalog row may be `SKIP` / `PROVIDER_CATALOG_NOT_REQUIRED`.
+- Follow-DSH with successful catalog read: `PASS` / `PROVIDER_CATALOG_RESOLVED`.
+- Follow-DSH with an attempted but failed catalog read: `FAIL` / `PROVIDER_CATALOG_UNAVAILABLE`.
+- Hub unavailable/incompatible before catalog access: `BLOCKED`, not `FAIL`.
+
+## Credential safety
+
+The matrix never reads or returns credential values, provider configuration payloads, quota data, pricing, cookies, tokens, or raw exception dumps. The standalone row defaults to `NOT_RUN` / `CREDENTIAL_STATUS_NOT_PROBED` unless an authorized real-environment validation explicitly reports evidence.
+
+## Trusted evidence
+
+`buildReadinessMatrix()` accepts an optional evidence map so CI/report aggregation can be added later without changing row semantics. Evidence can set only the existing status vocabulary. Invalid statuses are ignored rather than broadening the contract.
+
+An evidence record may contain:
+
+```json
+{
+  "status": "PASS",
+  "reason_code": "CI_GREEN",
+  "evidence_source": "github-actions",
+  "evidence_ref": "run-123"
+}
+```
+
+The matrix does not fetch or trust arbitrary remote data by itself. Loading and authenticating an evidence source is the responsibility of the higher layer that calls the builder.