Add native Windows compatibility layer

routes/admin_wipe_routes.py

@@ -44,7 +44,7 @@ def _wipe_memory_files():
             continue
         try:
             if name == "memory.json":
-                with open(p, "w") as f:
+                with open(p, "w", encoding="utf-8") as f:
                     json.dump([], f)
             else:
                 os.remove(p)

routes/contacts_routes.py

@@ -29,7 +29,7 @@ LOCAL_CONTACTS_FILE = DATA_DIR / "contacts.json"
 
 def _load_settings():
     if SETTINGS_FILE.exists():
-        return json.loads(SETTINGS_FILE.read_text())
+        return json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
     return {}
 
 
@@ -79,7 +79,7 @@ def _load_local_contacts() -> List[Dict]:
     try:
         if not LOCAL_CONTACTS_FILE.exists():
             return []
-        data = json.loads(LOCAL_CONTACTS_FILE.read_text())
+        data = json.loads(LOCAL_CONTACTS_FILE.read_text(encoding="utf-8"))
         rows = data.get("contacts", data) if isinstance(data, dict) else data
         return [_normalize_contact(c) for c in (rows or []) if isinstance(c, dict)]
     except Exception as e:

routes/cookbook_routes.py

@@ -7,6 +7,7 @@ import os
 import re
 import shlex
 import shutil
+import subprocess
 import sys
 import uuid
 from pathlib import Path
@@ -17,6 +18,15 @@ from src.auth_helpers import require_user
 from pydantic import BaseModel
 
 from core.middleware import require_admin
+from core.platform_compat import (
+    IS_WINDOWS,
+    detached_popen_kwargs,
+    find_bash,
+    kill_process_tree,
+    pid_alive,
+    safe_chmod,
+    which_tool,
+)
 from routes.shell_routes import TMUX_LOG_DIR
 
 logger = logging.getLogger(__name__)
@@ -208,16 +218,20 @@ def setup_cookbook_routes() -> APIRouter:
         if not _cookbook_state_path.exists():
             return ""
         try:
-            state = json.loads(_cookbook_state_path.read_text())
+            state = json.loads(_cookbook_state_path.read_text(encoding="utf-8"))
             env = state.get("env") if isinstance(state, dict) else {}
             return _decrypt_secret(env.get("hfToken") if isinstance(env, dict) else "")
         except Exception:
             return ""
 
     def _cookbook_ssh_dir() -> Path:
-        app_ssh = Path("/app/.ssh")
-        if Path("/app").exists():
-            return app_ssh
+        # The Docker image keeps cookbook keys under /app/.ssh; that path only
+        # exists inside the container. On Windows (and any non-container host)
+        # fall back to the user profile's ~/.ssh, which OpenSSH on Win10+ uses.
+        if not IS_WINDOWS:
+            app_ssh = Path("/app/.ssh")
+            if Path("/app").exists():
+                return app_ssh
         return Path.home() / ".ssh"
 
     def _cookbook_ssh_key_path() -> Path:
@@ -244,13 +258,15 @@ def setup_cookbook_routes() -> APIRouter:
         ssh_dir = _cookbook_ssh_dir()
         key_path = _cookbook_ssh_key_path()
         ssh_dir.mkdir(parents=True, exist_ok=True)
-        try:
-            os.chmod(ssh_dir, 0o700)
-        except Exception:
-            pass
+        # safe_chmod no-ops on Windows (~/.ssh is already ACL-restricted to the
+        # user profile); applies 0o700 on POSIX.
+        safe_chmod(ssh_dir, 0o700)
         if not key_path.exists():
+            # ssh-keygen ships with the OpenSSH client on Win10+; resolve it via
+            # which_tool so the .exe is found even when PATHEXT is unusual.
+            ssh_keygen = which_tool("ssh-keygen") or "ssh-keygen"
             proc = await asyncio.create_subprocess_exec(
-                "ssh-keygen", "-t", "ed25519", "-N", "", "-C", "odysseus-cookbook", "-f", str(key_path),
+                ssh_keygen, "-t", "ed25519", "-N", "", "-C", "odysseus-cookbook", "-f", str(key_path),
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
             )
@@ -258,11 +274,8 @@ def setup_cookbook_routes() -> APIRouter:
             if proc.returncode != 0:
                 detail = (stderr or stdout).decode("utf-8", errors="replace").strip()[-500:]
                 return {"ok": False, "error": detail or "Failed to generate SSH key"}
-        try:
-            os.chmod(key_path, 0o600)
-            os.chmod(key_path.with_suffix(".pub"), 0o644)
-        except Exception:
-            pass
+        safe_chmod(key_path, 0o600)
+        safe_chmod(key_path.with_suffix(".pub"), 0o644)
         return {"ok": True, "public_key": _read_cookbook_public_key()}
 
     def _user_shell_path_bootstrap() -> list[str]:
@@ -314,6 +327,56 @@ def setup_cookbook_routes() -> APIRouter:
             return await _remote_binary_available(remote, ssh_port, binary, windows=windows)
         return shutil.which(binary) is not None
 
