@allansantos-dev/smart-tool 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,23 +1,50 @@
-# Changelog
-
-## 0.9.0 - beta
-
-First release for beta testers. Windows only.
-
-- `smart_search`: semantic + lexical search (Weaviate-style relative score fusion), results split into code, tests and
-  docs, likeliest functions per chunk, per-project language profile; asks the calling agent to define the scope when no
-  scope model is configured.
-- `web_search`: parallel sources (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and Startpage through a
-  resident browser), bilingual queries, cache shared across sessions with volatility checks, research mode.
-- `web_fetch`: reads a known URL and returns only the answer to the prompt, 24 h page cache, browser rendering for
-  JavaScript pages.
-- Model gateway through adapters: built-in OpenAI-compatible adapter; user adapters as Python files in
-  `~/.smart-tool/adapters`.
-- Optional local embedder through the mcp-memory sidecar when the gateway has no embedding model.
-- PreToolUse hook for Claude Code (HTTP to the daemon) and Codex (thin command), with Redirect, Advise only and Off modes.
-- Setup screen: model gateway, models, agents (MCP registration, hook install, hook behavior), web provider keys,
-  contact for public APIs, local models, start at logon.
-- The daemon owns its port: falls back to a free port and rewrites the smart-tool URLs the clients keep.
-- Install and update with `npx @allansantos-dev/smart-tool@latest install`: the package brings uv (checksum verified)
-  and a private Python 3.12 in `~/.smart-tool/runtime`, so only Node.js is required. The tray offers the update command
-  when npm has a newer version. Product page on GitHub Pages.
+# Changelog
+
+## 0.9.2 - beta
+
+- Installer reported success after a broken Camoufox download: camoufox 0.5.6 prints the error of `fetch` and exits 0.
+  The installer now catches that error and fails the step (retried 3 times), every request of the download has a
+  60 s read timeout (a stalled download used to wait until the 3-minute idle limit), and the final check requires the
+  Camoufox and Chromium executables on disk, so an incomplete browser can never end in "Smart Tool ready".
+- Setup screen: text, model and adapter fields were unstyled boxes (inputs without a type), selects and model fields
+  now look like comboboxes; the hook change opens inside the client's card in a scrollable block with Confirm and
+  Cancel instead of overflowing the page; "Save behavior" works without registering the MCP first; web search keys
+  are set one provider at a time from a provider selector instead of a stack of key fields.
+- Product page: the display font was a family that Google Fonts does not serve (titles fell back to Arial Narrow);
+  it now uses Big Shoulders Display. The page shows the current version (a test keeps it in sync with version.py),
+  links to the release notes and says what the installer does on failures and older installations. A failed Pages
+  deploy is retried once, the run fails unless the live page shows the version, and every release republishes it.
+
+## 0.9.1 - beta
+
+- Installer on a regular Windows code page (cp1252): the steps' output was garbled or crashed the step; every child
+  process now writes UTF-8.
+- Camoufox download (1.3 GB) looked stuck: its progress is shown every 50 MB, a stalled connection fails after 60 s and
+  is retried (3 attempts), and a step is stopped only after a stretch without any output instead of a fixed 10 minutes.
+  Steps run with closed stdin, so an unexpected prompt fails at once instead of waiting unseen.
+- An older installation in another folder (found through its running tray or daemon, logon task, Startup script or
+  agent hooks; only folders made by the installer) is stopped, its hooks are pointed at the new installation and its
+  program folder is removed. Its state folders are left in place.
+- Requirements now state about 2 GB of downloads and 4 GB of disk.
+
+## 0.9.0 - beta
+
+First release for beta testers. Windows only.
+
+- `smart_search`: semantic + lexical search (Weaviate-style relative score fusion), results split into code, tests and
+  docs, likeliest functions per chunk, per-project language profile; asks the calling agent to define the scope when no
+  scope model is configured.
+- `web_search`: parallel sources (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and Startpage through a
+  resident browser), bilingual queries, cache shared across sessions with volatility checks, research mode.
+- `web_fetch`: reads a known URL and returns only the answer to the prompt, 24 h page cache, browser rendering for
+  JavaScript pages.
+- Model gateway through adapters: built-in OpenAI-compatible adapter; user adapters as Python files in
+  `~/.smart-tool/adapters`.
+- Optional local embedder through the mcp-memory sidecar when the gateway has no embedding model.
+- PreToolUse hook for Claude Code (HTTP to the daemon) and Codex (thin command), with Redirect, Advise only and Off modes.
+- Setup screen: model gateway, models, agents (MCP registration, hook install, hook behavior), web provider keys,
+  contact for public APIs, local models, start at logon.
+- The daemon owns its port: falls back to a free port and rewrites the smart-tool URLs the clients keep.
+- Install and update with `npx @allansantos-dev/smart-tool@latest install`: the package brings uv (checksum verified)
+  and a private Python 3.12 in `~/.smart-tool/runtime`, so only Node.js is required. The tray offers the update command
+  when npm has a newer version. Product page on GitHub Pages.

