@tiens.nguyen/gu-cli 1.0.892 → 1.0.894

package/README.md

@@ -1,17 +1,17 @@
 <h1 align="center">gu — the coding agent for your own models</h1>
 
 <p align="center">
-  <strong>A coding agent in your terminal that runs on Ollama, MLX or any OpenAI-compatible API.</strong><br>
-  It reads your repo, makes the change, runs the tests and shows you what it did. Your code stays in your folder.<br>
-  <strong>Free for 30 days. No account, no sign-in, no card.</strong>
+  <strong>A coding agent in your terminal that runs on Ollama or any OpenAI-compatible API.</strong><br>
+  It reads your repo, makes the change, runs the tests and shows you what it did.<br>
+  <strong>Free installs run entirely on your machine. Free for 30 days: no account, no sign-in, no card.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="npm" src="https://img.shields.io/npm/v/@tiens.nguyen/gu-cli?color=6366f1&label=npm"></a>
   <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="downloads" src="https://img.shields.io/npm/dm/@tiens.nguyen/gu-cli?color=6366f1"></a>
-  <img alt="node" src="https://img.shields.io/node/v/@tiens.nguyen/gu-cli?color=6366f1">
+  <img alt="node 20.19+" src="https://img.shields.io/badge/node-20.19%2B-6366f1">
   <img alt="platforms" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-supported-6366f1">
-  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@tiens.nguyen/gu-cli?color=6366f1"></a>
+  <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-6366f1">
 </p>
 
 <p align="center">
@@ -37,18 +37,21 @@ gu
 ```
 
 **Free to start, no account needed.** The first run creates a free 30-day token for this
-computer automatically. Press Enter to use it. It also asks how this machine runs and which model
-provider to use. Then type what you want done.
+computer. Press Enter to use it, pick a model provider, then type what you want done.
+
+A free install is **private**: gu's API and its database (MongoDB) run on this computer, next to
+your code. The first run shows what it will install and asks before installing anything.
+Needs **Node.js 20.19+**.
 
 > **`gu: command not found`?** Run `npx @tiens.nguyen/gu-cli fix-path`. See [Troubleshooting](#troubleshooting).
 
 ## Why gu
 
-- **Your models, your choice.** Run [Ollama](https://ollama.com) or MLX on your own machine or a GPU
-  box on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
+- **Your models, your choice.** Run [Ollama](https://ollama.com) on your own machine or a GPU box
+  on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
   one model to plan and another to code; switch any time with `/model`.
-- **Private by default.** Logs hold no prompts, code or keys unless you run `gu --log`. Need
-  everything in-house? Private mode runs the API and database on your own servers.
+- **Private by default.** A free install keeps the agent, its API and its database on your
+  computer. Logs hold no prompts, code or keys unless you run `gu --log`.
 - **It proves it works.** gu runs the build and the tests and fixes what fails. For web pages, the
   `browser` tool drives a real Chrome and checks the result before gu says it is done.
 - **It stays in the repo.** Every edit is a file you can read, diff and revert; `/undo` puts back
@@ -65,16 +68,14 @@ provider to use. Then type what you want done.
 cloud, work on remote Linux boxes over SSH, or want a coding agent that costs $4 a month instead
 of a model subscription.
 
-**Probably not if** you want the strongest frontier model with zero setup and don't mind where your
-code goes: the model vendors' own agents are simpler for that. gu can still use those models
-through an OpenAI-compatible API, but its strength is everything else.
+**Want a frontier model?** gu runs those too, through any OpenAI-compatible API, and keeps
+everything else: the edits in your repo, the tests, the browser check and `/undo`.
 
 ## Quick start
 
 1. **Start gu.** Run `gu` in a project folder. Your free 30-day token is created on the spot:
    no sign-up, no browser, no card.
 2. **Check your models.** `gu doctor` sets up and tests the models on this machine.
-   (`gu doctor --client` installs only the agent's dependencies, when the models run elsewhere.)
 3. **Ask.** Type what you want done. Conversations are saved per folder and resumed next time;
    `/new` starts a fresh one.
 
@@ -86,9 +87,10 @@ gu uses up to three models, each with its own command:
 | --- | --- | --- |
 | `/model` | **coding**: writes the code | this session (`/quick-models` keeps 2 to flip with ← / →) |
 | `/agent-model` | **agent**: talks to you and plans | this machine |
-| `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine; re-indexes what was indexed |
+| `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine |
 
-Run `/doctor` any time to check that each one answers.
+Run `/doctor` any time to check that each one answers. Coding works best with a strong model:
+small local models often fail at multi-step changes.
 
 ## Using gu
 
@@ -102,10 +104,23 @@ gu [-v|--verbose] [--log] [--color] [--name <text>] [--license <pro token>]
 | `--log` | log this run in detail to `~/.gonext/worker.log` (default: starts, stops and errors only) |
 | `--color` | colour the live thought and the thinking spinner |
 | `--name <text>` | show `<text>` instead of the gu logo in the banner (this run only) |
-| `--license <token>` | choose a Pro licence on first install |
+| `--license <token>` | use a Pro licence on first install |
 
 Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab completes.
 
+**The commands you'll use most**
+
+| Command | What it does |
+| --- | --- |
+| `/model` | switch the coding model |
+| `/new` | start a new conversation in this folder |
+| `/undo` | put back the files the last stopped turn changed (asks first) |
+| `/test-auto` | for this folder: verify and fix until the tests pass |
+| `/browser` | let the agent check web pages in a real Chrome |
+| `/mcp` | add MCP servers, and choose which tools run without asking |
+| `/doctor` | check that every model answers |
+| `/support` | send a request with gu's logs attached (secrets masked; shows you first) |
+
 <details>
 <summary><strong>All slash commands</strong></summary>
 
@@ -117,28 +132,24 @@ Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab
 | `/new` | start a new conversation in this folder (the old one is archived) |
 | `/undo [runId]` | put back the files the last stopped turn changed, from its backups (asks first) |
 | `/test-auto` | toggle auto-test for this folder: verify and fix until it passes |
-| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window ([guide](browser-extension/README.md)) |
+| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window |
 | `/shells` | long commands the agent left running in the background: status, output, stop one |
-| `/rag` | where this folder's RAG index lives: local, cloud or both |
+| `/rag` | where this folder's RAG index lives |
 | `/tokens` | break down the last prompt sent to the coding model, including how much was RAG |
 | `/prices [update]` | price tables, and what the last turn and this session cost |
 | `/budget` | your API provider budgets and balances (Pro) |
 | `/mcp [list\|tools\|add\|remove\|enable\|disable\|approve\|allow\|disallow\|reconnect]` | MCP servers, and which of their tools run without asking |
 | `/hooks [list\|approve\|unapprove]` | commands gu runs on `onStart`, `onAsk`, `onToolDone`, `onTurnEnd` |
 | `/switch-skill [claude\|gu]` | use Claude Code's (`.claude`) or gu's (`.gonext`) skills, MCP servers and hooks in this folder |
-| `/skill-pack <name> [--out <file>] [--runtime <dir>]` | pack a skill with its MCP servers, hooks and code into one zip for another machine (no venvs, databases or secrets) |
-| `/skill-install <zip\|folder> [--gu] [--claude] [--dry-run]` | install a packed skill for gu and Claude Code; without gu: `node <name>/install.mjs` |
-| `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's: shows its plan, last command and next step, then asks (needs the memory skill) |
-| `/skills-copy-to-claude [--dry-run] [name…]` | copy gu's skills into Claude Code's folders |
+| `/skill-pack <name>`, `/skill-install <zip\|folder>` | pack a skill with its MCP servers and hooks into one zip, and install it on another machine (no secrets) |
+| `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's |
 | `/proxy [show\|set\|on\|off\|clear\|test]` | route model calls through an HTTP proxy (local calls go direct) |
 | `/s3 [test]` | use your own S3 bucket for the RAG index and generated files |
-| `/server` | pick a deployment server (host/user) for this session |
-| `/host-mode` | undo client mode: run agent turns on this machine again |
 | `/save-settings`, `/load-settings` | move providers, models and key *names* (no secrets) to another machine |
 | `/save-preset`, `/open-presets`, `/use-presets` | your whole setup, keys included, to copy, edit and apply (backs up first) |
-| `/clear-logs` | show what logs, RAG indexes and old API versions take on disk, then ask what to clear |
-| `/voucher CODE` | use a voucher code: adds free days to this computer's trial or your free account |
-| `/support` | send the support team a request with gu's logs attached (secrets masked; shows what goes first) |
+| `/clear-logs` | show what logs and indexes take on disk, then ask what to clear |
+| `/voucher CODE` | add free days to this computer's trial or your free account |
+| `/support` | send the support team a request with gu's logs attached |
 | `/help`, `/exit` | list commands / quit |
 
 Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skills`) is a slash command too.
