soothe-cli 0.11.0__tar.gz → 1.0.0__tar.gz

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: soothe-cli
-Version: 0.11.0
+Version: 1.0.0
 Summary: Soothe CLI client - communicates with daemon via WebSocket
 Project-URL: Homepage, https://github.com/mirasoth/soothe
 Project-URL: Documentation, https://soothe.readthedocs.io
 Project-URL: Repository, https://github.com/mirasoth/soothe
 License: MIT
 Keywords: cli,client,soothe,tui,websocket
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/pyproject.toml

@@ -11,7 +11,7 @@ license = { text = "MIT" }
 requires-python = ">=3.11,<3.14"
 keywords = ["soothe", "cli", "client", "tui", "websocket"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/cli/main.py

@@ -198,10 +198,10 @@ def main(
             help=(
                 "Auto-show the in-flow plan panel while a goal is executing "
                 "and hide it when the goal completes. Ctrl+t toggles "
-                "thereafter. Default: disabled."
+                "thereafter. Default: enabled."
             ),
         ),
-    ] = False,
+    ] = True,
     show_version: Annotated[  # noqa: FBT002
         bool,
         typer.Option("--version", help="Show version and exit."),

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/config/cli_config.py

@@ -33,9 +33,9 @@ class CLIConfig:
     """Markdown appearance preset (``match-app``, ``langchain``, ``standard``, …)."""
 
     # Plan panel visibility preference
-    plan_panel_default_visible: bool = False
+    plan_panel_default_visible: bool = True
     """When True, auto-show the in-flow plan panel while a goal is executing and
-    hide it when the goal completes. Default False (Ctrl+t to open)."""
+    hide it when the goal completes. Default True (Ctrl+t to close)."""
 
     # Output streaming overrides (RFC-614)
     output_streaming_enabled: bool | None = None

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/__init__.py

@@ -1,13 +1,9 @@
 """Public API for the app sub-package."""
 
 from soothe_cli.tui.app._app import SootheApp
-from soothe_cli.tui.app._module_init import (
-    AppResult,
-    TextualSessionState,
-    run_textual_app,
-    run_textual_tui,
-    save_theme_preference,
-)
+from soothe_cli.tui.app._entrypoints import run_textual_app, run_textual_tui
+from soothe_cli.tui.app._theme_prefs import save_theme_preference
+from soothe_cli.tui.app._types import AppResult, TextualSessionState
 
 __all__ = [
     "SootheApp",

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_app.py

@@ -30,13 +30,13 @@ from soothe_cli.tui.app._execution import _ExecutionMixin
 from soothe_cli.tui.app._history import _HistoryMixin
 from soothe_cli.tui.app._messages_mixin import _MessagesMixin
 from soothe_cli.tui.app._model import _ModelMixin
-from soothe_cli.tui.app._module_init import (
+from soothe_cli.tui.app._startup import _StartupMixin
+from soothe_cli.tui.app._theme_prefs import _load_theme_preference
+from soothe_cli.tui.app._types import (
     DeferredAction,
     QueuedMessage,
     TextualSessionState,
-    _load_theme_preference,
 )
-from soothe_cli.tui.app._startup import _StartupMixin
 from soothe_cli.tui.app._ui import _UIMixin
 from soothe_cli.tui.composer_mode import normalize_composer_mode
 from soothe_cli.tui.widgets.chat_input import ChatInput
@@ -486,10 +486,10 @@ class SootheApp(
                 )
                 yield Container(id="messages")
         # In-flow plan panel: sits above the sticky bottom chrome so Ctrl+t
-        # never covers the thinking row or chat input. Stays collapsed by
-        # default; auto-shows while a goal is executing only when
-        # CLIConfig.plan_panel_default_visible is True (--plan-panel).
-        plan_visible = getattr(self._daemon_config, "plan_panel_default_visible", False)
+        # never covers the thinking row or chat input. Auto-shows while a goal
+        # is executing when CLIConfig.plan_panel_default_visible is True
+        # (default); --no-plan-panel disables it.
+        plan_visible = getattr(self._daemon_config, "plan_panel_default_visible", True)
         yield PlanQuickViewOverlay(
             id="plan-quick-view-overlay",
             default_visible=plan_visible,

soothe_cli-1.0.0/src/soothe_cli/tui/app/_clarification.py

@@ -0,0 +1,41 @@
+"""Clarification wire-content formatting for plan-review and tool-approval submits.
+
+Pure utility — no mixin state dependency. Extracted from `_execution.py` to
+keep the execution mixin focused on agent execution and message routing.
+"""
+
+from __future__ import annotations
+
+_PLAN_REVIEW_ACTIONS = frozenset({"Approve", "Reject", "Refine"})
+_TOOL_APPROVAL_ACTIONS = frozenset({"Approve", "Reject", "Edit"})
+
+
+def clarification_wire_content(answers: list[str], *, origin_node: str = "") -> str:
+    """Human-readable turn content for a clarification submit (not a new goal).
+
+    Option-selector actions use a stable `<prefix>: …` header so a dropped
+    `clarification_answer` flag cannot turn a bare action into Pass1 TASK.
+    Plan review → `Plan review:` (Refine carries refinement text in
+    `answers[1]`). Tool approval → `Tool approval:` (Edit carries revised
+    instructions in `answers[1]`). When `origin_node` is empty (legacy
+    callers) the action label alone selects the prefix, preserving the safety
+    net for any selector-origin submit.
+    """
+    non_empty = [a for a in answers if str(a).strip()]
+    if not non_empty:
+        return ""
+    first = str(answers[0]).strip() if answers else ""
+    is_tool_approval = origin_node == "tool_approval"
+    is_selector_action = first in _PLAN_REVIEW_ACTIONS or first in _TOOL_APPROVAL_ACTIONS
+    if is_selector_action:
+        refinement = str(answers[1]).strip() if len(answers) > 1 else ""
+        # Origin-aware prefix; when origin is unknown (legacy caller), default
+        # to "Plan review" to preserve the pre-RFC behavior where the action
+        # label alone selected the plan-review prefix.
+        prefix = "Tool approval" if is_tool_approval else "Plan review"
+        if refinement:
+            return f"{prefix}: {first} — {refinement}"
+        return f"{prefix}: {first}"
+    if len(non_empty) == 1:
+        return non_empty[0]
+    return " | ".join(f"A{i + 1}: {a}" for i, a in enumerate(answers) if str(a).strip())

soothe_cli-1.0.0/src/soothe_cli/tui/app/_entrypoints.py

@@ -0,0 +1,95 @@
+"""App entry points and slash-command URL constants.
+
+`run_textual_app` and `run_textual_tui` are the public async and sync entry
+points for launching the Textual TUI. `_COMMAND_URLS` maps slash-commands
+that just open a browser to their target URLs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Any
+
+from soothe_cli._version import CHANGELOG_URL, DOCS_URL
+from soothe_cli.tui.app._terminal import init_terminal_integration
+from soothe_cli.tui.app._types import AppResult
+
+_COMMAND_URLS: dict[str, str] = {
+    "/changelog": CHANGELOG_URL,
+    "/docs": DOCS_URL,
+    "/feedback": "https://github.com/mirasoth/soothe/issues/new/choose",
+}
+"""Slash-command to URL mapping for commands that just open a browser."""
+
+
+async def run_textual_app(
+    *,
+    daemon_config: Any,  # noqa: ANN401
+    assistant_id: str | None = None,
+    cwd: str | Path | None = None,
+    resume_loop_id: str | None = None,
+    initial_prompt: str | None = None,
+    initial_skill: str | None = None,
+    mcp_server_info: list[dict[str, Any]] | None = None,
+    profile_override: dict[str, Any] | None = None,
+) -> AppResult:
+    """Run the Textual TUI (daemon execution only)."""
+    from soothe_cli.tui.app._app import SootheApp  # deferred to avoid circular import
+
+    # Disable iTerm2 cursor guide before Textual takes over the terminal.
+    # Previously this was an import-time side effect; now explicit.
+    init_terminal_integration()
+
+    app = SootheApp(
+        daemon_config=daemon_config,
+        assistant_id=assistant_id,
+        cwd=cwd,
+        resume_loop_id=resume_loop_id,
+        initial_prompt=initial_prompt,
+        initial_skill=initial_skill,
+        mcp_server_info=mcp_server_info,
+        profile_override=profile_override,
+    )
+    try:
+        await app.run_async()
+    finally:
+        if app._daemon_session is not None:
+            from soothe_cli.runtime.transport.session import TUI_EXIT_HANDSHAKE_TIMEOUT_S
+
+            await app._daemon_session.close(handshake_timeout=TUI_EXIT_HANDSHAKE_TIMEOUT_S)
+
+    return AppResult(
+        return_code=app.return_code or 0,
+        loop_id=app._lc_loop_id,
+        session_stats=app._session_stats,
+        update_available=app._update_available,
+    )
+
+
+def run_textual_tui(
+    config: Any,  # noqa: ANN401
+    resume_loop_id: str | None = None,
+    initial_prompt: str | None = None,
+) -> AppResult:
+    """Launch the Textual TUI with optional loop attachment and initial prompt.
+
+    Args:
+    config: Soothe configuration used for daemon-backed startup.
+    resume_loop_id: Loop id to attach to when starting the TUI
+    initial_prompt: Auto-submit prompt on launch
+    """
+
+    # Caller cwd is forwarded as the loop workspace hint.
+    # Daemon workspace is ephemeral TEMP unless SOOTHE_WORKSPACE env set.
+    cwd = os.getcwd()
+
+    return asyncio.run(
+        run_textual_app(
+            resume_loop_id=resume_loop_id,
+            initial_prompt=initial_prompt,
+            daemon_config=config,
+            cwd=cwd,
+        )
+    )

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_execution.py

@@ -10,7 +10,7 @@ import sys
 import time
 import webbrowser
 from contextlib import suppress
-from typing import Any, Literal
+from typing import Any
 
 from textual.app import ScreenStackError
 from textual.containers import VerticalScroll
@@ -30,11 +30,13 @@ from soothe_cli.cli.execution.daemon_errors import (
 from soothe_cli.display import theme
 from soothe_cli.display.shell_color import shell_subprocess_env, wrap_shell_command_for_color
 from soothe_cli.runtime.state.session_stats import SessionStats
-from soothe_cli.tui.app._module_init import (
-    _COMMAND_URLS,
+from soothe_cli.tui.app._clarification import clarification_wire_content
+from soothe_cli.tui.app._entrypoints import _COMMAND_URLS
+from soothe_cli.tui.app._model_params import _extract_model_params_flag
+from soothe_cli.tui.app._types import (
     DeferredAction,
+    InputMode,
     QueuedMessage,
-    _extract_model_params_flag,
 )
 from soothe_cli.tui.widgets.chat_input import ChatInput
 from soothe_cli.tui.widgets.messages import (
@@ -49,44 +51,8 @@ from soothe_cli.tui.widgets.welcome import WelcomeBanner
 
 _monotonic = time.monotonic
 
-InputMode = Literal["normal", "shell", "command"]
-
 logger = logging.getLogger(__name__)
 
-_PLAN_REVIEW_ACTIONS = frozenset({"Approve", "Reject", "Refine"})
-_TOOL_APPROVAL_ACTIONS = frozenset({"Approve", "Reject", "Edit"})
-
-
-def clarification_wire_content(answers: list[str], *, origin_node: str = "") -> str:
-    """Human-readable turn content for a clarification submit (not a new goal).
-
-    Option-selector actions use a stable `<prefix>: …` header so a dropped
-    `clarification_answer` flag cannot turn a bare action into Pass1 TASK.
-    Plan review → `Plan review:` (Refine carries refinement text in
-    `answers[1]`). Tool approval → `Tool approval:` (Edit carries revised
-    instructions in `answers[1]`). When `origin_node` is empty (legacy
-    callers) the action label alone selects the prefix, preserving the safety
-    net for any selector-origin submit.
-    """
-    non_empty = [a for a in answers if str(a).strip()]
-    if not non_empty:
-        return ""
-    first = str(answers[0]).strip() if answers else ""
-    is_tool_approval = origin_node == "tool_approval"
-    is_selector_action = first in _PLAN_REVIEW_ACTIONS or first in _TOOL_APPROVAL_ACTIONS
-    if is_selector_action:
-        refinement = str(answers[1]).strip() if len(answers) > 1 else ""
-        # Origin-aware prefix; when origin is unknown (legacy caller), default
-        # to "Plan review" to preserve the pre-RFC behavior where the action
-        # label alone selected the plan-review prefix.
-        prefix = "Tool approval" if is_tool_approval else "Plan review"
-        if refinement:
-            return f"{prefix}: {first} — {refinement}"
-        return f"{prefix}: {first}"
-    if len(non_empty) == 1:
-        return non_empty[0]
-    return " | ".join(f"A{i + 1}: {a}" for i, a in enumerate(answers) if str(a).strip())
-
 
 class _ExecutionMixin:
     """Agent execution, message routing, queue, shell commands, and daemon events."""

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_history.py

@@ -11,7 +11,7 @@ from soothe_sdk.display import card_binder as _binder
 from soothe_sdk.display.transcript_types import MessageData
 from textual.content import Content
 
-from soothe_cli.tui.app._module_init import _LoopHistoryPayload
+from soothe_cli.tui.app._types import _LoopHistoryPayload
 from soothe_cli.tui.widgets.messages import AppMessage
 
 logger = logging.getLogger(__name__)

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_messages_mixin.py

@@ -17,11 +17,13 @@ from textual.app import App
 from textual.containers import Container, VerticalScroll
 from textual.css.query import NoMatches
 
-from soothe_cli.tui.app._module_init import (
+from soothe_cli.tui.app._terminal import (
     _ITERM_CURSOR_GUIDE_ON,
+    _write_iterm_escape,
+)
+from soothe_cli.tui.app._types import (
     DeferredAction,
     _LoopHistoryPayload,
-    _write_iterm_escape,
 )
 from soothe_cli.tui.widgets.file_change_preview import FileChangePreviewWidget
 from soothe_cli.tui.widgets.messages import (
@@ -1212,15 +1214,15 @@ class _MessagesMixin:
     def on_app_focus(self) -> None:
         """Restore primary input focus when the terminal regains OS focus.
 
-        When the user opens a link via `webbrowser.open`, OS focus shifts to
-        the browser. On returning to the terminal, Textual fires `AppFocus`
-        (requires a terminal that supports FocusIn events). Re-focusing the
-        primary input keeps it ready for typing — but only when no other
-        focusable widget (e.g., a step card control) currently owns focus, so
-        the user does not lose an in-progress answer to a tab-out and back.
+        Fires when focus returns from an external program (e.g. a browser
+        link). Re-focuses the primary input unless a modal is open, another
+        focusable widget owns focus, or an unsubmitted QA card is active
+        (its own focus guard handles recapture).
         """
         if self.screen.is_modal:
             return
+        if self._has_active_qa_widget():
+            return
         focused = self.focused
         primary = self._primary_text_input()
         if primary is not None:
@@ -1235,15 +1237,12 @@ class _MessagesMixin:
         self._chat_input.focus_input()
 
     def on_click(self, _event: Click) -> None:
-        """Focus the chat input when the click landed on non-focusable chrome.
-
-        Original intent: clicking the dead transcript area should drop the
-        caret back in the prompt. But this handler bubbles for *every* click,
-        so an unconditional refocus also steals focus from inline focusable
-        widgets (e.g., the StructuredAskUserWidget answer field) on the same
-        click that Textual just used to focus them. Skip the refocus whenever
-        the click landed on a focusable widget — Textual's default focus
-        handling already does the right thing there.
+        """Focus the chat input when a click lands on non-focusable chrome.
+
+        Bubbles for every click, so an unconditional refocus would steal
+        focus from inline focusable widgets. Skip when the click target is
+        focusable, a text selection is active, or an unsubmitted QA card is
+        on screen (scrolling to review a plan must not yank focus).
         """
         if not self._chat_input:
             return
@@ -1254,6 +1253,8 @@ class _MessagesMixin:
             return
         if self._click_landed_on_focusable(_event):
             return
+        if self._has_active_qa_widget():
+            return
         self.call_after_refresh(self.focus_primary_input)
 
     def _click_landed_on_focusable(self, event: Click) -> bool:
@@ -1277,6 +1278,14 @@ class _MessagesMixin:
             node = getattr(node, "parent", None)
         return False
 
+    def _has_active_qa_widget(self) -> bool:
+        """Return True when an unsubmitted StructuredAskUserWidget is mounted."""
+        adapter = getattr(self, "_ui_adapter", None)
+        if adapter is None:
+            return False
+        by_step = getattr(adapter, "_clarification_input_by_step", None) or {}
+        return any(not getattr(w, "_submitted", False) for w in by_step.values())
+
     def on_text_selected(self, _event: TextSelected) -> None:
         """Copy selected transcript text on mouse release.
 

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_model.py

@@ -17,9 +17,9 @@ from textual.css.query import NoMatches
 from textual.theme import Theme
 
 from soothe_cli.display import theme
-from soothe_cli.tui.app._module_init import (
+from soothe_cli.tui.app._theme_prefs import save_theme_preference
+from soothe_cli.tui.app._types import (
     DeferredAction,
-    save_theme_preference,
 )
 from soothe_cli.tui.widgets.messages import AppMessage, ErrorMessage
 from soothe_cli.tui.widgets.welcome import WelcomeBanner

soothe_cli-1.0.0/src/soothe_cli/tui/app/_model_params.py

@@ -0,0 +1,97 @@
+"""Parser for the `--model-params` flag in `/model` slash-command arguments."""
+
+from __future__ import annotations
+
+import json
+import shlex
+from typing import Any
+
+
+def _extract_model_params_flag(raw_arg: str) -> tuple[str, dict[str, Any] | None]:
+    """Extract `--model-params` and its JSON value from a `/model` arg string.
+
+    Handles quoted (`'...'` / `"..."`) and bare `{...}` values with balanced
+    braces so that JSON containing spaces works without quoting.
+
+    Note:
+    The bare-brace mode counts `{` / `}` characters without awareness of
+    JSON string contents. Values that contain literal braces inside strings
+    (e.g., `{"stop": "end}here"}`) will mis-parse. Users should quote the
+    value in that case.
+
+    Args:
+    raw_arg: The argument string after `/model `.
+
+    Returns:
+    Tuple of `(remaining_args, parsed_dict | None)`. Returns `None` for the
+    dict when the flag is absent.
+
+    Raises:
+    ValueError: If the value is missing, has unclosed quotes,
+    unbalanced braces, or is not valid JSON.
+    TypeError: If the parsed JSON is not a dict.
+    """
+    flag = "--model-params"
+    idx = raw_arg.find(flag)
+    if idx == -1:
+        return raw_arg, None
+
+    before = raw_arg[:idx].rstrip()
+    after = raw_arg[idx + len(flag) :].lstrip()
+
+    if not after:
+        msg = "--model-params requires a JSON object value"
+        raise ValueError(msg)
+
+    # Determine the JSON string boundaries.
+    if after[0] in {"'", '"'}:
+        quote = after[0]
+        end = -1
+        backslash_count = 0
+        for i, ch in enumerate(after[1:], start=1):
+            if ch == "\\":
+                backslash_count += 1
+                continue
+            if ch == quote and backslash_count % 2 == 0:
+                end = i
+                break
+            backslash_count = 0
+        if end == -1:
+            msg = f"Unclosed {quote} in --model-params value"
+            raise ValueError(msg)
+        # Parse the quoted token with shlex so escaped quotes are unescaped.
+        json_str = shlex.split(after[: end + 1], posix=True)[0]
+        rest = after[end + 1 :].lstrip()
+    elif after[0] == "{":
+        # Walk forward to find the matching closing brace.
+        depth = 0
+        end = -1
+        for i, ch in enumerate(after):
+            if ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    end = i
+                    break
+        if end == -1:
+            msg = "Unbalanced braces in --model-params value"
+            raise ValueError(msg)
+        json_str = after[: end + 1]
+        rest = after[end + 1 :].lstrip()
+    else:
+        # Non-brace, non-quoted — take the next whitespace-delimited token.
+        parts = after.split(None, 1)
+        json_str = parts[0]
+        rest = parts[1] if len(parts) > 1 else ""
+
+    remaining = f"{before} {rest}".strip()
+    try:
+        params = json.loads(json_str)
+    except json.JSONDecodeError:
+        msg = f'Invalid JSON in --model-params: {json_str!r}. Expected format: --model-params \'{{"key": "value"}}\''
+        raise ValueError(msg) from None
+    if not isinstance(params, dict):
+        msg = "--model-params must be a JSON object, got " + type(params).__name__
+        raise TypeError(msg)
+    return remaining, params

{soothe_cli-0.11.0 → soothe_cli-1.0.0}/src/soothe_cli/tui/app/_startup.py

@@ -20,7 +20,7 @@ from textual.containers import VerticalScroll
 from textual.css.query import NoMatches
 
 from soothe_cli._version import CHANGELOG_URL
-from soothe_cli.tui.app._module_init import (
+from soothe_cli.tui.app._types import (
     TextualSessionState,
 )
 from soothe_cli.tui.widgets.chat_input import ChatInput

soothe_cli-1.0.0/src/soothe_cli/tui/app/_terminal.py

@@ -0,0 +1,75 @@
+"""iTerm2 terminal integration: cursor guide escape sequences and lifecycle.
+
+The cursor guide (highlight cursor line) causes visual artifacts when Textual
+takes over the terminal in alternate screen mode. We disable it before the app
+launches and restore on exit. Both atexit and exit() override are used for
+defense-in-depth: atexit catches abnormal termination (SIGTERM, unhandled
+exceptions), while exit() ensures restoration before Textual's cleanup.
+
+Unlike the previous catch-all module, this module performs **no** side effects
+at import time. Call `init_terminal_integration()` explicitly before starting
+the Textual app.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Detection: check env vars AND that stderr is a TTY (avoids false positives
+# when env vars are inherited but running in non-TTY context like CI)
+_IS_ITERM = (
+    (
+        os.environ.get("LC_TERMINAL", "") == "iTerm2"
+        or os.environ.get("TERM_PROGRAM", "") == "iTerm.app"
+    )
+    and hasattr(os, "isatty")
+    and os.isatty(2)
+)
+
+# iTerm2 cursor guide escape sequences (OSC 1337)
+# Format: OSC 1337 ; HighlightCursorLine=<yes|no> ST
+# Where OSC = ESC ] (0x1b 0x5d) and ST = ESC \ (0x1b 0x5c)
+_ITERM_CURSOR_GUIDE_OFF = "\x1b]1337;HighlightCursorLine=no\x1b\\"
+_ITERM_CURSOR_GUIDE_ON = "\x1b]1337;HighlightCursorLine=yes\x1b\\"
+
+
+def _write_iterm_escape(sequence: str) -> None:
+    """Write an iTerm2 escape sequence to stderr.
+
+    Silently fails if the terminal is unavailable (redirected, closed, broken
+    pipe). This is a cosmetic feature, so failures should never crash the app.
+    """
+    if not _IS_ITERM:
+        return
+    try:
+        import sys
+
+        if sys.__stderr__ is not None:
+            sys.__stderr__.write(sequence)
+            sys.__stderr__.flush()
+    except OSError:
+        # Terminal may be unavailable (redirected, closed, broken pipe)
+        pass
+
+
+def _restore_cursor_guide() -> None:
+    """Restore iTerm2 cursor guide on exit.
+
+    Registered with atexit to ensure the cursor guide is re-enabled
+    when the CLI exits, regardless of how the exit occurs.
+    """
+    _write_iterm_escape(_ITERM_CURSOR_GUIDE_ON)
+
+
+def init_terminal_integration() -> None:
+    """Disable the iTerm2 cursor guide and register restore-on-exit.
+
+    Call this explicitly before starting the Textual app. This replaces the
+    previous import-time side effect so that merely importing the module does
+    not write to the terminal.
+    """
+    _write_iterm_escape(_ITERM_CURSOR_GUIDE_OFF)
+    if _IS_ITERM:
+        import atexit
+
+        atexit.register(_restore_cursor_guide)