dsh-gate

dsh-gate lets Codex supervise long-running DeepSeek Harness sessions through MCP while keeping the DSH Host and sessions independent of the MCP process.

The workspace contains:

• @dsh-gate/mcp-server: nine MCP tools over DSH's public network client and reconnect controller;
• @dsh-gate/supervisor-tools: DSH-side handoff, artifact admission, and reported-failure budget tools;
• two narrow operator skills, example Codex/DSH configuration, and a deterministic bootstrap/doctor/Host workflow.

Deploy, verify, and start

pnpm bootstrap      # fetch the pinned DSH fork commit, build & link the exact
                    # network client, install the supervisor plugin into an
                    # isolated project-local DSH home (.dsh-state/) — never starts the Host
pnpm run doctor     # verify pin, link, built artifacts, and plugin/profile
pnpm host:start     # start the independent DSH Web Host on http://127.0.0.1:8080
pnpm run doctor --live  # additionally verify the running Host identity/protocol

Then copy config/codex-mcp.example.toml into the matching Codex config and replace the <workspace-root> placeholder with this checkout's absolute path — the only machine-specific value. The server executable is packages/mcp-server/dist/cli.js — if an older config still points at dist/index.js, update it to dist/cli.js (the library entry does not start the MCP server). Codex MCP configuration supports stdio servers with command, args, environment, startup timeout, and tool timeout fields.

For the full operator guide — prerequisites, the compatibility contract and update policy, Host independence, browser visibility, clean failure recovery, and the official-upstream-PR limitation — read DEPLOYMENT.md.

The pinned DSH fork commit

@dsh-gate/mcp-server imports @deepseek-ai/dsh-client-connection/network-client, the generic network-client and reconnect-controller exports. Those exports are not part of any published DSH release; they are consumed from the public fork at exactly one commit:

• fork: https://github.com/yidapan666-creator/deepseek-harness.git
• commit: 7212c955438c70c9a2d168f67e85a8014b8d4488

The commit SHA is the compatibility contract — bootstrap fetches by SHA (never a moving branch), doctor refuses a checkout whose HEAD differs or whose remote does not identify the fork, and a dirty checkout is refused without destructive recovery. The link itself is created by the existing scripts/link-local-dsh.mjs, reused by bootstrap; it is local-only, and no machine path is committed into package metadata. dist/cli.js probes the seam first and prints a clear diagnostic instead of a raw module-resolution error when it is missing.

To update the pin: change DSH_PINNED_COMMIT in scripts/dsh-gate-lib.mjs, remove .dsh-state/dsh, and re-run pnpm bootstrap. See DEPLOYMENT.md for the policy and for why the fork commit is not claimed as an upstream merge.

Supervision cadence

dsh_wait runs a five-minute aggregated progress cadence: by default it returns about one observation every 300000 ms, and it returns early only for a material supervisor boundary — for example a terminal state, approval/question, checkpoint, blocker, or escalation. Ordinary event churn never triggers rapid repeated wait calls. Each cadence observation aggregates progress since the previous asOfSeq — step delta, tool counts, token deltas — plus a compact, bounded projectActivity summary of the distinct project files touched by successful edits/writes and the targeted verification commands attempted (for example pnpm verify). Terminal observations carry the task-scope totals. No raw logs, diffs, or tool outputs are ever included.

The queued prompt starts with the human-readable objective and embeds the durable task packet afterward. This keeps protocol validation unchanged while making new supervised sessions recognizable by task name in the DSH Web sidebar.

Long handoff details

supervisor_handoff.summary is capped at 2048 characters. When a task needs a longer report, write it as Markdown under .dsh-handoff/<taskId>/ inside the session cwd (the directory is gitignored), pass the relative path in artifacts, and reference it from the concise summary. The handoff tool rejects over-limit summaries with exactly this instruction and never writes handoff data itself — in particular, never to ~/.codex or any other global directory. Artifact admission enforces containment: relative paths only, no traversal, symlinks, hardlinks, or non-regular files, hashed through a validated handle within the session cwd.

Release status

The source is licensed under MIT and prepared for public hosting at yidapan666-creator/dsh-gate: the DSH dependency is a public fork commit pinned by SHA, the working tree contains no machine-specific paths or secrets, and pnpm verify passes with the bootstrap-managed link. Publication as npm packages is a separate, still-blocked decision: both packages keep "private": true, and a clean package install cannot build or run until the upstream DSH network-client seam is published (the fork pin works for source deployments, not for registry consumers).

The remaining upstream limitation is npm publication: both packages stay private until the generic @deepseek-ai/dsh-client-connection/network-client exports are published upstream. The public fork pin at 7212c955438c70c9a2d168f67e85a8014b8d4488 makes source deployments reproducible today; it is not an upstream merge and no merge is claimed.

Source installation, build, tests, packaging checks, and the protocol contract are covered by the documented verification workflow.

See docs/protocol.md for state semantics, docs/manual-e2e.md for the acceptance path, docs/benchmark.md for the evaluation design, docs/source-provenance.md for source and license traceability, and docs/source-backed-reuse-review.md for the historical design review. For contributors: CONTRIBUTING.md. For vulnerability reporting: SECURITY.md.