package/NOTICE

@@ -1,32 +1,32 @@
-Smart Tool
-Copyright 2026 Allan Santos
-
-Licensed under the Apache License, Version 2.0 (see LICENSE).
-
-Smart Tool does not bundle third-party code. The installer downloads the components below from their official
-sources into the installation folder or the user's profile; each keeps its own license.
-
-Python packages (installation venv, from PyPI)
-- ddgs (MIT)
-- trafilatura (Apache-2.0)
-- pystray (LGPL-3.0; used unmodified as a library)
-- Pillow (MIT-CMU)
-- PyYAML (MIT)
-
-Browser runtime (web_adapters/browser/.venv, from PyPI and the projects' download servers)
-- camoufox Python package (MIT) and the Camoufox browser, a Firefox fork (MPL-2.0), fetched by `camoufox fetch`
-- crawl4ai (Apache-2.0), https://github.com/unclecode/crawl4ai: page rendering is powered by Crawl4AI
-- Playwright (Apache-2.0) and the Chromium build it installs (BSD-style, see https://www.chromium.org)
-
-Node runtime and packages (web_adapters/node, from nodejs.org and npm)
-- Node.js, downloaded only when no supported Node is installed (MIT and bundled licenses)
-- open-websearch (Apache-2.0)
-- typescript (Apache-2.0)
-- java-parser (Apache-2.0)
-- @angular/compiler (MIT)
-- their dependencies as pinned in web_adapters/node/package-lock.json (MIT, ISC, BSD and Apache-2.0)
-
-Web search sources
-Smart Tool queries public search engines and APIs (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and
-Startpage through a local browser, and optionally Tavily and Firecrawl with your own key). Using them is subject to
-each service's terms of use; free tiers are rate limited per IP address.
+Smart Tool
+Copyright 2026 Allan Santos
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Smart Tool does not bundle third-party code. The installer downloads the components below from their official
+sources into the installation folder or the user's profile; each keeps its own license.
+
+Python packages (installation venv, from PyPI)
+- ddgs (MIT)
+- trafilatura (Apache-2.0)
+- pystray (LGPL-3.0; used unmodified as a library)
+- Pillow (MIT-CMU)
+- PyYAML (MIT)
+
+Browser runtime (web_adapters/browser/.venv, from PyPI and the projects' download servers)
+- camoufox Python package (MIT) and the Camoufox browser, a Firefox fork (MPL-2.0), fetched by `camoufox fetch`
+- crawl4ai (Apache-2.0), https://github.com/unclecode/crawl4ai: page rendering is powered by Crawl4AI
+- Playwright (Apache-2.0) and the Chromium build it installs (BSD-style, see https://www.chromium.org)
+
+Node runtime and packages (web_adapters/node, from nodejs.org and npm)
+- Node.js, downloaded only when no supported Node is installed (MIT and bundled licenses)
+- open-websearch (Apache-2.0)
+- typescript (Apache-2.0)
+- java-parser (Apache-2.0)
+- @angular/compiler (MIT)
+- their dependencies as pinned in web_adapters/node/package-lock.json (MIT, ISC, BSD and Apache-2.0)
+
+Web search sources
+Smart Tool queries public search engines and APIs (DuckDuckGo, Yahoo, Wikipedia, Exa, Parallel, Keenable, Google and
+Startpage through a local browser, and optionally Tavily and Firecrawl with your own key). Using them is subject to
+each service's terms of use; free tiers are rate limited per IP address.

package/README.md

@@ -1,116 +1,117 @@
-# Smart Tool
-
-A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search:
-
-| Tool | What it does |
-|---|---|
-| `smart_search` / `smart_search_result` | Semantic + lexical search over an indexed project, results split into code, tests and docs, with the likeliest functions per chunk |
-| `web_search` / `web_search_result` | Web search across several sources in parallel, in the query language and in English, with a cache shared across sessions; `depth="research"` runs a multi-round research loop |
-| `web_fetch` | Reads a known URL and returns only the answer to your prompt, written by a small model; pages are cached for 24 h |
-| `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage |
-
-An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
-are cheaper, or just tells the agent what Smart Tool would do.
-
-**Status:** 0.9.0 beta. Windows only.
-
-## Requirements
-
-- Windows 10 or 11 (x64) and Node.js 18 or newer for `npx`. Python is not needed: the installer brings its own.
-- About 1 GB of downloads on first install (Python 3.12 and its packages, Node.js when no supported version is
-  installed, the Camoufox and Chromium browsers used for pages that need JavaScript).
-- An OpenAI-compatible model API for embeddings and small chat calls (OpenAI, OpenRouter, a LiteLLM proxy, Ollama...).
-  Web search works without it; smart_search falls back to lexical search.
-
-## Install
-
-```powershell
-npx @allansantos-dev/smart-tool@latest install
-```
-
-Run the same command to update; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
-verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` or the registry, then
-copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
-installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
-`http://127.0.0.1:8765` (another free port is used, and announced, if 8765 is taken).
-
-State lives in `~/.smart-tool`: `config.json`, your model adapters in `adapters/` and indexes, caches and logs in
-`data/`. Secrets (API keys) are encrypted with Windows DPAPI for your user.
-
-## Set up
-
-Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup`.
-
-1. **Model gateway**: pick an adapter and fill its fields. The built-in **OpenAI-compatible** adapter takes a base
-   URL ending where the API starts, like the OpenAI SDK `base_url` (`https://api.openai.com/v1`,
-   `https://openrouter.ai/api/v1`, `http://localhost:11434/v1`), and an optional API key. Saving tests `/models` first.
-2. **Models**: embedding, rerank (optional; without it results use the hybrid order), the router model (small, no
-   reasoning: it decides before tool calls), the index classification model and the research model. Any id the gateway
-   accepts works; the catalog is shown as suggestions.
-3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
-   hook and choose its behavior:
-   - **Redirect** (default): the native tool is denied with the reason and the Smart Tool tool to use.
-   - **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
-   - **Off**: no routing.
-4. **Local models** (optional): if the mcp-memory embedding sidecar is installed on the machine, its local embedder
-   can serve as a fallback (or preferred) embedding model.
-5. **Web search providers** work without keys on their free public tiers; add your own key for more volume. Set your
-   own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent.
-
-## Writing a model adapter
-
-An adapter is a Python file in `~/.smart-tool/adapters/`. It appears in the setup screen next to the built-in one.
-
-```python
-import json
-import urllib.request
-
-NAME = "my_gateway"            # unique id
-LABEL = "My gateway"           # shown in the setup screen
-FIELDS = (                     # rendered as inputs; secret values are stored with DPAPI
-    {"name": "url", "label": "Address", "required": True, "placeholder": "http://10.0.0.5"},
-    {"name": "token", "label": "Token", "secret": True},
-)
-
-
-def request(options, route, body=None, timeout=15):
-    """route is OpenAI-style: models, model/info, embeddings, chat/completions, rerank. body None means GET.
-    Return (parsed JSON, response headers); let urllib.error.HTTPError propagate."""
-    data = json.dumps(body).encode() if body is not None else None
-    headers = {"Content-Type": "application/json"}
-    if options.get("token"):
-        headers["Authorization"] = "Bearer " + options["token"]
-    req = urllib.request.Request(f"{options['url']}/v1/{route}", data=data, headers=headers)
-    with urllib.request.urlopen(req, timeout=timeout) as response:
-        return json.load(response), response.headers
-
-
-def verify(options):
-    """Raise RuntimeError with a reason a person can act on."""
-    request(options, "models", timeout=10)
-```
-
-Embeddings and chat use the OpenAI request and response formats; rerank uses the Cohere/Jina format served by
-LiteLLM (`{"model", "query", "documents", "top_n"}` returning `results[].index` and `relevance_score`). A file that
-fails to load is listed in the setup screen with its error and does not affect the others.
-
-## Data and privacy
-
-- Indexed code stays on your machine. Chunks are sent to your model gateway to compute embeddings, and small excerpts
-  go to its chat models (scope, profile, routing, web_fetch answers). Use a local gateway (Ollama, LiteLLM) to keep
-  everything local.
-- Web queries go to the search sources listed in `NOTICE`. Their free tiers are rate limited per IP address; respect
-  each service's terms of use.
-- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine.
-
-## Uninstall
-
-Turn off "Start automatically" in the setup screen, quit from the tray, remove the hook entries from
-`~/.claude/settings.json` / `~/.codex/hooks.json` (the setup screen shows them), run `claude mcp remove smart-tool -s
-user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`.
-
-## License
-
-Apache License 2.0. See `LICENSE` and `NOTICE` for third-party components.
-
-Page rendering is powered by [Crawl4AI](https://github.com/unclecode/crawl4ai) (Apache-2.0).
+# Smart Tool
+
+A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search:
+
+| Tool | What it does |
+|---|---|
+| `smart_search` / `smart_search_result` | Semantic + lexical search over an indexed project, results split into code, tests and docs, with the likeliest functions per chunk |
+| `web_search` / `web_search_result` | Web search across several sources in parallel, in the query language and in English, with a cache shared across sessions; `depth="research"` runs a multi-round research loop |
+| `web_fetch` | Reads a known URL and returns only the answer to your prompt, written by a small model; pages are cached for 24 h |
+| `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage |
+
+An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
+are cheaper, or just tells the agent what Smart Tool would do.
+
+**Status:** 0.9.0 beta. Windows only.
+
+## Requirements
+
+- Windows 10 or 11 (x64) and Node.js 18 or newer for `npx`. Python is not needed: the installer brings its own.
+- About 2 GB of downloads and 4 GB of disk on first install: Python 3.12 and its packages, Node.js when no
+  supported version is installed, and the browsers for pages that need JavaScript (Camoufox alone is a 1.3 GB
+  download; the installer shows its progress).
+- An OpenAI-compatible model API for embeddings and small chat calls (OpenAI, OpenRouter, a LiteLLM proxy, Ollama...).
+  Web search works without it; smart_search falls back to lexical search.
+
+## Install
+
+```powershell
+npx @allansantos-dev/smart-tool@latest install
+```
+
+Run the same command to update; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
+verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` or the registry, then
+copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
+installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
+`http://127.0.0.1:8765` (another free port is used, and announced, if 8765 is taken).
+
+State lives in `~/.smart-tool`: `config.json`, your model adapters in `adapters/` and indexes, caches and logs in
+`data/`. Secrets (API keys) are encrypted with Windows DPAPI for your user.
+
+## Set up
+
+Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup`.
+
+1. **Model gateway**: pick an adapter and fill its fields. The built-in **OpenAI-compatible** adapter takes a base
+   URL ending where the API starts, like the OpenAI SDK `base_url` (`https://api.openai.com/v1`,
+   `https://openrouter.ai/api/v1`, `http://localhost:11434/v1`), and an optional API key. Saving tests `/models` first.
+2. **Models**: embedding, rerank (optional; without it results use the hybrid order), the router model (small, no
+   reasoning: it decides before tool calls), the index classification model and the research model. Any id the gateway
+   accepts works; the catalog is shown as suggestions.
+3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
+   hook and choose its behavior:
+   - **Redirect** (default): the native tool is denied with the reason and the Smart Tool tool to use.
+   - **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
+   - **Off**: no routing.
+4. **Local models** (optional): if the mcp-memory embedding sidecar is installed on the machine, its local embedder
+   can serve as a fallback (or preferred) embedding model.
+5. **Web search providers** work without keys on their free public tiers; add your own key for more volume. Set your
+   own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent.
+
+## Writing a model adapter
+
+An adapter is a Python file in `~/.smart-tool/adapters/`. It appears in the setup screen next to the built-in one.
+
+```python
+import json
+import urllib.request
+
+NAME = "my_gateway"            # unique id
+LABEL = "My gateway"           # shown in the setup screen
+FIELDS = (                     # rendered as inputs; secret values are stored with DPAPI
+    {"name": "url", "label": "Address", "required": True, "placeholder": "http://10.0.0.5"},
+    {"name": "token", "label": "Token", "secret": True},
+)
+
+
+def request(options, route, body=None, timeout=15):
+    """route is OpenAI-style: models, model/info, embeddings, chat/completions, rerank. body None means GET.
+    Return (parsed JSON, response headers); let urllib.error.HTTPError propagate."""
+    data = json.dumps(body).encode() if body is not None else None
+    headers = {"Content-Type": "application/json"}
+    if options.get("token"):
+        headers["Authorization"] = "Bearer " + options["token"]
+    req = urllib.request.Request(f"{options['url']}/v1/{route}", data=data, headers=headers)
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return json.load(response), response.headers
+
+
+def verify(options):
+    """Raise RuntimeError with a reason a person can act on."""
+    request(options, "models", timeout=10)
+```
+
+Embeddings and chat use the OpenAI request and response formats; rerank uses the Cohere/Jina format served by
+LiteLLM (`{"model", "query", "documents", "top_n"}` returning `results[].index` and `relevance_score`). A file that
+fails to load is listed in the setup screen with its error and does not affect the others.
+
+## Data and privacy
+
+- Indexed code stays on your machine. Chunks are sent to your model gateway to compute embeddings, and small excerpts
+  go to its chat models (scope, profile, routing, web_fetch answers). Use a local gateway (Ollama, LiteLLM) to keep
+  everything local.
+- Web queries go to the search sources listed in `NOTICE`. Their free tiers are rate limited per IP address; respect
+  each service's terms of use.
+- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine.
+
+## Uninstall
+
+Turn off "Start automatically" in the setup screen, quit from the tray, remove the hook entries from
+`~/.claude/settings.json` / `~/.codex/hooks.json` (the setup screen shows them), run `claude mcp remove smart-tool -s
+user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`.
+
+## License
+
+Apache License 2.0. See `LICENSE` and `NOTICE` for third-party components.
+
+Page rendering is powered by [Crawl4AI](https://github.com/unclecode/crawl4ai) (Apache-2.0).

package/atomic_io.py

@@ -1,94 +1,94 @@
-#!/usr/bin/env python3
-"""Gravação atômica de arquivo pequeno de estado/credencial, compartilhada pelos módulos
-do Smart Tool."""
-import glob
-import os
-import time
-import uuid
-
-_REPLACE_ATTEMPTS = 4
-_REPLACE_BACKOFF_S = 0.05
-TMP_SUFFIX = ".tmp."
-ORPHAN_AGE_S = 300
-
-
-def rotate(path, max_bytes):
-    """Keeps one previous generation (`path.1`) once an append-only log reaches max_bytes. Best effort: a log
-    locked by another process is rotated on a later append, and the append itself still happens."""
-    try:
-        if os.path.getsize(path) >= max_bytes:
-            os.replace(path, path + ".1")
-    except OSError:
-        pass
-
-
-def atomic_replace(tmp_path, final_path):
-    """`os.replace` com retry curto: no Windows, `MoveFileEx` falha com `PermissionError`
-    enquanto outro processo mantém o destino aberto — e estes arquivos têm vários leitores
-    concorrentes (hook do router, tray, configure.py). A janela é de
-    milissegundos, então insistir resolve; a exceção só sobe na última tentativa."""
-    for attempt in range(_REPLACE_ATTEMPTS):
-        try:
-            os.replace(tmp_path, final_path)
-            return
-        except PermissionError:
-            if attempt == _REPLACE_ATTEMPTS - 1:
-                raise
-            time.sleep(_REPLACE_BACKOFF_S)
-
-
-def tmp_path_for(final_path):
-    """Sufixo único por chamada (não por pid): duas threads/processos podem gravar o mesmo
-    arquivo quase ao mesmo tempo."""
-    return final_path + TMP_SUFFIX + uuid.uuid4().hex
-
-
-def sweep_orphans(final_path, max_age_s=ORPHAN_AGE_S):
-    """Remove tmp de gravação interrompida (kill -9, queda de energia) do mesmo arquivo.
-    Esses tmp carregam o mesmo conteúdo do destino — credencial, no caso — com nome
-    aleatório e ninguém mais os apagaria. Best-effort: nunca impede a gravação em curso."""
-    limite = time.time() - max_age_s
-    for candidate in glob.glob(glob.escape(final_path) + TMP_SUFFIX + "*"):
-        try:
-            if os.path.getmtime(candidate) < limite:
-                os.remove(candidate)
-        except OSError:
-            pass
-
-
-def _write_and_replace(final_path, data, encoding=None):
-    sweep_orphans(final_path)
-    tmp_path = tmp_path_for(final_path)
-    try:
-        # `O_EXCL` garante tmp novo (nunca aproveita um abandonado, que pode ser de outro
-        # conteúdo); `0o600` é o pedido de permissão restrita onde o SO honra (no Windows
-        # só liga o atributo read-only — lá a confidencialidade vem da ACL do diretório).
-        flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
-        fd = os.open(tmp_path, flags, 0o600)
-        mode = "wb" if encoding is None else "w"
-        extra = {} if encoding is None else {"encoding": encoding, "newline": ""}
-        with os.fdopen(fd, mode, **extra) as f:
-            f.write(data)
-            # `os.replace` só garante que o nome aparece inteiro; sem o flush+fsync uma
-            # queda de energia pode persistir o rename sem os dados e deixar o destino —
-            # que era o único lugar com o conteúdo anterior — vazio ou com lixo.
-            f.flush()
-            os.fsync(f.fileno())
-        atomic_replace(tmp_path, final_path)
-    except Exception:
-        try:
-            os.remove(tmp_path)
-        except OSError:
-            pass
-        raise
-
-
-def write_secret_bytes(final_path, data):
-    """Grava bytes em `final_path` com o tmp restrito, `fsync` dos dados antes do rename
-    (a durabilidade da entrada de diretório fica com o SO) e replace atômico."""
-    _write_and_replace(final_path, data)
-
-
-def write_secret_text(final_path, text, encoding="utf-8"):
-    """Mesmo contrato de `write_secret_bytes`, para conteúdo textual (JSON de token)."""
-    _write_and_replace(final_path, text, encoding=encoding)
+#!/usr/bin/env python3
+"""Gravação atômica de arquivo pequeno de estado/credencial, compartilhada pelos módulos
+do Smart Tool."""
+import glob
+import os
+import time
+import uuid
+
+_REPLACE_ATTEMPTS = 4
+_REPLACE_BACKOFF_S = 0.05
+TMP_SUFFIX = ".tmp."
+ORPHAN_AGE_S = 300
+
+
+def rotate(path, max_bytes):
+    """Keeps one previous generation (`path.1`) once an append-only log reaches max_bytes. Best effort: a log
+    locked by another process is rotated on a later append, and the append itself still happens."""
+    try:
+        if os.path.getsize(path) >= max_bytes:
+            os.replace(path, path + ".1")
+    except OSError:
+        pass
+
+
+def atomic_replace(tmp_path, final_path):
+    """`os.replace` com retry curto: no Windows, `MoveFileEx` falha com `PermissionError`
+    enquanto outro processo mantém o destino aberto — e estes arquivos têm vários leitores
+    concorrentes (hook do router, tray, configure.py). A janela é de
+    milissegundos, então insistir resolve; a exceção só sobe na última tentativa."""
+    for attempt in range(_REPLACE_ATTEMPTS):
+        try:
+            os.replace(tmp_path, final_path)
+            return
+        except PermissionError:
+            if attempt == _REPLACE_ATTEMPTS - 1:
+                raise
+            time.sleep(_REPLACE_BACKOFF_S)
+
+
+def tmp_path_for(final_path):
+    """Sufixo único por chamada (não por pid): duas threads/processos podem gravar o mesmo
+    arquivo quase ao mesmo tempo."""
+    return final_path + TMP_SUFFIX + uuid.uuid4().hex
+
+
+def sweep_orphans(final_path, max_age_s=ORPHAN_AGE_S):
+    """Remove tmp de gravação interrompida (kill -9, queda de energia) do mesmo arquivo.
+    Esses tmp carregam o mesmo conteúdo do destino — credencial, no caso — com nome
+    aleatório e ninguém mais os apagaria. Best-effort: nunca impede a gravação em curso."""
+    limite = time.time() - max_age_s
+    for candidate in glob.glob(glob.escape(final_path) + TMP_SUFFIX + "*"):
+        try:
+            if os.path.getmtime(candidate) < limite:
+                os.remove(candidate)
+        except OSError:
+            pass
+
+
+def _write_and_replace(final_path, data, encoding=None):
+    sweep_orphans(final_path)
+    tmp_path = tmp_path_for(final_path)
+    try:
+        # `O_EXCL` garante tmp novo (nunca aproveita um abandonado, que pode ser de outro
+        # conteúdo); `0o600` é o pedido de permissão restrita onde o SO honra (no Windows
+        # só liga o atributo read-only — lá a confidencialidade vem da ACL do diretório).
+        flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
+        fd = os.open(tmp_path, flags, 0o600)
+        mode = "wb" if encoding is None else "w"
+        extra = {} if encoding is None else {"encoding": encoding, "newline": ""}
+        with os.fdopen(fd, mode, **extra) as f:
+            f.write(data)
+            # `os.replace` só garante que o nome aparece inteiro; sem o flush+fsync uma
+            # queda de energia pode persistir o rename sem os dados e deixar o destino —
+            # que era o único lugar com o conteúdo anterior — vazio ou com lixo.
+            f.flush()
+            os.fsync(f.fileno())
+        atomic_replace(tmp_path, final_path)
+    except Exception:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def write_secret_bytes(final_path, data):
+    """Grava bytes em `final_path` com o tmp restrito, `fsync` dos dados antes do rename
+    (a durabilidade da entrada de diretório fica com o SO) e replace atômico."""
+    _write_and_replace(final_path, data)
+
+
+def write_secret_text(final_path, text, encoding="utf-8"):
+    """Mesmo contrato de `write_secret_bytes`, para conteúdo textual (JSON de token)."""
+    _write_and_replace(final_path, text, encoding=encoding)

package/bin/smart-tool.mjs

@@ -74,7 +74,11 @@ async function main() {
   if (process.platform !== "win32" || process.arch !== "x64") fail(`Smart Tool runs on Windows x64 only (this is ${process.platform}-${process.arch}).`);
   await ensureUv();
   const python = ensurePython();
-  const installer = spawnSync(python, [join(PACKAGE_DIR, "install.py"), "--skip-tests", ...rest], { stdio: "inherit", cwd: PACKAGE_DIR });
+  const installer = spawnSync(python, [join(PACKAGE_DIR, "install.py"), "--skip-tests", ...rest], {
+    stdio: "inherit",
+    cwd: PACKAGE_DIR,
+    env: { ...process.env, PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
+  });
   if (installer.error) fail(`the installer did not start: ${installer.error.message}`);
   process.exit(installer.status ?? 1);
 }