witbitz-code 1.3.2__tar.gz → 1.3.3__tar.gz

{witbitz_code-1.3.2/src/witbitz_code.egg-info → witbitz_code-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.3.2
+Version: 1.3.3
 Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
 Author: Witbitz
 License-Expression: MIT
@@ -66,7 +66,8 @@ OpenCode's own window on this computer is refused ("coding runs from the Spaces
 being written another account cannot add to it. This splits the bill fairly between people who share a computer; it is not
 a wall between them (they already share its files and shell).
 
-To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`.
+To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`. (`pipx uninstall` alone
+leaves the pairing and its keys behind, and does not stop a witbitz-code that is still running — `setup` offers to stop one.)
 
 The same thing one step at a time: install OpenCode (`curl -fsSL https://opencode.ai/install | bash`), then
 `witbitz-code pair` and `witbitz-code serve`.

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/README.md

@@ -41,7 +41,8 @@ OpenCode's own window on this computer is refused ("coding runs from the Spaces
 being written another account cannot add to it. This splits the bill fairly between people who share a computer; it is not
 a wall between them (they already share its files and shell).
 
-To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`.
+To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`. (`pipx uninstall` alone
+leaves the pairing and its keys behind, and does not stop a witbitz-code that is still running — `setup` offers to stop one.)
 
 The same thing one step at a time: install OpenCode (`curl -fsSL https://opencode.ai/install | bash`), then
 `witbitz-code pair` and `witbitz-code serve`.

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "witbitz-code"
-version = "1.3.2"
+version = "1.3.3"
 description = "Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay."
 readme = "README.md"
 requires-python = ">=3.10"

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/__init__.py

@@ -4,4 +4,4 @@ The Python implementation of tools/witbitz-code.mjs (docs/opencode-relay.md phas
 vectors and cross-implementation tests.
 """
 
-__version__ = "1.3.2"
+__version__ = "1.3.3"

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/cli.py

@@ -17,6 +17,7 @@ import os
 import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Any
 
@@ -25,7 +26,7 @@ import httpx
 from . import __version__
 from . import pair as pair_cmd
 from . import pairings as pp
-from . import codekeys, codetools, confidential, keys, models, plugins, policy, uninstall as uninstall_mod, winconsole, wizard
+from . import codekeys, codetools, confidential, keys, models, plugins, policy, uninstall as uninstall_mod, winagent, winconsole, wizard
 from ._js import to_number, truthy
 from .connector import pairings_for_port, start_connector
 from .payers import SessionPayers
@@ -176,6 +177,11 @@ async def serve(args: list[str]) -> int:
     tools_env, tools_config, note = await asyncio.to_thread(codetools.code_tools, plugins.opencode_config_dir())
     if note:
         _err(note)
+    # On Windows: UTF-8 Python, Git Bash, the agent's own Python and the note naming them (winagent.py; measured).
+    w_add, w_instr, w_note = await asyncio.to_thread(winagent.windows_agent, plugins.opencode_config_dir())
+    if w_note:
+        _err(w_note)
+    tools_env, tools_config = winagent.apply(tools_env, tools_config, w_add, w_instr)
     # THIS COMPUTER'S CODING KEYS (codekeys.py; docs/code-account-keys.md): the only model keys witbitz-code uses. A pairing
     # made before them is not served — every call of its account would be refused.
     unkeyed = [p for p in pairings if not codekeys.for_computer(p.get("computerId") or "")]
@@ -201,11 +207,22 @@ async def serve(args: list[str]) -> int:
         # THE PROXY (confidential.py): started BEFORE OpenCode, which is always pointed at it — it puts each account's key on
         # the calls of that account's prompts, enforces the confidential models and refuses a model Witbitz does not offer.
         pport = models.proxy_port_for(port)
+        recheck = {"at": -1e9}
+
+        def key_refused() -> None:  # TrustedRouter refused a key: ask the account now (at most once a minute), not in hours
+            if time.monotonic() - recheck["at"] >= 60:
+                recheck["at"] = time.monotonic()
+                asyncio.ensure_future(live_keys.check(keys_http, _err))
+
         try:
             proxy = await confidential.start_confidential_proxy(port=pport, log=_err, on_progress=lambda ev: live["connector"] and live["connector"].progress(ev),
-                                                                credential_for=credential_for, offered=lambda m: m in offered)
+                                                                credential_for=credential_for, offered=lambda m: m in offered,
+                                                                on_key_refused=key_refused)
         except OSError as e:
-            _err(f"witbitz-code: could not start the model proxy on 127.0.0.1:{pport} ({e}) — free that port and run serve again")
+            held = "; ".join(f"{(o.get('cmd') or 'a program')[:70]} (process {o['pid']})" for o in ports.port_owners(pport))
+            _err(f"witbitz-code: could not start the model proxy on 127.0.0.1:{pport} ({e})"
+                 + (f" — held by {held}: an earlier witbitz-code still running? witbitz-code setup offers to stop it" if held
+                    else " — free that port and run serve again"))
             return 1
         route = models.proxy_config(proxy.port)
         if await is_listening(port) and "--no-opencode" not in args:
@@ -267,15 +284,19 @@ async def setup(args: list[str]) -> int:
 
     client = net.new_client()
 
-    async def keys_state(p: dict) -> str:
+    async def keys_state(p: dict) -> dict:
         entry = codekeys.for_computer(p.get("computerId") or "")
         if not entry:
-            return "none"
+            return {"state": "none"}
         try:
             st = await codekeys.status(client, entry)
-        except Exception:  # noqa: BLE001 — offline: unknown, never a removal
-            return "unknown"
-        return "live" if st.get("live") is True else st.get("why") if st.get("why") in ("revoked", "paused") else "unknown"
+        except Exception as e:  # noqa: BLE001 — offline: unknown, never a removal
+            return {"state": "unknown", "why": f"could not reach Witbitz ({str(e)[:80]})"}
+        if st.get("live") is True:
+            return {"state": "live"}
+        if st.get("why") in ("revoked", "paused"):
+            return {"state": st["why"]}
+        return {"state": "unknown", "why": str(st.get("why") or "no answer")}
 
     d = wizard.Deps(
         say=_err, ask=lambda q: keys.read_line(q), secret=lambda q: keys.read_line(q, hidden=True),

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/codekeys.py

@@ -17,6 +17,7 @@ import json
 import os
 import tempfile
 import time
+from email.utils import parsedate_to_datetime
 from pathlib import Path
 from typing import Any
 
@@ -114,8 +115,24 @@ def signed_message(op: str, key_id: str, ts: int) -> str:
     return f"wbcode-v1|{op}|{key_id}|{ts}"  # = codeKeys.mjs signedMessage
 
 
+# THIS COMPUTER'S CLOCK, as the server sees it. The server refuses a signed call more than 5 minutes off its own time, and a
+# clock can be: WSL's falls behind while the laptop sleeps (the owner, 2026-10-08 — setup trusted keys the account had taken
+# back, because the check that would have said so was refused). A refusal carries the server's time in its Date header;
+# from then on this process signs to that time. The signature still proves the key; only `ts` moves.
+SKEW_FIX_S = 60
+_clock = {"skew": 0.0}
+
+
+def reset_clock() -> None:
+    _clock["skew"] = 0.0
+
+
+def _now() -> float:
+    return time.time() + _clock["skew"]
+
+
 def signed_body(op: str, entry: dict, now: float | None = None) -> dict:
-    ts = int(now if now is not None else time.time())
+    ts = int(now if now is not None else _now())
     sig = _sign_key(entry).sign(signed_message(op, entry["keyId"], ts).encode())
     return {"keyId": entry["keyId"], "ts": ts, "sig": _b64u(sig)}
 
@@ -153,9 +170,10 @@ def save(entry: dict) -> None:
     _write_all(doc)
 
 
-def forget(computer_id: str) -> bool:
+def forget(computer_id: str, key_id: str | None = None) -> bool:
+    """Drop this computer's keys — with `key_id`, only if they are still THOSE keys (a re-pair may have replaced them)."""
     doc = read_all()
-    keep = [k for k in doc["keys"] if k.get("computerId") != computer_id]
+    keep = [k for k in doc["keys"] if k.get("computerId") != computer_id or (key_id is not None and k.get("keyId") != key_id)]
     if len(keep) == len(doc["keys"]):
         return False
     doc["keys"] = keep
@@ -214,13 +232,41 @@ async def mint(client: httpx.AsyncClient, *, id_token: str, account: str, comput
     return entry
 
 
+def _server_time(r: httpx.Response) -> float | None:
+    try:
+        return parsedate_to_datetime(r.headers.get("date") or "").timestamp()
+    except (TypeError, ValueError):
+        return None
+
+
+async def _signed_post(client: httpx.AsyncClient, path: str, op: str, entry: dict, timeout: float = 10) -> httpx.Response:
+    """A signed call; refused while this computer's clock is off the server's, it is signed again to the server's time."""
+    r = await client.post(api_base() + path, json=signed_body(op, entry), timeout=timeout)
+    if r.status_code == 401:
+        server = _server_time(r)
+        if server is not None and abs(server - _now()) > SKEW_FIX_S:
+            _clock["skew"] = server - time.time()
+            r = await client.post(api_base() + path, json=signed_body(op, entry), timeout=timeout)
+    return r
+
+
+def _why(r: httpx.Response) -> str:
+    """The server's own sentence for a refusal, with its status — what a person reads when the answer could not be had."""
+    try:
+        msg = str(((r.json() or {}).get("error") or {}).get("message") or "")
+    except ValueError:
+        msg = ""
+    return f"{msg} ({r.status_code})" if msg else f"the account answered {r.status_code}"
+
+
 async def status(client: httpx.AsyncClient, entry: dict) -> dict:
-    """{live, why?, month?} — and a Tinfoil key minted or renewed server-side is opened into the entry (the caller saves)."""
-    r = await client.post(api_base() + "/status", json=signed_body("status", entry), timeout=10)
+    """{live, why?, month?} — and a Tinfoil key minted or renewed server-side is opened into the entry (the caller saves).
+    live None: the answer could not be had, and `why` says why."""
+    r = await _signed_post(client, "/status", "status", entry)
     if r.status_code == 404:
         return {"live": False, "why": "revoked"}
     if r.status_code != 200:
-        return {"live": None, "why": f"status answered {r.status_code}"}  # unknown — keep going as before
+        return {"live": None, "why": _why(r)}  # unknown — keep going as before, and say why
     d = (r.json() or {}).get("data") or {}
     tf = (d.get("sealed") or {}).get("tinfoil")
     if tf:
@@ -234,7 +280,7 @@ async def status(client: httpx.AsyncClient, entry: dict) -> dict:
 async def revoke(client: httpx.AsyncClient, entry: dict) -> bool:
     """This computer gives its keys back (unpair, uninstall). True when the server confirmed."""
     try:
-        r = await client.post(api_base() + "/revoke", json=signed_body("revoke", entry), timeout=10)
+        r = await _signed_post(client, "/revoke", "revoke", entry)
     except httpx.HTTPError:
         return False
     return r.status_code in (200, 404)  # 404: already gone
@@ -249,13 +295,39 @@ class LiveKeys:
     """The keys of the pairings `serve` answers for, and what the server last said about each (status every few hours)."""
 
     def __init__(self, computer_ids: list[str]) -> None:
-        self.entries: dict[str, dict] = {c: e for c in computer_ids if (e := for_computer(c))}
+        self.ids = list(computer_ids)
+        self.entries: dict[str, dict] = {}
         self.refuse: dict[str, str] = {}
+        self.unknown: dict[str, str] = {}
+        self._seen: Any = "never"
+        self._fresh()
+
+    def _fresh(self) -> None:
+        """Re-read the keys file when it changed: a re-pair while serve runs replaces this computer's keys (the owner,
+        2026-10-08: a running serve kept answering with the old ones — "Invalid API key")."""
+        try:
+            st = keys_path().stat()
+            seen: Any = (st.st_mtime_ns, st.st_size, st.st_ino)
+        except OSError:
+            seen = None
+        if seen == self._seen:
+            return
+        self._seen = seen
+        for c in self.ids:
+            e = for_computer(c)
+            prev = self.entries.get(c)
+            if e:
+                if prev and prev.get("keyId") != e.get("keyId"):
+                    self.refuse.pop(c, None)  # new keys: what was said of the old ones is not about these
+                self.entries[c] = e
+            else:
+                self.entries.pop(c, None)
 
     def credential(self, computer_id: str | None) -> dict | None:
         """The proxy's answer for a call owned by `computer_id`: its keys, or {refuse: sentence}. None: no owner."""
         if not computer_id:
             return None
+        self._fresh()
         if computer_id in self.refuse:
             return {"refuse": self.refuse[computer_id]}
         e = self.entries.get(computer_id)
@@ -264,13 +336,25 @@ class LiveKeys:
         return {"trustedrouter": e.get("trustedrouter", ""), "tinfoil": e.get("tinfoil", "")}
 
     async def check(self, client: httpx.AsyncClient, say: Any = lambda _m: None) -> None:
+        self._fresh()
         for cid, e in list(self.entries.items()):
             try:
                 st = await status(client, e)
             except httpx.HTTPError:
                 continue  # unknown: keep going as before; the next check asks again
+            if st.get("live") is None:
+                if self.unknown.get(cid) != st.get("why"):
+                    say(f'witbitz-code: could not check the coding keys of "{e.get("name")}" with your account — {st.get("why")}')
+                self.unknown[cid] = str(st.get("why"))
+                continue
+            self.unknown.pop(cid, None)
             if st.get("live") is False and st.get("why") == "revoked":
-                forget(cid)
+                now = for_computer(cid)
+                if now and now.get("keyId") != e.get("keyId"):  # a re-pair replaced these keys while the account was asked
+                    self.entries[cid] = now
+                    self.refuse.pop(cid, None)
+                    continue
+                forget(cid, e.get("keyId"))
                 self.entries.pop(cid, None)
                 self.refuse[cid] = REVOKED_TEXT
                 say(f'witbitz-code: the coding keys of "{e.get("name")}" → {e.get("account")} were revoked — pair again to code from that account')

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/confidential.py

@@ -457,7 +457,7 @@ class ConfidentialProxy:
                  reader: Any = "default", log: Callable[[str], Any] = print, policies: set | None = None,
                  verify: Callable | None = None, sleep: Callable = asyncio.sleep, on_progress: Callable[[dict], Any] = lambda ev: None,
                  cache_marks: bool = True, credential_for: Callable[["_Request"], dict | None] | None = None,
-                 offered: Callable[[str], bool] | None = None) -> None:
+                 offered: Callable[[str], bool] | None = None, on_key_refused: Callable[[], Any] = lambda: None) -> None:
         self.port, self.host, self.upstream = port, host, upstream
         self.client = client or httpx.AsyncClient(trust_env=False, timeout=httpx.Timeout(None, connect=15.0))
         self.models = models if models is not None else mdl.confidential_models()
@@ -473,6 +473,16 @@ class ConfidentialProxy:
         # key OpenCode sends is used as is (tests, and a proxy run by hand).
         self._credential_for = credential_for
         self._offered = offered
+        # TrustedRouter refused an account's key (401): it was taken back — a removal in the app, a re-pair. serve asks the
+        # account at once instead of at its next check, hours later (the owner, 2026-10-08: "Invalid API key").
+        self._on_key_refused = on_key_refused
+
+    def _key_refused(self, status: int) -> None:
+        if status == 401 and self._credential_for is not None:
+            try:
+                self._on_key_refused()
+            except Exception:  # noqa: BLE001 — a hook must never fail a call
+                pass
 
     def add_confidential(self, lst: Any) -> int:
         """Models the account offers as confidential today — added, never removed (models.add_confidential)."""
@@ -579,6 +589,7 @@ class ConfidentialProxy:
         try:
             async with self.client.stream(req.method, target, headers=_forward_headers(req.headers), content=None if req.method in ("GET", "HEAD") else out) as up:
                 headers = {k: v for k, v in up.headers.items() if k.lower() not in ("content-encoding", "content-length", "transfer-encoding", "connection")}
+                self._key_refused(up.status_code)
                 await res.head(up.status_code, headers)
                 async for c in up.aiter_bytes():
                     await res.write(c)
@@ -614,6 +625,7 @@ class ConfidentialProxy:
             tell("waiting", bytes=len(raw))
             async with self.client.stream("POST", target, headers=headers, content=raw) as up:
                 if not up.is_success:
+                    self._key_refused(up.status_code)
                     text = (await up.aread()).decode("utf-8", "replace")
                     if res.headers_sent:
                         raise Refusal(502, f"{label}: TrustedRouter answered {up.status_code} when asked again ({text[:160]})", "upstream_error")

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/pair.py

@@ -279,6 +279,8 @@ async def _keys_line(p: dict, keys: Any) -> str:
         st = await keys.status(entry)
     except Exception as e:  # noqa: BLE001 — status is a reading, never a failure of the command
         return f"coding keys: could not ask ({str(e)[:60]})"
+    if st.get("live") is None:
+        return f"coding keys: could not check with your account — {st.get('why')}"
     if st.get("live") is False:
         return "coding keys: revoked — pair again: witbitz-code pair" if st.get("why") == "revoked" else "coding keys: paused by Witbitz"
     m = st.get("month") or {}

witbitz_code-1.3.3/src/witbitz_code/ports.py

@@ -0,0 +1,87 @@
+"""Who is listening on a port of this computer — this user's processes only (= tools/witbitz-code.mjs portOwners).
+
+setup asks it before starting: an earlier witbitz-code still running (`pipx uninstall` does not stop it) holds OpenCode's
+port and the model proxy's (port + 100), and keeps answering the phone with the keys it started with (the owner,
+2026-10-08: "could not start the model proxy … address already in use", then "Invalid API key"). Linux reads /proc; macOS
+asks lsof; elsewhere nothing is known and setup says the port is taken.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def port_owners(port: int) -> list[dict]:
+    """[{pid, cmd}] of this user's processes listening on 127.0.0.1/::1 `port` (never this process)."""
+    if Path("/proc/net/tcp").exists():
+        return _proc_owners(port)
+    if shutil.which("lsof"):
+        return _lsof_owners(port)
+    return []
+
+
+def _proc_owners(port: int) -> list[dict]:
+    inodes: set[str] = set()
+    for f in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            lines = Path(f).read_text().splitlines()[1:]
+        except OSError:
+            continue
+        for line in lines:
+            c = line.split()
+            if len(c) >= 10 and c[3] == "0A" and int(c[1].rsplit(":", 1)[-1], 16) == port:  # 0A = LISTEN
+                inodes.add(c[9])
+    if not inodes:
+        return []
+    hits = []
+    for p in os.listdir("/proc"):
+        if not p.isdigit() or int(p) == os.getpid():
+            continue
+        try:
+            fds = os.listdir(f"/proc/{p}/fd")
+        except OSError:
+            continue  # not this user's
+        owns = False
+        for fd in fds:
+            try:
+                link = os.readlink(f"/proc/{p}/fd/{fd}")
+            except OSError:
+                continue
+            if link.startswith("socket:[") and link[8:-1] in inodes:
+                owns = True
+                break
+        if not owns:
+            continue
+        try:
+            cmd = " ".join(x for x in Path(f"/proc/{p}/cmdline").read_bytes().decode("utf-8", "replace").split("\0") if x)
+        except OSError:
+            cmd = ""
+        hits.append({"pid": int(p), "cmd": cmd})
+    return hits
+
+
+def _lsof_owners(port: int) -> list[dict]:
+    try:
+        out = subprocess.run(["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"], capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.SubprocessError):
+        return []
+    hits = []
+    for pid in sorted({int(x) for x in out.split() if x.isdigit()}):
+        if pid == os.getpid():
+            continue
+        try:
+            cmd = subprocess.run(["ps", "-o", "command=", "-p", str(pid)], capture_output=True, text=True, timeout=5).stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            cmd = ""
+        hits.append({"pid": pid, "cmd": cmd})
+    return hits
+
+
+def on_wsl() -> bool:
+    try:
+        return "microsoft" in Path("/proc/version").read_text().lower()
+    except OSError:
+        return False

witbitz_code-1.3.3/src/witbitz_code/winagent.py

@@ -0,0 +1,111 @@
+"""What OpenCode gets on Windows, measured (2026-10-08, Windows 11, OpenCode 1.18.30; six teacher tasks with Hebrew data on
+DeepSeek V4.1 Flash, Claude Haiku 4.5 and GLM 5.3 Flash — 48/48 correct with all of this, 45/48 without):
+
+- PYTHONUTF8=1 — Windows Python writes cp1252 to a pipe and died printing Hebrew ("'charmap' codec can't encode").
+- Git Bash as the shell (SHELL) where it is installed — a model's bash habits (heredocs, /c/ paths in a shell) just work
+  there; in PowerShell 5.1 Haiku opened 7 of 12 runs with a heredoc even when told not to.
+- A Python of its own first on PATH, with a python3 that is real — the bare name is the Microsoft Store stub, which prints
+  "Python" and fails. code.ps1 makes it: %LOCALAPPDATA%\\Witbitz\\agent-python, a uv venv with python3.exe beside python.exe.
+- An instructions file saying all that — above all that OpenCode's read/write tools are Windows programs: under Git Bash,
+  Haiku wrote "/c/Users/…" with the write tool, which landed in C:\\c\\Users\\… while it reported Done.
+
+Off Windows nothing changes. code.ps1 (spaces/public) installs the Git and the Python this looks for."""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import sys
+from pathlib import Path
+from typing import Callable
+
+INSTRUCTIONS_NAME = "witbitz-windows.md"
+
+GIT_BASH = """# This computer
+- Windows. Your shell is Git Bash. In shell commands paths look like /c/Users/name/folder, but the read/write/edit tools are Windows programs and need C:\\Users\\name\\folder (or a path relative to the working directory). Never pass /c/... to those tools.
+- Python: run `python` or `python3` (a Python of your own is first on PATH). If a module is missing, `python -m pip install <name>`.
+- Files with non-English text (e.g. Hebrew) are UTF-8. Prefer Python for CSV, Excel and Word files.
+- pip's "[notice] A new release of pip" line is not an error.
+"""
+
+POWERSHELL = """# This computer
+- Windows. Your shell is Windows PowerShell 5.1. Paths look like C:\\Users\\name\\folder - use that form everywhere, including in the read/write/edit tools.
+- Python: run `python` or `python3` (a Python of your own is first on PATH, when there is one). If a module is missing, `python -m pip install <name>`.
+- Files with non-English text (e.g. Hebrew) are UTF-8. In PowerShell always pass `-Encoding UTF8` to Get-Content, Set-Content, Out-File, Import-Csv and Export-Csv. Prefer Python for CSV, Excel and Word files.
+- PowerShell has no here-documents: `python << 'EOF'` does not work. For anything longer than one line, write a .py file and run `python file.py`.
+- pip's "[notice] A new release of pip" line is not an error.
+"""
+
+
+def _witbitz_dir(env: dict) -> str:
+    return ntpath.join(env.get("LOCALAPPDATA", ""), "Witbitz")
+
+
+def find_git_bash(env: dict, exists: Callable[[str], bool]) -> str | None:
+    """Git Bash: the one code.ps1 installs first, then Git for Windows' usual places."""
+    candidates = [env.get("WITBITZ_GIT_BASH", ""), ntpath.join(_witbitz_dir(env), "git", "bin", "bash.exe")]
+    for root in (env.get("ProgramFiles", ""), env.get("ProgramW6432", ""), env.get("ProgramFiles(x86)", "")):
+        if root:
+            candidates.append(ntpath.join(root, "Git", "bin", "bash.exe"))
+    if env.get("LOCALAPPDATA"):
+        candidates.append(ntpath.join(env["LOCALAPPDATA"], "Programs", "Git", "bin", "bash.exe"))
+    return next((c for c in candidates if c and exists(c)), None)
+
+
+def find_agent_python(env: dict, exists: Callable[[str], bool]) -> str | None:
+    """The Scripts folder of the agent's own Python (code.ps1 makes it), or None."""
+    home = env.get("WITBITZ_AGENT_PYTHON") or ntpath.join(_witbitz_dir(env), "agent-python")
+    scripts = ntpath.join(home, "Scripts")
+    return scripts if exists(ntpath.join(scripts, "python.exe")) else None
+
+
+def _write_once(f: Path, text: str) -> None:
+    try:
+        if f.read_text(encoding="utf-8") == text:
+            return
+    except (OSError, UnicodeDecodeError):
+        pass
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text(text, encoding="utf-8", newline="")
+
+
+def windows_agent(config_dir: Path, env: dict | None = None, platform: str | None = None,
+                  exists: Callable[[str], bool] = os.path.exists) -> tuple[dict, str | None, str]:
+    """→ (env additions — PATH_PREPEND is a list for apply(), the instructions file or None, a line for the log or "")."""
+    platform = sys.platform if platform is None else platform
+    if platform != "win32":
+        return {}, None, ""
+    env = os.environ if env is None else env
+    add: dict = {"PYTHONUTF8": "1"}
+    bash = find_git_bash(env, exists)
+    if bash:
+        add["SHELL"] = bash
+    py = find_agent_python(env, exists)
+    if py:
+        add["PATH_PREPEND"] = [py]
+    f = Path(config_dir) / INSTRUCTIONS_NAME
+    instr: str | None = None
+    try:
+        _write_once(f, GIT_BASH if bash else POWERSHELL)
+        instr = str(f)
+    except OSError:
+        pass
+    shell = f"Git Bash ({bash})" if bash else "PowerShell (no Git Bash found)"
+    pyline = f"Python {ntpath.dirname(py)}" if py else "no Python of its own (run the installer again to add it)"
+    return add, instr, f"witbitz-code: on Windows — shell {shell}, {pyline}, UTF-8 for Python"
+
+
+def apply(tools_env: dict, tools_config: dict, add: dict, instructions: str | None, base_path: str | None = None) -> tuple[dict, dict]:
+    """Fold windows_agent's result into codetools' (env, config), without changing either: the agent's Python goes first on
+    PATH (ahead of ast-grep), and its instructions file joins the list (OpenCode's config merge replaces lists)."""
+    env = {k: v for k, v in tools_env.items()}
+    for k, v in add.items():
+        if k != "PATH_PREPEND":
+            env[k] = v
+    if add.get("PATH_PREPEND"):
+        rest = env.get("PATH", base_path if base_path is not None else os.environ.get("PATH", ""))
+        env["PATH"] = ";".join(list(add["PATH_PREPEND"]) + ([rest] if rest else []))
+    config = {k: v for k, v in tools_config.items()}
+    if instructions:
+        config["instructions"] = list(tools_config.get("instructions") or []) + [instructions]
+    return env, config

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code/wizard.py

@@ -21,7 +21,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from . import codekeys
+from . import codekeys, ports
 from . import pairings as pp
 from .connector import _url_port
 
@@ -74,6 +74,9 @@ class Deps:
     keys_state: Callable[[dict], Awaitable[str]] | None = None
     forget_keys: Callable[[dict], Any] = lambda p: codekeys.forget(p.get("computerId") or "")
     is_listening: Callable[[int], Awaitable[bool]] = None  # type: ignore[assignment]
+    port_owners: Callable[[int], list] = ports.port_owners  # [{pid, cmd}] — this user's processes on a port (ports.py)
+    stop_process: Callable[[int], bool] = lambda pid: __import__("witbitz_code.uninstall", fromlist=["stop_process"]).stop_process(pid)
+    wsl: bool = field(default_factory=ports.on_wsl)
     serve_here: Callable[[int], Awaitable[int]] = None  # type: ignore[assignment]
     result: dict = field(default_factory=lambda: {"opencode": False, "paired": False, "keys": False, "running": ""})
 
@@ -126,7 +129,17 @@ async def run_setup(d: Deps) -> dict:
     mine = on(everything, port)
     # A pairing the account has let go of (the owner, 2026-10-08: reinstalled after a removal and "it does not present the
     # QR code"): its keys come back revoked, so it is not a pairing any more — say so and scan again. Offline is not that.
-    gone = [p for p in mine if d.keys_state and d.code_keys(p) and await d.keys_state(p) == "revoked"]
+    unchecked: dict[str, str] = {}  # computerId → why the account could not be asked (said at step 3, never a silent ✓)
+    gone = []
+    for p in mine:
+        if not (d.keys_state and d.code_keys(p)):
+            continue
+        st = await d.keys_state(p)
+        state, why = (st, "") if isinstance(st, str) else (str(st.get("state") or ""), str(st.get("why") or ""))
+        if state == "revoked":
+            gone.append(p)
+        elif state == "unknown":
+            unchecked[p.get("computerId") or ""] = why or "no answer"
     for p in gone:
         d.forget_keys(p)
     if mine and len(gone) == len(mine):
@@ -157,13 +170,49 @@ async def run_setup(d: Deps) -> dict:
             return {**result, "stopped": "keys"}
     caps = (d.code_keys(mine[0]) or {}).get("caps") or {}
     d.say(f"   ✓ Issued by your Spaces account (this computer: up to ${caps.get('modelsUsd', '?')} of models and ${caps.get('toolsUsd', '?')} of tools a month)")
+    for p in mine:
+        why = unchecked.get(p.get("computerId") or "")
+        if why:
+            d.say(f"   ? Could not check them with your account just now — {why}. Using them as they are;")
+            d.say("     if your phone shows this computer as removed, run: witbitz-code pair")
     result["keys"] = True
 
     # 4 — running (this package has no background service yet: it runs in this window)
     d.say("\n4. Keep it running")
-    if await d.is_listening(port):
-        d.say(f"   OpenCode is already running on 127.0.0.1:{port}, started some other way. witbitz-code starts OpenCode itself,")
-        d.say("   with your account's keys — close that OpenCode first, or serve will stop and say so.")
+    # OpenCode's port AND the model proxy's (port + 100): an earlier witbitz-code still running holds both, and keeps answering
+    # the phone with the keys it started with (the owner, 2026-10-08: `pipx uninstall` left it running — "could not start
+    # the model proxy … address already in use", then "Invalid API key"). This person's own process: offer to stop it.
+    for _ in range(6):
+        busy = [q for q in (port, port + 100) if await d.is_listening(q)]
+        if not busy:
+            break
+        owners: list[dict] = []
+        for q in busy:
+            for o in d.port_owners(q):
+                if all(o["pid"] != x["pid"] for x in owners):
+                    owners.append(o)
+        if not owners:
+            d.say(f"   Port {busy[0]} is taken by a program that is not yours{' — on WSL, another Linux distro on this computer shares its ports' if d.wsl else ''}.")
+            d.say(f"   Run setup with another port: witbitz-code setup --port {port + 1}")
+            return {**result, "stopped": "busy"}
+        listed = "; ".join(f"{(o.get('cmd') or 'a program')[:70]} (process {o['pid']})" for o in owners)
+        d.say(f"   Already running here: {listed}.")
+        d.say("   That is an earlier witbitz-code or an OpenCode started some other way — it would keep answering your phone with")
+        d.say("   other keys. witbitz-code starts OpenCode itself, with this computer's keys from your account.")
+        a = str(d.ask(f"   Stop {'them' if len(owners) > 1 else 'it'} now? [Y/n] — or type s to stop here: ") or "").strip().lower()
+        if a.startswith("s"):
+            d.say("   Stopped. Run setup again when you are ready.")
+            return {**result, "stopped": "busy"}
+        if a.startswith("n"):
+            if str(d.ask("   Close it yourself, then press Enter — or type s to stop here: ") or "").strip().lower().startswith("s"):
+                d.say("   Stopped. Run setup again when you are ready.")
+                return {**result, "stopped": "busy"}
+            continue
+        for o in owners:
+            d.say(f"   ✓ Stopped process {o['pid']}" if d.stop_process(o["pid"]) else f"   ✖ Could not stop process {o['pid']}")
+    else:
+        d.say(f"   Ports {port} and {port + 100} are still in use. Close what holds them, then run setup again.")
+        return {**result, "stopped": "busy"}
     d.say("\nDone. Starting witbitz-code in this window — keep it open (Ctrl-C stops it). Open Spaces → ☰ → Code on your phone.\n")
     result["running"] = "here"
     result["port"] = port

{witbitz_code-1.3.2 → witbitz_code-1.3.3/src/witbitz_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.3.2
+Version: 1.3.3
 Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
 Author: Witbitz
 License-Expression: MIT
@@ -66,7 +66,8 @@ OpenCode's own window on this computer is refused ("coding runs from the Spaces
 being written another account cannot add to it. This splits the bill fairly between people who share a computer; it is not
 a wall between them (they already share its files and shell).
 
-To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`.
+To start over: `witbitz-code uninstall`, then `pipx install witbitz-code` and `witbitz-code setup`. (`pipx uninstall` alone
+leaves the pairing and its keys behind, and does not stop a witbitz-code that is still running — `setup` offers to stop one.)
 
 The same thing one step at a time: install OpenCode (`curl -fsSL https://opencode.ai/install | bash`), then
 `witbitz-code pair` and `witbitz-code serve`.

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/src/witbitz_code.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/witbitz_code/pairings.py
 src/witbitz_code/payers.py
 src/witbitz_code/plugins.py
 src/witbitz_code/policy.py
+src/witbitz_code/ports.py
 src/witbitz_code/qr.py
 src/witbitz_code/receipt.py
 src/witbitz_code/relay.py
@@ -38,6 +39,7 @@ src/witbitz_code/seen.py
 src/witbitz_code/tinfoil_read.py
 src/witbitz_code/tools_probe.py
 src/witbitz_code/uninstall.py
+src/witbitz_code/winagent.py
 src/witbitz_code/winconsole.py
 src/witbitz_code/wizard.py
 src/witbitz_code.egg-info/PKG-INFO
@@ -65,9 +67,11 @@ tests/test_outputs.py
 tests/test_pair_flows.py
 tests/test_plugins.py
 tests/test_policy.py
+tests/test_ports.py
 tests/test_registry.py
 tests/test_relay_codec.py
 tests/test_setup.py
 tests/test_tools_probe.py
 tests/test_uninstall.py
+tests/test_winagent.py
 tests/test_winconsole.py

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/tests/test_codekeys.py

@@ -142,6 +142,121 @@ def test_live_keys_follow_what_the_server_says():
     assert live.credential("cmp_1") == {"refuse": codekeys.REVOKED_TEXT} and codekeys.for_computer("cmp_1") is None, "revoked: forgotten here too"
 
 
+
+# ── 1.3.3: the laptop's clock, a refusal that says why, keys that change under a running serve ──────────────────────────
+# The owner, 2026-10-08, on WSL: setup said "✓ Issued" over keys the account had taken back, a running serve answered with
+# them ("Invalid API key"), and a re-pair's keys never reached it. A WSL clock falls behind while the laptop sleeps, and the
+# server refuses a signed call more than 5 minutes off — so the answer never came, and nothing said why.
+def _server(skew_s: float, answer: dict, calls: list):
+    """A /status + /revoke that keeps its own clock (local + skew) and refuses a call more than 300 s off, as codeKeys.mjs."""
+    from email.utils import formatdate
+    import time as _t
+
+    def handler(req):
+        body = json.loads(req.content or b"{}")
+        calls.append((req.url.path, body.get("ts")))
+        now = _t.time() + skew_s
+        date = {"date": formatdate(now, usegmt=True)}
+        if abs(int(body.get("ts", 0)) - now) > 300:
+            return httpx.Response(401, headers=date, json={"error": {"code": "unauthorized", "message": "the request is too old or from the future — check this computer's clock"}})
+        return httpx.Response(200, headers=date, json={"data": answer})
+    return handler
+
+
+def test_a_laptop_whose_clock_is_off_still_gets_the_answer_and_signs_to_the_servers_time_after():
+    from fakes import give_code_keys
+
+    codekeys.reset_clock()
+    e = give_code_keys("cmp_1")
+    calls = []
+    async def go():
+        async with client_for(_server(-3600, {"live": False, "why": "revoked"}, calls)) as c:  # this computer is an hour AHEAD
+            first = await codekeys.status(c, e)
+            second = await codekeys.status(c, e)
+            gone = await codekeys.revoke(c, e)
+        return first, second, gone
+    first, second, gone = run(go())
+    assert first == {"live": False, "why": "revoked"} and second == first and gone is True
+    assert len(calls) == 4, f"one refused call, then every call signed to the server's clock: {calls}"
+    codekeys.reset_clock()
+
+
+def test_an_answer_that_cannot_be_had_says_why():
+    from fakes import give_code_keys
+
+    codekeys.reset_clock()
+    e = give_code_keys("cmp_1")
+    def refuse(req):
+        return httpx.Response(401, json={"error": {"code": "unauthorized", "message": "the signature does not match this computer"}})
+    async def go():
+        async with client_for(refuse) as c:
+            return await codekeys.status(c, e)
+    st = run(go())
+    assert st["live"] is None and "signature does not match" in st["why"]
+
+
+def _replace_keys(computer_id: str, kid: str, tr: str) -> dict:
+    from fakes import give_code_keys
+
+    e = give_code_keys(computer_id)
+    e = {**e, "keyId": e["userId"] + "." + kid, "kid": kid, "trustedrouter": tr}
+    codekeys.save(e)
+    return e
+
+
+def test_a_running_serve_picks_up_the_keys_a_new_pairing_saved():
+    from fakes import give_code_keys
+
+    give_code_keys("cmp_1")
+    live = codekeys.LiveKeys(["cmp_1"])
+    assert live.credential("cmp_1")["trustedrouter"] == "sk-tr-made-up-cmp_1"
+    _replace_keys("cmp_1", "k_" + "2" * 24, "sk-tr-the-new-one")
+    assert live.credential("cmp_1")["trustedrouter"] == "sk-tr-the-new-one", "the new pairing's key, without a restart"
+
+
+def test_the_old_keys_revocation_never_forgets_the_new_pairings_keys():
+    from fakes import give_code_keys
+
+    give_code_keys("cmp_1")
+    live = codekeys.LiveKeys(["cmp_1"])
+    landed = {}
+    def answer(req):  # the re-pair lands while the check is asking about the OLD keys — the server took those back
+        landed.setdefault("new", _replace_keys("cmp_1", "k_" + "2" * 24, "sk-tr-the-new-one"))
+        return httpx.Response(200, json={"data": {"live": False, "why": "revoked"}})
+    async def check():
+        async with client_for(answer) as c:
+            await live.check(c, lambda _m: None)
+    run(check())
+    new = landed["new"]
+    assert (codekeys.for_computer("cmp_1") or {}).get("keyId") == new["keyId"], "the new pairing's keys are still on disk"
+    assert live.credential("cmp_1")["trustedrouter"] == "sk-tr-the-new-one"
+
+
+
+def test_a_key_trustedrouter_refuses_makes_the_proxy_say_so_at_once_for_both_kinds_of_model():
+    # a removal in the app (or a re-pair) takes the keys back; serve asked the account only every few hours, so the phone
+    # read TrustedRouter's "Invalid API key" until then. Now the proxy tells serve, which asks the account at once.
+    told = []
+    def upstream(req):
+        return httpx.Response(401, json={"error": {"message": "Invalid API key"}})
+    async def gate_ok():  # TrustedRouter's gateway attestation is its own test (test_confidential.py)
+        return {"ok": True}
+    async def go(model):
+        p = await cf.start_confidential_proxy(upstream="https://tr.test", client=httpx.AsyncClient(transport=httpx.MockTransport(upstream)),
+                                              reader=None, log=lambda _l: None, credential_for=lambda req: {"trustedrouter": "sk-old"},
+                                              on_key_refused=lambda: told.append(model), gate=gate_ok)
+        try:
+            async with httpx.AsyncClient(timeout=10) as oc:
+                r = await oc.post(f"http://127.0.0.1:{p.port}/v1/chat/completions", json={"model": model, "messages": []}, headers={"x-session-id": "s"})
+                return r.status_code
+        finally:
+            await p.close()
+    plain = run(go("openai/gpt-6-sol"))
+    conf_model = next(iter(mdl.confidential_models()))
+    conf = run(go(conf_model))
+    assert plain == 401 and conf == 401 and told == ["openai/gpt-6-sol", conf_model]
+
+
 # ── who pays ─────────────────────────────────────────────────────────────────────────────────────────────────────────
 def test_each_turn_is_its_accounts_and_another_account_cannot_steer_into_it():
     p = SessionPayers()

witbitz_code-1.3.3/tests/test_ports.py

@@ -0,0 +1,31 @@
+"""ports.port_owners against a real listening process (setup's step 4 asks it before offering to stop an earlier run)."""
+
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from witbitz_code import ports
+
+pytestmark = pytest.mark.skipif(not Path("/proc/net/tcp").exists() and sys.platform != "darwin", reason="Linux /proc or macOS lsof")
+
+
+def test_the_process_listening_on_a_port_is_named_and_a_free_port_has_nobody():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+    child = subprocess.Popen([sys.executable, "-c", f"import socket,time;s=socket.socket();s.bind(('127.0.0.1',{port}));s.listen();time.sleep(30)"])
+    try:
+        for _ in range(50):
+            hits = ports.port_owners(port)
+            if hits:
+                break
+            time.sleep(0.1)
+        assert [h["pid"] for h in hits] == [child.pid] and "socket" in hits[0]["cmd"]
+    finally:
+        child.kill()
+        child.wait()
+    assert ports.port_owners(port) == []

{witbitz_code-1.3.2 → witbitz_code-1.3.3}/tests/test_setup.py

@@ -118,7 +118,9 @@ class Fake:
             find_opencode=lambda: "/usr/bin/opencode" if self._oc else "", can_install_opencode=lambda: False,
             all_pairings=lambda: list(self._pairings), pair=pair, move_pairing=lambda p, port: None,
             code_keys=lambda p: {"caps": {"modelsUsd": 50, "toolsUsd": 5}} if p.get("computerId") in self._keyed else None,
-            is_listening=listening, serve_here=serve_here, **over)
+            serve_here=serve_here,
+            # never this machine's real processes: the real lookup finds whatever listens on 4096 HERE (an OpenCode does)
+            **{"is_listening": listening, "port_owners": lambda port: [], "stop_process": lambda pid: False, "wsl": False, **over})
 
 
 def test_a_new_computer_is_paired_gets_its_keys_from_the_account_and_is_served_without_a_key_prompt():
