substrate-setup 0.3.1__tar.gz → 0.4.1__tar.gz

substrate_setup-0.4.1/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.4.1 — 2026-05-30
+
+- Fix `substrate-setup --version` reporting a stale number. `__version__` is
+  now derived from the installed package metadata
+  (`importlib.metadata.version`) instead of a hand-maintained string, so it
+  can never drift from `pyproject.toml` again. (0.4.0 shipped with a leftover
+  `__version__ = "0.3.1"`; the compatibility fix itself was unaffected.)
+
+## 0.4.0 — 2026-05-30
+
+- Lower the supported Python floor from **3.12 to 3.8**. Nothing in the tool
+  actually required 3.12 — the gate was conservative. `pip install
+  substrate-setup` now works on Anaconda's default 3.9 and other older
+  interpreters, no `uv`/`pipx` workaround needed.
+  - `enum.StrEnum` (3.11+) imports natively on 3.11+ with a minimal
+    `(str, Enum)` backport on older interpreters.
+  - The `tomllib` → `tomli` fallback is now `sys.version_info`-gated, and
+    `tomli` is a declared dependency (`python_version < '3.11'`) — previously
+    the fallback path had no dependency backing it and would have failed.
+  - `tomli-w` lower bound relaxed `1.2 → 1.0` so 3.8 resolves.
+- No CLI or config-schema changes — pure compatibility widening. The
+  test/type tooling still requires 3.9+ (`pytest-httpx`/`mypy` dropped 3.8);
+  end users on 3.8 are unaffected.
+
+## 0.3.1 — 2026-05-24
+
+- Persist `SUBSTRATE_API_KEY` automatically during `configure`:
+  on Windows, writes `HKCU\Environment\SUBSTRATE_API_KEY` via `winreg`
+  + `WM_SETTINGCHANGE` broadcast — visible to GUI agents (Codex Desktop)
+  on next launch without the user editing rc files or restarting their
+  session. On macOS / Linux, appends a marker-fenced `export` block (or
+  fish-syntax `set -gx` for fish users) to the user's shell rc. Re-runs
+  collapse stale blocks idempotently — the rc never grows on repeated
+  configures.
+- Codex adapter now prints a one-line Windows Defender exclusion command
+  to eliminate SmartScreen prompts on per-action helper binary spawns.
+  Informational only — substrate-setup never elevates itself.
+- Adapters surface env-persistence failures with a clear `WARNING:`
+  prefix + manual fallback hint so users notice when the convenience
+  step fails but the config file itself was written successfully.
+- Codex adapter drops the stale "/v1/responses NOT YET STARTED" warning
+  — Phase 2 shipped on 2026-05-24.
+- No config schema changes from 0.3.0. Upgrade cleanly via
+  `uv tool install --force substrate-setup` (or pipx).

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substrate-setup
-Version: 0.3.1
+Version: 0.4.1
 Summary: One-shot local configurator for coding agents against a Substrate gateway
 Project-URL: Homepage, https://github.com/FrankXiaA/substrate-solutions
 Project-URL: Source, https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup
@@ -14,16 +14,21 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Utilities
-Requires-Python: >=3.12
+Requires-Python: >=3.8
 Requires-Dist: httpx>=0.27
 Requires-Dist: ruamel-yaml>=0.18
-Requires-Dist: tomli-w>=1.2
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: mypy<2,>=1.13; extra == 'dev'
-Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; (python_version >= '3.9') and extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff<1,>=0.7; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -34,10 +39,16 @@ One-shot configurator that points local coding agents at a Substrate gateway.
 
 ## Install
 
-`substrate-setup` requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:
+`substrate-setup` runs on **Python 3.8 or newer** — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain `pip` works:
 
 ```bash
-# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+pip install substrate-setup
+```
+
+If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use `uv` or `pipx`:
+
+```bash
+# Option A — uv (also downloads a Python for the tool if needed)
 uv tool install substrate-setup
 
 # Option B — pipx
@@ -52,8 +63,6 @@ curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-> **Why not `pip install substrate-setup`?** It works only if the `pip` on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default `pip` (Python 3.9) is the common pitfall — PyPI hides every release from it with `Requires-Python >=3.12` and the error message is unhelpful. `uv` and `pipx` both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.
-
 ## Use
 
 ```bash

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/README.md

