fix(setup): disclose where an existing API key came from

When the wizard found an API key, it said "found existing X. Use it?"
without naming the source. A user whose shell had OPENROUTER_API_KEY
exported thought the wizard was hallucinating a key — they had no
such entry in .env and didn't remember exporting one. Trust damaged,
and there was no clear path to fix it short of reading the code.

Changes
  - _mask_key(): shows prefix + last 4 chars only, hides the middle,
    so the user can recognise which key the wizard latched onto
    without the key being visible in output.
  - _resolve_api_key(): names the source explicitly — "from shell
    environment" or "from the .env file in this workspace" — and
    shows the masked preview every time an existing key is found.
  - When the shell has the key exported AND the user says "no, use
    a different one", warn that shell env takes precedence over
    .env at runtime and show the exact command to unset it
    (POSIX + PowerShell variants).
  - Non-interactive / quickstart paths also print the source now
    so CI logs are legible.

Tests (11 new, 264 total)
  - TestMaskKey: prefix preservation, last-4 exposure, middle
    redaction, short-key / empty-key handling.
  - TestKeySourceAttribution: shell-only case, .env-only case,
    both-present precedence (shell wins), no-key-anywhere case,
    shell-overrides warning presence + unset command presence.
  - TestNonInteractiveReuse: shell + .env reuse messages both
    name the source and show the masked preview.

All 253 tests pass (1 skipped for Windows symlink rights).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NikitasT2003

src/thesis_agent/cli.py

@@ -395,6 +395,24 @@ def _resolve_provider(
     )
 
 
