fix: wait for the Python console runtime on Windows

.agents/notes/implemented/bug-fix/2026-09-06-windows-python-console-spawn-wait.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-06-windows-python-console-spawn-wait.md
+2026-09-06-windows-python-console-spawn-wait.md: 92443bcf8a6e4e5609dc469efa4ebd1d82ab127f
+2026-09-06-windows-python-console-spawn-wait.zh.md: dba2f324b29955580fc11e7cea7a0525a8bc8c86

.agents/notes/implemented/bug-fix/2026-09-06-windows-python-console-spawn-wait.md

@@ -0,0 +1,27 @@
+# Agent Note: Wait for the Windows Python console runtime
+
+Status: implemented
+
+English | [中文](2026-09-06-windows-python-console-spawn-wait.zh.md)
+
+## Problem
+
+The installed Python `dsh.exe` console command intermittently exits with Windows access violation `0xc0000005` before initializing a profile. Its smoke assertion omitted the process status and reported only empty streams. A [native faulthandler probe](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34030851888) captures the fault in Python 3.10 `os._execvpe`, called by the runtime console entry, rather than in the bundled Node executable. Direct executable controls pass.
+
+## Decision
+
+The [Python console entry](../../../../python/sdk-runtime/src/deepseek_harness_runtime/__init__.py) uses `subprocess.run` on Windows, inherits standard streams and environment, waits for runtime completion, and exits with the runtime status. POSIX retains `os.execvpe` process replacement. Windows CRT exec is not POSIX process replacement; the explicit spawn-and-wait path avoids the observed native exec operation.
+
+The [installed-wheel smoke](../../../../scripts/smoke-python-runtime.py) reports decimal and unsigned 32-bit hexadecimal status alongside captured streams when profile installation fails. This preserves the distinction between ordinary command failure and native process exceptions.
+
+## Alternatives considered
+
+**Disable Node compile caching.** Not selected: cache environment changes correlated with early probes, but cold-cache controls also passed and Python faulthandler locates the actual fault at the native exec call. Cache configuration remains unchanged.
+
+**Retry or bypass the installed console command.** Rejected because either masks the shipped command failure instead of repairing its process launch. The keyless installed-wheel assertion remains required.
+
+## Consequences
+
+Windows keeps a Python parent until the runtime exits; it no longer depends on CRT overlay behavior. The standard synchronous subprocess implementation owns waiting and interruption cleanup. No custom process-tree manager or global host setting is added.
+
+[Runtime-resolution tests](../../../../python/sdk/tests/test_runtime_resolution.py) retain POSIX forwarding and cover Windows argument/environment forwarding, statuses 0/37/513, real child completion, Unicode streams and arguments with spaces. Native Windows owns the wide exit-status case because POSIX truncates process statuses to eight bits. The [native fixed-count comparison](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34031142773) passes all four patched launches with compile caching enabled; all four unpatched controls also pass in that batch, so it is not a same-batch reproduction. Full installed-wheel CI must validate the final artifact separately from local branch-level tests.