@@ -162,11 +164,38 @@ def test_paired_for_another_port_uses_it():
     assert r["port"] == 4097 and f.served == [4097] and f.paired == []
 
 
-def test_an_opencode_started_elsewhere_is_named():
+def test_a_port_taken_by_a_program_that_is_not_yours_stops_setup_with_another_port_to_use():
     f = Fake(listening=True)
-    run(wizard.run_setup(f.deps()))
-    assert any("started some other way" in line for line in f.said)
-    assert any("close that OpenCode first" in line for line in f.said)
+    r = run(wizard.run_setup(f.deps()))
+    assert r["stopped"] == "busy" and f.served == []
+    assert any("Port 4096 is taken by a program that is not yours" in line for line in f.said)
+    assert any("witbitz-code setup --port 4097" in line for line in f.said)
+
+
+def test_an_earlier_witbitz_code_still_running_is_named_and_stopped_both_ports_then_this_one_serves():
+    # the owner, 2026-10-08: `pipx uninstall` left the old serve running — its OpenCode on 4096, its proxy on 4196
+    held = {4096: {"pid": 11, "cmd": "opencode serve --port 4096"}, 4196: {"pid": 10, "cmd": "/usr/bin/python3 witbitz-code serve"}}
+    f = Fake(pairings=[{"name": "desk", "opencodeUrl": "http://127.0.0.1:4096", "idx": {"room": "r"}, "computerId": "c"}], keyed={"c"}, answers=[""])
+    stopped = []
+    async def listening(port):
+        return port in held
+    def stop(pid):
+        stopped.append(pid)
+        for q in [q for q, o in held.items() if o["pid"] == pid]:
+            held.pop(q)
+        return True
+    r = run(wizard.run_setup(f.deps(is_listening=listening, port_owners=lambda port: [held[port]] if port in held else [], stop_process=stop)))
+    assert sorted(stopped) == [10, 11] and f.served == [4096] and not r.get("stopped")
+    assert any("Already running here: opencode serve --port 4096 (process 11); /usr/bin/python3 witbitz-code serve (process 10)" in line for line in f.said)
+
+
+def test_s_stops_setup_and_leaves_the_running_one_alone():
+    held = {4096: {"pid": 11, "cmd": "opencode serve"}}
+    f = Fake(answers=["s"])
+    async def listening(port):
+        return port in held
+    r = run(wizard.run_setup(f.deps(is_listening=listening, port_owners=lambda port: [held[port]] if port in held else [], stop_process=lambda pid: (_ for _ in ()).throw(AssertionError("never")))))
+    assert r["stopped"] == "busy" and f.served == []
 
 
 def test_a_computer_removed_from_the_account_is_paired_again_and_shows_the_qr():