+    def _launch_local_detached(session_id: str, bash_lines: list[str]) -> dict:
+        """Windows-native stand-in for a LOCAL tmux session (tmux doesn't exist
+        on Windows). Mirrors shell_routes._generate_win_detached / bg_jobs.launch:
+        runs the wrapper detached so it survives a browser/SSE disconnect (the
+        whole point of the tmux feature for long downloads/serves), writing a
+        <session>.log the status poller tails and a <session>.pid for liveness.
+
+        `bash_lines` is the same bash wrapper used on POSIX. Prefers Git Bash
+        for full command-syntax parity; falls back to a cmd.exe wrapper that
+        runs the script through whatever bash is reachable, else best-effort
+        directly (simple commands only). Returns the launched job record."""
+        log_path = TMUX_LOG_DIR / f"{session_id}.log"
+        pid_path = TMUX_LOG_DIR / f"{session_id}.pid"
+        bash = find_bash()
+        if bash:
+            # Run the existing bash wrapper verbatim through Git Bash, redirecting
+            # all output to the log the poller reads. Paths handed to bash use
+            # POSIX form + shell-quoting so drive paths / spaces survive.
+            inner = TMUX_LOG_DIR / f"{session_id}_run.sh"
+            inner.write_text("\n".join(bash_lines) + "\n", encoding="utf-8")
+            lp = shlex.quote(log_path.as_posix())
+            ip = shlex.quote(inner.as_posix())
+            script_path = TMUX_LOG_DIR / f"{session_id}.sh"
+            script_path.write_text(
+                f"bash {ip} > {lp} 2>&1\n",
+                encoding="utf-8",
+            )
+            argv = [bash, str(script_path)]
+        else:
+            # No bash on this Windows host: the bash wrapper can't run. Fall back
+            # to a cmd.exe wrapper that just records a clear error to the log so
+            # the UI surfaces "install Git Bash" instead of silently hanging.
+            script_path = TMUX_LOG_DIR / f"{session_id}.cmd"
+            script_path.write_text(
+                "@echo off\r\n"
+                f'echo Cookbook LOCAL execution on Windows needs Git Bash ^(bash.exe^) on PATH. > "{log_path}" 2>&1\r\n'
+                f'echo Install Git for Windows, then retry. >> "{log_path}"\r\n',
+                encoding="utf-8",
+            )
+            argv = [os.environ.get("ComSpec", "cmd.exe"), "/c", str(script_path)]
+        proc = subprocess.Popen(
+            argv,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            **detached_popen_kwargs(),
+        )
+        pid_path.write_text(str(proc.pid), encoding="utf-8")
+        return {"pid": proc.pid, "log_path": str(log_path)}
+
     @router.post("/api/model/download")
     async def model_download(request: Request, req: ModelDownloadRequest):
         """Download a HuggingFace model in a tmux session.
@@ -379,9 +442,12 @@ def setup_cookbook_routes() -> APIRouter:
 
         remote = req.remote_host  # None for local
         is_windows = req.platform == "windows"
+        # LOCAL execution on a native-Windows host never uses tmux (it uses the
+        # detached-process path below), regardless of the UI-supplied platform.
+        local_windows = IS_WINDOWS and not remote
         logger.info(f"Download request: repo={req.repo_id}, remote={remote}, ssh_port={req.ssh_port}, platform={req.platform}")
 
-        if not is_windows and not await _binary_available("tmux", remote, req.ssh_port):
+        if not is_windows and not local_windows and not await _binary_available("tmux", remote, req.ssh_port):
             return {
                 "ok": False,
                 "error": _missing_binary_message("tmux", remote or "local server"),
@@ -425,7 +491,7 @@ def setup_cookbook_routes() -> APIRouter:
             ps_lines.append('}}')
             ps_lines.append(f'Remove-Item -Force "$HOME\\{remote_runner}" -ErrorAction SilentlyContinue')
             runner_path = TMUX_LOG_DIR / f"{session_id}_run.ps1"
-            runner_path.write_text("\r\n".join(ps_lines) + "\r\n")
+            runner_path.write_text("\r\n".join(ps_lines) + "\r\n", encoding="utf-8")
 
             # scp the .ps1 script, then launch it as a detached process with log + pid files
             _port = req.ssh_port
@@ -492,8 +558,10 @@ def setup_cookbook_routes() -> APIRouter:
             runner_lines.append(f"rm -f {remote_runner}")
             runner_lines.append('exec "${SHELL:-/bin/bash}"')
             runner_path = TMUX_LOG_DIR / f"{session_id}_run.sh"
-            runner_path.write_text("\n".join(runner_lines) + "\n")
-            runner_path.chmod(0o755)
+            runner_path.write_text("\n".join(runner_lines) + "\n", encoding="utf-8")
+            # Local temp file is scp'd then chmod'd on the remote; the local bit
+            # is irrelevant (no-op on Windows).
+            safe_chmod(runner_path, 0o755)
 
             # scp the runner script, then create tmux session on the remote
             _port = req.ssh_port
@@ -504,7 +572,8 @@ def setup_cookbook_routes() -> APIRouter:
                 f"ssh {_spf}{remote} 'chmod +x {remote_runner} && tmux new-session -d -s {session_id} \"./{remote_runner}\"'"
             )
         else:
-            # Local: run hf download in a local tmux session
+            # Local: run hf download in the background (tmux on POSIX, a detached
+            # process + logfile on Windows where tmux doesn't exist).
             if req.env_prefix:
                 lines.append(_safe_env_prefix(req.env_prefix))
             else:
@@ -512,29 +581,43 @@ def setup_cookbook_routes() -> APIRouter:
             # Show whether the HF token reached this run (masked) — tells a gated
             # "not authorized" failure apart from a missing token.
             lines.append(_HF_TOKEN_STATUS_SNIPPET)
-            # < /dev/null suppresses interactive "update available? [Y/n]" prompt
-            lines.append(f"{hf_cmd} < /dev/null")
-            lines.append('if [ $? -eq 0 ]; then echo ""; echo "DOWNLOAD_OK"; else echo ""; echo "DOWNLOAD_FAILED (exit $?)"; fi')
-            lines.append(f"rm -f '{wrapper_script}'")
-            lines.append('exec "${SHELL:-/bin/bash}"')
-            wrapper_script.write_text("\n".join(lines) + "\n")
-            wrapper_script.chmod(0o755)
-            setup_cmd = f"tmux new-session -d -s {session_id} {shlex.quote(str(wrapper_script))}"
+            if IS_WINDOWS:
+                # Detached path: no controlling TTY, so skip `< /dev/null`
+                # (handled by Popen stdin=DEVNULL) and don't keep a shell open.
+                lines.append(hf_cmd)
+                lines.append('if [ $? -eq 0 ]; then echo ""; echo "DOWNLOAD_OK"; else echo ""; echo "DOWNLOAD_FAILED (exit $?)"; fi')
+            else:
+                # < /dev/null suppresses interactive "update available? [Y/n]" prompt
+                lines.append(f"{hf_cmd} < /dev/null")
+                lines.append('if [ $? -eq 0 ]; then echo ""; echo "DOWNLOAD_OK"; else echo ""; echo "DOWNLOAD_FAILED (exit $?)"; fi')
+                lines.append(f"rm -f '{wrapper_script}'")
+                lines.append('exec "${SHELL:-/bin/bash}"')
+                wrapper_script.write_text("\n".join(lines) + "\n", encoding="utf-8")
+                wrapper_script.chmod(0o755)
+            setup_cmd = None if IS_WINDOWS else f"tmux new-session -d -s {session_id} {shlex.quote(str(wrapper_script))}"
 
         logger.info(f"Model download: {req.repo_id} (include={req.include}, session={session_id}, remote={remote})")
         logger.info(f"Download setup_cmd: {setup_cmd}")
 
-        proc = await asyncio.create_subprocess_shell(
-            setup_cmd,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.PIPE,
-        )
-        await proc.wait()
+        if setup_cmd is None:
+            # LOCAL Windows: launch the bash wrapper detached; no tmux setup_cmd.
+            try:
+                _launch_local_detached(session_id, lines)
+            except Exception as e:
+                logger.error(f"Local detached download launch failed: {e}")
+                return {"ok": False, "error": str(e), "session_id": session_id}
+        else:
+            proc = await asyncio.create_subprocess_shell(
+                setup_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await proc.wait()
 
-        if proc.returncode != 0:
-            stderr = (await proc.stderr.read()).decode(errors="replace")
-            logger.error(f"Download failed (rc={proc.returncode}): {stderr}")
-            return {"ok": False, "error": stderr, "session_id": session_id}
+            if proc.returncode != 0:
+                stderr = (await proc.stderr.read()).decode(errors="replace")
+                logger.error(f"Download failed (rc={proc.returncode}): {stderr}")
+                return {"ok": False, "error": stderr, "session_id": session_id}
 
         # Log to assistant
         try:
@@ -643,7 +726,7 @@ def setup_cookbook_routes() -> APIRouter:
         paths_code += "print(json.dumps(models))\n"
 
         scan_py = TMUX_LOG_DIR / "scan_cache.py"
-        scan_py.write_text(paths_code)
+        scan_py.write_text(paths_code, encoding="utf-8")
 
         if host:
             _pf = f"-p {ssh_port} " if ssh_port and ssh_port != "22" else ""
@@ -652,15 +735,27 @@ def setup_cookbook_routes() -> APIRouter:
                 cmd = f'ssh {_pf}{host} "python -" < \'{scan_py}\''
             else:
                 cmd = f"ssh {_pf}{host} 'python3 -' < '{scan_py}'"
+            proc = await asyncio.create_subprocess_shell(
+                cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(Path.home()),
+            )
         else:
-            cmd = f"python3 '{scan_py}'"
-
-        proc = await asyncio.create_subprocess_shell(
-            cmd,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.PIPE,
-            cwd=str(Path.home()),
-        )
+            # LOCAL scan: run the interpreter directly. `python3` isn't a thing on
+            # Windows (it's `python`/`py`), and shell single-quoting of the path
+            # doesn't survive cmd.exe — so resolve the interpreter and exec it
+            # with the script path as an argv element (no shell quoting needed).
+            local_py = (
+                which_tool("python3") or which_tool("python")
+                or which_tool("py") or "python"
+            )
+            proc = await asyncio.create_subprocess_exec(
+                local_py, str(scan_py),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(Path.home()),
+            )
         stdout_b, stderr_b = await asyncio.wait_for(proc.communicate(), timeout=60)
 
         models = []
@@ -785,8 +880,11 @@ def setup_cookbook_routes() -> APIRouter:
         session_id = f"serve-{uuid.uuid4().hex[:8]}"
         remote = req.remote_host
         is_windows = req.platform == "windows"
+        # LOCAL execution on a native-Windows host never uses tmux (detached
+        # process path below), regardless of the UI-supplied platform.
+        local_windows = IS_WINDOWS and not remote
 
-        if not is_windows and not await _binary_available("tmux", remote, req.ssh_port):
+        if not is_windows and not local_windows and not await _binary_available("tmux", remote, req.ssh_port):
             return {
                 "ok": False,
                 "error": _missing_binary_message("tmux", remote or "local server"),
@@ -832,7 +930,7 @@ def setup_cookbook_routes() -> APIRouter:
             ps_lines.append('Write-Host ""')
             ps_lines.append('Write-Host "=== Process exited with code $LASTEXITCODE ==="')
             runner_path = TMUX_LOG_DIR / f"{session_id}_run.ps1"
-            runner_path.write_text("\r\n".join(ps_lines) + "\r\n")
+            runner_path.write_text("\r\n".join(ps_lines) + "\r\n", encoding="utf-8")
 
             _port = req.ssh_port
             _Pf = f"-P {_port} " if _port and _port != "22" else ""
@@ -956,14 +1054,24 @@ def setup_cookbook_routes() -> APIRouter:
                 runner_lines.append('fi')
 
             runner_lines.append(req.cmd)
-            # Keep shell open after exit so user can see errors
-            runner_lines.append('echo ""; echo "=== Process exited with code $? ==="; exec "${SHELL:-/bin/bash}"')
+            if local_windows:
+                # Detached background process — no interactive shell to keep open.
+                # Print the exit marker the status poller looks for, then stop.
+                runner_lines.append('echo ""; echo "=== Process exited with code $? ==="')
+            else:
+                # Keep shell open after exit so user can see errors
+                runner_lines.append('echo ""; echo "=== Process exited with code $? ==="; exec "${SHELL:-/bin/bash}"')
 
             runner_path = TMUX_LOG_DIR / f"{session_id}_run.sh"
-            runner_path.write_text("\n".join(runner_lines) + "\n")
-            runner_path.chmod(0o755)
+            runner_path.write_text("\n".join(runner_lines) + "\n", encoding="utf-8")
+            # chmod is a no-op on Windows; bash on Windows runs the script
+            # regardless of the executable bit.
+            safe_chmod(runner_path, 0o755)
 
-            if remote:
+            if local_windows:
+                # LOCAL Windows: launch the bash runner detached (tmux replacement).
+                setup_cmd = None
+            elif remote:
                 remote_runner = f".{session_id}_run.sh"
                 # If command references scripts/, scp those too
                 scp_extras = ""
@@ -976,9 +1084,10 @@ def setup_cookbook_routes() -> APIRouter:
                     if diff_script.exists():
                         scp_extras = f"scp -O {_Pf}-q '{diff_script}' {remote}:.diffusion_server.py && "
                         runner_path.write_text(
-                            runner_path.read_text().replace(
+                            runner_path.read_text(encoding="utf-8").replace(
                                 "scripts/diffusion_server.py", ".diffusion_server.py"
-                            )
+                            ),
+                            encoding="utf-8",
                         )
                 setup_cmd = (
                     f"{scp_extras}"
@@ -988,16 +1097,24 @@ def setup_cookbook_routes() -> APIRouter:
             else:
                 setup_cmd = f"tmux new-session -d -s {session_id} {shlex.quote(str(runner_path))}"
 
-        proc = await asyncio.create_subprocess_shell(
-            setup_cmd,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.PIPE,
-        )
-        await proc.wait()
+        if setup_cmd is None:
+            # LOCAL Windows: launch the bash runner detached; no tmux setup_cmd.
+            try:
+                _launch_local_detached(session_id, runner_lines)
+            except Exception as e:
+                logger.error(f"Local detached serve launch failed: {e}")
+                return {"ok": False, "error": str(e), "session_id": session_id}
+        else:
+            proc = await asyncio.create_subprocess_shell(
+                setup_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await proc.wait()
 
-        if proc.returncode != 0:
-            stderr = (await proc.stderr.read()).decode(errors="replace")
-            return {"ok": False, "error": stderr, "session_id": session_id}
+            if proc.returncode != 0:
+                stderr = (await proc.stderr.read()).decode(errors="replace")
+                return {"ok": False, "error": stderr, "session_id": session_id}
 
         # Auto-register as model endpoint if serving a diffusion model
         endpoint_id = None
@@ -1404,6 +1521,16 @@ def setup_cookbook_routes() -> APIRouter:
                 proc = await asyncio.create_subprocess_shell(
                     cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
                 )
+            elif IS_WINDOWS:
+                # No `kill` binary / POSIX signals on Windows. taskkill /F /T tears
+                # down the PID and its children. There's no graceful-vs-force
+                # distinction, so TERM/KILL/INT all map to the same forced kill.
+                # NB: never use os.kill(pid, 0) to probe here — on Windows that
+                # routes to TerminateProcess and would kill the process.
+                if not pid_alive(req.pid):
+                    return {"ok": False, "error": f"PID {req.pid} is not running"}
+                await asyncio.to_thread(kill_process_tree, req.pid)
+                return {"ok": True, "pid": req.pid, "signal": sig}
             else:
                 proc = await asyncio.create_subprocess_exec(
                     "kill", f"-{sig}", str(req.pid),
@@ -1427,7 +1554,7 @@ def setup_cookbook_routes() -> APIRouter:
         require_admin(request)
         if _cookbook_state_path.exists():
             try:
-                return _state_for_client(json.loads(_cookbook_state_path.read_text()))
+                return _state_for_client(json.loads(_cookbook_state_path.read_text(encoding="utf-8")))
             except Exception:
                 return {}
         return {}
@@ -1456,7 +1583,7 @@ def setup_cookbook_routes() -> APIRouter:
                 data = {}
             try:
                 if _cookbook_state_path.exists():
-                    on_disk = json.loads(_cookbook_state_path.read_text())
+                    on_disk = json.loads(_cookbook_state_path.read_text(encoding="utf-8"))
                 else:
                     on_disk = {}
             except Exception:
@@ -1636,7 +1763,7 @@ def setup_cookbook_routes() -> APIRouter:
         tasks = []
         if _cookbook_state_path.exists():
             try:
-                state = json.loads(_cookbook_state_path.read_text())
+                state = json.loads(_cookbook_state_path.read_text(encoding="utf-8"))
                 saved_tasks = state.get("tasks", [])
                 if isinstance(saved_tasks, list):
                     tasks = saved_tasks
@@ -1705,26 +1832,36 @@ def setup_cookbook_routes() -> APIRouter:
                     ssh_base.extend(["-p", str(_tport)])
                 check_cmd = ssh_base + [remote, "tmux", "has-session", "-t", session_id]
                 capture_cmd = ssh_base + [remote, "tmux", "capture-pane", "-t", session_id, "-p", "-S", "-50"]
+            elif IS_WINDOWS:
+                # LOCAL Windows task: launched as a detached process (no tmux).
+                # Liveness comes from the <session>.pid file, output from the
+                # <session>.log file the wrapper redirects into. No subprocess.
+                check_cmd = None
+                capture_cmd = None
             else:
                 check_cmd = ["tmux", "has-session", "-t", session_id]
                 capture_cmd = ["tmux", "capture-pane", "-t", session_id, "-p", "-S", "-50"]
 
-            try:
-                alive = subprocess.run(check_cmd, timeout=10, capture_output=True)
-                is_alive = alive.returncode == 0
-            except Exception:
-                is_alive = False
+            local_win_task = (not remote) and IS_WINDOWS
 
-            # Capture last lines for progress. Prefer the "Downloading" line
-            # (real aggregate bytes) over "Fetching N files" (whole-file count that
-            # lags with hf_transfer). Falls back to the true last line otherwise.
             progress_text = ""
             full_snapshot = ""
-            if is_alive:
+
+            if local_win_task:
+                # File-based liveness + output for the detached-process model.
+                pid_path = TMUX_LOG_DIR / f"{session_id}.pid"
+                log_path = TMUX_LOG_DIR / f"{session_id}.log"
+                task_pid = None
                 try:
-                    cap = subprocess.run(capture_cmd, timeout=10, capture_output=True, text=True)
-                    if cap.returncode == 0:
-                        full_snapshot = cap.stdout.strip()
+                    task_pid = int(pid_path.read_text(encoding="utf-8").strip())
+                except Exception:
+                    task_pid = None
+                is_alive = pid_alive(task_pid)
+                try:
+                    if log_path.exists():
+                        full_snapshot = log_path.read_text(
+                            encoding="utf-8", errors="replace"
+                        ).strip()[-12000:]
                         lines = [l.strip() for l in full_snapshot.split('\n') if l.strip()]
                         downloading_lines = [l for l in lines if l.startswith("Downloading")]
                         if downloading_lines:
@@ -1733,10 +1870,36 @@ def setup_cookbook_routes() -> APIRouter:
                             progress_text = lines[-1]
                 except Exception:
                     pass
+            else:
+                try:
+                    alive = subprocess.run(check_cmd, timeout=10, capture_output=True)
+                    is_alive = alive.returncode == 0
+                except Exception:
+                    is_alive = False
 
-            # Determine status
+                # Capture last lines for progress. Prefer the "Downloading" line
+                # (real aggregate bytes) over "Fetching N files" (whole-file count that
+                # lags with hf_transfer). Falls back to the true last line otherwise.
+                if is_alive:
+                    try:
+                        cap = subprocess.run(capture_cmd, timeout=10, capture_output=True, text=True)
+                        if cap.returncode == 0:
+                            full_snapshot = cap.stdout.strip()
+                            lines = [l.strip() for l in full_snapshot.split('\n') if l.strip()]
+                            downloading_lines = [l for l in lines if l.startswith("Downloading")]
+                            if downloading_lines:
+                                progress_text = downloading_lines[-1]
+                            elif lines:
+                                progress_text = lines[-1]
+                    except Exception:
+                        pass
+
+            # Determine status. For the local-Windows detached model the log file
+            # persists after the process exits, so a finished download still has a
+            # snapshot to classify (DOWNLOAD_OK / exit marker) — evaluate it even
+            # when the PID is gone instead of blindly reporting "stopped".
             status = "unknown"
-            if is_alive:
+            if is_alive or (local_win_task and full_snapshot):
                 lower = full_snapshot.lower()
                 has_exit = "=== process exited with code" in lower
                 has_error = "error" in lower or "failed" in lower or "traceback" in lower
@@ -1754,6 +1917,9 @@ def setup_cookbook_routes() -> APIRouter:
                     status = "completed"
                 elif "application startup complete" in lower:
                     status = "ready"
+                elif not is_alive:
+                    # local-Windows: process gone, log has no success/ready marker.
+                    status = "stopped"
                 else:
                     status = "running"
             else:

routes/document_helpers.py

@@ -148,7 +148,7 @@ def _locate_upload(upload_dir: str, file_id: str):
     try:
         idx_path = os.path.join(upload_dir, "uploads.json")
         if os.path.exists(idx_path):
-            with open(idx_path, "r") as f:
+            with open(idx_path, "r", encoding="utf-8") as f:
                 idx = _json.load(f)
             for meta in (idx.values() if isinstance(idx, dict) else []):
                 if meta.get("id") == file_id:

routes/email_helpers.py

@@ -444,7 +444,7 @@ _init_scheduled_db()
 
 def _load_settings():
     if SETTINGS_FILE.exists():
-        return json.loads(SETTINGS_FILE.read_text())
+        return json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
     return {}
 
 

routes/email_routes.py

@@ -2834,7 +2834,7 @@ def setup_email_routes():
         if not path.exists():
             return {"total_unread": 0, "total_urgent": 0, "max_score": 0, "per_uid": {}}
         try:
-            data = _json.loads(path.read_text())
+            data = _json.loads(path.read_text(encoding="utf-8"))
         except Exception:
             return {"total_unread": 0, "total_urgent": 0, "max_score": 0, "per_uid": {}}
         # Drop `notified_uids` from the payload — it's an internal scheduler

routes/embedding_routes.py

@@ -86,7 +86,7 @@ def _load_custom_endpoint() -> dict:
     """Load the saved custom embedding endpoint, if any."""
     try:
         if os.path.exists(_ENDPOINT_FILE):
-            return json.loads(Path(_ENDPOINT_FILE).read_text())
+            return json.loads(Path(_ENDPOINT_FILE).read_text(encoding="utf-8"))
     except Exception:
         pass
     return {}
@@ -94,7 +94,7 @@ def _load_custom_endpoint() -> dict:
 
 def _save_custom_endpoint(data: dict):
     Path(_ENDPOINT_FILE).parent.mkdir(parents=True, exist_ok=True)
-    Path(_ENDPOINT_FILE).write_text(json.dumps(data, indent=2))
+    Path(_ENDPOINT_FILE).write_text(json.dumps(data, indent=2), encoding="utf-8")
 
 
 def setup_embedding_routes():

routes/mcp_routes.py

@@ -141,7 +141,7 @@ def setup_mcp_routes(mcp_manager: McpManager):
                         }
                     }
                     filepath = os.path.join(oauth_dir, oauth_filename)
-                    with open(filepath, "w") as f:
+                    with open(filepath, "w", encoding="utf-8") as f:
                         json.dump(creds, f, indent=2)
                     logger.info(f"Wrote OAuth credentials to {filepath}")
                     parsed_env.pop("GOOGLE_CLIENT_ID", None)
@@ -354,7 +354,7 @@ def setup_mcp_routes(mcp_manager: McpManager):
             if not keys_file or not os.path.exists(keys_file):
                 raise HTTPException(400, "OAuth keys file not found")
 
-            with open(keys_file) as f:
+            with open(keys_file, encoding="utf-8") as f:
                 keys_data = json.load(f)
             keys = keys_data.get("installed") or keys_data.get("web")
             if not keys:
@@ -427,7 +427,7 @@ def setup_mcp_routes(mcp_manager: McpManager):
             keys_file = os.path.expanduser(oauth_cfg.get("keys_file", ""))
             token_file = os.path.expanduser(oauth_cfg.get("token_file", ""))
 
-            with open(keys_file) as f:
+            with open(keys_file, encoding="utf-8") as f:
                 keys_data = json.load(f)
             keys = keys_data.get("installed") or keys_data.get("web")
             client_id = keys["client_id"]
@@ -457,7 +457,7 @@ def setup_mcp_routes(mcp_manager: McpManager):
 
             # Save tokens to the file the MCP package expects
             os.makedirs(os.path.dirname(token_file), exist_ok=True)
-            with open(token_file, "w") as f:
+            with open(token_file, "w", encoding="utf-8") as f:
                 json.dump(tokens, f, indent=2)
             logger.info(f"Saved OAuth tokens to {token_file}")
 

routes/note_routes.py

@@ -145,7 +145,7 @@ async def dispatch_reminder(
             _slug = "".join(c if (c.isalnum() or c in "-_.@") else "_" for c in (owner or "default"))
             cache_path = _P(f"data/note_pings_{_slug}.json")
             if cache_path.exists():
-                cache = _json.loads(cache_path.read_text())
+                cache = _json.loads(cache_path.read_text(encoding="utf-8"))
             last = cache.get(cache_key)
             if last:
                 last_channel = None
@@ -428,7 +428,7 @@ async def dispatch_reminder(
                 _STATE = _P(f"data/note_pings_{_slug}.json")
             _STATE.parent.mkdir(parents=True, exist_ok=True)
             try:
-                _cache = cache or (_json.loads(_STATE.read_text()) if _STATE.exists() else {})
+                _cache = cache or (_json.loads(_STATE.read_text(encoding="utf-8")) if _STATE.exists() else {})
             except Exception:
                 _cache = {}
             sent_channel = "email" if email_sent else "ntfy" if ntfy_sent else "browser"
@@ -436,7 +436,7 @@ async def dispatch_reminder(
                 "at": _dt.now(_tz.utc).isoformat(),
                 "channel": sent_channel,
             }
-            _STATE.write_text(_json.dumps(_cache))
+            _STATE.write_text(_json.dumps(_cache), encoding="utf-8")
         except Exception as _e:
             logger.debug(f"dispatch_reminder: cache write failed: {_e}")
 

routes/prefs_routes.py

@@ -11,7 +11,7 @@ PREFS_FILE = os.path.join("data", "user_prefs.json")
 def _load():
     """Load the raw prefs file (internal use only)."""
     try:
-        with open(PREFS_FILE, "r") as f:
+        with open(PREFS_FILE, "r", encoding="utf-8") as f:
             return json.load(f)
     except (FileNotFoundError, json.JSONDecodeError):
         return {}
@@ -19,7 +19,7 @@ def _load():
 
 def _save(prefs):
     os.makedirs(os.path.dirname(PREFS_FILE), exist_ok=True)
-    with open(PREFS_FILE, "w") as f:
+    with open(PREFS_FILE, "w", encoding="utf-8") as f:
         json.dump(prefs, f, indent=2)
 
 

routes/research_routes.py

@@ -69,7 +69,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if not path.exists():
             return False
         try:
-            return json.loads(path.read_text()).get("owner") == user
+            return json.loads(path.read_text(encoding="utf-8")).get("owner") == user
         except Exception:
             return False
 
@@ -130,7 +130,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if not path.exists():
             raise HTTPException(404, "Research not found")
         try:
-            owner = json.loads(path.read_text()).get("owner")
+            owner = json.loads(path.read_text(encoding="utf-8")).get("owner")
         except Exception:
             raise HTTPException(404, "Research not found")
         if owner != user:
@@ -190,7 +190,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         items = []
         for p in data_dir.glob("*.json"):
             try:
-                d = json.loads(p.read_text())
+                d = json.loads(p.read_text(encoding="utf-8"))
                 # SECURITY: only show research belonging to this user. Legacy
                 # JSONs without an `owner` field are hidden — auth was the only
                 # gate before, so every user saw every other user's reports.
@@ -239,7 +239,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if not path.exists():
             raise HTTPException(404, "Research not found")
         try:
-            data = json.loads(path.read_text())
+            data = json.loads(path.read_text(encoding="utf-8"))
         except Exception as e:
             raise HTTPException(500, f"Failed to read research: {e}")
         # SECURITY: 404 (not 403) so we don't leak that the report exists.
@@ -255,11 +255,11 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if not path.exists():
             raise HTTPException(404, "Research not found")
         try:
-            data = json.loads(path.read_text())
+            data = json.loads(path.read_text(encoding="utf-8"))
             if data.get("owner") != user:
                 raise HTTPException(404, "Research not found")
             data["archived"] = bool(archived)
-            path.write_text(json.dumps(data))
+            path.write_text(json.dumps(data), encoding="utf-8")
         except HTTPException:
             raise
         except Exception as e:
@@ -276,7 +276,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if json_path.exists():
             # SECURITY: verify ownership before letting the caller delete it.
             try:
-                data = json.loads(json_path.read_text())
+                data = json.loads(json_path.read_text(encoding="utf-8"))
                 if data.get("owner") != user:
                     raise HTTPException(404, "Research not found")
             except HTTPException:
@@ -452,7 +452,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         if result is None:
             p = Path("data/deep_research") / f"{session_id}.json"
             if p.exists():
-                d = json.loads(p.read_text())
+                d = json.loads(p.read_text(encoding="utf-8"))
                 return {
                     "result": d.get("result", ""),
                     "sources": d.get("sources", []),
@@ -486,7 +486,7 @@ def setup_research_routes(research_handler, session_manager=None) -> APIRouter:
         path = Path("data/deep_research") / f"{session_id}.json"
         if path.exists():
             try:
-                disk = json.loads(path.read_text())
+                disk = json.loads(path.read_text(encoding="utf-8"))
                 if not result:
                     result = disk.get("result")
                 if not sources:

routes/shell_routes.py

@@ -6,11 +6,17 @@ import logging
 import os
 import shlex
 import shutil
+import subprocess
 import uuid
 import tempfile
 from pathlib import Path
 from typing import Dict, Any
 
+# POSIX-only: `pty`/`fcntl` transitively import `termios`, which does NOT exist
+# on Windows, so importing them unconditionally crashed app startup there
+# (ModuleNotFoundError: termios — issues #140/#92/#63/#149/#150). The PTY code
+# path is only reachable on POSIX; Windows uses pipe streaming + a detached-job
+# fallback for the tmux feature (see _generate_win_detached).
 try:
     import fcntl
     import pty
@@ -25,6 +31,12 @@ from fastapi import APIRouter, Request, HTTPException
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
+from core.platform_compat import (
+    IS_WINDOWS,
+    detached_popen_kwargs,
+    find_bash,
+)
+
 
 def _require_admin(request: Request):
     """Reject non-admin callers. Shell exec is admin-only — never expose to
