Fix Windows MCP robustness and bump 0.4.3rc2

Author: ChesterRa

docs/guide/faq.md

@@ -160,12 +160,26 @@ cccc daemon stop    # Stop existing instance
 cccc daemon start   # Start fresh
 ```
 
-### Port 8848 is in use
+### Port 8848 is unavailable
 
 ```bash
 CCCC_WEB_PORT=9000 cccc
 ```
 
+On Windows, Hyper-V / WSL / WinNAT / HNS can reserve a TCP port even when no
+process is listening on it. If `8848` still fails to start and you do not see an
+owning PID, check the excluded port ranges:
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+If `8848` falls inside one of those ranges, start CCCC on a different port:
+
+```powershell
+cccc web --port 9000
+```
+
 ### MCP not working
 
 ```bash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cccc-pair"
-version = "0.4.3rc1"
+version = "0.4.3rc2"
 description = "Global multi-agent delivery kernel with working groups, scopes, and an append-only collaboration ledger"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.9"

src/cccc/cli/common.py

@@ -38,6 +38,7 @@
 from ..kernel.system_prompt import render_system_prompt
 from ..paths import ensure_home
 from ..ports.im.config_schema import canonicalize_im_config
+from ..ports.web.bind_preflight import ensure_tcp_port_bindable
 from ..util.conv import coerce_bool
 from ..util.process import SOFT_TERMINATE_SIGNAL, best_effort_signal_pid, pid_is_alive, terminate_pid
 
@@ -459,6 +460,17 @@ def _stop_daemon() -> None:
                         pass
             daemon_process = None
 
+    # Keep runtime binding aligned with remote_access settings/UI.
+    host, port = _resolve_web_server_binding()
+    log_level = str(os.environ.get("CCCC_WEB_LOG_LEVEL") or "").strip() or "info"
+    reload_mode = _env_flag("CCCC_WEB_RELOAD", default=False)
+
+    try:
+        ensure_tcp_port_bindable(host=host, port=port)
+    except RuntimeError as e:
+        print(f"[cccc] Error: {e}", file=sys.stderr)
+        return 1
+
     # Start daemon
     print("[cccc] Starting daemon...", file=sys.stderr)
     if not _start_daemon():
@@ -470,11 +482,6 @@ def _stop_daemon() -> None:
     monitor_thread = threading.Thread(target=_monitor_daemon, daemon=True)
     monitor_thread.start()
 
-    # Keep runtime binding aligned with remote_access settings/UI.
-    host, port = _resolve_web_server_binding()
-    log_level = str(os.environ.get("CCCC_WEB_LOG_LEVEL") or "").strip() or "info"
-    reload_mode = _env_flag("CCCC_WEB_RELOAD", default=False)
-    
     # Run web. Let uvicorn own signal handling; set a bounded graceful timeout to
     # avoid hanging forever on long-lived connections (e.g. SSE/WebSocket).
     import uvicorn

src/cccc/cli/system_cmds.py

@@ -172,7 +172,7 @@ def cmd_mcp(args: argparse.Namespace) -> int:
 
 def cmd_setup(args: argparse.Namespace) -> int:
     """Setup CCCC MCP for agent runtimes (configure MCP, print guidance)."""
-    import shutil
+    from ..kernel.runtime import get_cccc_mcp_stdio_command
 
     runtime = str(args.runtime or "").strip()
     project_path = Path(args.path or ".").resolve()
@@ -204,12 +204,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
 
     results: dict[str, Any] = {"mcp": {}, "notes": []}
 
-    # Find cccc executable path for MCP config
-    cccc_path = shutil.which("cccc") or sys.executable
-    if cccc_path == sys.executable:
-        cccc_cmd = [sys.executable, "-m", "cccc.ports.mcp.main"]
-    else:
-        cccc_cmd = ["cccc", "mcp"]
+    cccc_cmd = get_cccc_mcp_stdio_command()
 
     def _cmd_line(parts: list[str]) -> str:
         return " ".join(shlex.quote(p) for p in parts)