@@ -149,32 +160,25 @@ Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skill
 <summary><strong>Shell commands</strong></summary>
 
 ```
-gu status                      worker status and the running model servers
-gu start | stop | restart      the background worker (stop --models: model servers too)
-gu logs [--lines N] [-f]       tail the worker log; gu logs <port|pid|chat|embed> for a model server
-gu doctor [--client]           set up and check models on this machine
-gu rag [plan [path] | --test]  test the embedder, list knowledge bases, estimate index time
-gu api <start|stop|restart|status|upgrade>   the local API (private machines)
+gu status                      is gu running, and which model servers
+gu start | stop | restart      the background worker
+gu logs [--lines N] [-f]       follow gu's log
+gu doctor                      set up and check models on this machine
+gu rag [plan [path] | --test]  test the embedder, estimate index time
 gu workspace revert [runId]    undo an agent run's file edits from its backups
 gu support                     send a support request with masked logs
-gu test-proxy                  check model calls through a proxy
-gu mongo migrate-from-docker   macOS: move a Docker MongoDB to Homebrew
-gu clear [--scratch|--keep-history] [--yes]   back to a fresh machine (asks first)
+gu clear [--yes]               back to a fresh machine (asks first)
 gu fix-path | fix-powershell   repair PATH / remove PowerShell's `gu` alias
 ```
 
-`gu-cli` takes the same commands, plus `login [--api-base <url>]`, `set <workerKey>`,
-`token [<token>]`, `ws-ping-test` and `simulate-chat [text…]`.
-
 </details>
 
 ## Where gu keeps things
 
 | Path | Contents |
 | --- | --- |
-| `~/.gonext/worker.env` | sign-in: worker key and API address |
 | `~/.gonext/sessions/` | conversation history per folder (`archive/` holds old ones) |
-| `~/.gonext/worker.log`, `~/.gonext/local-api.log` | logs |
+| `~/.gonext/worker.log` | log |
 | `~/.gonext/mcp.json` | MCP servers and their allow rules |
 | `~/.gonext/skills/`, `<folder>/.gonext/skills/` | skills: everywhere / this folder only |
 
@@ -182,57 +186,35 @@ gu fix-path | fix-powershell   repair PATH / remove PowerShell's `gu` alias
 
 | | How long | What you need |
 | --- | --- | --- |
