cli/load(fix[here]): Reject multi-workspace here invocations

why: --here is a current-window workflow. Accepting multiple workspace files
silently changes behavior for earlier entries and leaves behind unexpected
sessions instead of failing fast.
what:
- reject --here when more than one workspace file is provided
- clarify the parser help text for the single-workspace contract
- add CLI coverage that exits before any workspace is loaded
- document the single-workspace restriction in the load guide

Author: tony

docs/cli/load.md

@@ -264,6 +264,8 @@ $ tmuxp load --here .
 
 When used, tmuxp builds the workspace panes inside the current window rather than spawning a new session.
 
+`--here` only supports a single workspace file per invocation.
+
 ```{note}
 When `--here` needs to provision a directory, environment, or shell, tmuxp uses tmux primitives (`set-environment` and `respawn-pane`) instead of typing `cd` / `export` into the pane. If provisioning is needed, tmux will replace the active pane process before the workspace commands run, so long-running child processes in that pane can be terminated.
 ```

src/tmuxp/cli/load.py

@@ -1027,7 +1027,10 @@ def create_load_subparser(parser: argparse.ArgumentParser) -> argparse.ArgumentP
         "--here",
         dest="here",
         action="store_true",
-        help="use the current window for the first workspace window",
+        help=(
+            "use the current window for the first workspace window "
+            "(single workspace only)"
+        ),
     )
     parser.add_argument(
         "--no-shell-command-before",
@@ -1170,6 +1173,13 @@ def command_load(
         sys.exit()
         return
 
+    if args.here and len(args.workspace_files) > 1:
+        msg = "--here only supports one workspace file"
+        if parser is not None:
+            parser.error(msg)
+        tmuxp_echo(cli_colors.error("[Error]") + f" {msg}")
+        sys.exit(2)
+
     # Parse --set KEY=VALUE args into template context
     template_context: dict[str, str] | None = None
     if args.set:

tests/cli/test_load.py

@@ -19,9 +19,11 @@
 from tmuxp._internal.config_reader import ConfigReader
 from tmuxp._internal.private_path import PrivatePath
 from tmuxp.cli.load import (
+    CLILoadNamespace,
     _dispatch_build,
     _load_append_windows_to_current_session,
     _load_attached,
+    command_load,
     load_plugins,
     load_workspace,
 )
@@ -1688,6 +1690,61 @@ def test_load_here_and_detached_mutually_exclusive() -> None:
         parser.parse_args(["load", "--here", "-d", "myconfig"])
 
 
+class MultiWorkspaceHereFixture(t.NamedTuple):
+    """Fixture for invalid multi-workspace --here invocations."""
+
+    test_id: str
+    cli_args: list[str]
+    expected_exit_code: int
+    expected_error: str
+
+
+MULTI_WORKSPACE_HERE_FIXTURES: list[MultiWorkspaceHereFixture] = [
+    MultiWorkspaceHereFixture(
+        test_id="rejects-two-workspaces",
+        cli_args=["load", "--here", "first", "second"],
+        expected_exit_code=2,
+        expected_error="--here only supports one workspace file",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(MultiWorkspaceHereFixture._fields),
+    MULTI_WORKSPACE_HERE_FIXTURES,
+    ids=[fixture.test_id for fixture in MULTI_WORKSPACE_HERE_FIXTURES],
+)
+def test_load_here_rejects_multiple_workspace_files(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    test_id: str,
+    cli_args: list[str],
+    expected_exit_code: int,
+    expected_error: str,
+) -> None:
+    """--here exits before load_workspace when multiple files are provided."""
+    parser = cli.create_parser()
+    args = t.cast(CLILoadNamespace, parser.parse_args(cli_args))
+    load_calls: list[str] = []
+
+    monkeypatch.setattr(
+        "tmuxp.cli.load.util.oh_my_zsh_auto_title",
+        lambda: None,
+    )
+    monkeypatch.setattr(
+        "tmuxp.cli.load.load_workspace",
+        lambda *args, **kwargs: load_calls.append(test_id),
+    )
+
+    with pytest.raises(SystemExit) as excinfo:
+        command_load(args, parser=parser)
+
+    result = capsys.readouterr()
+    assert excinfo.value.code == expected_exit_code
+    assert expected_error in result.err
+    assert load_calls == []
+
+
 def test_load_append_and_detached_mutually_exclusive() -> None:
     """--append and -d cannot be used together."""
     from tmuxp.cli import create_parser