@@ -4,10 +4,16 @@ One-shot configurator that points local coding agents at a Substrate gateway.
 
 ## Install
 
-`substrate-setup` requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:
+`substrate-setup` runs on **Python 3.8 or newer** — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain `pip` works:
 
 ```bash
-# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+pip install substrate-setup
+```
+
+If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use `uv` or `pipx`:
+
+```bash
+# Option A — uv (also downloads a Python for the tool if needed)
 uv tool install substrate-setup
 
 # Option B — pipx
@@ -22,8 +28,6 @@ curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-> **Why not `pip install substrate-setup`?** It works only if the `pip` on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default `pip` (Python 3.9) is the common pitfall — PyPI hides every release from it with `Requires-Python >=3.12` and the error message is unhelpful. `uv` and `pipx` both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.
-
 ## Use
 
 ```bash

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "substrate-setup"
-version = "0.3.1"
+version = "0.4.1"
 description = "One-shot local configurator for coding agents against a Substrate gateway"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.8"
 authors = [{ name = "Substrate Solutions" }]
 license = { text = "MIT" }
 keywords = ["substrate", "llm", "gateway", "aider", "continue", "hermes", "openai-compatible"]
@@ -18,6 +18,10 @@ classifiers = [
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Code Generators",
   "Topic :: Utilities",
@@ -25,7 +29,11 @@ classifiers = [
 dependencies = [
   "httpx>=0.27",
   "ruamel.yaml>=0.18",
-  "tomli-w>=1.2",
+  "tomli-w>=1.0",
+  # Reading TOML (codex config, credentials probe) uses the stdlib
+  # ``tomllib`` on 3.11+; older interpreters fall back to the ``tomli``
+  # backport. See ``credentials.py`` / ``agents/codex.py`` import guards.
+  "tomli>=2.0; python_version < '3.11'",
 ]
 
 [project.urls]
@@ -34,9 +42,12 @@ Source = "https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-a
 Issues = "https://github.com/FrankXiaA/substrate-solutions/issues"
 
 [project.optional-dependencies]
+# Runtime floor is Python 3.8, but the test/type tooling needs 3.9+
+# (pytest-httpx>=0.30 and modern mypy both dropped 3.8). Developing/testing
+# the package therefore requires 3.9+; end users on 3.8 are unaffected.
 dev = [
   "pytest>=8.0",
-  "pytest-httpx>=0.30",
+  "pytest-httpx>=0.30; python_version >= '3.9'",
   "ruff>=0.7,<1",
   "mypy>=1.13,<2",
 ]
@@ -50,8 +61,14 @@ packages = ["substrate_setup"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.ruff]
+target-version = "py38"
+
 [tool.mypy]
-python_version = "3.12"
+# Lowest version mypy itself supports as an analysis target; the package's
+# runtime floor is 3.8 (see requires-python). 3.8-only breakage is caught by
+# the test suite + import smoke, not the type checker.
+python_version = "3.9"
 strict = true
 ignore_missing_imports = true
 packages = ["substrate_setup"]

substrate_setup-0.4.1/substrate_setup/__init__.py

@@ -0,0 +1,14 @@
+"""substrate-setup — one-shot configurator for coding agents.
+
+See https://github.com/FrankXiaA/substrate-solutions for the gateway it
+configures against.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth: read the version from the installed package
+    # metadata (driven by pyproject.toml) so it can never drift from the
+    # published release. ``importlib.metadata`` is stdlib since Python 3.8.
+    __version__ = version("substrate-setup")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/aider.py

@@ -56,7 +56,12 @@ from substrate_setup.agents.base import (
     ResultStatus,
 )
 from substrate_setup.backup import backup_once
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 
 MANAGED_KEYS_MARKER = "_substrate_setup_managed_keys"
 MANAGED_KEYS: list[str] = ["openai-api-base", "openai-api-key", "model"]
@@ -262,7 +267,14 @@ class AiderAgent(Agent):
             )
             _restrict_file_mode(meta_path)
 
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         print(format_persist_message_for_user(persist_result))
 
         return AgentResult(

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/base.py

@@ -5,11 +5,24 @@ interface. The orchestrator in cli.py treats them polymorphically.
 """
 from __future__ import annotations
 
+import sys
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from enum import StrEnum
 from pathlib import Path
 
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:  # pragma: no cover - Python <3.11 backport
+    # ``enum.StrEnum`` landed in 3.11. On older interpreters a plain
+    # ``(str, Enum)`` mixin gives the same behaviour: members are real
+    # ``str`` instances, so ``ResultStatus.SUCCESS == "success"`` holds.
+    # ``__str__ = str.__str__`` matches 3.11's StrEnum, where ``str(member)``
+    # returns the bare value rather than ``"ResultStatus.SUCCESS"``.
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        __str__ = str.__str__
+
 from substrate_setup.catalog import CatalogEntry
 
 

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/claude_code.py

@@ -44,7 +44,12 @@ from substrate_setup.agents.base import (
     ResultStatus,
 )
 from substrate_setup.backup import backup_once
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 
 MANAGED_ENV_KEYS_MARKER = "_substrate_setup_managed_env_keys"
 MANAGED_ENV_KEYS: list[str] = [
@@ -219,7 +224,14 @@ class ClaudeCodeAgent(Agent):
             )
             _restrict_file_mode(settings_path)
 
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         bullets = "\n".join(f"     - {m.id}" for m in chat_models)
         print(
             "Claude Code configured to use the Substrate gateway.\n"

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/codex.py

@@ -42,10 +42,10 @@ from typing import Any
 
 import tomli_w
 
-try:
+if sys.version_info >= (3, 11):
     import tomllib
-except ImportError:  # pragma: no cover — Python <3.11 fallback
-    import tomli as tomllib  # type: ignore[no-redef]
+else:  # pragma: no cover — Python <3.11 uses the tomli backport
+    import tomli as tomllib
 
 from substrate_setup.agents.base import (
     Agent,
@@ -54,7 +54,12 @@ from substrate_setup.agents.base import (
     ResultStatus,
 )
 from substrate_setup.backup import backup_once
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 
 PROVIDER_KEY = "substrate"
 ENV_KEY_NAME = "SUBSTRATE_API_KEY"
@@ -217,7 +222,14 @@ class CodexAgent(Agent):
             cfg_path.write_text(f"{MARKER_COMMENT}\n{body}", encoding="utf-8")
             _restrict_file_mode(cfg_path)
 
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         bullets = "\n".join(f"     - {m.id}" for m in chat_models)
         print(
             "Codex configured to use the Substrate gateway.\n"

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/continue_dev.py

@@ -46,7 +46,12 @@ from substrate_setup.agents.base import (
     ResultStatus,
 )
 from substrate_setup.backup import backup_once
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 from substrate_setup.catalog import CatalogEntry
 from substrate_setup.markers import MARKER_KEY, MARKER_VALUE, is_substrate_managed
 
@@ -241,7 +246,14 @@ class ContinueAgent(Agent):
         if not ctx.dry_run:
             _dump_yaml(yaml_path, payload)
 
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         print(format_persist_message_for_user(persist_result))
 
         msg = f"{len(ctx.catalog)} models written, API base + key set in {yaml_path}."

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/cursor.py

@@ -17,7 +17,12 @@ from substrate_setup.agents.base import (
     ConfigureContext,
     ResultStatus,
 )
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 
 
 def _user_data_candidates() -> list[Path]:
@@ -44,7 +49,14 @@ class CursorAgent(Agent):
         return None
 
     def configure(self, ctx: ConfigureContext) -> AgentResult:
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         chat_models = [
             e for e in ctx.catalog
             if e.output_modality == "text"

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/agents/hermes.py

@@ -62,7 +62,12 @@ from substrate_setup.agents.base import (
     ResultStatus,
 )
 from substrate_setup.backup import backup_once
-from substrate_setup.env_persist import format_persist_message_for_user, persist_substrate_api_key
+from substrate_setup.env_persist import (
+    PersistResult,
+    PersistStatus,
+    format_persist_message_for_user,
+    persist_substrate_api_key,
+)
 
 # Top-level marker key listing the model.* keys substrate-setup owns.
 MANAGED_KEYS_MARKER = "_substrate_setup_managed_keys"
@@ -387,7 +392,14 @@ class HermesAgent(Agent):
         if not ctx.dry_run:
             _dump_yaml(cfg_path, payload)
 
-        persist_result = persist_substrate_api_key(ctx.api_key)
+        if not ctx.dry_run:
+            persist_result = persist_substrate_api_key(ctx.api_key)
+        else:
+            persist_result = PersistResult(
+                status=PersistStatus.SKIPPED,
+                message="(dry-run) would persist SUBSTRATE_API_KEY",
+                path=None,
+            )
         print(format_persist_message_for_user(persist_result))
 
         msg = (

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/credentials.py

@@ -8,10 +8,10 @@ from collections.abc import Callable
 from getpass import getpass
 from pathlib import Path
 
-try:
+if sys.version_info >= (3, 11):
     import tomllib
-except ImportError:  # pragma: no cover - Python <3.11 fallback
-    import tomli as tomllib  # type: ignore[no-redef]
+else:  # pragma: no cover - Python <3.11 uses the tomli backport
+    import tomli as tomllib
 
 KEY_REGEX = re.compile(r"^sk-substrate-[A-Za-z0-9_-]{20,}$")
 ENV_VAR = "SUBSTRATE_API_KEY"

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/data/fallback_catalog.json

@@ -2,13 +2,13 @@
   "object": "list",
   "data": [
     {
-      "id": "claude-opus-4-7",
+      "id": "claude-opus-4-8",
       "object": "model",
-      "created": 1776297600,
+      "created": 1779926400,
       "owned_by": "anthropic",
-      "display_name": "Claude Opus 4.7",
+      "display_name": "Claude Opus 4.8",
       "description": "Anthropic flagship (most capable, agentic coding)",
-      "context_length": 200000,
+      "context_length": 1000000,
       "max_completion_tokens": 32000,
       "pricing": {
         "input_per_million_usd": 5.0,
@@ -29,7 +29,7 @@
       "owned_by": "anthropic",
       "display_name": "Claude Sonnet 4.6",
       "description": "Balanced quality and speed",
-      "context_length": 200000,
+      "context_length": 1000000,
       "max_completion_tokens": 32000,
       "pricing": {
         "input_per_million_usd": 3.0,

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/substrate_setup/env_persist.py

@@ -25,6 +25,7 @@ import sys
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
+from typing import Any, cast
 
 _ENV_VAR = "SUBSTRATE_API_KEY"
 _MARKER_OPEN = "# >>> substrate-setup managed >>>"
@@ -89,14 +90,15 @@ def _persist_windows(api_key: str) -> PersistResult:
             path=None,
         )
 
+    wr = cast(Any, winreg)  # cross-platform mypy: winreg attrs absent from Linux stubs
     try:
-        with winreg.OpenKey(
-            winreg.HKEY_CURRENT_USER,
+        with wr.OpenKey(
+            wr.HKEY_CURRENT_USER,
             "Environment",
             0,
-            winreg.KEY_SET_VALUE,
+            wr.KEY_SET_VALUE,
         ) as h:
-            winreg.SetValueEx(h, _ENV_VAR, 0, winreg.REG_EXPAND_SZ, api_key)
+            wr.SetValueEx(h, _ENV_VAR, 0, wr.REG_EXPAND_SZ, api_key)
     except OSError as exc:
         return PersistResult(
             status=PersistStatus.ERROR,
@@ -130,8 +132,10 @@ def _broadcast_setting_change_windows() -> None:
     HWND_BROADCAST = 0xFFFF
     WM_SETTINGCHANGE = 0x001A
     SMTO_ABORTIFHUNG = 0x0002
-    user32 = ctypes.WinDLL("user32", use_last_error=True)
-    result = wintypes.DWORD()
+    ct = cast(Any, ctypes)   # cross-platform mypy: WinDLL absent from Linux stubs
+    wt = cast(Any, wintypes)  # cross-platform mypy: wintypes attrs absent from Linux stubs
+    user32 = ct.WinDLL("user32", use_last_error=True)
+    result = wt.DWORD()
     try:
         user32.SendMessageTimeoutW(
             HWND_BROADCAST,
@@ -140,7 +144,7 @@ def _broadcast_setting_change_windows() -> None:
             "Environment",
             SMTO_ABORTIFHUNG,
             5000,
-            ctypes.byref(result),
+            ct.byref(result),
         )
     except OSError:
         pass  # broadcast is best-effort
@@ -170,20 +174,32 @@ def _persist_posix(api_key: str) -> PersistResult:
         export_line = f'export {_ENV_VAR}="{api_key}"'
     block = f"{_MARKER_OPEN}\n{export_line}\n{_MARKER_CLOSE}\n"
 
-    # Ensure parent dir exists — fish users on a fresh install won't
-    # have ~/.config/fish/ yet.
-    rc.parent.mkdir(parents=True, exist_ok=True)
-    existing = rc.read_text(encoding="utf-8") if rc.exists() else ""
-
-    # Strip ALL existing marker blocks (defensive: a buggy earlier run
-    # or hand-editing could leave duplicates) and append exactly one new
-    # block. Invariant: exactly one marker block after any call.
-    stripped = _MARKER_BLOCK_RE.sub("", existing)
-    if stripped and not stripped.endswith("\n"):
-        stripped += "\n"
-    new_body = stripped + block
-
-    rc.write_text(new_body, encoding="utf-8")
+    # Wrap the rc read/write in try/except — mirror the Windows path's
+    # OSError handling. Without this, an unreadable file (binary or bad
+    # encoding) or an unwritable mount (read-only filesystem, permissions
+    # error) crashes configure with an unhandled exception instead of
+    # returning a clean ERROR result the orchestrator can surface.
+    try:
+        # Ensure parent dir exists — fish users on a fresh install won't
+        # have ~/.config/fish/ yet.
+        rc.parent.mkdir(parents=True, exist_ok=True)
+        existing = rc.read_text(encoding="utf-8") if rc.exists() else ""
+
+        # Strip ALL existing marker blocks (defensive: a buggy earlier run
+        # or hand-editing could leave duplicates) and append exactly one new
+        # block. Invariant: exactly one marker block after any call.
+        stripped = _MARKER_BLOCK_RE.sub("", existing)
+        if stripped and not stripped.endswith("\n"):
+            stripped += "\n"
+        new_body = stripped + block
+
+        rc.write_text(new_body, encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return PersistResult(
+            status=PersistStatus.ERROR,
+            message=f"Failed to write {rc}: {exc}",
+            path=rc,
+        )
 
     return PersistResult(
         status=PersistStatus.PERSISTED,

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/tests/agents/test_claude_code.py

@@ -169,6 +169,10 @@ def test_configure_handles_malformed_json(home_dir):
     assert "valid JSON" in result.message
 
 
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="POSIX file modes don't apply on Windows (NTFS reports 0o666)",
+)
 def test_configure_chmods_0600_on_posix(home_dir, monkeypatch):
     monkeypatch.setattr(sys, "platform", "linux")
     ClaudeCodeAgent().configure(_ctx())

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/tests/agents/test_codex.py

@@ -181,6 +181,10 @@ def test_configure_returns_clean_error_on_malformed_toml(home_dir):
     assert "valid TOML" in result.message
 
 
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="POSIX file modes don't apply on Windows (NTFS reports 0o666)",
+)
 def test_configure_chmods_0600_on_posix(home_dir, monkeypatch):
     monkeypatch.setattr(sys, "platform", "linux")
     CodexAgent().configure(_ctx())

{substrate_setup-0.3.1 → substrate_setup-0.4.1}/tests/agents/test_cursor.py

@@ -125,7 +125,19 @@ def test_cursor_configure_calls_env_persist(monkeypatch, tmp_path):
     assert captured == [VALID_KEY]
 
 
-def test_walkthrough_excludes_image_gen_models(capsys):
+def test_walkthrough_excludes_image_gen_models(monkeypatch, capsys):
+    # Patch persist at the call site — without this, configure() on a
+    # Windows test host writes SUBSTRATE_API_KEY to the real
+    # HKCU\Environment hive (no $HOME redirection in scope here).
+    monkeypatch.setattr(
+        "substrate_setup.agents.cursor.persist_substrate_api_key",
+        lambda key: PersistResult(
+            status=PersistStatus.PERSISTED,
+            message="patched in test",
+            path=None,
+        ),
+    )
+
     chat = CatalogEntry(
         id="openai/gpt-5.5", provider="openai",
         display_name="GPT-5.5", description="...",