fix: doctor wizards isatty-gate before prompting (clean JSON stdout on non-TTY)

Advisory follow-up to ef6f924. The guard_wizard_eof EOF-catch let the wizard
call input() first, which echoes the prompt onto stdout before EOFing — so
`teaagent doctor <x> --wizard </dev/null` emitted a classified JSON error
prefixed with "MCP host (default 127.0.0.1): ...", breaking `| jq`. The unit
test used side_effect=EOFError mocks that never write the prompt, so it missed
the pollution; a live check confirmed it.

guard_wizard_eof now isatty-pre-checks: on non-TTY it returns the classified
error BEFORE the wizard body (no prompt echoed, clean JSON), keeping the
EOFError catch as belt-and-suspenders for a TTY that still hits end-of-input.
The five doctor wizards are interactive-only (no value flags), so requiring a
TTY is the correct contract; the four existing wizard tests declare a TTY
(patch sys.stdin.isatty -> True) — the interactive path they exercise — with
the same assertions, no test weakened. setup stays clean via its existing
cannot_prompt gate (verified).

Live: doctor mcp/providers/model --wizard </dev/null -> clean classified JSON.

Gate: governance-gap (clean machine-readable error contract; AGENTS.md: tool errors must be actionable and classified)
Constraint: isatty pre-check for doctor wizards only; setup/init unchanged; 4 existing tests declare the interactive precondition, no assertion removed
Tested: full suite 6745 passed / 6 failed via sharded xdist (same 6 = 4 pre-existing + 2 xdist-only; zero new); 11 targeted doctor tests; live </dev/null cleanliness on 3 wizards; ruff/mypy clean
Not-tested: the 4 pre-existing failures (prior-session debt, diagnosed for owner triage)
Confidence: high
Action: G-P2-19
Roadmap-Status: unchanged

Author: johnteee

teaagent/cli/_handlers/_doctor/_wizard_io.py

@@ -1,40 +1,53 @@
-"""Shared EOF guard for ``teaagent doctor ... --wizard`` flows."""
+"""Shared interactive-input guard for ``teaagent doctor ... --wizard`` flows."""
 
 from __future__ import annotations
 
 import functools
+import sys
 from typing import Any, Callable
 
 from .sanitize import print_json
 
 
+def _classified_no_tty(wizard: str) -> None:
+    print_json(
+        {
+            'ok': False,
+            'error': (
+                f'{wizard} needs interactive input; run it in a terminal, or '
+                'use the non-wizard commands/flags to configure without prompts'
+            ),
+        }
+    )
+
+
 def guard_wizard_eof(
     wizard: str,
 ) -> Callable[[Callable[[Any], int]], Callable[[Any], int]]:
