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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.3.2
+Version: 1.3.4
 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.4}/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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "witbitz-code"
-version = "1.3.2"
+version = "1.3.4"
 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.4}/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.4"

{witbitz_code-1.3.2 → witbitz_code-1.3.4}/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.4}/src/witbitz_code/codekeys.py

@@ -15,8 +15,8 @@ from __future__ import annotations
 import base64
 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 +114,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)}
 
@@ -130,17 +146,9 @@ def read_all() -> dict:
 
 
 def _write_all(doc: dict) -> None:
-    path = keys_path()
-    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".account-keys.")
-    try:
-        os.fchmod(fd, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            f.write(json.dumps(doc, indent=1) + "\n")
-        os.replace(tmp, path)
-    except BaseException:
-        Path(tmp).unlink(missing_ok=True)
-        raise
+    # pairings.write_private: 0600, atomic, and Windows-safe (Windows Python 3.12 has no os.fchmod — the owner's native
+    # Windows pairing died here, the real error hidden by a cleanup that could not delete the still-open temp file).
+    pp.write_private(keys_path(), json.dumps(doc, indent=1) + "\n")
 
 
 def for_computer(computer_id: str) -> dict | None:
@@ -153,9 +161,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 +223,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 +271,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 +286,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 +327,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.4}/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.4}/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.2 → witbitz_code-1.3.4}/src/witbitz_code/payers.py

@@ -16,7 +16,6 @@ from __future__ import annotations
 
 import json
 import os
-import tempfile
 import threading
 from pathlib import Path
 
@@ -49,12 +48,7 @@ class SessionPayers:
         if not self._persist:
             return
         try:
-            self._path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-            fd, tmp = tempfile.mkstemp(dir=str(self._path.parent), prefix=".session-payers.")
-            os.fchmod(fd, 0o600)
-            with os.fdopen(fd, "w", encoding="utf-8") as f:
-                f.write(json.dumps({"v": 1, "owners": self._owner}))
-            os.replace(tmp, self._path)
+            pp.write_private(self._path, json.dumps({"v": 1, "owners": self._owner}))  # Windows-safe (no os.fchmod there)
         except OSError:
             pass  # memory still knows; a restart forgets, and a forgotten conversation is refused, never misbilled
 

witbitz_code-1.3.4/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.2 → witbitz_code-1.3.4}/src/witbitz_code/uninstall.py

@@ -170,7 +170,7 @@ def stop_process(pid: int) -> bool:
         if gone():
             return True
     try:
-        os.kill(pid, signal.SIGKILL)
+        os.kill(pid, getattr(signal, "SIGKILL", signal.SIGTERM))  # Windows has no SIGKILL
     except OSError:
         pass
     time.sleep(0.3)

witbitz_code-1.3.4/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