+def _mask_key(key: str) -> str:
+    """Show the shape of a key without leaking it.
+
+    Preserves the recognisable prefix (e.g. `sk-or-`, `sk-ant-`) and the last
+    4 characters, hiding the middle. `sk-or-abc…wxyz`. For unusually short
+    keys we just print the length.
+    """
+    k = (key or "").strip()
+    if not k:
+        return "<empty>"
+    if len(k) < 12:
+        return f"<{len(k)} chars>"
+    # Prefix runs up to the second dash if present, otherwise first 6 chars.
+    prefix_end = k.find("-", k.find("-") + 1)
+    prefix = k[: prefix_end + 1] if 0 < prefix_end < 15 else k[:6]
+    return f"{prefix}…{k[-4:]}"
+
+
 def _resolve_api_key(
     *,
     info: dict,
@@ -406,6 +424,8 @@ def _resolve_api_key(
     """Return a key, or None if the user chose to skip.
 
     Precedence: --api-key flag > shell env > .env > interactive prompt (with retry).
+    Always tells the user *where* an existing key came from, and shows a
+    masked preview so they can recognise it before reusing.
     """
     import questionary
 
@@ -414,26 +434,63 @@ def _resolve_api_key(
 
     shell_key = (os.environ.get(info["key_env"]) or "").strip() or None
     env_key = _read_env_var(info["key_env"])
-    existing = shell_key or env_key
+
+    # Source attribution: shell env wins at runtime (it overrides .env when
+    # the agent boots via python-dotenv), so honour that precedence here too.
+    if shell_key:
+        existing = shell_key
+        source = "shell environment"
+        hint = (
+            "Your shell has this variable exported (likely from your profile "
+            "or a parent process). It will override any value in .env."
+        )
+    elif env_key:
+        existing = env_key
+        source = "the .env file in this workspace"
+        hint = ""
+    else:
+        existing = None
+        source = ""
+        hint = ""
 
     if existing and not force:
-        # Non-interactive or quickstart: reuse silently.
+        preview = _mask_key(existing)
+        # Non-interactive or quickstart: still announce the source + preview.
         if non_interactive or quickstart:
-            console.print(f"  [dim]reusing existing {info['key_env']} from shell/.env[/]")
+            console.print(
+                f"  [dim]reusing {info['key_env']} [cyan]{preview}[/] "
+                f"from {source}[/]"
+            )
             return existing
+
+        console.print(f"  found {info['key_env']}  [cyan]{preview}[/]  [dim](from {source})[/]")
+        if hint:
+            console.print(f"  [dim]{hint}[/]")
         try:
             use_existing = _ask(
                 questionary.confirm,
-                f"Found an existing {info['key_env']}. Use it?",
+                "Use this key?",
                 default=True,
             )
         except _Cancelled:
             raise
         if use_existing:
             console.print("  [green]reusing existing key.[/]")
             return existing
-        # Clear transition so the user sees the flow moved on.
-        console.print("  [dim]ok — enter a new key.[/]\n")
+        # User said No. Warn them about shell-env precedence before taking a new key.
+        if shell_key:
+            console.print(
+                "  [yellow]note:[/] your shell env has "
+                f"[cyan]{info['key_env']}[/] exported. Any new key you paste "
+                "will be written to [cyan].env[/], but the shell env will "
+                "still take precedence until you unset it."
+            )
+            console.print(
+                f"    to unset:  [cyan]unset {info['key_env']}[/]  "
+                f"(bash/zsh)  or  [cyan]Remove-Item Env:{info['key_env']}[/]  (PowerShell)\n"
+            )
+        else:
+            console.print("  [dim]ok — enter a new key.[/]\n")
 
     if non_interactive:
         console.print(f"[red]no {info['key_env']} provided (required for --non-interactive)[/]")

tests/test_wizard_key_source.py

@@ -0,0 +1,242 @@
+"""Wizard must be honest about where an existing key came from.
+
+Context: a user reported the wizard finding an OpenRouter key they were sure
+they hadn't set. Investigation showed their shell had `OPENROUTER_API_KEY`
+exported from a parent process. The wizard was correct to detect it, but its
+output did not distinguish shell env from `.env`, making the key look like a
+phantom. These tests lock in the fix: the wizard names the source and shows
+a masked preview.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+from typer.testing import CliRunner
+
+from thesis_agent import cli
+
+runner = CliRunner()
+
+
+class _Prompt:
+    def __init__(self, answers: list[Any]):
+        self._answers = answers
+
+    def ask(self):
+        if not self._answers:
+            raise AssertionError("script exhausted")
+        a = self._answers.pop(0)
+        if isinstance(a, BaseException):
+            raise a
+        return a
+
+
+class _FakeChoice:
+    def __init__(self, label: str, value: Any = None):
+        self.title = label
+        self.value = value if value is not None else label
+
+    def __eq__(self, other):
+        return isinstance(other, _FakeChoice) and self.value == other.value
+
+    def __hash__(self):
+        return hash(self.value)
+
+
+class _FakeQuestionary:
+    Choice = _FakeChoice
+
+    def __init__(self, script: list[Any]):
+        self._script = script
+
+    def _n(self):
+        return _Prompt([self._script.pop(0)])
+
+    def select(self, *a, **k):
+        return self._n()
+
+    def confirm(self, *a, **k):
+        return self._n()
+
+    def password(self, *a, **k):
+        return self._n()
+
+    def text(self, *a, **k):
+        return self._n()
+
+
+@pytest.fixture
+def ws(tmp_path: Path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    for v in (
+        "THESIS_PROVIDER",
+        "ANTHROPIC_API_KEY",
+        "OPENROUTER_API_KEY",
+        "OPENROUTER_BASE_URL",
+        "OPENROUTER_SITE_URL",
+        "OPENROUTER_SITE_NAME",
+    ):
+        monkeypatch.delenv(v, raising=False)
+    monkeypatch.setattr(cli, "_validate_key", lambda *a, **kw: (True, "ok"))
+    monkeypatch.setattr(cli, "_copy_examples", lambda: 0)
+    return tmp_path
+
+
+def _install_fake_q(monkeypatch, script: list[Any]):
+    monkeypatch.setitem(sys.modules, "questionary", _FakeQuestionary(script))
+
+
+# ---------------------------------------------------------------------------
+# _mask_key
+# ---------------------------------------------------------------------------
+
+class TestMaskKey:
+    def test_openrouter_key_preserves_prefix_and_last_four(self):
+        out = cli._mask_key("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")
+        assert out.startswith("sk-or-")
+        assert out.endswith("c264")
+        assert "…" in out
+        # Middle must be masked — the long hex body should not appear
+        assert "71b768574b63558d" not in out
+
+    def test_anthropic_key_preserves_prefix(self):
+        out = cli._mask_key("sk-ant-abcdefghijklmnop")
+        assert out.startswith("sk-ant-")
+        assert out.endswith("mnop")
+        assert "abcdefghij" not in out
+
+    def test_very_short_key_only_reports_length(self):
+        out = cli._mask_key("xyz")
+        assert "xyz" not in out
+        assert "chars" in out
+
+    def test_empty_key(self):
+        assert cli._mask_key("") == "<empty>"
+
+
+# ---------------------------------------------------------------------------
+# Source attribution: shell env vs .env
+# ---------------------------------------------------------------------------
+
+class TestKeySourceAttribution:
+    def test_key_from_shell_env_is_labelled(self, ws: Path, monkeypatch):
+        """When shell env has the key, wizard must say 'shell environment'
+        so the user knows where the phantom key came from."""
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-from-shell-xxxx9999")
+        _install_fake_q(monkeypatch, [
+            "openrouter",   # provider
+            True,           # use existing? → yes
+            False,          # add attribution headers? → no (bool confirm)
+            True,           # create workspace?
+            False,          # copy examples?
+        ])
+        result = runner.invoke(cli.app, ["setup"])
+        assert result.exit_code == 0, result.stdout
+        assert "shell environment" in result.stdout
+        # Masked preview must show — last 4 chars visible, middle hidden
+        assert "9999" in result.stdout
+        assert "v1-from-shell" not in result.stdout  # body masked
+
+    def test_key_from_env_file_is_labelled(self, ws: Path, monkeypatch):
+        """When only .env has the key (no shell env), wizard must say '.env'."""
+        (ws / ".env").write_text(
+            "THESIS_PROVIDER=openrouter\nOPENROUTER_API_KEY=sk-or-v1-in-dotenv-1234\n",
+            encoding="utf-8",
+        )
+        _install_fake_q(monkeypatch, [
+            "openrouter",
+            True,    # use existing
+            False,   # attribution headers
+            True,    # create ws
+            False,   # examples
+        ])
+        result = runner.invoke(cli.app, ["setup"])
+        assert result.exit_code == 0, result.stdout
+        assert ".env" in result.stdout
+        assert "shell environment" not in result.stdout
+        assert "1234" in result.stdout
+        assert "in-dotenv" not in result.stdout
+
+    def test_warns_when_shell_overrides_dotenv(self, ws: Path, monkeypatch):
+        """Critical UX case: user says 'no, use a different key'. If shell
+        still has the old one exported, it will *win* at runtime. Wizard
+        must warn + show how to unset."""
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-stale-aaaa1234")
+        _install_fake_q(monkeypatch, [
+            "openrouter",
+            False,                              # don't reuse — enter fresh
+            "sk-or-v1-fresh-brand-new-bbbb5678",  # password
+            False,                              # attribution headers
+            True, False,
+        ])
+        result = runner.invoke(cli.app, ["setup"])
+        assert result.exit_code == 0, result.stdout
+        # The warning must name the shell + the env var + show how to unset.
+        assert "shell env" in result.stdout.lower()
+        assert "precedence" in result.stdout.lower() or "override" in result.stdout.lower()
+        assert "unset OPENROUTER_API_KEY" in result.stdout or "Remove-Item" in result.stdout
+
+    def test_no_key_anywhere_shows_no_source(self, ws: Path, monkeypatch):
+        _install_fake_q(monkeypatch, [
+            "anthropic",
+            "sk-ant-fresh",
+            True, False,
+        ])
+        result = runner.invoke(cli.app, ["setup"])
+        assert result.exit_code == 0, result.stdout
+        assert "shell environment" not in result.stdout
+        assert "found ANTHROPIC_API_KEY" not in result.stdout
+
+    def test_shell_env_takes_precedence_over_dotenv(self, ws: Path, monkeypatch):
+        """When both are present, shell wins (matches python-dotenv runtime)."""
+        (ws / ".env").write_text(
+            "THESIS_PROVIDER=openrouter\nOPENROUTER_API_KEY=sk-or-v1-in-env-aaaa\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-shell-zzzz1111")
+        _install_fake_q(monkeypatch, [
+            "openrouter",
+            True, False,
+            True, False,
+        ])
+        result = runner.invoke(cli.app, ["setup"])
+        assert result.exit_code == 0, result.stdout
+        # Source must be shell (not .env)
+        assert "shell environment" in result.stdout
+        assert "1111" in result.stdout  # shell key's preview wins
+        assert "aaaa" not in result.stdout  # .env key hidden
+
+
+# ---------------------------------------------------------------------------
+# Non-interactive mode still reuses silently but names the source
+# ---------------------------------------------------------------------------
+
+class TestNonInteractiveReuse:
+    def test_reuse_message_names_shell_env(self, ws: Path, monkeypatch):
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-v1-ci-env-yyyy9999")
+        result = runner.invoke(cli.app, [
+            "setup", "--non-interactive",
+            "--provider", "openrouter",
+            "--skip-validation", "--skip-examples",
+        ])
+        assert result.exit_code == 0, result.stdout
+        assert "shell environment" in result.stdout
+        assert "9999" in result.stdout  # masked preview
+
+    def test_reuse_message_names_env_file(self, ws: Path, monkeypatch):
+        (ws / ".env").write_text(
+            "THESIS_PROVIDER=openrouter\nOPENROUTER_API_KEY=sk-or-v1-persisted-wwww0000\n",
+            encoding="utf-8",
+        )
+        result = runner.invoke(cli.app, [
+            "setup", "--non-interactive",
+            "--provider", "openrouter",
+            "--skip-validation", "--skip-examples",
+        ])
+        assert result.exit_code == 0, result.stdout
+        assert ".env file" in result.stdout or "env file" in result.stdout.lower()
+        assert "0000" in result.stdout