-    """Wrap a doctor wizard so exhausted stdin fails cleanly, not with a crash.
-
-    The wizards prompt with ``input()``/``getpass``. On ``</dev/null`` or when
-    piped answers run out, those raise ``EOFError``, which previously surfaced
-    as the generic ``Unexpected error`` (the same first-run crash class removed
-    for ``init``/``setup`` in G23/G38). Return a classified error instead;
-    provided/piped answers still work while they last.
+    """Guard a doctor wizard against non-interactive stdin.
+
+    The wizards prompt with ``input()``/``getpass``, which write the prompt to
+    stdout. The wizard's own result is JSON on stdout, so on a non-TTY stdin we
+    must not even *start* prompting — otherwise the echoed prompt corrupts the
+    JSON (and the read would ``EOFError`` into the generic ``Unexpected error``,
+    the first-run crash class removed for ``init``/``setup`` in G23/G38).
+
+    So fail fast with a classified error *before* the wizard body when stdin is
+    not a TTY (clean JSON, no prompt echoed), and keep an ``EOFError`` catch as a
+    belt-and-suspenders for an interactive session that still hits end-of-input
+    (e.g. Ctrl-D).
     """
 
     def decorator(fn: Callable[[Any], int]) -> Callable[[Any], int]:
         @functools.wraps(fn)
         def wrapper(args: Any) -> int:
+            if not sys.stdin.isatty():
+                _classified_no_tty(wizard)
+                return 1
             try:
                 return fn(args)
             except EOFError:
-                print_json(
-                    {
-                        'ok': False,
-                        'error': (
-                            f'{wizard} needs interactive input; run it in a '
-                            'terminal or pipe answers to its prompts'
-                        ),
-                    }
-                )
+                _classified_no_tty(wizard)
                 return 1
 
         return wrapper

tests/test_cli.py

@@ -322,6 +322,7 @@ def test_doctor_model_ok_when_key_set() -> None:
 def test_doctor_model_wizard_uses_keychain_when_prompt_empty() -> None:
     output = io.StringIO()
     with (
+        patch('sys.stdin.isatty', return_value=True),
         patch('teaagent.cli._handlers._doctor.model.getpass.getpass', return_value=''),
         patch('teaagent.cli._handlers._doctor.model.input', return_value=''),
         patch('teaagent.wizard.subprocess.run') as security_run,
@@ -430,6 +431,7 @@ def test_doctor_aigateway_wizard_writes_env() -> None:
         env_path.write_text('export OPENAI_API_KEY=sk-existing\n', encoding='utf-8')
         output = io.StringIO()
         with (
+            patch('sys.stdin.isatty', return_value=True),
             patch(
                 'teaagent.cli._handlers._doctor.model.input',
                 side_effect=['acct123', 'gw123', 'y'],
@@ -465,6 +467,7 @@ def test_doctor_aigateway_wizard_writes_compat_base_url() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         output = io.StringIO()
         with (
+            patch('sys.stdin.isatty', return_value=True),
             patch(
                 'teaagent.cli._handlers._doctor.model.input',
                 side_effect=['acct123', 'gw123', 'n'],
@@ -502,6 +505,7 @@ def test_doctor_aigateway_wizard_writes_compat_base_url() -> None:
 def test_doctor_aigateway_wizard_reads_keychain_token_when_input_empty() -> None:
     output = io.StringIO()
     with (
+        patch('sys.stdin.isatty', return_value=True),
         patch(
             'teaagent.cli._handlers._doctor.model.input',
             side_effect=['acct123', 'gw123', 'n'],

tests/test_dogfood_doctor_wizard_tty_g38_twin.py

@@ -1,14 +1,16 @@
 # test-type: behavior
-"""G38 twin: `doctor ... --wizard` must not crash on exhausted stdin.
+"""G38 twin: `doctor ... --wizard` must not crash or pollute stdout on non-TTY.
 
-The five doctor wizards prompt with ``input()``/``getpass``. On piped/headless
-stdin those raised ``EOFError`` and surfaced as the generic ``Unexpected
-error`` (rc 1, empty/opaque message) — the same first-run crash class removed
-for ``init``/``setup`` in G23/G38, and reachable straight from ``init``'s own
+The five doctor wizards prompt with ``input()``/``getpass``, which echo the
+prompt to stdout — and the wizard's own result is JSON on stdout. On piped or
+headless stdin those reads previously ``EOFError``ed into the generic
+``Unexpected error`` (rc 1) — the same first-run crash class removed for
+``init``/``setup`` in G23/G38, and reachable straight from ``init``'s own
 ``next_steps`` (``teaagent doctor mcp --wizard``). Each wizard must now fail
-fast with a classified ``{"ok": false, "error": ...}``. Provided/piped answers
-still work (the guard only catches EOF), so the existing wizard tests that mock
-``input``/``getpass`` keep passing.
+fast with a classified ``{"ok": false, "error": ...}`` *before* prompting, so
+the JSON stdout stays clean. Provided input on a real TTY still works, so the
+existing wizard tests (which declare a TTY and mock ``input``/``getpass``) keep
+passing.
 """
 
 from __future__ import annotations
@@ -36,52 +38,47 @@
     ids=['mcp', 'project', 'providers', 'aigateway', 'model'],
 )
 def test_doctor_wizard_non_tty_is_classified_error(argv: list[str], tmp_path) -> None:
-    """Each wizard on exhausted stdin -> rc 1 + classified error, never a crash."""
+    """Non-TTY -> rc 1 + clean classified JSON, no prompt echoed, no crash."""
     output = io.StringIO()
-    with (
-        patch('teaagent.cli._handlers._doctor.model.input', side_effect=EOFError),
-        patch('teaagent.cli._handlers._doctor.project.input', side_effect=EOFError),
-        patch('getpass.getpass', side_effect=EOFError),
-        redirect_stdout(output),
-    ):
+    with patch('sys.stdin.isatty', return_value=False), redirect_stdout(output):
         exit_code = main([*argv, '--root', str(tmp_path)])
 
     assert exit_code == 1
     raw = output.getvalue()
     assert 'Unexpected error' not in raw
+    # The classified error must be the whole of stdout — no echoed prompt prefix.
     payload = json.loads(raw)
     assert payload['ok'] is False
     assert 'interactive' in payload['error']
 
 
 def test_require_wizard_tty_allows_a_tty() -> None:
-    """Happy path passes through unchanged, no output.
+    """Happy path passes through unchanged on a TTY, with no added output.
 
     Successor to the removed ``require_wizard_tty`` isatty check: the wizard
     guard is now the ``guard_wizard_eof`` decorator, which must leave a
-    successful (non-EOF) call untouched — the same "allowed path is not
-    blocked" guarantee, now covering provided/piped input, not just a TTY.
+    successful call on an interactive stdin untouched.
     """
     output = io.StringIO()
 
     @guard_wizard_eof('teaagent doctor demo --wizard')
     def _ok(_args: object) -> int:
         return 0
 
-    with redirect_stdout(output):
+    with patch('sys.stdin.isatty', return_value=True), redirect_stdout(output):
         assert _ok(object()) == 0
     assert output.getvalue() == ''
 
 
 def test_guard_wizard_eof_converts_eof_to_classified_error() -> None:
-    """An EOFError inside the wizard becomes a classified error and rc 1."""
+    """On a TTY that still hits end-of-input, EOFError -> classified error, rc 1."""
     output = io.StringIO()
 
     @guard_wizard_eof('teaagent doctor demo --wizard')
     def _boom(_args: object) -> int:
         raise EOFError
 
-    with redirect_stdout(output):
+    with patch('sys.stdin.isatty', return_value=True), redirect_stdout(output):
         rc = _boom(object())
 
     assert rc == 1