src/cccc/daemon/mcp_install.py

@@ -6,6 +6,7 @@
 import subprocess
 from pathlib import Path
 
+from ..kernel.runtime import get_cccc_mcp_stdio_command
 from ..util.conv import coerce_bool
 from ..util.fs import read_json
 
@@ -106,10 +107,11 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
         return True
     if is_mcp_installed(runtime):
         return True
+    cccc_cmd = get_cccc_mcp_stdio_command()
     try:
         if runtime == "claude":
             result = subprocess.run(
-                ["claude", "mcp", "add", "-s", "user", "cccc", "--", "cccc", "mcp"],
+                ["claude", "mcp", "add", "-s", "user", "cccc", "--", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -119,7 +121,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "codex":
             result = subprocess.run(
-                ["codex", "mcp", "add", "cccc", "--", "cccc", "mcp"],
+                ["codex", "mcp", "add", "cccc", "--", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -129,7 +131,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "droid":
             result = subprocess.run(
-                ["droid", "mcp", "add", "--type", "stdio", "cccc", "cccc", "mcp"],
+                ["droid", "mcp", "add", "--type", "stdio", "cccc", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -139,7 +141,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "amp":
             result = subprocess.run(
-                ["amp", "mcp", "add", "cccc", "cccc", "mcp"],
+                ["amp", "mcp", "add", "cccc", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -149,7 +151,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "auggie":
             result = subprocess.run(
-                ["auggie", "mcp", "add", "cccc", "--", "cccc", "mcp"],
+                ["auggie", "mcp", "add", "cccc", "--", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -159,7 +161,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "neovate":
             result = subprocess.run(
-                ["neovate", "mcp", "add", "-g", "cccc", "cccc", "mcp"],
+                ["neovate", "mcp", "add", "-g", "cccc", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -169,7 +171,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "gemini":
             result = subprocess.run(
-                ["gemini", "mcp", "add", "-s", "user", "cccc", "cccc", "mcp"],
+                ["gemini", "mcp", "add", "-s", "user", "cccc", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),
@@ -179,7 +181,7 @@ def ensure_mcp_installed(runtime: str, cwd: Path, *, auto_mcp_runtimes: tuple[st
 
         if runtime == "kimi":
             result = subprocess.run(
-                ["kimi", "mcp", "add", "cccc", "--command", "cccc", "mcp"],
+                ["kimi", "mcp", "add", "cccc", "--command", *cccc_cmd],
                 capture_output=True,
                 text=True,
                 cwd=str(cwd),

src/cccc/kernel/runtime.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 import shutil
+import sys
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 
@@ -166,6 +168,23 @@ def get_runtime_command(name: str) -> List[str]:
     return [config["command"]]
 
 
+def get_cccc_mcp_stdio_command() -> List[str]:
+    """Return the most stable command line for launching `cccc mcp`.
+
+    Prefer an absolute path to the installed `cccc` entrypoint when available.
+    On Windows this avoids relying on runtime-specific PATH inheritance for MCP
+    child processes. Fall back to the current Python interpreter otherwise.
+    """
+    cccc_path = shutil.which("cccc")
+    if cccc_path:
+        try:
+            cccc_path = str(Path(cccc_path).resolve())
+        except Exception:
+            cccc_path = str(cccc_path)
+        return [cccc_path, "mcp"]
+    return [sys.executable, "-m", "cccc.ports.mcp.main"]
+
+
 def get_runtime_command_with_flags(name: str) -> List[str]:
     """Get the command with recommended flags for autonomous operation."""
     commands = {

src/cccc/ports/mcp/common.py

@@ -34,8 +34,67 @@ class _RuntimeContext:
     actor_id: str
 
 
+def _proc_parent_pid_windows(pid: int) -> int:
+    if pid <= 0 or os.name != "nt":
+        return 0
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        TH32CS_SNAPPROCESS = 0x00000002
+        INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+
+        class PROCESSENTRY32W(ctypes.Structure):
+            _fields_ = [
+                ("dwSize", wintypes.DWORD),
+                ("cntUsage", wintypes.DWORD),
+                ("th32ProcessID", wintypes.DWORD),
+                ("th32DefaultHeapID", ctypes.c_size_t),
+                ("th32ModuleID", wintypes.DWORD),
+                ("cntThreads", wintypes.DWORD),
+                ("th32ParentProcessID", wintypes.DWORD),
+                ("pcPriClassBase", ctypes.c_long),
+                ("dwFlags", wintypes.DWORD),
+                ("szExeFile", wintypes.WCHAR * 260),
+            ]
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
+        kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
+        kernel32.Process32FirstW.argtypes = [wintypes.HANDLE, ctypes.POINTER(PROCESSENTRY32W)]
+        kernel32.Process32FirstW.restype = wintypes.BOOL
+        kernel32.Process32NextW.argtypes = [wintypes.HANDLE, ctypes.POINTER(PROCESSENTRY32W)]
+        kernel32.Process32NextW.restype = wintypes.BOOL
+        kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+        kernel32.CloseHandle.restype = wintypes.BOOL
+
+        snapshot = kernel32.CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0)
+        if snapshot in (0, INVALID_HANDLE_VALUE, None):
+            return 0
+        try:
+            entry = PROCESSENTRY32W()
+            entry.dwSize = ctypes.sizeof(PROCESSENTRY32W)
+            if not kernel32.Process32FirstW(snapshot, ctypes.byref(entry)):
+                return 0
+            while True:
+                if int(entry.th32ProcessID or 0) == int(pid):
+                    parent = int(entry.th32ParentProcessID or 0)
+                    return 0 if parent == int(pid) else parent
+                if not kernel32.Process32NextW(snapshot, ctypes.byref(entry)):
+                    break
+        finally:
+            kernel32.CloseHandle(snapshot)
+    except Exception:
+        return 0
+    return 0
+
+
 def _proc_parent_pid(pid: int) -> int:
-    if pid <= 0 or os.name != "posix":
+    if pid <= 0:
+        return 0
+    if os.name == "nt":
+        return _proc_parent_pid_windows(pid)
+    if os.name != "posix":
         return 0
     try:
         status_path = Path("/proc") / str(pid) / "status"

src/cccc/ports/mcp/main.py

@@ -73,10 +73,27 @@ def _encode_cursor(offset: int) -> str:
     return str(max(0, int(offset)))
 
 
+def _stdin_buffer() -> Any:
+    return getattr(sys.stdin, "buffer", None)
+
+
+def _stdout_buffer() -> Any:
+    return getattr(sys.stdout, "buffer", None)
+
+
 def _read_message() -> Optional[Dict[str, Any]]:
     """Read a single JSON-RPC message from stdin."""
     try:
-        line = sys.stdin.readline()
+        raw_stdin = _stdin_buffer()
+        if raw_stdin is not None:
+            raw_line = raw_stdin.readline()
+            if not raw_line:
+                return None
+            line = raw_line.decode("utf-8")
+        else:
+            line = sys.stdin.readline()
+            if not line:
+                return None
         if not line:
             return None
         return json.loads(line.strip())
@@ -86,7 +103,13 @@ def _read_message() -> Optional[Dict[str, Any]]:
 
 def _write_message(msg: Dict[str, Any]) -> None:
     """Write a single JSON-RPC message to stdout."""
-    sys.stdout.write(json.dumps(msg, ensure_ascii=False) + "\n")
+    payload = json.dumps(msg, ensure_ascii=False) + "\n"
+    raw_stdout = _stdout_buffer()
+    if raw_stdout is not None:
+        raw_stdout.write(payload.encode("utf-8"))
+        raw_stdout.flush()
+        return
+    sys.stdout.write(payload)
     sys.stdout.flush()