@@ -78,11 +90,25 @@ class ShellExecRequest(BaseModel):
     use_tmux: bool = False      # run in tmux session (survives browser disconnect)
 
 
+async def _create_shell(command: str, **kwargs):
+    """Spawn a shell subprocess for `command`.
+
+    POSIX: /bin/sh via create_subprocess_shell (unchanged behaviour).
+    Windows: prefer a real bash (Git Bash/WSL) so bash-syntax commands behave
+    the same as on Linux; fall back to cmd.exe when no bash is installed.
+    """
+    if IS_WINDOWS:
+        bash = find_bash()
+        if bash:
+            return await asyncio.create_subprocess_exec(bash, "-c", command, **kwargs)
+    return await asyncio.create_subprocess_shell(command, **kwargs)
+
+
 async def _exec_shell(command: str, timeout: int = EXEC_TIMEOUT) -> Dict[str, Any]:
     """Run a shell command and return stdout/stderr/exit_code."""
     proc = None
     try:
-        proc = await asyncio.create_subprocess_shell(
+        proc = await _create_shell(
             command,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
@@ -355,6 +381,93 @@ async def _generate_tmux(cmd: str, request: Request):
         pass
 
 
+async def _generate_win_detached(cmd: str, request: Request):
+    """Windows stand-in for the tmux path (issues #84/#162).
+
+    tmux doesn't exist on Windows, so we run the command in a *detached* child
+    (DETACHED_PROCESS — survives browser disconnect, same as the tmux session)
+    that writes output to a log file, and tail that log over SSE. Prefers bash
+    (Git Bash) for command-syntax parity; falls back to cmd.exe. There's no
+    `tmux attach` equivalent, but the "keeps running if you disconnect" contract
+    holds, which is the point of the feature for long Cookbook downloads."""
+    TMUX_LOG_DIR.mkdir(parents=True, exist_ok=True)
+    session_id = f"cookbook-{uuid.uuid4().hex[:8]}"
+    log_path = TMUX_LOG_DIR / f"{session_id}.log"
+    exit_path = TMUX_LOG_DIR / f"{session_id}.exit"
+
+    bash = find_bash()
+    if bash:
+        script_path = TMUX_LOG_DIR / f"{session_id}.sh"
+        script_path.write_text(
+            f"{cmd} > {shlex.quote(str(log_path))} 2>&1\n"
+            f"echo $? > {shlex.quote(str(exit_path))}\n",
+            encoding="utf-8",
+        )
+        argv = [bash, str(script_path)]
+    else:
+        script_path = TMUX_LOG_DIR / f"{session_id}.cmd"
+        # cmd.exe wrapper: run, redirect all output to the log, record exit code.
+        script_path.write_text(
+            "@echo off\r\n"
+            f'call {cmd} > "{log_path}" 2>&1\r\n'
+            f'echo %ERRORLEVEL%> "{exit_path}"\r\n',
+            encoding="utf-8",
+        )
+        argv = [os.environ.get("ComSpec", "cmd.exe"), "/c", str(script_path)]
+
+    try:
+        subprocess.Popen(
+            argv,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            **detached_popen_kwargs(),
+        )
+    except Exception as e:
+        yield f"data: {json.dumps({'stream': 'stderr', 'data': f'Failed to launch background job: {e}'})}\n\n"
+        yield f"data: {json.dumps({'exit_code': -1})}\n\n"
+        return
+
+    yield f"data: {json.dumps({'stream': 'stdout', 'data': f'Started background job: {session_id}'})}\n\n"
+
+    lines_sent = 0
+    exit_code = None
+    while True:
+        if await request.is_disconnected():
+            yield f"data: {json.dumps({'stream': 'stdout', 'data': f'Disconnected. Background job {session_id} continues running.'})}\n\n"
+            return
+        try:
+            if log_path.exists():
+                lines = log_path.read_text(encoding="utf-8", errors="replace").splitlines()
+                for line in lines[lines_sent:]:
+                    yield f"data: {json.dumps({'stream': 'stdout', 'data': line})}\n\n"
+                lines_sent = len(lines)
+        except Exception as e:
+            logger.debug("win detached log read error: %s", e)
+
+        if exit_path.exists():
+            # Drain any final lines, then read the recorded exit code.
+            await asyncio.sleep(0.3)
+            try:
+                if log_path.exists():
+                    lines = log_path.read_text(encoding="utf-8", errors="replace").splitlines()
+                    for line in lines[lines_sent:]:
+                        yield f"data: {json.dumps({'stream': 'stdout', 'data': line})}\n\n"
+                    lines_sent = len(lines)
+                exit_code = int((exit_path.read_text(encoding="utf-8", errors="replace").strip() or "0"))
+            except Exception:
+                exit_code = 0
+            break
+        await asyncio.sleep(1.0)
+
+    yield f"data: {json.dumps({'exit_code': exit_code})}\n\n"
+    for p in (log_path, exit_path, script_path):
+        try:
+            p.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
 def setup_shell_routes() -> APIRouter:
     router = APIRouter(tags=["shell"])
 
@@ -393,22 +506,24 @@ def setup_shell_routes() -> APIRouter:
         )
 
         if use_tmux:
-            return StreamingResponse(
-                _generate_tmux(cmd, request),
-                media_type="text/event-stream",
-            )
+            # tmux is POSIX-only; Windows uses a detached-process + logfile tail
+            # that preserves the "survives disconnect" behaviour.
+            gen = _generate_win_detached(cmd, request) if IS_WINDOWS else _generate_tmux(cmd, request)
+            return StreamingResponse(gen, media_type="text/event-stream")
 
-        if use_pty:
+        if use_pty and not IS_WINDOWS:
             return StreamingResponse(
                 _generate_pty(cmd, timeout, request),
                 media_type="text/event-stream",
             )
+        # Windows has no PTY; fall through to pipe streaming below (output still
+        # streams line-by-line, just without live in-place progress-bar redraws).
 
         async def generate():
             proc = None
             reader_tasks = []
             try:
-                proc = await asyncio.create_subprocess_shell(
+                proc = await _create_shell(
                     cmd,
                     stdout=asyncio.subprocess.PIPE,
                     stderr=asyncio.subprocess.PIPE,

routes/upload_routes.py

@@ -105,7 +105,7 @@ def setup_upload_routes(upload_handler):
         info = None
         uploads_db = os.path.join(UPLOAD_DIR, "uploads.json")
         if os.path.exists(uploads_db):
-            with open(uploads_db) as f:
+            with open(uploads_db, encoding="utf-8") as f:
                 db = json.load(f)
             info = next((fi for fi in db.values() if fi["id"] == file_id), None)
             if info:
@@ -153,7 +153,7 @@ def setup_upload_routes(upload_handler):
         info = None
         uploads_db = os.path.join(UPLOAD_DIR, "uploads.json")
         if os.path.exists(uploads_db):
-            with open(uploads_db) as f:
+            with open(uploads_db, encoding="utf-8") as f:
                 db = json.load(f)
             info = next((fi for fi in db.values() if fi["id"] == file_id), None)
         return info
@@ -199,7 +199,7 @@ def setup_upload_routes(upload_handler):
         cache_path = _vision_cache_path(file_id)
         if not force and os.path.exists(cache_path):
             try:
-                with open(cache_path) as f:
+                with open(cache_path, encoding="utf-8") as f:
                     return {"text": f.read(), "cached": True}
             except Exception as e:
                 logger.warning(f"Vision cache read failed for {file_id}: {e}")
@@ -210,7 +210,7 @@ def setup_upload_routes(upload_handler):
             logger.error(f"Vision analysis failed for {file_id}: {e}")
             raise HTTPException(500, f"Vision analysis failed: {e}")
         try:
-            with open(cache_path, "w") as f:
+            with open(cache_path, "w", encoding="utf-8") as f:
                 f.write(text)
         except Exception as e:
             logger.warning(f"Vision cache write failed for {file_id}: {e}")
@@ -238,7 +238,7 @@ def setup_upload_routes(upload_handler):
         text = (body or {}).get("text", "")
         if not isinstance(text, str):
             raise HTTPException(400, "text must be a string")
-        with open(_vision_cache_path(file_id), "w") as f:
+        with open(_vision_cache_path(file_id), "w", encoding="utf-8") as f:
             f.write(text)
         return {"ok": True}
 

routes/vault_routes.py

@@ -16,6 +16,7 @@ from fastapi import APIRouter, Request
 from pydantic import BaseModel
 
 from core.middleware import require_admin
+from core.platform_compat import IS_WINDOWS, safe_chmod, which_tool
 
 logger = logging.getLogger(__name__)
 
@@ -23,10 +24,23 @@ VAULT_FILE = Path("data/vault.json")
 
 
 def _find_bw() -> str:
-    """Locate the bw binary, checking PATH and common npm-global locations."""
-    p = shutil.which("bw")
+    """Locate the bw binary, checking PATH and common npm-global locations.
+
+    On Windows the Bitwarden CLI shim is `bw.cmd`/`bw.exe`, resolved by
+    which_tool via PATHEXT.
+    """
+    p = which_tool("bw")
     if p:
         return p
+    if IS_WINDOWS:
+        appdata = os.environ.get("APPDATA", os.path.expanduser("~"))
+        for candidate in (
+            os.path.join(appdata, "npm", "bw.cmd"),
+            os.path.join(appdata, "npm", "bw.exe"),
+        ):
+            if os.path.isfile(candidate):
+                return candidate
+        return "bw"
     home = os.path.expanduser("~")
     for candidate in (
         f"{home}/.npm-global/bin/bw",
@@ -47,7 +61,7 @@ def _find_bw() -> str:
 def _load_config() -> dict:
     if VAULT_FILE.exists():
         try:
-            return json.loads(VAULT_FILE.read_text())
+            return json.loads(VAULT_FILE.read_text(encoding="utf-8"))
         except Exception:
             pass
     return {}
@@ -55,11 +69,10 @@ def _load_config() -> dict:
 
 def _save_config(cfg: dict):
     VAULT_FILE.parent.mkdir(parents=True, exist_ok=True)
-    VAULT_FILE.write_text(json.dumps(cfg, indent=2))
-    try:
-        os.chmod(str(VAULT_FILE), 0o600)
-    except Exception:
-        pass
+    VAULT_FILE.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+    # POSIX: restrict the BW_SESSION store to 0o600. Windows: no-op (profile dir
+    # is ACL-restricted already).
+    safe_chmod(str(VAULT_FILE), 0o600)
 
 
 async def _run_bw(args: list, session: str = None, input_text: str = None) -> tuple: