Load(fix[progress]): Honor panel opt-in

tony · tony · commit cd2526a7d2d8 · 2026-06-27T05:22:20.000-05:00
why: Restoring native before_script streaming made progress-lines a no-op.
Explicit panel requests should still capture script output, while default
loads should leave TTY-aware scripts attached to the terminal.

what:
- Capture before_script output only for explicit nonzero progress-lines
- Keep default and zero-line modes on native script output
- Update CLI docs, env docs, changelog, and load tests
diff --git a/CHANGES b/CHANGES
@@ -120,7 +120,7 @@ tmuxp 1.67.0 makes {ref}`tmuxp-load` visibly track the workspace build it is per
 
 The {ref}`tmuxp-load` command now shows an animated progress display while it builds a session. Built-in formats cover terse, window-focused, pane-focused, and verbose views, while `--progress-format` and `TMUXP_PROGRESS_FORMAT` allow a custom display.
 
-`--progress-lines` and `TMUXP_PROGRESS_LINES` control how much `before_script` output appears in the panel, and `--no-progress` or `TMUXP_PROGRESS=0` restores quiet output.
+`--progress-lines` and `TMUXP_PROGRESS_LINES` capture `before_script` output in the panel when requested, and `--no-progress` or `TMUXP_PROGRESS=0` restores quiet output.
 
 ## tmuxp 1.66.0 (2026-03-08)
 
diff --git a/docs/cli/load.md b/docs/cli/load.md
@@ -218,21 +218,21 @@ $ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject
 
 ### Panel lines
 
-The spinner shows script output in a panel below the spinner line. Control the panel height with `--progress-lines`:
+By default, `before_script` runs with its normal terminal output before the spinner appears. Use `--progress-lines` to capture that output in a panel below the spinner line:
 
-Hide the panel entirely (script output goes to stdout):
+Keep native script output and hide the panel:
 
 ```console
 $ tmuxp load --progress-lines 0 myproject
 ```
 
-Show unlimited lines (capped to terminal height):
+Capture unlimited lines (capped to terminal height):
 
 ```console
 $ tmuxp load --progress-lines -1 myproject
 ```
 
-Set a custom height (default is 3):
+Capture five lines:
 
 ```console
 $ tmuxp load --progress-lines 5 myproject
diff --git a/docs/configuration/environmental-variables.md b/docs/configuration/environmental-variables.md
@@ -60,15 +60,15 @@ Equivalent to the `--progress-format` CLI flag.
 
 ## `TMUXP_PROGRESS_LINES`
 
-Number of script-output lines shown in the spinner panel. Defaults to `3`.
+Capture `before_script` output in the spinner panel with this many lines. By default, scripts keep their normal terminal output.
 
-Set to `0` to hide the panel entirely (script output goes to stdout):
+Set to `0` to keep native script output and hide the panel:
 
 ```console
 $ TMUXP_PROGRESS_LINES=0 tmuxp load myproject
 ```
 
-Set to `-1` for unlimited lines (capped to terminal height):
+Set to `-1` to capture unlimited lines (capped to terminal height):
 
 ```console
 $ TMUXP_PROGRESS_LINES=-1 tmuxp load myproject
diff --git a/src/tmuxp/cli/load.py b/src/tmuxp/cli/load.py
@@ -478,9 +478,9 @@ def load_workspace(
     progress_format : str, optional
         Spinner format preset name or custom format string with tokens.
     panel_lines : int, optional
-        Number of script-output lines shown in the spinner panel.
-        Defaults to the :class:`~tmuxp.cli._progress.Spinner` default (3).
-        Override via ``TMUXP_PROGRESS_LINES`` environment variable.
+        Nonzero values capture ``before_script`` output in the spinner panel.
+        By default, scripts keep their normal terminal output. Override via
+        ``TMUXP_PROGRESS_LINES`` environment variable.
     no_progress : bool
         Disable the progress spinner entirely. Default False.
         Also disabled when ``TMUXP_PROGRESS=0``.
@@ -658,6 +658,7 @@ def load_workspace(
     else:
         _panel_lines_env_int = None
     _panel_lines = panel_lines if panel_lines is not None else _panel_lines_env_int
+    _panel_lines_explicit = panel_lines is not None or _panel_lines_env_int is not None
     _private_path = str(PrivatePath(workspace_file))
     _spinner = Spinner(
         message=(
@@ -670,6 +671,9 @@ def load_workspace(
     )
     _success_emitted = False
     _has_before_script = "before_script" in expanded_workspace
+    _capture_script_output = (
+        _has_before_script and _panel_lines_explicit and _panel_lines != 0
+    )
 
     def _emit_success() -> None:
         nonlocal _success_emitted
@@ -680,12 +684,14 @@ def _emit_success() -> None:
 
     def _on_build_event(event: dict[str, t.Any]) -> None:
         spinner.on_build_event(event)
-        if event.get("event") == "before_script_done":
+        if event.get("event") == "before_script_done" and not _capture_script_output:
             spinner.start()
 
     spinner = _spinner
     with _silence_stream_handlers():
-        if not _has_before_script:
+        if _capture_script_output:
+            builder.on_script_output = spinner.add_output_line
+        if not _has_before_script or _capture_script_output:
             spinner.start()
         builder.on_build_event = _on_build_event
         try:
@@ -809,8 +815,8 @@ def create_load_subparser(parser: argparse.ArgumentParser) -> argparse.ArgumentP
         type=int,
         default=None,
         help=(
-            "Number of script-output lines shown in the spinner panel (default: 3). "
-            "0 hides the panel entirely (script output goes to stdout). "
+            "Capture before_script output in the spinner panel with N lines. "
+            "0 keeps native script output and hides the panel. "
             "-1 shows unlimited lines (capped to terminal height). "
             "Env: TMUXP_PROGRESS_LINES"
         ),
diff --git a/tests/cli/test_load.py b/tests/cli/test_load.py
@@ -967,6 +967,139 @@ def fake_dispatch_build(
     ]
 
 
+class ProgressLinesCaptureFixture(t.NamedTuple):
+    """Test fixture for explicit progress-lines capture mode."""
+
+    test_id: str
+    panel_lines: int | None
+    env_value: str | None
+    expected_capture: bool
+
+
+PROGRESS_LINES_CAPTURE_FIXTURES: list[ProgressLinesCaptureFixture] = [
+    ProgressLinesCaptureFixture(
+        test_id="cli_panel_lines",
+        panel_lines=5,
+        env_value=None,
+        expected_capture=True,
+    ),
+    ProgressLinesCaptureFixture(
+        test_id="env_panel_lines",
+        panel_lines=None,
+        env_value="4",
+        expected_capture=True,
+    ),
+    ProgressLinesCaptureFixture(
+        test_id="cli_zero_lines",
+        panel_lines=0,
+        env_value=None,
+        expected_capture=False,
+    ),
+    ProgressLinesCaptureFixture(
+        test_id="env_zero_lines",
+        panel_lines=None,
+        env_value="0",
+        expected_capture=False,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(ProgressLinesCaptureFixture._fields),
+    PROGRESS_LINES_CAPTURE_FIXTURES,
+    ids=[f.test_id for f in PROGRESS_LINES_CAPTURE_FIXTURES],
+)
+def test_load_workspace_handles_explicit_before_script_progress_lines(
+    server: Server,
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+    test_id: str,
+    panel_lines: int | None,
+    env_value: str | None,
+    expected_capture: bool,
+) -> None:
+    """Explicit progress-lines controls before_script output capture."""
+    import yaml
+
+    from tmuxp.cli._colors import ColorMode, Colors
+
+    calls: list[str] = []
+    captured_script_callback: list[t.Callable[[str], None] | None] = []
+
+    class FakeSpinner:
+        def __init__(self, *_args: t.Any, **_kwargs: t.Any) -> None:
+            pass
+
+        def start(self) -> None:
+            calls.append("start")
+
+        def stop(self) -> None:
+            calls.append("stop")
+
+        def success(self) -> None:
+            calls.append("success")
+
+        def add_output_line(self, line: str) -> None:
+            calls.append(f"add_output_line:{line}")
+
+        def on_build_event(self, event: dict[str, t.Any]) -> None:
+            calls.append(str(event["event"]))
+
+    def fake_dispatch_build(
+        builder: WorkspaceBuilder,
+        *_args: t.Any,
+        **_kwargs: t.Any,
+    ) -> None:
+        captured_script_callback.append(builder.on_script_output)
+        assert builder.on_build_event is not None
+
+        builder.on_build_event({"event": "before_script_started"})
+        if builder.on_script_output is not None:
+            builder.on_script_output("before line")
+        builder.on_build_event({"event": "before_script_done"})
+
+    config = {
+        "session_name": f"before-script-progress-{test_id}",
+        "before_script": "echo before",
+        "windows": [{"window_name": "main"}],
+    }
+    config_file = tmp_path / f"{test_id}.yaml"
+    config_file.write_text(yaml.dump(config))
+
+    monkeypatch.delenv("TMUX", raising=False)
+    if env_value is None:
+        monkeypatch.delenv("TMUXP_PROGRESS_LINES", raising=False)
+    else:
+        monkeypatch.setenv("TMUXP_PROGRESS_LINES", env_value)
+    monkeypatch.setattr("tmuxp.cli.load.Spinner", FakeSpinner)
+    monkeypatch.setattr("tmuxp.cli.load._dispatch_build", fake_dispatch_build)
+
+    result = load_workspace(
+        str(config_file),
+        socket_name=server.socket_name,
+        cli_colors=Colors(ColorMode.NEVER),
+        panel_lines=panel_lines,
+    )
+
+    assert result is None
+    assert (captured_script_callback[0] is not None) is expected_capture
+    if expected_capture:
+        assert calls == [
+            "start",
+            "before_script_started",
+            "add_output_line:before line",
+            "before_script_done",
+            "stop",
+        ]
+    else:
+        assert calls == [
+            "before_script_started",
+            "before_script_done",
+            "start",
+            "stop",
+        ]
+
+
 def test_load_masks_home_in_spinner_message(monkeypatch: pytest.MonkeyPatch) -> None:
     """Spinner message should mask home directory via PrivatePath."""
     monkeypatch.setattr(pathlib.Path, "home", lambda: pathlib.Path("/home/testuser"))
