Skip to main content
Glama
README.md
<p align="center">
  <img src="docs/assets/logo.svg" alt="codex-dsh-native-team logo" width="400">
</p>

<h1 align="center">codex-dsh-native-team</h1>

<p align="center">
  External GPT leadership for native DeepSeek Harness Agent Teams — powered by an MCP bridge.
</p>

<p align="center">
  <strong>English</strong> | <a href="README.zh-CN.md">简体中文</a>
</p>

<p align="center">
  <a href="https://github.com/asdstrind/codex-dsh-native-team/releases/tag/v1.8.0-rc.8"><img src="https://img.shields.io/badge/version-1.8.0--rc.8-blue.svg" alt="Version 1.8.0-rc.8"></a>
  <a href="https://github.com/asdstrind/codex-dsh-native-team/releases"><img src="https://img.shields.io/badge/status-pre--release-orange.svg" alt="Status: pre-release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/platform-Windows-0078D6.svg" alt="Platform: Windows">
  <img src="https://img.shields.io/badge/node-%3E%3D24-339933.svg" alt="Node.js 24 or newer">
  <img src="https://img.shields.io/badge/DSH-0.2.2--rc.3-4B32C3.svg" alt="Target runtime: DSH Desktop/Host 0.2.2-rc.3">
  <a href="https://github.com/asdstrind/codex-dsh-native-team/releases/tag/v1.8.0-rc.8"><img src="https://img.shields.io/badge/GitHub-release%20notes-181717.svg" alt="GitHub release notes"></a>
</p>

<p align="center">
  <a href="#documentation">Documentation</a> ·
  <a href="docs/INSTALLATION.md">Installation</a> ·
  <a href="https://github.com/asdstrind/codex-dsh-native-team/releases/tag/v1.8.0-rc.8">Release</a> ·
  <a href="docs/ARCHITECTURE.md">Architecture</a>
</p>

<p align="center">
  <img src="docs/assets/architecture.svg" alt="Architecture: an external GPT/Codex Lead calls the MCP bridge with its three tools, which routes to the native DSH team — a real Root Session with zero model requests and native workers using native tools, Global Skills and peer messaging; waits are event-driven and the Lead answers blockers and integrates the final result" width="920">
</p>

