turnloop 0.1.3__tar.gz → 0.1.5__tar.gz

{turnloop-0.1.3 → turnloop-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: turnloop
-Version: 0.1.3
+Version: 0.1.5
 Summary: A local-first agentic coding harness: streaming tool loop, permission gating, context compaction, subagents, and any LLM provider.
 Project-URL: Homepage, https://github.com/Pranesh-2005/turnloop
 Author: Pranesh
@@ -49,7 +49,7 @@ tl experiment run smoke         # a measurement run, offline and free
 
 Four runtime dependencies: `textual`, `pydantic`, `httpx`, `pyyaml`. No vendor
 SDKs, no agent framework — the loop is the point, so the loop is written here.
-~18,000 lines of Python, 255 tests, no network in the default test run.
+~18,000 lines of Python, 290 tests, no network in the default test run.
 
 ---
 
@@ -117,7 +117,7 @@ point.
 Verify:
 
 ```bash
-tl --version                # turnloop 0.1.3
+tl --version                # turnloop 0.1.5
 tl doctor                   # every provider, key presence, shell, context budget
 ```
 
@@ -143,8 +143,14 @@ tl --resume                                 # resume the most recent session
 tl --resume <session-id>                    # resume a specific one
 tl sessions                                 # list recorded sessions
 tl config                                   # merged config + which layer each value came from
+tl config --edit                            # interactive settings editor
+tl mcp                                      # add, edit, enable/disable, remove MCP servers
 ```
 
+`config --edit` and `mcp` are deliberately the only paths that write a settings file,
+and neither is reachable by the model — see
+[Editing configuration](#editing-configuration).
+
 ### Flags
 
 | flag | meaning |
@@ -195,9 +201,10 @@ focus and would otherwise swallow them.
 /compact     summarize conversation now /memory       discovered memory files
 /cost        token and cost accounting  /tools        available tools
 /context     what is filling the window /mcp          MCP server status
-/model       show or change model       /hooks        configured hooks
-/provider    switch provider            /sessions     recorded sessions
-/export      transcript to markdown     /doctor       diagnostics
+/model       show or change model       /mcp add      add an MCP server
+/provider    switch provider            /config       settings editor
+/export      transcript to markdown     /hooks        configured hooks
+/sessions    recorded sessions          /doctor       diagnostics
 /quit        exit
 ```
 
@@ -336,7 +343,18 @@ every segment is allowed.** Without that, `Bash(git *)` grants
 scanner that respects quoting — `shlex` discards operators, so the `rm` comes back
 looking like an argument to `git`. 48 tests cover this file alone.
 
-Ten deny rules ship by default, including `Read(**/.env)`.
+Twelve deny rules ship by default, including `Read(**/.env)` and — since 0.1.4 —
+`Write(**/.turnloop/settings*.json)` and `Edit(**/.turnloop/settings*.json)`. Those two
+close a self-escalation path: settings files set `permission_mode` and
+`permissions.allow`, so a model that could write one could grant itself `bypass` on the
+next launch. Verified against the real engine *in bypass mode*, which is the case that
+matters — deny beats bypass, so the block holds even there.
+
+It is a guardrail, not a sandbox, and the boundary is worth being precise about. `Write`
+and `Edit` are blocked; **`Bash` is not**, so a shell redirect reaches the same file.
+Closing that properly needs a path guard below the tool layer rather than more patterns.
+In `default` mode Bash asks a human first, so this only bites under `bypass` — which is
+already the mode that means "I accept the consequences."
 
 ### Context compaction
 
@@ -851,11 +869,34 @@ and through session JSONL, so a `--resume`d conversation does not hit the same w
 check, and anyone who pointed 0.1.2 at Gemini got one working tool call and then a
 400. Fixed in 0.1.3.
 
-**The lesson, four times over in one project:** an 84-run sweep failing while printing
+### `NoActiveWorker`: 283 green tests and a crash on the first keystroke
+
+The config UI shipped with tests covering `/config` — they asserted that dispatching it
+returned `open_screen="config"`. All 283 passed. Typing `/config` in the actual TUI
+raised `NoActiveWorker: push_screen must be run from a worker`.
+
+Textual's `push_screen_wait` blocks the calling coroutine until the screen is dismissed,
+so it must run inside a worker; called from the message pump it would deadlock the pump
+it is waiting on, and Textual refuses rather than hanging. `_handle_command` runs on the
+pump. So does Textual's action dispatch, which meant the same defect existed at four
+call sites, not the one in the traceback — including the provider form reachable from
+`tl config --edit`, a path the crash report never touched.
+
+The correct pattern was eleven lines away in the same file: `_permission_worker` is
+`@work`-decorated, which is exactly why *its* `push_screen_wait` works.
+
+Two things this cost, both worth stating. The tests verified the layer *below* the bug —
+that the command produced the right instruction, never that the app could carry it out.
+And **0.1.4 shipped this way**, so `pip install turnloop==0.1.4` crashes on `/config`.
+Fixed in 0.1.5. The tests now drive a real app through Textual's `run_test()` pilot and
+fail if the decorators are removed.
+
+**The lesson, five times over in one project:** an 84-run sweep failing while printing
 a tidy report of zeros; a tool returning empty with `ok: true`; a sweep sitting at
 10/18 doing nothing for 25 minutes; an adapter passing its live test and failing on
-the turn the test never made. Each was caught only by looking past the summary line —
-and the last one only by using the thing instead of testing it.
+the turn the test never made; a feature with green tests that crashed on its first
+keystroke. Each was caught only by looking past the summary line — and the last two
+only by using the thing instead of testing it.
 
 ---
 
@@ -889,7 +930,7 @@ one-line edit in a CRLF checkout does not produce a whole-file diff.
 ## Testing
 
 ```bash
-pytest                    # 255 tests, no network
+pytest                    # 290 tests, no network
 ruff check turnloop
 mypy turnloop
 ```
@@ -901,12 +942,14 @@ mypy turnloop
 | `test_providers.py` | 35 | adapters vs recorded `.sse`, image blocks, thought signatures |
 | `test_tools_files.py` | 28 | Read/Write/Edit/Glob/Grep, encodings, newlines, image detection |
 | `test_loop.py` | 20 | streaming, truncation, iteration cap |
-| `test_hooks_mcp_commands.py` | 20 | lifecycle hooks, MCP client, slash commands |
+| `test_hooks_mcp_commands.py` | 23 | lifecycle hooks, MCP client, slash commands |
 | `test_config.py` | 21 | layering, env overrides, presets, narrow-console guard |
 | `test_compaction.py` | 16 | three tiers, tool_use/tool_result invariant |
 | `test_bash.py` | 14 | shell selection, process-tree kill |
+| `test_configio.py` | 15 | minimal-diff writes, atomic save, secret-bearing MCP targets, the settings deny rules |
+| `test_config_screen.py` | 10 | provider form validation, caps derivation, env indicator leaks |
 | `test_websearch.py` | 9 | HTML parsing, backend selection, truncation, failure modes |
-| `test_tui.py` | 8 | Textual snapshots |
+| `test_tui.py` | 15 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
 
 `conftest.py` monkeypatches httpx's transport to raise unless a test is marked
 `live` — **network is off at the transport layer**, so a forgotten real call fails
@@ -957,6 +1000,87 @@ Shell expansion inside a command template (`` !`cmd` ``) goes through the permis
 engine like any other Bash call. A markdown file in a repository is not trusted input
 just because it is on disk.
 
+### Editing configuration
+
+`tl config --edit` edits the provider table, permission mode, tool verbosity, iteration
+cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers. The
+same screens open inside a running session as `/config` and `/mcp add`.
+
+**Adding a provider** is a form for `kind`, `model`, `base_url`, and `api_key_env`, with
+a live ✓/✗ showing whether that environment variable is currently set. Capabilities are
+re-derived from `preset_for(model)` on every save, mirroring what `load_settings` does
+for `--model` — without that, a provider added through the UI keeps the previous model's
+context window and pricing, and `doctor`'s context-budget line quietly lies. An
+`openai_compat` provider without a `base_url` is refused by the form, because
+`load_settings` would otherwise raise on the *next* launch, turning a typo into a CLI
+that will not start.
+
+Four further properties are structural rather than cosmetic:
+
+**Only the diff is written.** Neither screen dumps the settings model. It writes the
+difference against the packaged defaults, merged into whatever the file already holds.
+Round-tripping the full model would freeze today's deny list and provider table into
+your file permanently, so a future security default could never reach you.
+
+**Writes are atomic and validated.** The edited settings round-trip through
+`Settings.model_validate` before anything touches disk, then land via a temp file and
+`os.replace`. A malformed settings file makes `load_settings` raise and the CLI exit 2 —
+failing closed is right, but only if we never cause it ourselves.
+
+**Secrets are named, never stored.** Provider credentials are edited as the env var
+*name*, and the written config has an `api_key_env` key and no `api_key` value at all —
+a config UI with a "paste your key here" box writes secrets into a JSON file that gets
+committed, which is how keys leak. The ✓/✗ indicator reports the name and a boolean,
+never the value, a prefix, or a length. MCP `env` values are literal by protocol necessity, so a server carrying any is
+forced to `settings.local.json` and refused a shared file, and the screen creates
+`.turnloop/.gitignore` before writing — otherwise a secret-bearing file can be committed
+before the first session ever runs.
+
+**No agent-reachable route writes settings.** No tool and no hook mutates a settings
+file — which is what makes the deny rules above meaningful instead of decorative.
+`/config` and `/mcp add` are slash commands, and that is safe for a specific reason worth
+stating: `dispatch_command` has exactly one caller, reached from the prompt Input's
+`on_input_submitted`. The model emits tool calls, not typed input, so it cannot reach
+that path. The property lives in the dispatch path rather than in the commands, so a
+future refactor that routes model output through `dispatch_command` would break it
+silently — there is a comment there saying so.
+
+**In-session saves reload only what is safe to reload.** `permission_mode`,
+`permissions`, `max_iterations` and `tool_verbosity` are read from the live `Settings`
+and `PermissionEngine`, so they take effect immediately. `provider`, `providers`,
+`search` and `include_memory` are baked into objects built once at agent construction,
+so the confirmation names them as needing a restart. Reporting "saved" while the old
+permission mode is still being enforced would be worse than saying nothing.
+
+One honest gap: removing a server deletes it from the one file you chose. `deep_merge`
+has no tombstone, so a server also defined in a higher layer stays effective. The screen
+says so rather than pretending otherwise.
+
+### MCP servers are a trust decision
+
+Adding an MCP server is the same class of decision as `npm install`, and turnloop cannot
+check it for you. Two specific reasons, both inherent to the protocol rather than to this
+implementation:
+
+**A stdio server is a program you agreed to run.** `command` and `args` are spawned as a
+child process at every launch, with your full user privileges and any `env` you set. The
+add form states this and requires an explicit confirmation, because a text field labelled
+"command" does not otherwise read like "execute this forever."
+
+**Tool descriptions are untrusted text that enters the model's context.** A server
+advertises its own names and descriptions, and those go into the system prompt verbatim.
+A hostile or compromised server can put instructions there. Nothing in the protocol
+authenticates that text.
+
+What turnloop does about it, which is containment rather than prevention: MCP tools are
+`read_only = False` unconditionally (`mcp/adapter.py`), because the protocol has no
+read-only annotation worth trusting — so they always prompt in `default` mode and are
+refused outright in `plan` mode. A dead or misbehaving server degrades to "that tool is
+unavailable" and never blocks the loop. Connections are lazy and every call is bounded.
+
+None of that helps if you install a server that does exactly what it says. Read what you
+add.
+
 ---
 
 ## Limitations

{turnloop-0.1.3 → turnloop-0.1.5}/README.md

@@ -20,7 +20,7 @@ tl experiment run smoke         # a measurement run, offline and free
 
 Four runtime dependencies: `textual`, `pydantic`, `httpx`, `pyyaml`. No vendor
 SDKs, no agent framework — the loop is the point, so the loop is written here.
-~18,000 lines of Python, 255 tests, no network in the default test run.
+~18,000 lines of Python, 290 tests, no network in the default test run.
 
 ---
 
@@ -88,7 +88,7 @@ point.
 Verify:
 
 ```bash
-tl --version                # turnloop 0.1.3
+tl --version                # turnloop 0.1.5
 tl doctor                   # every provider, key presence, shell, context budget
 ```
 
@@ -114,8 +114,14 @@ tl --resume                                 # resume the most recent session
 tl --resume <session-id>                    # resume a specific one
 tl sessions                                 # list recorded sessions
 tl config                                   # merged config + which layer each value came from
+tl config --edit                            # interactive settings editor
+tl mcp                                      # add, edit, enable/disable, remove MCP servers
 ```
 
+`config --edit` and `mcp` are deliberately the only paths that write a settings file,
+and neither is reachable by the model — see
+[Editing configuration](#editing-configuration).
+
 ### Flags
 
 | flag | meaning |
@@ -166,9 +172,10 @@ focus and would otherwise swallow them.
 /compact     summarize conversation now /memory       discovered memory files
 /cost        token and cost accounting  /tools        available tools
 /context     what is filling the window /mcp          MCP server status
-/model       show or change model       /hooks        configured hooks
-/provider    switch provider            /sessions     recorded sessions
-/export      transcript to markdown     /doctor       diagnostics
+/model       show or change model       /mcp add      add an MCP server
+/provider    switch provider            /config       settings editor
+/export      transcript to markdown     /hooks        configured hooks
+/sessions    recorded sessions          /doctor       diagnostics
 /quit        exit
 ```
 
@@ -307,7 +314,18 @@ every segment is allowed.** Without that, `Bash(git *)` grants
 scanner that respects quoting — `shlex` discards operators, so the `rm` comes back
 looking like an argument to `git`. 48 tests cover this file alone.
 
-Ten deny rules ship by default, including `Read(**/.env)`.
+Twelve deny rules ship by default, including `Read(**/.env)` and — since 0.1.4 —
+`Write(**/.turnloop/settings*.json)` and `Edit(**/.turnloop/settings*.json)`. Those two
+close a self-escalation path: settings files set `permission_mode` and
+`permissions.allow`, so a model that could write one could grant itself `bypass` on the
+next launch. Verified against the real engine *in bypass mode*, which is the case that
+matters — deny beats bypass, so the block holds even there.
+
+It is a guardrail, not a sandbox, and the boundary is worth being precise about. `Write`
+and `Edit` are blocked; **`Bash` is not**, so a shell redirect reaches the same file.
+Closing that properly needs a path guard below the tool layer rather than more patterns.
+In `default` mode Bash asks a human first, so this only bites under `bypass` — which is
+already the mode that means "I accept the consequences."
 
 ### Context compaction
 
@@ -822,11 +840,34 @@ and through session JSONL, so a `--resume`d conversation does not hit the same w
 check, and anyone who pointed 0.1.2 at Gemini got one working tool call and then a
 400. Fixed in 0.1.3.
 
-**The lesson, four times over in one project:** an 84-run sweep failing while printing
+### `NoActiveWorker`: 283 green tests and a crash on the first keystroke
+
+The config UI shipped with tests covering `/config` — they asserted that dispatching it
+returned `open_screen="config"`. All 283 passed. Typing `/config` in the actual TUI
+raised `NoActiveWorker: push_screen must be run from a worker`.
+
+Textual's `push_screen_wait` blocks the calling coroutine until the screen is dismissed,
+so it must run inside a worker; called from the message pump it would deadlock the pump
+it is waiting on, and Textual refuses rather than hanging. `_handle_command` runs on the
+pump. So does Textual's action dispatch, which meant the same defect existed at four
+call sites, not the one in the traceback — including the provider form reachable from
+`tl config --edit`, a path the crash report never touched.
+
+The correct pattern was eleven lines away in the same file: `_permission_worker` is
+`@work`-decorated, which is exactly why *its* `push_screen_wait` works.
+
+Two things this cost, both worth stating. The tests verified the layer *below* the bug —
+that the command produced the right instruction, never that the app could carry it out.
+And **0.1.4 shipped this way**, so `pip install turnloop==0.1.4` crashes on `/config`.
+Fixed in 0.1.5. The tests now drive a real app through Textual's `run_test()` pilot and
+fail if the decorators are removed.
+
+**The lesson, five times over in one project:** an 84-run sweep failing while printing
 a tidy report of zeros; a tool returning empty with `ok: true`; a sweep sitting at
 10/18 doing nothing for 25 minutes; an adapter passing its live test and failing on
-the turn the test never made. Each was caught only by looking past the summary line —
-and the last one only by using the thing instead of testing it.
+the turn the test never made; a feature with green tests that crashed on its first
+keystroke. Each was caught only by looking past the summary line — and the last two
+only by using the thing instead of testing it.
 
 ---
 
@@ -860,7 +901,7 @@ one-line edit in a CRLF checkout does not produce a whole-file diff.
 ## Testing
 
 ```bash
-pytest                    # 255 tests, no network
+pytest                    # 290 tests, no network
 ruff check turnloop
 mypy turnloop
 ```
@@ -872,12 +913,14 @@ mypy turnloop
 | `test_providers.py` | 35 | adapters vs recorded `.sse`, image blocks, thought signatures |
 | `test_tools_files.py` | 28 | Read/Write/Edit/Glob/Grep, encodings, newlines, image detection |
 | `test_loop.py` | 20 | streaming, truncation, iteration cap |
-| `test_hooks_mcp_commands.py` | 20 | lifecycle hooks, MCP client, slash commands |
+| `test_hooks_mcp_commands.py` | 23 | lifecycle hooks, MCP client, slash commands |
 | `test_config.py` | 21 | layering, env overrides, presets, narrow-console guard |
 | `test_compaction.py` | 16 | three tiers, tool_use/tool_result invariant |
 | `test_bash.py` | 14 | shell selection, process-tree kill |
+| `test_configio.py` | 15 | minimal-diff writes, atomic save, secret-bearing MCP targets, the settings deny rules |
+| `test_config_screen.py` | 10 | provider form validation, caps derivation, env indicator leaks |
 | `test_websearch.py` | 9 | HTML parsing, backend selection, truncation, failure modes |
-| `test_tui.py` | 8 | Textual snapshots |
+| `test_tui.py` | 15 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
 
 `conftest.py` monkeypatches httpx's transport to raise unless a test is marked
 `live` — **network is off at the transport layer**, so a forgotten real call fails
@@ -928,6 +971,87 @@ Shell expansion inside a command template (`` !`cmd` ``) goes through the permis
 engine like any other Bash call. A markdown file in a repository is not trusted input
 just because it is on disk.
 
+### Editing configuration
+
+`tl config --edit` edits the provider table, permission mode, tool verbosity, iteration
+cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers. The
+same screens open inside a running session as `/config` and `/mcp add`.
+
+**Adding a provider** is a form for `kind`, `model`, `base_url`, and `api_key_env`, with
+a live ✓/✗ showing whether that environment variable is currently set. Capabilities are
+re-derived from `preset_for(model)` on every save, mirroring what `load_settings` does
+for `--model` — without that, a provider added through the UI keeps the previous model's
+context window and pricing, and `doctor`'s context-budget line quietly lies. An
+`openai_compat` provider without a `base_url` is refused by the form, because
+`load_settings` would otherwise raise on the *next* launch, turning a typo into a CLI
+that will not start.
+
+Four further properties are structural rather than cosmetic:
+
+**Only the diff is written.** Neither screen dumps the settings model. It writes the
+difference against the packaged defaults, merged into whatever the file already holds.
+Round-tripping the full model would freeze today's deny list and provider table into
+your file permanently, so a future security default could never reach you.
+
+**Writes are atomic and validated.** The edited settings round-trip through
+`Settings.model_validate` before anything touches disk, then land via a temp file and
+`os.replace`. A malformed settings file makes `load_settings` raise and the CLI exit 2 —
+failing closed is right, but only if we never cause it ourselves.
+
+**Secrets are named, never stored.** Provider credentials are edited as the env var
+*name*, and the written config has an `api_key_env` key and no `api_key` value at all —
+a config UI with a "paste your key here" box writes secrets into a JSON file that gets
+committed, which is how keys leak. The ✓/✗ indicator reports the name and a boolean,
+never the value, a prefix, or a length. MCP `env` values are literal by protocol necessity, so a server carrying any is
+forced to `settings.local.json` and refused a shared file, and the screen creates
+`.turnloop/.gitignore` before writing — otherwise a secret-bearing file can be committed
+before the first session ever runs.
+
+**No agent-reachable route writes settings.** No tool and no hook mutates a settings
+file — which is what makes the deny rules above meaningful instead of decorative.
+`/config` and `/mcp add` are slash commands, and that is safe for a specific reason worth
+stating: `dispatch_command` has exactly one caller, reached from the prompt Input's
+`on_input_submitted`. The model emits tool calls, not typed input, so it cannot reach
+that path. The property lives in the dispatch path rather than in the commands, so a
+future refactor that routes model output through `dispatch_command` would break it
+silently — there is a comment there saying so.
+
+**In-session saves reload only what is safe to reload.** `permission_mode`,
+`permissions`, `max_iterations` and `tool_verbosity` are read from the live `Settings`
+and `PermissionEngine`, so they take effect immediately. `provider`, `providers`,
+`search` and `include_memory` are baked into objects built once at agent construction,
+so the confirmation names them as needing a restart. Reporting "saved" while the old
+permission mode is still being enforced would be worse than saying nothing.
+
+One honest gap: removing a server deletes it from the one file you chose. `deep_merge`
+has no tombstone, so a server also defined in a higher layer stays effective. The screen
+says so rather than pretending otherwise.
+
+### MCP servers are a trust decision
+
+Adding an MCP server is the same class of decision as `npm install`, and turnloop cannot
+check it for you. Two specific reasons, both inherent to the protocol rather than to this
+implementation:
+
+**A stdio server is a program you agreed to run.** `command` and `args` are spawned as a
+child process at every launch, with your full user privileges and any `env` you set. The
+add form states this and requires an explicit confirmation, because a text field labelled
+"command" does not otherwise read like "execute this forever."
+
+**Tool descriptions are untrusted text that enters the model's context.** A server
+advertises its own names and descriptions, and those go into the system prompt verbatim.
+A hostile or compromised server can put instructions there. Nothing in the protocol
+authenticates that text.
+
+What turnloop does about it, which is containment rather than prevention: MCP tools are
+`read_only = False` unconditionally (`mcp/adapter.py`), because the protocol has no
+read-only annotation worth trusting — so they always prompt in `default` mode and are
+refused outright in `plan` mode. A dead or misbehaving server degrades to "that tool is
+unavailable" and never blocks the loop. Connections are lazy and every call is bounded.
+
+None of that helps if you install a server that does exactly what it says. Read what you
+add.
+
 ---
 
 ## Limitations

{turnloop-0.1.3 → turnloop-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnloop"
-version = "0.1.3"
+version = "0.1.5"
 description = "A local-first agentic coding harness: streaming tool loop, permission gating, context compaction, subagents, and any LLM provider."
 readme = "README.md"
 requires-python = ">=3.11"

turnloop-0.1.5/tests/test_config_screen.py

@@ -0,0 +1,100 @@
+"""Provider-editor pure logic (config_screen.py), tested without spinning up Textual.
+
+`_save()` on `ProviderFormModal` is a thin wrapper around these functions —
+testing them directly is cheaper than driving a pilot and covers exactly the
+validation and caps-derivation rules that matter.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from turnloop.config import load_settings
+from turnloop.errors import ConfigError
+from turnloop.providers.pricing import preset_for
+from turnloop.tui.config_screen import (
+    build_provider_dict,
+    env_status_text,
+    validate_provider_fields,
+    validate_provider_name,
+)
+
+
+def test_env_status_reports_set_and_unset_without_leaking_the_value(monkeypatch):
+    monkeypatch.setenv("TL_TEST_PRESENT_KEY", "super-secret-value")
+    monkeypatch.delenv("TL_TEST_ABSENT_KEY", raising=False)
+
+    present = env_status_text("TL_TEST_PRESENT_KEY")
+    absent = env_status_text("TL_TEST_ABSENT_KEY")
+
+    assert "set" in present and "not set" not in present
+    assert "not set" in absent
+    assert "super-secret-value" not in present
+    assert "super-secret-value" not in repr((present, absent))
+
+
+def test_env_status_blank_name_is_blank():
+    assert env_status_text("") == ""
+
+
+def test_validate_provider_name_rejects_blank_and_non_identifier():
+    assert validate_provider_name("", set(), is_new=True) is not None
+    assert validate_provider_name("has spaces", set(), is_new=True) is not None
+    assert validate_provider_name("fine_name", set(), is_new=True) is None
+    assert validate_provider_name("kebab-ok", set(), is_new=True) is None
+
+
+def test_validate_provider_name_refuses_a_collision_only_when_new():
+    assert validate_provider_name("nvidia", {"nvidia"}, is_new=True) is not None
+    assert validate_provider_name("nvidia", {"nvidia"}, is_new=False) is None
+
+
+def test_openai_compat_without_base_url_is_refused_by_the_form():
+    """The form check exists precisely because `load_settings` raises for the same
+    condition — this documents that the two are testing the same failure."""
+    assert validate_provider_fields("openai_compat", "some-model", None, None) is not None
+    assert validate_provider_fields("openai_compat", "some-model", "https://x", None) is None
+
+
+def test_openai_compat_without_base_url_also_fails_at_load_settings(tmp_path):
+    """The other half of the pair above: confirms the form isn't guarding against
+    a condition load_settings would have tolerated anyway."""
+    (tmp_path / ".turnloop").mkdir()
+    (tmp_path / ".turnloop" / "settings.local.json").write_text(
+        '{"providers": {"broken": {"kind": "openai_compat", "model": "x"}}}',
+        encoding="utf-8",
+    )
+    with pytest.raises(ConfigError, match="base_url"):
+        load_settings(tmp_path)
+
+
+def test_validate_provider_fields_requires_a_model():
+    assert validate_provider_fields("mock", "", None, None) is not None
+
+
+def test_validate_provider_fields_rejects_a_bad_api_key_env_name():
+    assert validate_provider_fields("mock", "m", None, "not a valid name") is not None
+    assert validate_provider_fields("mock", "m", None, "GOOD_NAME") is None
+
+
+def test_build_provider_dict_derives_caps_from_the_new_model_not_the_old_one():
+    """The whole point of gap 1's caps requirement: a provider that switches
+    models must not keep the previous model's context window and pricing."""
+    old = {
+        "kind": "openai_compat", "model": "gpt-4o-mini", "base_url": "https://old",
+        "caps": preset_for("gpt-4o-mini").model_dump(mode="json"),
+    }
+    updated = build_provider_dict(
+        old, kind="anthropic", model="claude-opus-4-5", base_url=None,
+        api_key_env="ANTHROPIC_API_KEY", tool_verbosity=None,
+    )
+
+    assert updated["caps"] == preset_for("claude-opus-4-5").model_dump(mode="json")
+    assert updated["caps"] != old["caps"]
+
+
+def test_build_provider_dict_falls_back_sanely_for_an_unrecognized_model():
+    caps = preset_for("some-model-nobody-has-heard-of")
+    assert caps.max_context == 128_000
+    assert caps.max_output == 8_192
+    assert caps.max_context > 0  # never a silent zero-context provider