-| **Free trial** | 30 days, starts on the first run | nothing: the token is created for you |
+| **Free trial** | 30 days, from the first run | nothing: the token is created for you |
 | **Free plan** | 3 more months on that computer | a free account at [gucli.com](https://gucli.com) |
-| **Pro** | while subscribed: **$4 a month** (110.000 ₫) + VAT, or $40 a year | the hosted agent and coder (no model server to run), up to 5 computers, provider budgets |
+| **Pro** | **$4 a month** or **$40 a year** (+ VAT where it applies) | hosted models (no model server to run), up to 5 computers, provider budgets |
+
+On Pro, the hosted models and the hosted API run on gu's servers, so the prompts and code you
+send through them go there. A free install keeps everything on your computer.
 
 Got a **voucher code**? Type `/voucher CODE` in gu (or enter it on your
-[account page](https://gucli.com/account)) for extra free days on top.
+[account page](https://gucli.com/account)) for extra free days.
 
 Free time belongs to the computer: reinstalling doesn't restart it. Already have a token? Paste
-it at the first-run question instead, or later with `gu-cli token <token>`. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
+it at the first-run question. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
 
 ## Troubleshooting
 
 **`gu: command not found` after install.** npm 11 skips install scripts it wasn't told to allow,
 so the step that adds npm's bin folder to your PATH may not have run. Run
 `npx @tiens.nguyen/gu-cli fix-path`. It also finds what an old install left behind (broken links,
-a second gu from another npm, a PATH line pinned to an old Homebrew folder) and asks before
-fixing each one. `--check` only reports.
+a second gu from another npm, a stale PATH line) and asks before fixing each one. `--check` only reports.
 
 **Windows: `gu` runs `Get-Unique`.** PowerShell has a built-in `gu` alias. Run `gu-cli fix-powershell`.
 
-**Node version.** Node.js 18+ runs the CLI. A private machine (API and database on this
-computer) needs **Node.js 20.19+**.
+**Node version.** gu needs **Node.js 20.19+** (a Pro install using only hosted models runs on 18+).
 
 **A change in a model or setting seems ignored.** `gu doctor` shows the model and URL actually in use.
 
-**Still stuck?** Run `gu support` (or `/support` in gu, or click **? support** in the footer). It
-sends the team your request with gu's logs attached, secrets masked, and shows you what goes
-before sending.
-
-<details>
-<summary><strong>Advanced: worker jobs and environment variables</strong></summary>
-
-The background worker also runs jobs queued from the [web app](https://gucli.com) on this machine:
-
-- **Agent chat**: choosing **Agent** in the web app runs a
-  [smolagents](https://github.com/huggingface/smolagents) agent on your local model
-  (`pip install smolagents certifi`). Cloud models are not allowed here; pick a local MLX or Ollama model.
-- **API checks**: the worker makes the HTTP request itself, measures status, latency and body,
-  and a local model writes a one-line summary.
-
-| Variable | Meaning |
-| --- | --- |
-| `GONEXT_API_BASE`, `GONEXT_WORKER_KEY` | API address and worker key (normally from `~/.gonext/worker.env`) |
-| `GONEXT_PROBE_PYTHON` | Python for agent scripts (default: `GONEXT_MLX_LM_PYTHON` or `python3`) |
-| `GONEXT_MLX_LM_PYTHON` | Python for the MLX probe (default `python3`) |
-| `GONEXT_OCR_MODEL_PATH` | local GLM-OCR directory (default `~/mlx-models/GLM-OCR-bf16`) |
-| `GONEXT_OCR_DEBUG=1` | print raw OCR output |
-| `GONEXT_SIMULATE_TEXT` | default reply for `simulate-chat` |
-
-</details>
+**Still stuck?** Run `gu support` (or `/support` in gu). It sends the team your request with gu's
+logs attached, secrets masked, and shows you what goes before sending.
 
 ## License
 
-[MIT](./LICENSE) © Tien Nguyen Song
+MIT © Tien Nguyen Song

package/client-expert-run.mjs

@@ -21,7 +21,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import { localModeNodeProblem } from "./node-version.mjs";
-import { downloadMongodExe, startPortableMongod, portableMongoInstalled, mongoWinPaths, mongodCommandLine, MONGO_WIN_VERSION } from "./mongo-windows.mjs";
+import { downloadMongodExe, startPortableMongod, portableMongoInstalled, mongoWinPaths, mongodCommandLine, MONGO_WIN_VERSION, mongodRuns, isDllNotFoundExit, installVcRuntime, VC_REDIST_URL } from "./mongo-windows.mjs";
 import {
   apiDepsInstalled,
   installApiDeps,
@@ -415,7 +415,7 @@ export function runInTerminal(cmd, { platform = process.platform, spawnFn = spaw
  * administrator prompt. Shown, asked, then done, like the other platforms. If the download fails
  * the winget commands are printed as the way out.
  */
-export async function ensureNativeMongoWindows(ask, mongo, { log = (l) => console.log(l), plan = null, waitFor = null, download = downloadMongodExe, start = startPortableMongod } = {}) {
+export async function ensureNativeMongoWindows(ask, mongo, { log = (l) => console.log(l), plan = null, waitFor = null, download = downloadMongodExe, start = startPortableMongod, runs = mongodRuns, installRuntime = installVcRuntime } = {}) {
   const installing = !mongo.installed;
   const paths = mongoWinPaths();
   const { host, port } = mongoHostPort(LOCAL_MONGO_URI);
@@ -445,6 +445,32 @@ export async function ensureNativeMongoWindows(ask, mongo, { log = (l) => consol
       return { ok: false, explained: true };
     }
   }
+  // A new Windows 11 has no Visual C++ runtime, and mongod.exe then dies at once with 0xC0000135 — started
+  // detached, that shows up only as "not answering". Ask mongod itself first, and say the real reason (GH #363).
+  const probe = await runs(paths);
+  if (!probe.ok && isDllNotFoundExit(probe.code)) {
+    log("\n  " + red("✗ ") + "MongoDB cannot start: this Windows is missing Microsoft's Visual C++ runtime");
+    log(dim("    (mongod.exe stops with 0xC0000135, \"a DLL was not found\"). It is a free Microsoft download, about 25 MB;"));
+    log(dim("    installing it asks for administrator permission once.   " + VC_REDIST_URL));
+    const ok = await readYesNo(ask, "  Install the Visual C++ runtime now? [Y/n]: ", true, log);
+    if (!ok) {
+      log(dim("\n  Not installed — install it from the link above, then run gu again."));
+      return { ok: false, explained: true };
+    }
+    log("\n  " + bold("Installing the Visual C++ runtime"));
+    const vc = await installRuntime({});
+    if (!vc.ok) {
+      log("\n  " + red("✗ ") + `could not install the Visual C++ runtime: ${vc.error ?? "unknown error"}`);
+      log(dim("  Install it yourself from " + VC_REDIST_URL + " , then run gu again."));
+      return { ok: false, explained: true };
+    }
+    log("  " + cyan("✓ Visual C++ runtime installed"));
+    const again = await runs(paths);
+    if (!again.ok) {
+      log("\n  " + red("✗ ") + "mongod.exe still cannot run" + (again.code != null ? ` (exit code ${again.code})` : "") + ". A restart of Windows may be needed; then run gu again.");
+      return { ok: false, explained: true };
+    }
+  }
   let started;
   try {
     started = await start({ port, paths });

package/gonext_agent_chat.py

@@ -2800,7 +2800,7 @@ def _lexical_fallback_search(query: str, files, max_files: int = 8, per_file: in
     total = 0
     for abs_path, _rel in files:
         try:
-            with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+            with _open_project_text(abs_path) as fh:
                 found, hits, lines = set(), 0, []
                 for i, line in enumerate(fh, 1):
                     matched = [t for t, rx in rxs if rx.search(line)]
@@ -5798,11 +5798,23 @@ _RAG_TEXT_EXTS = {
     ".html", ".htm", ".css", ".scss", ".sass", ".less", ".xml", ".yaml", ".yml",
     ".toml", ".ini", ".cfg", ".conf", ".env", ".sh", ".bash", ".zsh", ".sql",
     ".graphql", ".proto", ".gradle", ".dockerfile", ".tsv", ".csv",
+    # WINDOWS / .NET (#490). This list is also what grep_repo can SEE, so a file type missing
+    # here is invisible to search and RAG alike — on a Windows project that was the scripts,
+    # the project files and half the UI: a .csproj, a web.config, a .xaml view, a .ps1 build
+    # step could not be found by any tool, and nothing said so.
+    ".ps1", ".psm1", ".psd1", ".bat", ".cmd", ".vb", ".fs", ".fsx", ".razor", ".cshtml",
+    ".vbhtml", ".xaml", ".axaml", ".csproj", ".vbproj", ".fsproj", ".vcxproj", ".sln",
+    ".props", ".targets", ".config", ".resx", ".manifest", ".reg",
+    # Other common source types the list never had.
+    ".dart", ".scala", ".lua", ".pl", ".pm", ".r", ".ex", ".exs", ".erl", ".hs", ".clj",
+    ".m", ".mm", ".tf", ".hcl", ".cmake", ".groovy", ".kts", ".astro", ".prisma",
 }
 _RAG_SKIP_DIRS = {
     "node_modules", ".git", ".svn", ".hg", "__pycache__", ".venv", "venv",
     "dist", "build", ".next", ".nuxt", "out", ".cache", "bin", "obj", ".idea",
     ".gradle", "vendor", "target",
+    # Visual Studio's per-machine cache (IntelliSense DBs, solution state) — never project code.
+    ".vs",
     # ANOTHER AGENT'S SESSION LOG IS NOT PROJECT STATE. Reported live: asked to "continue",
     # the agent listed .claude-memory/, read latest-checkpoint.md, and reasoned from it —
     # "a partial session about d365-sharepoint-upload … 25 edits … resume from memory" — as if
@@ -6480,6 +6492,33 @@ def _rag_unzip(zip_path: str, dest_dir: str = "") -> tuple:
     return dest_dir, names, False
 
 
+def _sniff_text_encoding(path: str) -> str:
+    """The encoding to read a project file with: a BOM decides, else UTF-8.
+
+    WINDOWS WRITES UTF-16 (#490). Windows PowerShell 5.1's `>` and Out-File write UTF-16LE, and
+    some Visual Studio / Notepad files are UTF-16 too. Read as UTF-8, every character carries a
+    NUL after it, so no pattern ever matched and the index embedded noise. UTF-8 WITH a BOM
+    (Visual Studio's default for .cs) read fine except line 1, which began with U+FEFF and so
+    never matched `^using`. Only a BOM is trusted: guessing UTF-16 from NUL counts would also
+    "detect" it in binary files.
+    """
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(4)
+    except OSError:
+        return "utf-8"
+    if head.startswith(b"\xef\xbb\xbf"):
+        return "utf-8-sig"
+    if head.startswith(b"\xff\xfe") or head.startswith(b"\xfe\xff"):
+        return "utf-16"  # the codec reads the BOM and picks LE/BE
+    return "utf-8"
+
+
+def _open_project_text(path: str):
+    """Open a project file for READING ONLY, in the encoding its BOM names (see above)."""
+    return open(path, "r", encoding=_sniff_text_encoding(path), errors="replace")
+
+
 def _rag_iter_text_files(root: str):
     """Yield (abs_path, rel_path, ext) for indexable text files under root."""
     import os
@@ -6501,7 +6540,30 @@ def _rag_iter_text_files(root: str):
                     continue
             except OSError:
                 continue
-            yield abs_path, os.path.relpath(abs_path, root), ext
+            # "/" ON EVERY OS (#490). This is the RAG index's key for the file, and what search
+            # results show. With os.sep it was `src\a.py` on Windows and `src/a.py` elsewhere,
+            # so an index could not be shared between the two, and results printed differently
+            # per machine. Windows accepts "/" in every path the tools take.
+            yield abs_path, os.path.relpath(abs_path, root).replace(os.sep, "/"), ext
+
+
+def _rag_posix_chunk(c: dict, sep: str = "") -> dict:
+    """Move a chunk from an index built with `\\` paths (Windows, before #490) to `/` paths.
+
+    In place and without re-embedding: only the file key and the location line at the top of
+    its text change, so an existing Windows index keeps its vectors instead of re-embedding
+    the whole project once. A no-op off Windows, where `\\` can be part of a real file name.
+    """
+    if (sep or os.sep) != "\\":
+        return c
+    f = c.get("file")
+    if isinstance(f, str) and "\\" in f:
+        new = f.replace("\\", "/")
+        t = c.get("text")
+        if isinstance(t, str) and t.startswith(f + ":"):
+            c["text"] = new + t[len(f):]
+        c["file"] = new
+    return c
 
 
 # A line that STARTS a definition — where a chunk should be cut, and what names it. Kept
@@ -8376,6 +8438,30 @@ def _pipe_hidden_failure_note(line: str, ps: bool = False) -> str:
             + ("." if ps else ", or start the line with `set -o pipefail;`."))
 
 
+# A UNIX SEARCH COMMAND IN POWERSHELL (#490). Windows has no grep/rg/xargs, and its `find` is
+# FIND.EXE — a different program that answers `find . -name x` with "Parameter format not
+# correct". The model learned search as a shell habit, so it reaches for these anyway; the
+# error alone sends it to guess at Select-String syntax next. grep_repo / list_dir do the same
+# job inside gu on every OS, so the failure names them.
+_PS_NO_SEARCH_TOOL_RE = re.compile(
+    r"The term '(grep|egrep|fgrep|rg|ag|ack|xargs|locate|fd)' is not recognized"
+    r"|^(FIND): (?:Parameter format not correct|Invalid switch)",
+    re.M | re.I)
+
+
+def _ps_search_tool_hint(out: str) -> str:
+    """A pointer to grep_repo when PowerShell could not run a Unix search command, else ""."""
+    m = _PS_NO_SEARCH_TOOL_RE.search(out or "")
+    if not m:
+        return ""
+    prog = (m.group(1) or m.group(2) or "").lower()
+    what = ("`find` here is Windows' FIND.EXE, not Unix find" if prog == "find"
+            else f"`{prog}` does not exist on Windows")
+    return (f"\n\nNOTE — {what}. Search file CONTENTS with grep_repo(pattern, path, glob) "
+            "and list files with list_dir(path); both run inside gu on every OS. Do not retry "
+            "with Select-String or Get-ChildItem -Recurse.")
+
+
 # THE PROJECT'S OWN TEST COMMANDS (#360 review). The model guessed `python3 -m pytest` in a repo
 # whose package.json says `python3 -m unittest discover tests -v && node --test` — pytest was not
 # even installed. The manifests already say how each part of the project is tested; reading them
@@ -9320,11 +9406,15 @@ def _ws_write_file(path: str, content: str, action: str, backup) -> None:
     import tempfile
     _ws_record_change(action, path, backup)
     target = os.path.realpath(path)
+    # KEEP THE FILE'S ENCODING (#490). Reads decode a BOM'd UTF-8 or UTF-16 file, so an edit
+    # must write it back the same way — a UTF-16 .resx rewritten as UTF-8 is a different file to
+    # Visual Studio, and dropping a BOM shows up as a whole-file diff. No BOM = UTF-8, as before.
+    enc = _sniff_text_encoding(target) if os.path.isfile(target) else "utf-8"
     _STOP["writing"] += 1
     try:
         fd, tmp = tempfile.mkstemp(prefix=".gu-write-", suffix=".tmp", dir=os.path.dirname(target) or ".")
         try:
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            with os.fdopen(fd, "w", encoding=enc) as fh:
                 fh.write(content)
                 fh.flush()
                 os.fsync(fh.fileno())
@@ -9340,7 +9430,7 @@ def _ws_write_file(path: str, content: str, action: str, backup) -> None:
             except PermissionError:
                 if not _IS_WINDOWS:
                     raise
-                with open(target, "w", encoding="utf-8") as fh:
+                with open(target, "w", encoding=enc) as fh:
                     fh.write(content)
                 os.unlink(tmp)
             _agent_created_add(target)
@@ -14480,7 +14570,7 @@ def run_agent_chat(cfg):
                     _emit_read("Reading file", path, "skipped — already read, unchanged")
                     _last_obs["text"] = _rb
                     return _rb
-                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                with _open_project_text(rp) as fh:
                     data = fh.read(max(500, min(int(max_chars or 20000), 100000)))
                 out = _ws_cap_obs(data or "(empty file)", cap=_OBS_CAPS["read"])
                 _emit_read("Reading file", path, f"{data.count(chr(10)) + 1} line(s)"
@@ -14546,7 +14636,7 @@ def run_agent_chat(cfg):
             # drop what was deleted. Nothing extra is needed to catch the agent's OWN edits:
             # writing a file changes its mtime.
             import os as _os_idx
-            _prev = _rag_load_all(source_key) if not replaced else []
+            _prev = [_rag_posix_chunk(_c) for _c in (_rag_load_all(source_key) if not replaced else [])]
             _prev_stamp = {}
             for _c in _prev:
                 _st = _c.get("stamp")
@@ -14576,7 +14666,7 @@ def run_agent_chat(cfg):
                     unchanged_files += 1
                     continue
                 try:
-                    with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+                    with _open_project_text(abs_path) as fh:
                         text = fh.read()
                 except OSError:
                     skipped += 1
@@ -15169,7 +15259,7 @@ def run_agent_chat(cfg):
                             and not fnmatch.fnmatch(rel, glob):
                         continue
                     try:
-                        with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+                        with _open_project_text(abs_path) as fh:
                             for i, line in enumerate(fh, 1):
                                 if rx.search(line):
                                     # ABSOLUTE path — read_file_lines/read_text_file resolve
@@ -15220,7 +15310,7 @@ def run_agent_chat(cfg):
                 defs, calls, tests = [], [], []
                 for abs_path, rel, _ext in _rag_iter_text_files(root):
                     try:
-                        with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+                        with _open_project_text(abs_path) as fh:
                             text = fh.read()
                     except OSError:
                         continue
@@ -15302,7 +15392,7 @@ def run_agent_chat(cfg):
                                         start_line=int(start_line or 1),
                                         end_line=int(end_line or 0)))
                 rp = _rag_read_allowed((path or "").strip())
-                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                with _open_project_text(rp) as fh:
                     lines = fh.readlines()
                 s = max(1, int(start_line or 1))
                 e = int(end_line or 0) or len(lines)
@@ -15350,7 +15440,7 @@ def run_agent_chat(cfg):
                     _last_obs["text"] = msg
                     return msg
                 backup = _ws_snapshot(rp)
-                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                with _open_project_text(rp) as fh:
                     lines = fh.readlines()
                 s, e = int(start_line), int(end_line)
                 if not (1 <= s <= e <= len(lines)):
@@ -15403,7 +15493,7 @@ def run_agent_chat(cfg):
                     msg = f"Error: not a file: {path}"
                     _last_obs["text"] = msg
                     return msg
-                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                with _open_project_text(rp) as fh:
                     text = fh.read()
                 n = text.count(old_string)
                 if n == 0:
@@ -15964,6 +16054,8 @@ def run_agent_chat(cfg):
                             result += _pipe_hidden_failure_note(_hidden, ps=_ps)
                             _emit({"type": "step", "text":
                                    f"Command failed behind a pipe → {_trim_words(_hidden)}"})
+                        if _ps:
+                            result += _ps_search_tool_hint(out)
                         if rc != 0 and _use_shell and (_PS_QUOTE_ERR_RE if _ps else _SHELL_QUOTE_ERR_RE).search(out or ""):
                             result += _PS_HEREDOC_HINT if _ps else _HEREDOC_HINT
                         # Say where the shell now is, so a next `cd sub` is not done twice (#362).

package/gu-cli.mjs

@@ -1823,7 +1823,17 @@ if (args[0] === "deps") {
   // The agent's Python packages (smolagents + openai), installed in a plain process — what the installer and the
   // first start run, and what to run by hand when either said it could not (GH #308).
   const md = await import("./model-doctor.mjs");
-  const out = await md.ensureAgentDeps({ log: (l) => console.log(l), confirm: async () => true, modelHost: false, agreed: ["agentLibs"] });
+  // Running `gu-cli deps` agrees to the agent framework; installing Python itself (Windows, GH #363) is asked on its own.
+  const { askLine } = await import("./agent-deps-preflight.mjs");
+  const out = await md.ensureAgentDeps({
+    log: (l) => console.log(l),
+    confirm: async (q, defYes = true) => {
+      const typed = String(await askLine("  " + q + (defYes ? " [Y/n]: " : " [y/N]: "))).trim().toLowerCase();
+      return typed === "" ? defYes : /^y(es)?$/.test(typed);
+    },
+    modelHost: false,
+    agreed: ["agentLibs"],
+  });
   const ok = out.agentLibs === "installed" || out.agentLibs === "present";
   console.log(ok ? "\n  ✓ the agent framework is ready." : "\n  ✗ the agent framework is not installed — see the message above and " + md.PIP_LOG_FILE);
   process.exit(ok ? 0 : 1);

package/gu-repl.mjs

@@ -73,6 +73,8 @@ import {
   tokenRowWithPrice,
   visibleLen,
   createProbeReplyReader,
+  createMouseReportReader,
+  stripLeakedMouseReports,
   agentPickerItems,
   agentsIndicator,
   classifyCliArg,
@@ -709,7 +711,17 @@ if (REPL_LOG) {
     const md0 = await import("./model-doctor.mjs");
     await pre.agentDepsPreflight({
       hasLibs: () => md0.hasAgentLibs(),
-      install: () => md0.ensureAgentDeps({ log: (l) => console.log(l), confirm: async () => true, modelHost: false, agreed: ["agentLibs"] }),
+      // The "Install it now?" above agreed to the agent framework ONLY (agreed: agentLibs). Anything else this install
+      // would do — installing Python itself on Windows (GH #363) — is a new decision and gets its own question.
+      install: () => md0.ensureAgentDeps({
+        log: (l) => console.log(l),
+        confirm: async (q, defYes = true) => {
+          const typed = String(await pre.askLine("  " + q + (defYes ? " [Y/n]: " : " [y/N]: "))).trim().toLowerCase();
+          return typed === "" ? defYes : /^y(es)?$/.test(typed);
+        },
+        modelHost: false,
+        agreed: ["agentLibs"],
+      }),
       markDeclined: pre.markDeclinedOnDisk,
     });
   }
@@ -1304,7 +1316,30 @@ const PASTE_MODE_OFF = "\x1b[?2004l";
 // short paste goes in literally, a long one becomes "[Pasted text #N +M lines]" with the real
 // text kept in pasteStore and expanded when the turn is sent.
 let pasteBuffer = null;
-let mouseSeq = null;   // buffered SGR mouse report, from "\x1b[<" to its M/m terminator
+// Mouse reports in every shape node can deliver them (GH #365) — see createMouseReportReader.
+const mouseReader = createMouseReportReader();
+let _mouseTimer = null;
+let _mouseReplaying = false; // replayed keys skip the mouse reader, and only the mouse reader
+function mouseClearTimer() {
+  if (_mouseTimer) {
+    clearTimeout(_mouseTimer);
+    _mouseTimer = null;
+  }
+}
+/** Not a report after all: give the keys back to the rest of the input path, in order. */
+function mouseReplay(keys) {
+  _mouseReplaying = true;
+  try {
+    for (const [s, k] of keys) rl._ttyWrite(s, k);
+  } finally {
+    _mouseReplaying = false;
+  }
+}
+/** Timer fired: what is still held (a lone Esc, a "[" with nothing after it) is a keystroke. */
+function mouseFlush() {
+  _mouseTimer = null;
+  mouseReplay(mouseReader.flush());
+}
 const _origTtyWrite = rl._ttyWrite.bind(rl);
 rl._ttyWrite = (str, key) => {
   // A LIST PICKER OWNS EVERY KEY WHILE IT IS UP, and this has to happen HERE rather than in the
@@ -1384,20 +1419,26 @@ rl._ttyWrite = (str, key) => {
   // readline parses an SGR mouse report only as far as its "\x1b[<" prefix, then hands the
   // REST through as individual characters — which is how "0;62;21M" ended up typed into the
   // line. Buffer from the prefix to the M/m terminator so nothing leaks, then move the caret.
-  if (key?.code === "[<") {
-    mouseSeq = "";
-    return;
-  }
-  if (mouseSeq !== null) {
-    mouseSeq += typeof str === "string" ? str : "";
-    if (str === "M" || str === "m") {
-      const report = mouseSeq;
-      mouseSeq = null;
-      applyMouseReport(report);
-    } else if (mouseSeq.length > 24) {
-      mouseSeq = null; // malformed — never buffer unboundedly
+  //
+  // GH #365: by EVERY shape, not only node's "[<" key — an Esc that timed out (a stalled event
+  // loop, e.g. the repaint after restoring a window on Windows) sends "[<35;114;22M" through as
+  // plain characters, which is how hovering typed junk into the line. See createMouseReportReader.
+  if (!_mouseReplaying) {
+    const verdict = mouseReader.feed(str, key, { plainLeads: _clickEnabled || _mouseEnabled });
+    if (verdict.action === "hold") {
+      if (!_mouseTimer) _mouseTimer = setTimeout(mouseFlush, 300);
+      return;
+    }
+    if (verdict.action === "consume") {
+      mouseClearTimer();
+      applyMouseReport(verdict.report);
+      return;
+    }
+    if (verdict.action === "replay") {
+      if (!verdict.hold) mouseClearTimer();
+      mouseReplay(verdict.keys);
+      return;
     }
-    return;
   }
   // The terminal's answer to our \x1b[6n probe (ESC [ row ; col R) — the caret's ABSOLUTE row,
   // which is what mouse reports are measured against. It is INPUT: any byte of it we fail to
@@ -2119,6 +2160,8 @@ let slashSel = -1; // highlighted row in the current filtered list (-1 = none)
 let slashNames = []; // command names in the current filtered list (for Enter → run)
 let slashPrefix = ""; // the "/…" text the user typed (restored when ↑/↓ recall history)
 rl.on("line", (l) => {
+  // GH #365: a mouse report that got past every reader is junk, not part of the question.
+  l = stripLeakedMouseReports(l);
   // Enter ends any drag: if a release was lost (focus left the window mid-drag) the highlight
   // would otherwise stay painted over text nobody is selecting — see endDrag.
   endDrag();
@@ -14425,6 +14468,9 @@ async function main() {
                 // The yes two lines up IS the answer — do not ask the same thing again (#333).
                 agreed: ["agentLibs"],
               });
+              if (depsOut?.python3 === "missing") {
+                console.log(yellow("  ⚠ Without Python the agent cannot answer. Setup goes on, but install Python 3 and run `gu doctor` before your first question.\n"));
+              }
               // The worker reads worker.env ONCE at startup, so a daemon that is already
               // running still has the OLD python — the packages would look "not installed"
               // for the rest of its life. Restart it here rather than leaving the user to

package/model-doctor.mjs

@@ -1354,11 +1354,24 @@ export async function ensureClaudeSdk({ log, confirm }) {
  * (smolagents + openai) — required to run the agent?" — the same question twice in a row on
  * every first install. A yes that was just given is not asked for again.
  */
-export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxModels(), agreed = [] }) {
+export async function ensureAgentDeps({ log, confirm, modelHost = canHostMlxModels(), agreed = [], os = platform(), installPython = null }) {
   const out = {};
   log("");
   log("  Checking the agent's dependencies…");
-  // python3 — the whole agent runs on it; we can't install it for the user.
+  // python3 — the whole agent runs on it. On Windows gu offers to install it for this user (GH #363); elsewhere it can't.
+  if (!(await pyHasModule("sys")) && os === "win32") {
+    const yes = await confirm(
+      "Python 3 is not installed, and the agent runs on it. Install Python 3.12 for your user only? (about 25 MB from python.org; no administrator needed)",
+      true
+    );
+    if (yes) {
+      log("  Installing Python 3.12 …");
+      const install = installPython ?? (await import("./python-windows.mjs")).installPythonWindows;
+      const r = await install({});
+      if (r.ok) log("  ✓ Python 3.12 installed");
+      else log(`  ⚠ could not install Python: ${r.error ?? "unknown error"}`);
+    }
+  }
   if (!(await pyHasModule("sys"))) {
     log(`  ⚠ ${python3Bin()} not found. Install Python 3 — ${pythonInstallHint()} —`);
     log("    then run `gu-cli doctor` again.");

package/mongo-windows.mjs

@@ -17,6 +17,7 @@ import { mkdir, rename, writeFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { inflateRawSync } from "node:zlib";
+import { execFile } from "node:child_process";
 
 // Bump on purpose, like MONGO_WINGET_VERSION: 9.0.4 is what fastdl serves today (winget has 9.0.2).
 export const MONGO_WIN_VERSION = "9.0.4";
@@ -244,3 +245,65 @@ export async function startPortableMongod({ port = 27017, paths = mongoWinPaths(
     taskName: "gu-local-mongod",
   });
 }
+
+// ------------------------------------------------------------------- the Visual C++ runtime (GH #363)
+//
+// mongod.exe needs Microsoft's Visual C++ runtime (vcruntime140.dll, msvcp140.dll). A brand-new Windows 11
+// has none, so mongod stops at once with 0xC0000135 (STATUS_DLL_NOT_FOUND) and — started detached — nobody
+// sees why: gu only said "not answering yet" and the user was sent round in a circle.
+
+export const VC_REDIST_URL = "https://aka.ms/vs/17/release/vc_redist.x64.exe";
+
+/** The exit code Windows gives a program whose DLL is missing: 0xC0000135, as unsigned or signed. */
+export function isDllNotFoundExit(code) {
+  return code === 0xC0000135 || code === -1073741515;
+}
+
+/** Can this mongod.exe start at all? → { ok, code }. Runs `mongod --version` (it prints and exits). */
+export function mongodRuns(paths = mongoWinPaths(), { execFn = execFile, timeoutMs = 20000 } = {}) {
+  return new Promise((resolve) => {
+    try {
+      execFn(paths.exe, ["--version"], { timeout: timeoutMs, windowsHide: true }, (err) => {
+        if (!err) return resolve({ ok: true, code: 0 });
+        const code = typeof err.code === "number" ? err.code : null;
+        // ENOENT / killed by the timeout carry a string or signal, not an exit code: not "a DLL is missing".
+        resolve({ ok: false, code });
+      });
+    } catch {
+      resolve({ ok: false, code: null });
+    }
+  });
+}
+
+/** Exit codes of vc_redist.x64.exe that mean "it is there now": done, reboot wanted, a newer one already installed. */
+export function vcRedistInstalled(code) {
+  return code === 0 || code === 3010 || code === 1638;
+}
+
+/**
+ * Download Microsoft's runtime installer and run it quietly. Installing it needs administrator rights, so it is
+ * started with `-Verb RunAs` (one Windows permission prompt); a non-elevated child_process could not ask.
+ * → { ok, code, error? }. `download` and `run` are injectable so tests never touch the net or the machine.
+ */
+export async function installVcRuntime({ dir = join(homedir(), ".gonext"), fetchFn = fetch, run = null } = {}) {
+  const exe = join(dir, "vc_redist.x64.exe");
+  try {
+    await mkdir(dir, { recursive: true });
+    const res = await fetchFn(VC_REDIST_URL, { redirect: "follow" });
+    if (!res.ok) return { ok: false, code: null, error: `download failed (HTTP ${res.status})` };
+    await writeFile(exe, Buffer.from(await res.arrayBuffer()));
+  } catch (e) {
+    return { ok: false, code: null, error: `download failed: ${e?.message ?? e}` };
+  }
+  const runner = run ?? ((file) => new Promise((resolve) => {
+    const script = `$p = Start-Process -FilePath '${file.replace(/'/g, "''")}' -ArgumentList '/install','/quiet','/norestart' -Verb RunAs -Wait -PassThru; exit $p.ExitCode`;
+    execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { windowsHide: true, timeout: 600000 }, (err, _o, stderr) => {
+      resolve({ code: err ? (typeof err.code === "number" ? err.code : null) : 0, stderr: String(stderr ?? "") });
+    });
+  }));
+  const r = await runner(exe);
+  await rm(exe, { force: true }).catch(() => {});
+  if (vcRedistInstalled(r.code)) return { ok: true, code: r.code };
+  const declined = /canceled by the user|operation was canceled/i.test(r.stderr ?? "");
+  return { ok: false, code: r.code, error: declined ? "the administrator permission prompt was declined" : `the installer stopped with code ${r.code}` };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.892",
-  "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama, MLX or any OpenAI-compatible provider). macOS, Linux and Windows.",
+  "version": "1.0.894",
+  "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama or any OpenAI-compatible provider). Free installs run entirely on your machine. macOS, Linux and Windows.",
   "keywords": [
     "ai",
     "coding-agent",
@@ -9,7 +9,6 @@
     "terminal",
     "llm",
     "ollama",
-    "mlx",
     "openai",
     "agent",
     "mcp",
@@ -76,6 +75,7 @@
     "workspace-revert.mjs",
     "mongo-native.mjs",
     "mongo-windows.mjs",
+    "python-windows.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/python-windows.mjs

@@ -0,0 +1,91 @@
+/**
+ * PYTHON ON A NEW WINDOWS 11 (GH #363).
+ *
+ * A brand-new Windows 11 has no Python, and gu's agent runs on it. gu used to say "Install Python 3 — winget …"
+ * and then carry on through a long database setup that ended in a broken agent. Like the installer does for
+ * Node, gu now offers to do it: the official python.org installer, for THIS USER only (no administrator, no
+ * system-wide change), after checking that the file is signed by the Python Software Foundation.
+ *
+ * Pure parts (URL, folders, the PowerShell script) are separate; the net and the machine are injected so tests
+ * never download or install anything.
+ */
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+
+// Bump on purpose. 3.12 has prebuilt wheels for everything gu installs (see PYTHON_WHEELS_MAX).
+export const PYTHON_WIN_VERSION = "3.12.8";
+
+export function pythonWinInstallerUrl(version = PYTHON_WIN_VERSION) {
+  return `https://www.python.org/ftp/python/${version}/python-${version}-amd64.exe`;
+}
+
+/** Where a per-user install lands: %LOCALAPPDATA%\Programs\Python\Python312, its Scripts, and the `py` launcher. */
+export function pythonWinFolders(version = PYTHON_WIN_VERSION, localAppData = process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")) {
+  const [maj, min] = version.split(".");
+  const root = join(localAppData, "Programs", "Python", `Python${maj}${min}`);
+  return [root, join(root, "Scripts"), join(localAppData, "Programs", "Python", "Launcher")];
+}
+
+/** Put the new folders on THIS process's PATH: the installer only edits the saved PATH, which only new terminals read. */
+export function withPythonOnPath(pathValue, folders) {
+  const have = String(pathValue ?? "").split(";").map((p) => p.trim().toLowerCase());
+  const add = folders.filter((f) => !have.includes(f.toLowerCase()));
+  return add.length ? add.join(";") + ";" + String(pathValue ?? "") : String(pathValue ?? "");
+}
+
+/** The PowerShell that checks the signature, then installs quietly for the current user. Exit 90 = not signed by the PSF. */
+export function pythonInstallScript(file) {
+  const f = file.replace(/'/g, "''");
+  return [
+    `$f = '${f}'`,
+    `$s = Get-AuthenticodeSignature -FilePath $f`,
+    `if ($s.Status -ne 'Valid' -or "$($s.SignerCertificate.Subject)" -notmatch 'Python Software Foundation') { exit 90 }`,
+    `$p = Start-Process -FilePath $f -ArgumentList '/quiet','InstallAllUsers=0','PrependPath=1','Include_launcher=1','Include_test=0' -Wait -PassThru`,
+    `exit $p.ExitCode`,
+  ].join("; ");
+}
+
+/**
+ * The environment for the Python installer: the REAL profile. A test (or anyone) may point USERPROFILE/HOME at a scratch
+ * folder; the installer then fails with 0x80070003 ("path not found"). LOCALAPPDATA still names the real profile
+ * (<profile>\\AppData\\Local), so the profile is derived from it. Pure.
+ */
+export function pythonInstallerEnv(env = process.env) {
+  const out = { ...env };
+  const m = /^(.*)[\\/]AppData[\\/]Local[\\/]?$/i.exec(String(env.LOCALAPPDATA ?? ""));
+  if (m && m[1]) {
+    out.USERPROFILE = m[1];
+    out.HOME = m[1];
+  }
+  return out;
+}
+
+/**
+ * Download, verify, install. → { ok, folders?, error? }. `fetchFn` and `run` (file → { code }) are injectable.
+ * On success the process PATH is updated so the very next `py -3` in this run finds it.
+ */
+export async function installPythonWindows({ dir = join(homedir(), ".gonext"), version = PYTHON_WIN_VERSION, fetchFn = fetch, run = null, env = process.env } = {}) {
+  const file = join(dir, `python-${version}-amd64.exe`);
+  try {
+    await mkdir(dir, { recursive: true });
+    const res = await fetchFn(pythonWinInstallerUrl(version), { redirect: "follow" });
+    if (!res.ok) return { ok: false, error: `download failed (HTTP ${res.status})` };
+    await writeFile(file, Buffer.from(await res.arrayBuffer()));
+  } catch (e) {
+    return { ok: false, error: `download failed: ${e?.message ?? e}` };
+  }
+  const runner = run ?? ((f) => new Promise((resolve) => {
+    execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", pythonInstallScript(f)], { windowsHide: true, timeout: 900000, env: pythonInstallerEnv(env) }, (err) => {
+      resolve({ code: err ? (typeof err.code === "number" ? err.code : null) : 0 });
+    });
+  }));
+  const r = await runner(file);
+  await rm(file, { force: true }).catch(() => {});
+  if (r.code === 90) return { ok: false, error: "the downloaded file is not signed by the Python Software Foundation, so it was NOT installed" };
+  if (r.code !== 0) return { ok: false, error: `the Python installer stopped with code ${r.code}` };
+  const folders = pythonWinFolders(version, env.LOCALAPPDATA || undefined);
+  env.Path !== undefined ? (env.Path = withPythonOnPath(env.Path, folders)) : (env.PATH = withPythonOnPath(env.PATH, folders));
+  return { ok: true, folders };
+}

package/terminal-layout.mjs

@@ -451,9 +451,16 @@ export function promptBreakdownRows(b) {
 export function createMouseKeyWindow({ maxRun = 24 } = {}) {
   let run = 0;
   let current = false;
+  let prev = ""; // the previous key's text, for the split shape below
   return {
     track(str, key) {
-      if (key?.code === "[<") {
+      const text = typeof str === "string" ? str : "";
+      // The joined shape ("[<" as one key) — or the SPLIT one (GH #365): an Esc node timed out
+      // on, then "[" and "<" as ordinary characters. The "[" has already gone by as a key by
+      // then; the run starts at the "<".
+      const split = text === "<" && prev === "[";
+      prev = key?.code === "[<" ? "" : text;
+      if (key?.code === "[<" || (split && !run)) {
         run = 1;
         return (current = true);
       }
@@ -466,6 +473,100 @@ export function createMouseKeyWindow({ maxRun = 24 } = {}) {
   };
 }
 
+/**
+ * KEEP EVERY SHAPE OF A MOUSE REPORT OUT OF THE LINE (GH #365).
+ *
+ * The input filter used to recognise a report only by node's key code "[<" — the shape node
+ * produces when `ESC [ <` arrives together. When the event loop stalls for longer than
+ * readline's escape timeout (500ms) with an ESC at the end of a read, node gives the ESC up as a
+ * lone Esc key and the rest comes through as ORDINARY characters: "[", "<", "35;114;22M". Every
+ * one of those was typed into the line. Reported on Windows 11 after minimising and restoring
+ * the window (a full repaint, and Windows console writes block), then more with every hover,
+ * because the prompt reports mouse motion.
+ *
+ * Shapes, all consumed whole:
+ *     key "[<", then "35;114;22M"           ← the usual one
+ *     Esc, "[", "<", "35;114;22M"           ← the ESC timed out
+ *     "[", "<", "35;114;22M"                ← the Esc went elsewhere (plainLeads only)
+ *     "^", "[", "[", "<", …                 ← ESC spelled in caret notation (plainLeads only)
+ *
+ * Like createProbeReplyReader it holds anything that still fits the grammar and REPLAYS it
+ * verbatim the moment something does not, so a keystroke is delayed, never lost. A plain "[" or
+ * "^" is only held while the terminal is reporting the mouse (`plainLeads`), so typing them is
+ * not slowed down otherwise.
+ */
+const MOUSE_LEADS = ["\x1b[<", "^[[<", "[<"];
+const MOUSE_BODY_DONE = /^(\d+;\d+;\d+[Mm])$/;
+const MOUSE_BODY_PART = /^\d*(?:;\d*){0,2}$/;
+function mouseTextVerdict(text, plainLeads) {
+  for (const lead of MOUSE_LEADS) {
+    if (!plainLeads && lead !== "\x1b[<") continue;
+    if (lead.startsWith(text)) return { kind: "partial" };
+    if (!text.startsWith(lead)) continue;
+    const body = text.slice(lead.length);
+    if (MOUSE_BODY_DONE.test(body)) return { kind: "done", report: body };
+    if (body.length <= 20 && MOUSE_BODY_PART.test(body)) return { kind: "partial" };
+  }
+  return { kind: "bad" };
+}
+export function createMouseReportReader() {
+  let held = null; // [str, key] pairs
+  const textOf = (str, key) =>
+    key?.code === "[<" ? "\x1b[<" : key?.name === "escape" ? "\x1b" : typeof str === "string" ? str : "";
+  const startsOne = (str, key, plainLeads) =>
+    key?.code === "[<" || key?.name === "escape" || (plainLeads && (str === "[" || str === "^"));
+  return {
+    holding: () => held !== null,
+    /**
+     * Feed one keypress. `plainLeads`: the terminal is reporting the mouse right now.
+     *   { action: "pass" }                        — not ours; carry on
+     *   { action: "hold" }                        — may be a report; arm the flush timer
+     *   { action: "consume", report }             — a whole report, e.g. "35;114;22M"
+     *   { action: "replay", keys, hold? }         — not a report: replay `keys`; when `hold` is
+     *                                               set, the last key began a new candidate and
+     *                                               is still held
+     */
+    feed(str, key, { plainLeads = false } = {}) {
+      if (!held) {
+        if (!startsOne(str, key, plainLeads)) return { action: "pass" };
+        held = [[str, key]];
+        const v = mouseTextVerdict(textOf(str, key), plainLeads);
+        if (v.kind === "partial") return { action: "hold" };
+        held = null;
+        return { action: "pass" };
+      }
+      held.push([str, key]);
+      const text = held.map(([s, k]) => textOf(s, k)).join("");
+      const v = mouseTextVerdict(text, plainLeads);
+      if (v.kind === "done") {
+        held = null;
+        return { action: "consume", report: v.report };
+      }
+      if (v.kind === "partial") return { action: "hold" };
+      // Not a report. If the key that broke it could START one ("[" after "[", an Esc), keep it.
+      const last = held.pop();
+      const keys = held;
+      held = null;
+      if (startsOne(last[0], last[1], plainLeads) && mouseTextVerdict(textOf(last[0], last[1]), plainLeads).kind === "partial") {
+        held = [last];
+        return { action: "replay", keys, hold: true };
+      }
+      return { action: "replay", keys: [...keys, last] };
+    },
+    /** Timer fired: hand back whatever is still held. */
+    flush() {
+      const keys = held ?? [];
+      held = null;
+      return keys;
+    },
+  };
+}
+
+/** Last line of defence at submit: a report that got past every reader is not a question. */
+export function stripLeakedMouseReports(line) {
+  return String(line).replace(/(?:\x1b|\^\[)?\[<\d+;\d+;\d+[Mm]/g, "");
+}
+
 /**
  * A failed turn's message, as something a person can act on.
  *