@@ -184,9 +213,10 @@ def test_a_computer_removed_from_the_account_is_paired_again_and_shows_the_qr():
     assert not any(line.startswith("   ✓ Paired") for line in f.said[:f.said.index(next(x for x in f.said if "was removed" in x))])
 
 
-def test_keys_that_cannot_be_checked_are_not_taken_for_a_removal():
+def test_keys_that_cannot_be_checked_are_not_taken_for_a_removal_and_setup_says_why():
     f = Fake(pairings=[{"name": "desk", "opencodeUrl": "http://127.0.0.1:4096", "idx": {"room": "r"}, "computerId": "c"}], keyed={"c"})
     async def keys_state(p):
-        return "unknown"
+        return {"state": "unknown", "why": "the signature does not match this computer (401)"}
     r = run(wizard.run_setup(f.deps(keys_state=keys_state, forget_keys=lambda p: f._keyed.discard(p["computerId"]))))
     assert f.paired == [] and r["keys"] and f.served == [4096]
+    assert any("Could not check them with your account just now — the signature does not match this computer (401)" in line for line in f.said)

witbitz_code-1.3.3/tests/test_winagent.py

@@ -0,0 +1,69 @@
+"""What OpenCode gets on Windows (benchmark 2026-10-08, Windows 11, OpenCode 1.18.30, six teacher tasks with Hebrew data,
+DeepSeek V4.1 Flash / Claude Haiku 4.5 / GLM 5.3 Flash): PYTHONUTF8=1 (without it Windows Python crashed printing Hebrew),
+Git Bash as the shell (a model's bash habits just work there), a Python of its own first on PATH with a real python3 (the
+bare name is the Microsoft Store stub), and an instructions file naming all that — 48/48 correct with them, 45/48 without;
+Haiku on Git Bash 68 → 3 failed commands."""
+
+from pathlib import Path
+
+from witbitz_code import winagent
+
+LOCAL = r"C:\Users\t\AppData\Local"
+ENV = {"LOCALAPPDATA": LOCAL, "ProgramFiles": r"C:\Program Files", "PATH": r"C:\Windows\system32"}
+
+
+def exists_of(*paths):
+    have = {p.lower() for p in paths}
+    return lambda p: str(p).lower() in have
+
+
+def test_nothing_changes_off_windows(tmp_path):
+    cfg = tmp_path / "opencode"  # its own folder: conftest makes tmp_path/home for every test
+    add, instr, note = winagent.windows_agent(cfg, env=ENV, platform="linux", exists=exists_of())
+    assert (add, instr, note) == ({}, None, "")
+    assert not cfg.exists(), "no file written off Windows"
+
+
+def test_git_bash_python_and_utf8_on_windows(tmp_path):
+    bash = r"C:\Program Files\Git\bin\bash.exe"
+    py = LOCAL + r"\Witbitz\agent-python\Scripts\python.exe"
+    add, instr, note = winagent.windows_agent(tmp_path, env=ENV, platform="win32", exists=exists_of(bash, py))
+    assert add["PYTHONUTF8"] == "1"
+    assert add["SHELL"] == bash
+    assert add["PATH_PREPEND"] == [LOCAL + r"\Witbitz\agent-python\Scripts"]
+    text = Path(instr).read_text(encoding="utf-8")
+    assert "Git Bash" in text and r"C:\Users" in text and "/c/" in text, "the read/write tools need C:\\ paths, never /c/"
+    assert "Git Bash" in note and "agent-python" in note
+
+
+def test_witbitz_own_git_wins_over_none_and_powershell_is_the_fallback(tmp_path):
+    own = LOCAL + r"\Witbitz\git\bin\bash.exe"
+    add, _, _ = winagent.windows_agent(tmp_path, env=ENV, platform="win32", exists=exists_of(own))
+    assert add["SHELL"] == own
+    add, instr, note = winagent.windows_agent(tmp_path, env=ENV, platform="win32", exists=exists_of())
+    assert "SHELL" not in add and "PATH_PREPEND" not in add and add["PYTHONUTF8"] == "1"
+    text = Path(instr).read_text(encoding="utf-8")
+    assert "PowerShell" in text and "-Encoding UTF8" in text and "<<" in text
+    assert "no Python" in note
+
+
+def test_the_instructions_file_is_rewritten_only_when_it_changes(tmp_path):
+    _, instr, _ = winagent.windows_agent(tmp_path, env=ENV, platform="win32", exists=exists_of())
+    p = Path(instr)
+    before = p.stat().st_mtime_ns
+    winagent.windows_agent(tmp_path, env=ENV, platform="win32", exists=exists_of())
+    assert p.stat().st_mtime_ns == before
+
+
+def test_apply_puts_python_ahead_of_ast_grep_and_adds_to_the_instructions():
+    tools_env = {"PATH": r"C:\ast;C:\Windows\system32", "OPENCODE_EXPERIMENTAL_LSP_TOOL": "true"}
+    tools_config = {"instructions": [r"C:\cfg\witbitz-tools.md"]}
+    add = {"PYTHONUTF8": "1", "SHELL": r"C:\Git\bin\bash.exe", "PATH_PREPEND": [r"C:\py\Scripts"]}
+    env, config = winagent.apply(tools_env, tools_config, add, r"C:\cfg\witbitz-windows.md", base_path=r"C:\Windows\system32")
+    assert env["PATH"] == r"C:\py\Scripts;C:\ast;C:\Windows\system32"
+    assert env["SHELL"] == r"C:\Git\bin\bash.exe" and env["PYTHONUTF8"] == "1" and "PATH_PREPEND" not in env
+    assert config["instructions"] == [r"C:\cfg\witbitz-tools.md", r"C:\cfg\witbitz-windows.md"]
+    assert tools_config["instructions"] == [r"C:\cfg\witbitz-tools.md"], "the caller's config is not changed"
+    # no ast-grep: PATH starts from the base
+    env, config = winagent.apply({}, {}, add, None, base_path=r"C:\Windows\system32")
+    assert env["PATH"] == r"C:\py\Scripts;C:\Windows\system32" and config == {}