dsh-subprocess-win32

Readme

# dsh-subprocess-win32

English | [中文](README.zh-CN.md)

> **Native Windows Subprocess Runtime & Optimized Agent Presets for DeepSeek Harness (DSH)**

`dsh-subprocess-win32` is a specialized Cordis runtime plugin and preset management bundle designed for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) on Windows. It solves platform-specific process management limitations and provides streamlined, token-efficient Agent presets out of the box.

---

## Highlights & Features

- ⚙️ **Native Windows Subprocess Engine (`subprocess-win32`)**  
  Replaces Unix-centric subprocess handling with Windows-native process-tree inspection and clean termination for terminal tools and Git Bash, ensuring zero orphaned processes without affecting Linux/macOS behavior.
- 🚀 **Two Pre-Configured Windows Agent Presets**  
  - **`Minimal (Windows)`**: Lightweight, minimal token overhead with persistent Git Bash and `str_replace_editor`.
  - **`Anchored Standard (Windows)`**: Two-phase progressive loading preset. Starts with zero tool bloat and unlocks heavy tools (PowerShell, web, subagents) on demand.
- 🛡️ **Safe PowerShell Lifecycle Manager**  
  Provides unified commands for environment diagnostic (`doctor`), automated setup (`setup`), atomic updates (`update`), rollback, and clean uninstallation (`uninstall`)—no hidden background changes or silent PATH tampering.

---

## Why `dsh-subprocess-win32`?

DeepSeek Harness stock terminal tools rely on Unix-oriented process handling, which can cause process leaks, improper signal handling, or terminal stalls on Windows. 

`dsh-subprocess-win32` introduces a dedicated Windows process adapter registered directly in DSH's Cordis runtime plugin inventory. It pairs this robust backend with optimized Agent presets so Windows users get an out-of-the-box, enterprise-grade development experience.

---

## Ecosystem & Repository Relationship

This repository serves as the **core runtime and distribution bundle** for Windows DSH:

| Repository | Role in DSH | What It Provides | When to Use |
| :--- | :--- | :--- | :--- |
| **`dsh-subprocess-win32`** *(This repo)* | **Cordis Runtime Plugin** | `subprocess-win32` engine, lifecycle manager script, and managed copies of both presets | **Essential for Windows.** Install this first to enable Windows runtime support and both presets. |
| [**`dsh-anchored-standard-windows`**](https://github.com/delightedMaster/dsh-anchored-standard-windows) | **Agent Preset Package** | Standalone `agent.cordis.yml`, phase-gating modules, and isolated preset test suites | **Optional.** Used only if you want to inspect, customize, test, or distribute the Anchored preset independently. |

> 💡 **Quick Takeaway:** Most Windows users only need to install `dsh-subprocess-win32`. Its built-in lifecycle manager will automatically configure and render the `Anchored Standard (Windows)` and `Minimal (Windows)` presets for you.

---

## Install in another DSH profile

Prerequisites:

1. Windows x64, Node.js 22.19+ (24 LTS is recommended), Git for Windows, and a
   working DSH installation.
2. A profile whose bundle list can load local packages.

Clone this repository, then add the local package to the profile. On DSH builds
that expose the plugin command, the usual form is:

```powershell
dsh plugin --profile web add C:\src\dsh-subprocess-win32
```

If the installed CLI does not provide `add`, add the package as a local
dependency in that profile's `package.json` and add `dsh-subprocess-win32` to
`dsh.profile.bundles`, then run the profile's package-manager install. Do not put
the package in the DSH core release directory.

The bundle patch disables the stock `subprocess` row only on Windows and inserts
`subprocess-win32`. On Linux and macOS the stock row remains unchanged.

For the managed layout created by the Windows installer, the explicit lifecycle
entry point is:

```powershell
$setup = "$env:LOCALAPPDATA\DeepSeekHarness\setup\dsh-subprocess-win32.ps1"
& $setup -Action doctor
& $setup -Action setup -PackageSource C:\src\dsh-subprocess-win32
```

After setup, start a **new empty session** and select `Minimal (Windows)` or
`Anchored Standard (Windows)`. Existing sessions retain their original Agent
composition.

## Updating and rolling back

Core DSH updates and this bundle's updates are deliberately separate. Keep the
current package directory and install a new source tree beside it; do not replace
the active directory in place. Before applying a change, run:

```powershell
& $setup -Action doctor
& $setup -Action update -DryRun -PackageSource C:\src\dsh-subprocess-win32
```

Only apply the update after reviewing the manifest and test results:

```powershell
& $setup -Action update -PackageSource C:\src\dsh-subprocess-win32
& $setup -Action rollback
```

The manager backs up the DSH profile, keeps the previous package, and restores
the active pointer and profile files on failure. It does not automatically update
third-party DSH bundles or Codex plugins.

## Complete uninstall

Preview first, then confirm the destructive operation in an elevated PowerShell
only if Windows asks for it:

```powershell
& $setup -Action uninstall -DryRun
& $setup -Action uninstall
```

The managed uninstall reads its install manifest, stops only registered DSH
processes/tasks, removes the two DSH presets and the dedicated
`%LOCALAPPDATA%\DeepSeekHarness` root, and performs a residue audit. It does not
delete project source, `.agents\skills`, `.codex\skills`, Codex plugins, Codex
MCP configuration, or other Edge applications. Use the manager's export option
when you need a backup before removal; do not delete the root manually while a
host process is running.

## Windows limitations and safety

- Git/MSYS Bash can exit with `0xC0000142` when DSH's restricted
  `workspace-write` token is applied to this Windows process tree. The full-access
  validation passed; the package does **not** widen permissions, bypass approval,
  or silently select `danger-full-access`.
- The Windows fallback cannot provide Linux `landlock`; treat command output as
  untrusted and keep the DSH approval policy enabled.
- The Minimal alignment is about the model-visible schema and prompt surface. It
  is not a claim that Windows is a Linux kernel or that every workload will have
  identical latency, caching, or completion rate.
- Do not copy Codex `.codex-plugin` manifests into this package. Codex plugins,
  DSH Cordis bundles, Agent presets, Skills, and MCP definitions use different
  loaders. Only explicitly compatible `SKILL.md` and MCP Tools configurations may
  be shared.

## Development

Use the Node runtime from your DSH installation (or Node 22.19+):

```powershell
npm test
```

The tests cover preset phase gating, context suppression, tool discovery,
compaction recovery, and the Windows subprocess adapter. They do not claim that
the host's model provider, API key, or sandbox policy is configured.

## References and acknowledgements

This project is an integration and Windows adaptation. It is not affiliated with
DeepSeek, OpenAI, or the upstream maintainers.

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), including
  the official preset, Skills, Cordis bundle, and MCP designs.
- [`sjh9714/dsh-win32`](https://github.com/sjh9714/dsh-win32), fixed source commit
  `f8a68a9836b84fdfec5c1f36ab60cea9923c689f`, for the Windows subprocess direction.
- [`xiaobright/dsh-anchored-standard`](https://github.com/xiaobright/dsh-anchored-standard),
  fixed source commit `f57a1bde2dbaba3039bdae8631f78a0cb3ae3ebe`, for the
  two-phase Agent preset idea.
- [Anchored Standard issue #24](https://github.com/xiaobright/dsh-anchored-standard/issues/24),
  documenting current-Agent-scope tool schema lookup.

Thanks to the DeepSeek Harness and community contributors for publishing the
runtime seams, preset experiments, tests, and issue reports that made this
Windows package possible. See [`NOTICE`](NOTICE) for license and provenance
details.