**An independent third-party open-source project.** It plugs into DeepSeek Harness; it is not a DeepSeek product and is not endorsed by DeepSeek. See [third-party notice](#third-party-notice).

## Why this project?

DeepSeek Harness (DSH) already ships a real Agent Team runtime: official Root and Worker sessions, a native task board, task dependencies, peer messaging, event waits, a Team UI and tool approvals. External GPT agents such as OpenAI Codex are strong planners, but they cannot use any of that without extra glue:

- **Harness context and skills are not reusable.** A worker's real tools, project skills, environment and session history live inside DSH. A generic external agent cannot borrow them.
- **External agents cannot drive the native task board or worker communication.** Task ownership, revisions, dependencies, peer messages and settled events are native state; an outer orchestrator that keeps its own board duplicates them and drifts.
- **Driving DSH as a "dumb model API" wastes the platform.** If you only call a model per step, you lose the native sessions, Team tools, approvals and visibility you already paid for.
- **Polling, manual coordination and redundant review add overhead.** A wrapper that polls for progress, hand-manages worker state and adds mandatory review gates costs Lead turns without improving the work.

The resolution is deliberately narrow: **Keep the native team. Replace the reasoning Lead.**

"Replace" means the external GPT takes over the Lead's decision duties — planning, decomposition, key decisions, coordination and final integration. The DSH Root session, the official Native Team Service, the task board, workers, messages, approvals and the Team UI are kept exactly as DSH provides them. The native Root is real and official, but performs **zero model inference**; native guards reject every Root model request. No custom multi-agent framework, worker backend, task-state machine or worktree orchestrator is introduced.

### Who owns what

| Concern | Owned by native DSH | Handled by the bridge / external Lead |
|---|---|---|
| Root Session and Lead authorization identity | Official Session/Agent APIs and Team membership | Bridge creates and binds the Root; never runs inference for it |
| Workers, sessions and execution | Official Subagent Runtime and Agent Team Service | Bridge requests spawn/reuse through official APIs |
| Task board, revisions and dependencies | Official native task board; revision is the only execution state | Lead expresses task intent; bridge maps it to official operations |
| Worker-to-worker communication | Native `list_agents` / `send_message` / `wait_agent` | Bridge observes the message stream only to surface blockers |
| Event delivery and wake policy | Official team/session event log | Bridge projects durable events into a cursor-based wait |
| Tool approvals and permissions | Official Auto Review, execution approvals, user authorization | Bridge never bypasses or auto-approves |
| Planning, decisions and final acceptance | — | External GPT Lead, with acceptance evidence recorded on completion |

### When it fits

- You already use DSH Desktop and want its native teams, task board, sessions, skills and approvals — not a parallel orchestration stack.
- You want an external GPT agent to act as the Lead: planning, decomposition, blocker decisions and final integration.
- You want single-worker and multi-worker delegation behind one small MCP surface, with synchronous event-driven waits instead of polling.
- You want worker output integrated directly by the Lead, without a mandatory reviewer or per-file sign-off.

### When it does not fit

- You need a stable 1.0 API promise. This is a release candidate tied to DSH's release-candidate team-mode and Native Subagent APIs.
- You need macOS or Linux support today, or DSH versions other than the tested **DSH Desktop/Host 0.2.2-rc.3**.
- You need OS-level isolation between workers. Native teams share one workspace; use git worktrees when isolation matters.

## Architecture

The bridge is one stdio MCP server, `deepseek_harness`, with exactly three tools. It routes every operation to the official DSH team-mode task board and Native Subagent runtime — the native team model is kept, not reimplemented.

<p align="center">
  <img src="docs/assets/architecture.svg" alt="Reference architecture: external GPT/Codex Lead, the deepseek_harness MCP bridge with three tools, the native DSH Root with zero model inference, native workers with native tools, Global Skills and peer messaging, and the event-driven return path" width="880">
</p>

The flow is:

- **Task dispatch.** The Lead delegates a substantial independent module. The bridge creates or reuses one native team for the exact Codex thread and workspace, creates an official native task, spawns or reuses a native worker and makes exactly one delivery.
- **Peer communication.** Workers talk to each other with the official `list_agents` / `send_message` / `wait_agent` tools. The Lead is not in the middle of ordinary coordination.
- **Blocker escalation.** A genuine blocker reaches the external Lead through the existing native message path, is persisted and deduplicated by the bridge, and wakes the Lead through the existing wait.
- **Wait wake.** The Lead waits synchronously on durable events. Task revision completion, real blockers, important authorizations, serious errors and integration readiness wake it early; routine progress is buffered and does not wake.
- **Completion.** Each completed task revision travels with a short worker summary; the Lead reads summaries, not partial source, while other work is still running.
- **Final integration.** When all necessary tasks and requested checks are complete, the Lead integrates directly, accepts the exact completed revisions, and confirms with `complete(evidence)`. A 90-day archive clock starts only after that explicit confirmation.

### Components

| Component | Where it runs | Responsibility |
|---|---|---|
| External GPT / Codex Lead | Outside DSH | Planning, decomposition, key decisions, blocker answers, final integration |
| `deepseek_harness` MCP server | stdio process launched by the MCP client | The three tools, thread ownership checks, workspace resolution, idempotent RPC |
| Native Team Host adapter (`dsh-codex-team-adapter`) | Loaded into DSH Desktop as an official plugin | Official team-mode and Native Subagent API calls, event capture, wait coordination, Root guards, external-Lead journal |
| Official DSH team-mode task board and Native Subagent runtime | DSH Host | Sessions, teams, tasks, messages, execution, approvals |
| DSH Root Session | DSH Host | Official Lead authorization container with zero model requests |

The MCP server and the adapter run in separate processes and talk over an authenticated loopback control channel: a private per-user directory, HMAC-signed requests bound to a nonce and timestamp, a single-writer lock and a signed response. The MCP server never receives a second credential scope and never shares observer credentials.

### Verified surface

- Version `1.8.0-rc.8`, tag `v1.8.0-rc.8`, validated on 2026-11-16 against DSH Desktop/Host `0.2.2-rc.3` on Windows.
- Exactly three MCP tools: `dsh_delegate_task`, `dsh_team`, `dsh_team_wait`.
- Adapter API `native-team-subagents-rc.3`; capabilities report `available: true`, `rootInference: "forbidden"`, `projectWorkspaces: true`, `rootDiscovery: "official-list-and-workspace-barrier"` and the full build fingerprint checked by the installer and readiness gates.
- Tested with Node.js 24 or newer (Node 24.15.0 and the DSH Desktop runtime 24.21.0) on Windows. No other platform or DSH version is claimed.
- Clean-tree verification: 220/220 automated tests passed (0 failed, 0 skipped, 0 cancelled); `node scripts/check-architecture.mjs` reports 24 source modules, three tools and 0 legacy backend dependencies.
- Reproducible build: rebuilding `native-team-plugin/dist/host.mjs` from the public release tree produced a byte-identical bundle with the same build fingerprint as the production-verified adapter.
- DSH Root: `rootModelRequests: 0` across 46 roots / 1,955 root events, with zero Root request headers and zero Root model responses.
- Real native-team acceptance on DSH 0.2.2-rc.3: single-Worker task result 42; dual-Worker native bidirectional messaging; an active `[codex:blocking]` question answered by `questionId` with the task resumed to completion; the Global `remotion-render` Skill loaded inside a Worker; the default wait contract verified (omitted `timeoutMs` → 1,500,000 ms) with early wakes; cold restart with 46 historical teams completed in 49.2 s with team, task, cursor and session preservation.
- Maintenance-window data preservation: 45 historical teams and 2,648 original events unchanged; 428 session files preserved.

### Design principles

- **Native state is authoritative.** Tasks, revisions, sessions, messages and preservation belong to official DSH services; the bridge keeps only external-Lead receipts, cursors and acceptance evidence.
- **Replace decisions, not infrastructure.** The external GPT owns planning and integration; the Root and Team internals stay official.
- **One thin surface.** Three tools, flat bounded schemas and a strict per-action field table keep the MCP contract small and reject irrelevant input early.
- **Fail closed, never bypass.** Unknown outcomes are reconciled, official approvals and user authorization remain authoritative, and unavailable native capabilities are refused rather than emulated.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for components, protocols, state ownership and enforcement details.

## What is new in v1.8.0-rc.8

RC.8 is the compatibility release for **DSH Desktop/Host 0.2.2-rc.3**. It keeps the native team model and migrates the adapter to the official Native Subagent API shipped in that runtime.

### Official Native Subagent API migration

DSH 0.2.2-rc.3 removed the legacy `agentTeams` membership/spawn/message/wait/interrupt methods that RC.7 depended on, so the RC.7 adapter fails initialization on 0.2.2-rc.3 with `TEAM_API_UNSUPPORTED` before it can read its team journal. RC.8 uses the official Native Subagent API instead:

- the native Root and its members are resolved with official `subagents.rootOf` / `subagents.listDescendants` calls;
- a Worker is created through an official `subagents.startActivation` call, and the returned child Session identity is the Worker identity;
- messages and interrupts use official `subagents.sendMessage` and `subagents.interrupt` calls.

The native team model is unchanged: one real Root Session, native Workers, the native task board and native peer messages. The bridge keeps its own event-driven wait coordinator; waits are not replaced by a different native wait tool.

### Team Mode is enabled explicitly and persisted

For a new team the bridge installs the zero-inference Root guards first, then enables official Team mode with the official setter. The setter appends the team-mode selection and waits for the session persistence flush, and the bridge waits for that barrier before reporting team creation as complete. Historical roots without an explicit selection are treated as enabled by the official projection; closed or empty historical roots are not switched on silently.

Read-only team views expose `teamModeEnabled`. A disabled team exposes no board, so an empty view is never used to complete or archive a team; explicit open, resume and delegate calls wait for the official mode selection to be persisted.

### Worker Session IDs are the native identity

The Worker Session ID — the official child Session identity returned by the activation — is the real identity used for assignment, directed messages and native delivery:

- active task ownership is recorded against the Worker Session ID; the persisted and returned ownership field remains `ownerId`, and the `owner` value used by `task-update` (`claim` / `reassign` / `edit`) is the Worker Session ID;
- native message relay reads the official sender Session ID, and directed replies pin the exact Worker;
- blocking answers pin `questionId` plus the Worker Session ID: a `questionId` carries the Worker Session ID, the stable question key and, where applicable, the task revision;
- historical Worker display names remain read-only aliases for existing Sessions. New Workers cannot duplicate an existing alias, and an ambiguous name requires the exact Session ID.

### Lifecycle and shutdown reliability

- Cold restore discovers readiness once per Root batch and validates the whole cohort with one official session list after all roots flush; a missing Root rejects the entire publication.
- Adapter shutdown preserves real disposal errors, keeps the error journal, waits for persistence and throws an aggregated error; a failed close does not release the transport or the control lock.
- Orphaned control ownership after an offline maintenance upgrade is reclaimed only when the owning process is actually gone.
- Async member discovery refreshes the synchronous readiness view only at command and event boundaries; no new polling loop was added.

## Key features

### Native DSH Agent Teams

Every team is a real DSH team: official Root and Worker sessions, one **shared native task board** with revisions and dependencies, native Team tools and Team UI. The bridge owns no second scheduling database; the official task revision is the only execution state.

### External GPT Lead

OpenAI Codex (or another MCP-capable external agent) is the sole Lead and final integrator. It plans, splits work, makes decisions, replies to blockers and integrates the result. The bridge ships instructions and next-action guidance with the MCP surface, so the external client does not depend on a separate plugin or on editing `AGENTS.md`.

### Zero-inference DSH Root

The DSH Root Session is created through the official `agents.create` path and bound to the project workspace with `Workspace.attachSession`. It is a real native Lead authorization container, but its model requests are forbidden by Agent-lifetime and global guards; native messages that settle on the Root are rejected before inference. `snapshot` reports `rootModelRequests` and `blockedRootRequests` so the zero-inference property is observable.

### Single- and multi-worker teams

One worker and many workers use the same official team, task board and wait system. There is no separate "single-agent mode". A single-worker delegation is simply a team with one native task; a multi-worker team is the same mechanism with several tasks, dependencies and peer messages.

### Event-driven waiting

`dsh_team_wait` is a durable event wait, not a polling loop and not a heartbeat stream. Normal waits omit `timeoutMs`: the default is 25 minutes (1,500,000 ms), the host maximum is 3,600,000 ms and the managed MCP timeout is 3900 s. Results distinguish `requested_timeout_ms` (null when omitted), `effective_timeout_ms` and `recommended_next_wait_ms`. `after` and `afterWake` acknowledge ordinary replay pages and priority events separately, so unacknowledged events are never silently dropped.

### Proactive blocker escalation

Introduced in v1.8.0-rc.7, refined in RC.8. A worker that hits a genuine blocker uses its existing `send_message`, with a first line such as `[codex:blocking id=stable-key task=task-2]` sent to `target="lead"`. The bridge validates the native sender, task ownership and current revision, persists the question, and wakes the external Lead through the existing wait. The Lead replies through the existing `send` operation with the matching `questionId` and the exact Worker selector; RC.8 pins the answer to the Worker Session ID and the current task revision. Stale or uncertain questions can only be explicitly cancelled (`questionAction: "cancel"`), never replayed. No fourth MCP tool and no parallel communication service were added.

### Native worker-to-worker communication

Workers depend on each other directly through the official `list_agents`, `send_message` and `wait_agent` tools. Dependencies do not route through the external Lead, and one clear interface answer is enough; the bridge does not add repeated acknowledgements or mutual-approval loops.

### Global Skills integration

Introduced in v1.8.0-rc.7 and available in RC.8. The managed worker preset mounts the official skill filesystem and tool-skill components with the same scope as the worker, so the native skill catalog and `skill` loader are available: workers discover Global/Project Skills and load Skill bodies on demand through the official `skill` tool. Project `.dsh/skills` and `.agents/skills` take precedence over user-level directories; name overrides and `disable-model-invocation` are handled by the official registry. Skill recommendations use catalog directory metadata only — zero model calls, no skill-body scanning. Skills installed only under Codex skill directories are not automatically visible to DSH workers.

### Risk-based review

No default reviewer, no mutual approval, no per-file sign-off. Independent review is used only for security/permission/data-corruption risk, core algorithm or interface complexity, design conflicts, insufficient checks, or when the Lead explicitly requests it. Review evidence is pinned to the exact completed revision, and the reviewer must not be the implementer. The Lead accepts the exact completed revision.

### Direct final integration

The external Lead integrates directly after the first round: it fixes clear, local, low-risk defects and runs the affected checks. `integration_ready` means the recorded board is ready for review — it never means auto-acceptance. Completed tasks can precede worker settlement, so the Lead integrates first instead of waiting for closing text.

### Persistent team sessions

Teams, workers, task revisions, messages, reviews and cursors are persisted native state. The bridge keeps only the external Lead identity binding, idempotent receipts, explicit dispatch intents, event cursors and acceptance evidence. Completed and quiescent teams are archived after 90 days through the official APIs; existing native sessions, messages and task history are preserved.

## How it works

<p align="center">
  <img src="docs/assets/workflow.svg" alt="Seven-step sequence: plan, create native team, workers execute, Lead waits, event wake, Lead decisions, final integration" width="920">
</p>

1. **Plan.** The external GPT turns the user request into a short plan with independent modules, write scopes, dependencies and verification checks.
2. **Create the native team.** It calls `dsh_delegate_task` (or `dsh_team` with `action: "open"`). The bridge resolves the exact workspace, creates or reuses the official team, and spawns or reuses native workers.
3. **Workers execute natively.** Each worker runs in its own DSH session with real tools, native permissions, Global/Project Skills and peer messaging. Workers implement, run the affected checks and report a short result.
4. **The Lead waits.** The Lead finishes necessary dispatches and Lead actions, then calls `dsh_team_wait` and omits `timeoutMs`. The call blocks quietly for up to the default 25 minutes.
5. **A meaningful event wakes it.** A completed task revision, a blocker, an important authorization, a serious error or overall integration readiness returns from the wait with the relevant event and cursor. Routine progress and ordinary messages are buffered.
6. **The Lead decides.** It reads the short summary, answers the blocker with the existing `send` + `questionId`, schedules dependent work, and waits again with `after=nextCursor` and `afterWake=nextWakeCursor`.
7. **Final integration.** When all necessary tasks and requested checks are complete, the Lead integrates directly, accepts the current completed revisions, acknowledges events with `timeoutMs=0`, and calls `dsh_team complete(evidence)` once workers are inactive.

While workers are running, the Lead stays quiet: it reads completion summaries and task state, not partial source or diffs, and it does not emit periodic progress narration or routine snapshots. If the outer wrapper yields during a long wait, the Lead resumes the same pending wait with the longest blocking interval the client supports, without starting a second wait. A timeout with no blocker or necessary action is followed immediately by another wait using `after=nextCursor` and `afterWake=nextWakeCursor`.

In the v1.8.0-rc.8 acceptance run (2026-11-16) against DSH Desktop/Host 0.2.2-rc.3, a real Codex CLI session using default waits exercised a single-Worker task (result 42), dual-Worker native bidirectional messaging, an active `[codex:blocking]` question answered through `questionId` with the task resumed to completion, a Global Skill loaded inside a Worker, and a cold restart in 49.2 s with teams, tasks, cursors and sessions preserved. The Root recorded zero model requests. These are observed samples from one release validation, not performance guarantees.

## Real UI in this release

The native UI is DSH's own Team UI: the shared task board with task owners, write scopes and statuses, the worker/subagent catalog, and each worker's own DSH session. These are unmodified DSH surfaces — the bridge does not add a parallel UI.

<p align="center">
  <img src="docs/assets/native-team-board.png" alt="Real DSH Desktop native Agent Team panel showing four native members (lead, docs-worker, visual-worker, audit-worker) with live run states, above three shared native tasks with owners, write scopes and completed or in-progress statuses" width="620">
</p>

<p align="center"><sub><strong>Native team panel, captured from the live DSH Desktop window</strong> during the v1.8.0-rc.7 validation (2026-11-12). Four native members and three shared tasks on the real DSH task board; the bridge renders none of this UI. These captures are kept unchanged for RC.8 and were not re-captured.</sub></p>

<table>
  <tr>
    <td width="50%" align="center"><img src="docs/assets/native-team-workers.png" alt="Native DSH subagent catalog: lead, docs-worker, visual-worker and audit-worker with live run states" width="360"></td>
    <td width="50%" align="center"><img src="docs/assets/worker-activity.png" alt="Native DSH shared task board: three tasks with owners, write scopes and completed or in-progress statuses" width="360"></td>
  </tr>
  <tr>
    <td align="center"><sub>Native member catalog with live run states.</sub></td>
    <td align="center"><sub>Shared native task board: owner, write scope and status.</sub></td>
  </tr>
</table>

These are real captures cropped to the Team panel; the surrounding DSH sidebar and conversation were removed because they contained unrelated private workspaces. They are not mockups or reconstructed UI states.

## Quick start

This section is Windows-only and intentionally short. The full guide — prerequisites, installation details, MCP registration, upgrade, uninstall and troubleshooting — is in [docs/INSTALLATION.md](docs/INSTALLATION.md).

### 1. Prerequisites

- **Windows.** Windows is the tested and supported platform for this release.
- **Node.js 24 or newer** on `PATH` (`node --version`).
- **DSH Desktop/Host 0.2.2-rc.3** with the standard official Desktop base and web-app profile bundles and the official `auto` review permission preset loaded. Other DSH versions are not tested and are rejected either by the installer or by the adapter at runtime; the RC.7 adapter does not work on 0.2.2-rc.3 (see [Compatibility and upgrade](#compatibility-and-upgrade)).
- **An external MCP-capable client** (primarily OpenAI Codex) installed and signed in, so `%USERPROFILE%\.codex\config.toml` exists.
- An **absolute workspace directory** for the project the team will work in.
- The installer refuses to overwrite an existing installation. Existing installations need the offline maintenance upgrade, not `install.ps1` (see [Compatibility and upgrade](#compatibility-and-upgrade)).

### 2. Download and prepare the bridge package

Download the release artifacts from the [v1.8.0-rc.8 release](https://github.com/asdstrind/codex-dsh-native-team/releases/tag/v1.8.0-rc.8):

- `dsh-mcp-bridge-1.8.0-rc.8.zip` — the full source and build tree (it also carries the prebuilt adapter package under `packages/`)
- `dsh-codex-team-adapter-1.8.0-rc.8.tgz` — the native DSH adapter plugin
- `SHA256SUMS-1.8.0-rc.8.txt` — SHA-256 checksums for both assets

Extract the bridge package into an empty directory (the archive has no wrapper folder) and verify it before installing:

```powershell
Expand-Archive -Path .\dsh-mcp-bridge-1.8.0-rc.8.zip -DestinationPath C:\path\to\bridge
cd C:\path\to\bridge
npm ci --ignore-scripts
npm test
npm run build
```

`npm test` runs the automated suite (220 tests in this release). `npm run build` rebuilds `native-team-plugin/dist/host.mjs`. Internet access is needed for `npm ci`.

### 3. Install the adapter and register the MCP server

Run the installer from the extracted bridge package. It copies the bridge into a clean install directory, installs and loads the native adapter in the DSH Desktop profile, waits for adapter health, and registers the managed Codex MCP block:

```powershell
.\scripts\install.ps1 -Workspace C:\path\to\your\workspace -Archive C:\path\to\dsh-codex-team-adapter-1.8.0-rc.8.tgz
```

Add `-Write` to allow implementation work in the shared workspace (workspace-write). Without it, new teams are **read-only**:

```powershell
.\scripts\install.ps1 -Workspace C:\path\to\your\workspace -Archive C:\path\to\dsh-codex-team-adapter-1.8.0-rc.8.tgz -Write
```

The install directory defaults to `%USERPROFILE%\dsh-mcp-bridge` and must not already exist. Pass `-InstallDir <absolute empty directory>` to choose another location. The team permission selected at install/open time is immutable for that team.

A successful installation leaves behind:

- the bridge package in the install directory (`src/`, `scripts/`, `test/`, `native-team-plugin/`, `package.json`, `bridge.config.json` and `installation.json`);
- the `dsh-codex-team-adapter` plugin row in the DSH Desktop profile (`%USERPROFILE%\.dsh\profiles\desktop`), with the private control directory `%USERPROFILE%\.dsh\bridge-team`;
- a managed MCP block for `deepseek_harness` in `%USERPROFILE%\.codex\config.toml`;
- no changes to unrelated DSH profile rows, other MCP servers or official profile bundles.

### 4. Verify

From the install directory, check that the native adapter is healthy:

```powershell
cd "$env:USERPROFILE\dsh-mcp-bridge"
node src/cli.mjs doctor
```

`doctor` probes the native DSH Host only. It should report `"available": true`, version `1.8.0-rc.8`, `"backend": "native-agent-team"`, `"api": "native-team-subagents-rc.3"` and `"rootInference": "forbidden"`, plus the build fingerprint. Open a new Codex session (or reconnect the MCP connection) so the managed `deepseek_harness` server loads the v1.8.0-rc.8 tool schema. An existing Codex Desktop stdio connection can cache the previous schema until it reconnects.

### 5. First single-worker delegation

In Codex, describe the work and let it use the native team. For example:

```text
Use the deepseek_harness native team to implement this module:
<your task description>.
Delegate it with dsh_delegate_task, wait for the native task with dsh_team_wait
(omit timeoutMs), then verify the result and integrate it yourself.
```

The corresponding first call looks like:

```json
{
  "requestId": "first-module",
  "prompt": "Implement <module> in this workspace. Run the affected checks and report a short result.",
  "permission": "workspace-write",
  "writeScopes": ["src/<module>/"]
}
```

When `workspace` is omitted, the bridge resolves the project from the exact Codex thread (host metadata, rollout metadata and the latest `turn_context`), never from the MCP launch directory. If that evidence cannot be verified, pass an absolute `workspace` explicitly.

What a normal first delegation looks like:

- `dsh_delegate_task` returns `teamId`, `taskId`, `workerId`, `sessionId` and `cursor`; `workerId` and `sessionId` are the Worker Session ID — the native identity used for ownership and directed messages;
- the worker starts in its own native DSH session and runs the task with native tools;
- `dsh_team_wait` blocks until a meaningful event, then reports the wake kind and the replay page cursors;
- a completed task revision wakes the Lead with a short summary (no partial source review);
- after integration and acceptance of the completed revision, the Lead confirms the team with `complete(evidence)` once workers are inactive.

### 6. Multi-worker team

Ask Codex to split a larger change into independent modules with disjoint write scopes and explicit dependencies:

```text
Plan this change as several independent native tasks with disjoint write scopes.
Delegate each with dsh_delegate_task, keep the native dependencies between them,
wait with dsh_team_wait until all recorded tasks are complete, then integrate and
run the affected checks. Do not add a default reviewer.
```

Multi-worker is the same native team with more tasks and workers; workers coordinate over native peer messages and the Lead waits on the same durable event stream. See [docs/INSTALLATION.md](docs/INSTALLATION.md#11-multi-worker-team) for the walkthrough and [Available MCP tools](#available-mcp-tools) for the control surface.

### Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Install reports unsupported Team API | DSH Desktop/Host is not `0.2.2-rc.3`, or the standard Desktop base/web-app profile bundles are not loaded | Use the tested DSH version and its standard official Desktop profile |
| Install rejects the profile | Official RC.3 Desktop base/web-app profile bundle missing | Install/reinstall DSH Desktop `0.2.2-rc.3` so its standard profile bundles are present |
| `TEAM_API_UNSUPPORTED` at adapter startup | An RC.7 adapter is installed on DSH `0.2.2-rc.3`; the legacy `agentTeams` methods RC.7 needs were removed | Upgrade to the RC.8 adapter; RC.7 cannot initialize on `0.2.2-rc.3` (see [Compatibility and upgrade](#compatibility-and-upgrade)) |
| Upgrade preflight exits non-zero with blockers | Fail-closed inspection by design: a maintenance-window condition is unresolved | Resolve the listed blockers and run the supervised offline maintenance upgrade; there is no online auto-upgrade |
| `TEAM_AUTO_REVIEW_REQUIRED` | Official Auto Review is not loaded | Enable Auto Review; the adapter will not bypass approvals |
| `TEAM_WRITE_DISABLED` | The team is read-only or the installation did not enable writes | Reinstall/first-open with `-Write`; an existing team's permission cannot be widened later |
| `WORKSPACE_REQUIRED` / `resolve_missing_workspace` | The workspace could not be verified from the Codex thread | Pass an absolute `workspace`, or start the Codex thread in the project |
| Codex shows old tool schema or missing tools | The long-lived MCP connection cached the previous schema | Reconnect the MCP server or start a new Codex session |
| `doctor` fails or times out | DSH Desktop is not running or the native adapter is not loaded | Start DSH Desktop, then rerun `doctor`; use the repair step if needed |
| Wait returns routine events but no wake | Normal design: routine progress is buffered | Continue waiting with `after=nextCursor` and `afterWake=nextWakeCursor`; use `timeoutMs=0` only to page events |

## Compatibility and upgrade

### RC.8 with DSH 0.2.2-rc.3 — and why RC.7 cannot run there

RC.8 targets **DSH Desktop/Host 0.2.2-rc.3** exactly. The RC.7 adapter is **not compatible** with 0.2.2-rc.3: RC.7 requires legacy `agentTeams` methods that 0.2.2-rc.3 removed, so RC.7 adapter initialization fails with `TEAM_API_UNSUPPORTED` before it can read its team journal. For a 0.2.2-rc.3 runtime, install or upgrade to RC.8. RC.8 does not run on older DSH runtimes that lack the official Native Subagent API.

Do not mix versions: keep one adapter version in the DSH Desktop profile. The installer/readiness gates compare the full expected build fingerprint and require the adapter archive to be byte-equal to the reviewed build.

### Safe offline maintenance upgrade

`install.ps1` deliberately refuses to overwrite an existing installation; an existing RC.7 installation cannot be upgraded by rerunning it. The RC.8 upgrade is a supervised **offline maintenance cutover** and runs only inside an exclusive maintenance window, while DSH Desktop/Host is fully exited:

1. **Read-only preflight.** The release tooling fails closed rather than guessing. Inspection is read-only and changes no files:

   ```powershell
   node scripts\deploy-team-release.mjs --check --offline
   ```

   It inspects the external-Lead journal shape, event acknowledgements, request/dispatch state, process and lock owners, unknown/diagnostic branches and persistence drift, and reports blockers. Online apply is refused by design; there is no online auto-upgrade command.
2. **Offline cutover.** `scripts/offline-upgrade.mjs` provides `inspect`, `backup` and `apply` modes and runs only in the official offline maintenance mode through `scripts/run-official-maintenance.mjs`. The apply path:

   - requires a real official clean exit plus the official `sessionPersistence.flush()` barrier receipt;
   - holds kernel single-writer Session write leases together with the Profile lock, the Adapter control lock and storage locks;
   - creates a full consistency backup and verifies it: byte-level manifests are re-hashed, official readers validate the backup copy, and journal/team/session semantics are checked; drift is rejected before any file swap;
   - installs only the reviewed RC.8 build, verifies the installed bundle byte-for-byte, and re-checks the managed MCP surface and the three tools.
3. **Recovery.** Recovery is **same-version program-level forward repair**: keep the latest official sessions, teams, cursors and configuration, and re-apply the same reviewed RC.8 build under the offline gate. There is **no automatic rollback**, and cross-version downgrade is **unsupported**; an RC.7 adapter is not a working recovery target on 0.2.2-rc.3. The maintenance backup is evidence for that window, not a cross-version restore.

The operator commands for that window (every flag is implemented by `scripts/offline-upgrade.mjs`; placeholders are absolute paths):

```powershell
# Read-only business inspection (safe while the maintenance owner holds the locks)
node scripts\run-official-maintenance.mjs scripts\offline-upgrade.mjs inspect --bindings <bindings.mjs> --archive-file <app.asar>

# Backup after the official clean exit and the persistence flush receipt
node scripts\run-official-maintenance.mjs scripts\offline-upgrade.mjs backup --bindings <bindings.mjs> --archive-file <app.asar> --backup <new-backup-dir> --exit-receipt <exit-receipt.json> --flush-receipt <persistence-flushed.json>

# Cut over to the reviewed RC.8 build
node scripts\run-official-maintenance.mjs scripts\offline-upgrade.mjs apply --bindings <bindings.mjs> --archive-file <app.asar> --backup <verified-backup-dir> --source <reviewed-source-export> --archive <dsh-codex-team-adapter-1.8.0-rc.8.tgz> --bridge-node <node.exe> --original-patch <pre-maintenance-patch.yml>
```

The exact prerequisites (official maintenance bindings, real exit/flush receipts, reviewed source export) and the full supervised procedure are documented in [docs/INSTALLATION.md](docs/INSTALLATION.md).

## Available MCP tools

The server registers exactly three tools. Discovery is built in: `dsh_team({ "action": "capabilities" })` reports the native backend, version, build fingerprint, API (`native-team-subagents-rc.3`), wait bounds and lifecycle support, and `dsh_team({ "action": "help" })` returns the field-level help text. For a model catalog, use `dsh_team({ "action": "capabilities", "view": "models" })`.

### `dsh_delegate_task`

One unit of work on the official native team. Required: `requestId`, `prompt` (up to 16,000 characters). Repeated calls with the same `requestId` are idempotent; an interrupted admission becomes unknown and is reconciled, never replayed blindly. Task ownership is native: the Worker Session ID is the owner identity.

| Field | Required | Meaning |
|---|---|---|
| `requestId` | yes | Stable idempotency key for this delegation (letters, digits, `_`, `-`) |
| `prompt` | yes | Goal, scope, constraints and checks for the worker |
| `workspace` | no | Absolute project path; when omitted, resolved from the exact Codex thread |
| `teamId` | no | Reuse an existing team you own instead of resolving/creating one |
| `target` / `name` | no | `target` selects an existing idle Worker by Session ID or historical display alias; `name` names a new Worker; provide only one of them |
| `taskId` + `expectedRevision` | no | Pinned rework of a known native task; both fields are required together |
| `subject` | no | Short native task subject (up to 200 characters) |
| `provider` + `model` + `reasoningEffort` | no | Explicit native model route; `provider` and `model` are both required if either is set |
| `permission` | no | `read-only` (team default) or `workspace-write`; a team's grant is immutable |
| `writeScopes` | no | Workspace-relative paths or globs; collaboration hints, not locks |

```json
{
  "requestId": "first-module",
  "prompt": "Implement <module> in this workspace. Run the affected checks and report a short result.",
  "permission": "workspace-write",
  "writeScopes": ["src/<module>/"]
}
```

### `dsh_team`

Official native team control. `snapshot` includes members, tasks, dispatches, reviews, questions, readiness, lifecycle, root-inference counters and `teamModeEnabled`. Mutating actions need a stable `requestId`; fields not owned by an action are rejected before any host call.

| Action | Purpose | Key fields |
|---|---|---|
| `open` | Create or reopen the deterministic team for this thread + workspace | `requestId`, optional `workspace`, `permission` |
| `snapshot` | Read the current native board, questions, readiness, mode and counters | `teamId` |
| `spawn` | Spawn an extra native worker | `teamId`, `requestId`, `name`, `description`, `prompt`, `provider`, `model` |
| `configure` | Change a worker's model route | `teamId`, `requestId`, `target`, `provider`, `model` |
| `send` | Message a Worker by Session ID or historical alias; reply to a blocker with `questionId` (`questionAction: "cancel"` withdraws a stale/uncertain question) | `teamId`, `requestId`, `target`, `prompt`, `questionId` |
| `interrupt` / `stop` / `resume` | Native interruption, admission stop and explicit resume | `teamId`, `requestId`, `target` (interrupt only) |
| `task-create` / `task-get` / `task-update` | Native task board operations with revisions and dependencies; the `owner` value for `claim` / `reassign` / `edit` is the Worker Session ID | `taskId`, `expectedRevision`, `taskAction`, `owner` |
| `dispatch` / `cancel-dispatch` | One explicit native delivery to a worker/task pair | `taskId`, `target`, `prompt` |
| `review` | Record acceptance or rejection pinned to a completed revision | `taskId`, `expectedRevision`, `outcome`, `evidence` |
| `complete` | Final confirmation after integration and quiescence | `evidence` |
| `archive` / `restore` | Official archive or restore of Root + workers | `teamId`, `requestId` |
| `requests` | Inspect the external-Lead idempotency journal | `teamId`, optional `requestId` |
| `capabilities` / `help` | Discovery: backend, version, build fingerprint, API, wait bounds, lifecycle support, field help | optional `view` (`summary` or `models`) |

Reply to a blocker question with the existing `send` action. In RC.8 the answer must target the exact Worker (Session ID or historical alias) and carry the pending `questionId`, which pins the Worker Session ID and the original task revision:

```json
{
  "action": "send",
  "teamId": "<teamId returned by dsh_delegate_task>",
  "requestId": "answer-blocker-1",
  "target": "<Worker Session ID from snapshot.questions.workerId, or the historical worker name>",
  "questionId": "<questionId from snapshot.questions or wait.wakeEvents>",
  "prompt": "Use the provided input file. Do not synthesize a replacement."
}
```

### `dsh_team_wait`

Durable event wait shared by single-worker and multi-worker teams.

| Field | Required | Meaning |
|---|---|---|
| `teamId` | yes | Team to wait on |
| `after` | no | Cursor for the ordinary replay page; default `0` |
| `afterWake` | no | Explicit acknowledgement of prior priority events (`nextWakeCursor`); default `0` |
| `limit` | no | Replay page size, 1–100; default `50` |
| `kinds` | no | Optional event-kind filter: `message`, `settled`, `task`, `member`, `error`, `dispatch`, `control` |
| `timeoutMs` | no | Omit for normal waits; default 1,500,000 ms (25 min), max 3,600,000 ms (1 h) |
| `waitId` / `cancelWaitId` | no | Stable wait identity and explicit cancellation of a prior wait |

```json
{
  "teamId": "<teamId returned by dsh_delegate_task>",
  "after": 0,
  "afterWake": 0
}
```

A result distinguishes `requested_timeout_ms` (null when omitted), `effective_timeout_ms`, `recommended_next_wait_ms`, `nextCursor` and `nextWakeCursor`, and includes `wakeKind`, `wakeEvents` (not hidden by `kinds` or `limit`), `readiness` and `phase`. Omit `timeoutMs` for normal waiting: the effective default is 1,500,000 ms (25 minutes). Short explicit waits are for diagnostics, non-blocking checks or a user request — not routine polling. `timeoutMs: 0` pages events without blocking. Cancelling a wait or losing the connection releases only the wait; it never stops workers.

## Current limitations

This is a release candidate. Read these before adopting it:

- **RC / pre-release quality.** This is not a stable 1.0 release; APIs and behavior may change between release candidates.
- **Compatibility is exactly what was tested:** DSH Desktop/Host `0.2.2-rc.3`, Node.js 24 or newer, Windows. No macOS/Linux or other-DSH-version support is claimed. The RC.7 adapter does not run on 0.2.2-rc.3 (see [Compatibility and upgrade](#compatibility-and-upgrade)).
- **No automatic rollback and no supported cross-version downgrade.** Recovery is same-version program-level forward repair with a reviewed RC.8 build; an earlier adapter is not a recovery target on 0.2.2-rc.3.
- **DSH Root zero-inference does not mean total token cost is zero.** Workers and the external GPT still consume tokens; no token-saving or controlled token-reduction claim is made.
- **The outer Codex client/wrapper may still incur its own model-continuation cost during long waits.** The MCP server cannot control the client's scheduling or model calls.
- **The full 25-minute wall-clock timeout expiry was not awaited in acceptance.** The wait contract (1,500,000 ms default, 3,600,000 ms maximum) and early wakes were verified.
- **UI screenshots were not re-captured for RC.8.** The images on this page are kept from the RC.7 validation and document native DSH UI; they are not new RC.8 captures.
- **The HMR full chain was not re-validated** in the production maintenance window.
- **The recovery drill did not inject a Host-startup failure.** It covered removing and re-applying the same RC.8 program build, not a failed Host start.
- **Auto-archive remains; automatic delete is not implemented.** Completed and quiescent teams can auto-archive after 90 days, but automatic delete is not implemented and the official DSH API has no session-delete operation. Archive and delete are different features.
- **Skills installed only under Codex skill directories are not automatically visible to DSH workers.** They need to be installed into the native DSH skill scope.
- **An existing Codex Desktop stdio MCP connection may cache the previous tool schema** until the connection reconnects or a new session is opened.
- **Workers share one workspace:** `writeScopes` are collaboration hints, not file locks, and official Auto Review is not an OS sandbox. Use separate git worktrees when isolation is required.

## Documentation

- [Installation](docs/INSTALLATION.md) — verified Windows installation, Codex MCP registration, model configuration, single- and multi-worker walkthroughs, troubleshooting, upgrade and uninstall.
- [Architecture](docs/ARCHITECTURE.md) — components, data flow, wait and blocker protocols, session ownership, zero-inference enforcement, workspace mapping and limitations.
- [Release notes v1.8.0-rc.8](docs/RELEASE_NOTES_v1.8.0-rc.8.md) — what changed in this release, with a Chinese summary.
- [Changelog](CHANGELOG.md) — version history.
- [Contributing](CONTRIBUTING.md) and [Security policy](SECURITY.md).

### Repository layout

```text
.
├── README.md, README.zh-CN.md      this file and the Chinese translation
├── CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, THIRD_PARTY_NOTICES.md, LICENSE
├── docs/
│   ├── ARCHITECTURE.md             internals: components, protocols, ownership
│   ├── INSTALLATION.md             verified install, registration, upgrade, uninstall
│   ├── RELEASE_NOTES_v1.8.0-rc.8.md
│   └── assets/                     diagrams, project logo and real UI captures
├── src/                            MCP server, native team host, wire/auth, wait, guidance
├── native-team-plugin/             DSH Desktop adapter plugin (built with esbuild)
├── scripts/                        install, verify, repair, maintenance/offline-upgrade, release gates and uninstall tooling
├── test/                           automated test suite
├── bridge.config.json              native backend enablement
└── package.json
```

## License

This project's own code is licensed under the **MIT License**. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for third-party components. Copyright (c) 2026 asdstrind.

## Third-party notice

This is an **independent third-party open-source project**. It is **not** a DeepSeek official product and is **not** endorsed by DeepSeek. DeepSeek Harness (DSH) is an MIT-licensed product/platform of DeepSeek; this project plugs into its official release-candidate team-mode and Native Subagent APIs without modifying DSH. OpenAI Codex and Codex CLI are products of OpenAI; this project is not affiliated with OpenAI either. The project relies on the official DSH team-mode task board and Native Subagent runtime and does not modify, bypass or replace official permissions, approvals or source code.

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). For security reports, see [SECURITY.md](SECURITY.md). Release artifacts and notes are on the [GitHub releases page](https://github.com/asdstrind/codex-dsh-native-team/releases).

TDQS

C2.8/5.0

Scored across 3 tools

Disambiguation2/5

dsh_delegate_task overlaps with dsh_team's bundled "Worker/task operations," so it is unclear when to delegate versus use team task controls. Only dsh_team_wait is clearly distinct, while dsh_team packs many separate actions (open, snapshot, review, complete, archive, capabilities, help) into one ambiguous entry point.

Naming Consistency3/5

All names share the dsh_ prefix, but the base conventions are mixed: dsh_delegate_task is verb_noun, dsh_team is a bare noun, and dsh_team_wait is noun_verb. They remain readable, but there is no predictable verb_noun pattern across the set.

Tool Count2/5

Three tools is too thin for a surface that covers delegation, team lifecycle, worker/task operations, review, completion, archive/restore, capabilities, help, and waiting. Much of that functionality is compressed into the single dsh_team mega-tool rather than split into scoped tools.

Completeness3/5

Delegation, snapshot, review, complete, archive/restore, and waiting are represented, so the core lifecycle is mostly covered. However, explicit task cancellation/abort and granular worker/task operations are only implied inside dsh_team, leaving notable gaps in the visible surface.

Maintenance

ActivityMaintained
ResponsivenessOutdated data