.agents/notes/implemented/bug-fix/2026-09-06-windows-python-console-spawn-wait.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: 等待 Windows Python 控制台运行时
+
+Status: implemented
+
+[English](2026-09-06-windows-python-console-spawn-wait.md) | 中文
+
+## 问题
+
+Python 安装的 `dsh.exe` 控制台命令会在初始化 profile 前间歇性地以 Windows 访问冲突 `0xc0000005` 退出。其冒烟断言遗漏进程状态，只报告空标准流。[原生 faulthandler 探测](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34030851888) 将故障定位在运行时控制台入口调用的 Python 3.10 `os._execvpe`，而非打包的 Node 可执行文件。直接启动可执行文件的对照通过。
+
+## 决策
+
+[Python 控制台入口](../../../../python/sdk-runtime/src/deepseek_harness_runtime/__init__.py) 在 Windows 上使用 `subprocess.run`，继承标准流与环境，等待运行时结束，再以运行时状态退出。POSIX 保留 `os.execvpe` 进程替换。Windows CRT exec 并非 POSIX 进程替换；显式启动并等待的路径避开观测到的原生 exec 操作。
+
+[安装后 wheel 冒烟测试](../../../../scripts/smoke-python-runtime.py) 在 profile 安装失败时，同时报告十进制、无符号 32 位十六进制状态与捕获的标准流。这保留普通命令失败和原生进程异常的区别。
+
+## 已考虑的替代方案
+
+**禁用 Node 编译缓存。** 未采用：早期探测中缓存环境变化与结果相关，但冷缓存对照也能通过，且 Python faulthandler 将实际故障定位在原生 exec 调用。缓存配置保持不变。
+
+**重试或绕过已安装的控制台命令。** 拒绝，因为二者都会掩盖已发布命令的失败，而不是修复进程启动。keyless 安装后 wheel 断言仍为必需检查。
+
+## 后果
+
+Windows 保留 Python 父进程直到运行时退出，不再依赖 CRT overlay 行为。标准同步子进程实现负责等待和中断清理。不添加自定义进程树管理器或全局主机设置。
+
+[运行时解析测试](../../../../python/sdk/tests/test_runtime_resolution.py) 保留 POSIX 转发验证，并覆盖 Windows 参数／环境转发、状态 0/37/513、真实子进程完成、Unicode 标准流和带空格的参数。宽退出状态由原生 Windows 验证，因为 POSIX 会将进程状态截断为八位。[原生固定次数对照](https://github.com/deepseek-harness/deepseek-harness/actions/runs/34031142773) 中，启用编译缓存的四次修复后启动全部通过；该批次四次未修复对照也全部通过，因此它不是同批次复现。完整安装后 wheel CI 必须独立于本地分支级测试，验证最终产物。

python/sdk-runtime/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/sdk-runtime/README.md
-README.md: 050ae85d9b0a38b82a3c66a84c3d8f34e137be6c
-README.zh.md: 7066d7224752294c25b58cfe8fb6a94524a2013d
+README.md: fb7478f305015e60dafd23861ab6fd91f10757f3
+README.zh.md: 7c663aba8d387fb7b1048afe28d50faee7350303

python/sdk-runtime/README.md

@@ -19,7 +19,7 @@ Both carriers execute the same `dsh` grammar and shipped profiles, including the
 - `bundled_package_dir() -> Path` returns the installed module-data root and verifies its release metadata.
 - `bundled_runtime_path() -> Path` returns the current platform executable and verifies required sidecars.
 - `resolve_bundled_launch_args(mode=None) -> tuple[str, ...]` returns the executable argv by default. Explicit `mode="node"` or `DSH_RUNTIME_MODE=node` selects the repo-only Node carrier.
-- `main()` implements the installed `dsh` console command and rejects an absent or blank `DSH_HOME` before replacing the Python process.
+- `main()` implements the installed `dsh` console command and rejects an absent or blank `DSH_HOME`. On Windows it waits for the bundled process with inherited standard streams and forwards its exit status; on POSIX it replaces the Python process.
 
 Unsupported platforms and missing executables or sidecars raise `FileNotFoundError` with the build and installation routes. Unknown runtime modes raise `ValueError`.
 

python/sdk-runtime/README.zh.md

@@ -19,7 +19,7 @@ Wheel 会安装 `dsh` 控制台命令和 `deepseek_harness_runtime` Python 模
 - `bundled_package_dir() -> Path` 返回已安装模块数据根目录，并校验发布元数据。
 - `bundled_runtime_path() -> Path` 返回当前平台可执行程序，并校验必需伴随文件。
 - `resolve_bundled_launch_args(mode=None) -> tuple[str, ...]` 默认返回可执行程序 argv。显式 `mode="node"` 或 `DSH_RUNTIME_MODE=node` 会选择仅限仓库使用的 Node 载体。
-- `main()` 实现已安装的 `dsh` 控制台命令，并在替换 Python 进程前拒绝缺失或空白的 `DSH_HOME`。
+- `main()` 实现已安装的 `dsh` 控制台命令，并拒绝缺失或空白的 `DSH_HOME`。在 Windows 上，它让打包进程继承标准流，等待其结束并转发退出状态；在 POSIX 上，它替换 Python 进程。
 
 不支持的平台以及缺失的可执行程序或伴随文件会抛出 `FileNotFoundError`，并指出构建与安装路径。未知运行时模式会抛出 `ValueError`。
 

python/sdk-runtime/src/deepseek_harness_runtime/__init__.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 import os
 import platform
 import shutil
+import subprocess
 import sys
 from pathlib import Path
 
@@ -156,7 +157,7 @@ def _node_launch_args() -> tuple[str, str]:
 
 
 def main() -> None:
-    """Execute the bundled dsh CLI with an explicitly selected Harness home."""
+    """Launch the CLI with explicit DSH_HOME; wait on Windows, replace the process on POSIX."""
     if not os.environ.get("DSH_HOME", "").strip():
         print(
             "dsh: the Python runtime command requires an explicit DSH_HOME; "
@@ -165,6 +166,9 @@ def main() -> None:
         )
         raise SystemExit(2)
     argv = (*resolve_bundled_launch_args(), *sys.argv[1:])
+    if sys.platform == "win32":
+        # Windows CRT exec does not replace the process; wait and preserve the runtime status.
+        raise SystemExit(subprocess.run(argv, env=os.environ).returncode)
     os.execvpe(argv[0], argv, os.environ)
 
 

python/sdk/tests/test_runtime_resolution.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
+import os
+import subprocess
+import sys
 from pathlib import Path
+from types import SimpleNamespace
 
 import deepseek_harness_runtime as runtime
 import pytest
@@ -129,7 +133,7 @@ def test_python_dsh_command_executes_the_bundled_cli(
     called: dict[str, object] = {}
     monkeypatch.setenv("DSH_HOME", "/explicit/home")
     monkeypatch.setattr(runtime, "resolve_bundled_launch_args", lambda: ("/runtime",))
-    monkeypatch.setattr(runtime.sys, "argv", ["dsh", "plugin", "--profile", "sdk", "list"])
+    monkeypatch.setattr(runtime, "sys", SimpleNamespace(platform="linux", argv=["dsh", "plugin", "--profile", "sdk", "list"]))
 
     def execvpe(file: str, args: tuple[str, ...], env: dict[str, str]) -> None:
         called.update(file=file, args=args, home=env.get("DSH_HOME"))
@@ -143,3 +147,51 @@ def test_python_dsh_command_executes_the_bundled_cli(
         "args": ("/runtime", "plugin", "--profile", "sdk", "list"),
         "home": "/explicit/home",
     }
+
+
+@pytest.mark.parametrize("returncode", [0, 37, 513])
+def test_windows_console_waits_and_forwards_runtime_status(monkeypatch: pytest.MonkeyPatch, returncode: int) -> None:
+    monkeypatch.setenv("DSH_HOME", "/explicit/home")
+    monkeypatch.setattr(runtime, "sys", SimpleNamespace(platform="win32", argv=["dsh", "plugin", "argument with spaces", "中文"]))
+    monkeypatch.setattr(runtime, "resolve_bundled_launch_args", lambda: ("runtime.exe",))
+    called = []
+
+    def run(args: tuple[str, ...], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        called.append((args, kwargs))
+        return subprocess.CompletedProcess(args, returncode)
+
+    def forbidden_exec(*args: object) -> None:
+        pytest.fail("Windows console must wait instead of entering CRT exec")
+
+    monkeypatch.setattr(subprocess, "run", run)
+    monkeypatch.setattr(runtime.os, "execvpe", forbidden_exec)
+    with pytest.raises(SystemExit) as result:
+        main()
+    assert result.value.code == returncode
+    assert called == [(("runtime.exe", "plugin", "argument with spaces", "中文"), {"env": os.environ})]
+
+
+@pytest.mark.parametrize("returncode", [0, 37, pytest.param(513, marks=pytest.mark.skipif(sys.platform != "win32", reason="POSIX truncates process exit codes to eight bits"))])
+def test_windows_console_branch_preserves_real_child_io_and_completion(tmp_path: Path, returncode: int) -> None:
+    child = tmp_path / "child with spaces.py"
+    sentinel = tmp_path / "finished"
+    child.write_text(
+        "import pathlib,sys\n"
+        "assert sys.argv[1] == 'argument with spaces'\n"
+        "assert sys.argv[2] == '中文'\n"
+        "print('stdout-中文', flush=True)\n"
+        "print('stderr-中文', file=sys.stderr, flush=True)\n"
+        f"pathlib.Path({str(sentinel)!r}).write_text('done')\n"
+        f"raise SystemExit({returncode})\n", encoding="utf-8",
+    )
+    driver = (
+        "import deepseek_harness_runtime as runtime; from types import SimpleNamespace; "
+        f"runtime.sys = SimpleNamespace(platform='win32', argv=['dsh', 'argument with spaces', '中文']); "
+        f"runtime.resolve_bundled_launch_args = lambda: ({sys.executable!r}, {str(child)!r}); runtime.main()"
+    )
+    result = subprocess.run([sys.executable, "-c", driver], capture_output=True, text=True, encoding="utf-8",
+                            env={**os.environ, "DSH_HOME": str(tmp_path), "PYTHONIOENCODING": "utf-8"}, timeout=15)
+    assert result.returncode == returncode, result.stderr
+    assert result.stdout == "stdout-中文\n"
+    assert result.stderr == "stderr-中文\n"
+    assert sentinel.read_text() == "done"

python/sdk/tests/test_smoke_model.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import runpy
+import subprocess
 from pathlib import Path
 
 import pytest
@@ -262,3 +263,17 @@ def test_snapshot_generation_filename_must_match_header(tmp_path: Path) -> None:
 
     with pytest.raises(AssertionError, match="filename declares Session format v1"):
         SMOKE["selected_snapshot_session_files"](tmp_path)
+
+
+@pytest.mark.parametrize("returncode", [1, -1073741819, 3221225477])
+def test_profile_plugin_failure_reports_native_exit_status(monkeypatch: pytest.MonkeyPatch, returncode: int) -> None:
+    def failed_install(*args: object, **kwargs: object) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(args=[], returncode=returncode, stdout="", stderr="")
+
+    monkeypatch.setattr(subprocess, "run", failed_install)
+    with pytest.raises(AssertionError) as error:
+        SMOKE["smoke_sdk_profile_plugin"]("http://127.0.0.1:1")
+    message = str(error.value)
+    assert f"returncode={returncode}" in message
+    assert f"0x{returncode & 0xffffffff:08x}" in message
+    assert "stdout='' stderr=''" in message

scripts/smoke-python-runtime.py

@@ -1227,6 +1227,7 @@ def smoke_sdk_profile_plugin(base_url: str) -> None:
         if installed.returncode != 0:
             raise AssertionError(
                 f"Python-installed dsh could not add the external profile plugin: "
+                f"returncode={installed.returncode} (0x{installed.returncode & 0xffffffff:08x}) "
                 f"stdout={installed.stdout!r} stderr={installed.stderr!r}"
             )
         manifest = json.loads((dsh_home / "profiles" / "sdk" / "package.json").read_text())