kapsel-cli 0.6.8__tar.gz → 0.7.2__tar.gz

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapsel-cli
-Version: 0.6.8
+Version: 0.7.2
 Summary: Next-generation cross-platform terminal capsule & ergonomic shell multiplexer with context-aware command translation and 1,000+ CLI completions.
 Author-email: MrEiu <k648888@vip.qq.com>
 License: MIT

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/__init__.py

@@ -3,4 +3,4 @@ Kapsel: Cross-platform adaptive smart terminal capsule.
 Wrap complexity, expose simplicity.
 """
 
-__version__ = "0.6.8"
+__version__ = "0.7.2"

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/cli.py

@@ -102,17 +102,18 @@ def main(args: Optional[List[str]] = None) -> int:
         if not stripped:
             continue
 
-        normalized = " ".join(stripped.lower().split())
-        if normalized in ("exit", "quit", "bye"):
-            engine.history_mgr.record_command(command=user_input, mode="builtin")
-            os.environ.pop("KAPSEL_ACTIVE", None)
-            console.print("[dim]Exited Kapsel.[/]")
-            break
-
-        if normalized in ("restart", "kapsel restart", "reload"):
-            engine.history_mgr.record_command(command=user_input, mode="builtin")
-            from kapsel.completion.kps.builtins.restart import handle_restart
-            return handle_restart(console=console)
+        if "\n" not in stripped:
+            normalized = " ".join(stripped.lower().split())
+            if normalized in ("exit", "quit", "bye"):
+                engine.history_mgr.record_command(command=user_input, mode="builtin")
+                os.environ.pop("KAPSEL_ACTIVE", None)
+                console.print("[dim]Exited Kapsel.[/]")
+                break
+
+            if normalized in ("restart", "kapsel restart", "reload"):
+                engine.history_mgr.record_command(command=user_input, mode="builtin")
+                from kapsel.completion.kps.builtins.restart import handle_restart
+                return handle_restart(console=console)
 
         try:
             result = engine.dispatch(user_input)

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/completion/carapace_installer.py

@@ -192,9 +192,10 @@ def install_carapace(
 
 def ensure_carapace_installed(console: Optional[Console] = None) -> bool:
     """
-    Auto-bootstraps Carapace completion engine on first launch if not already available.
-    Zero-overhead (0ms) on subsequent launches when already installed.
-    Gracefully falls back to basic completion if offline, preventing any startup crash.
+    Checks if Carapace completion engine is available.
+    If not installed, prints a lightweight non-blocking notice and enters immediately.
+    Never blocks terminal startup with network downloads.
+    Users can install it anytime on demand using 'kapsel setup-completion'.
     """
     from kapsel.completion.carapace_engine import get_carapace_engine
 
@@ -203,16 +204,9 @@ def ensure_carapace_installed(console: Optional[Console] = None) -> bool:
         return True
 
     con = console or Console(legacy_windows=False)
-    con.print("[bold #00f0ff]🎯 First Launch: Auto-initializing Carapace completion engine (1,000+ tools)...[/]")
-
-    try:
-        success = install_carapace(console=con, force=False)
-        return success
-    except Exception as e:
-        logger.warning(f"Failed to auto-bootstrap Carapace: {e}")
-        con.print(
-            f"[yellow]Notice: Could not automatically setup Carapace ({e}). "
-            f"Continuing in basic autocompletion mode.[/]\n"
-        )
-        return False
+    con.print(
+        "[dim]ℹ Notice: Carapace completion engine not detected. Running in standard autocompletion mode.[/]\n"
+        "[dim]  (Optional: run '[bold cyan]kapsel setup-completion[/]' to enable 1,000+ tool completions)[/]\n"
+    )
+    return False
 

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/completion/kps/dispatcher.py

@@ -133,6 +133,7 @@ def _handle_kp_command(
         con.print("[dim]Executes multiple commands or pasted blocks asynchronously in the background.[/]\n")
         con.print("[bold white]Usage:[/]")
         con.print("  [bold #a855f7]kp <commands...>[/]             Execute commands sequentially in background (atomic, non-blocking)")
+        con.print("  [bold #a855f7]kp -s <commands...>[/]          Execute commands sequentially in background (explicit sequential)")
         con.print("  [bold #a855f7]kp -c <commands...>[/]          Execute commands concurrently in background parallel tracks")
         con.print("  [bold #a855f7]kp attach [id][/]                Attach to running block as interactive sub-terminal (二级终端)")
         con.print("  [bold #a855f7]kp status[/]                    List session blocks, running status, PID, and exit codes")
@@ -140,6 +141,7 @@ def _handle_kp_command(
         con.print("  [bold #a855f7]kp stop <id>[/]                 Terminate a running background block\n")
         con.print("[bold white]Examples:[/]")
         con.print("  kp npm run dev               (Runs dev server in background, prompt stays clean)")
+        con.print("  kp -s git pull\\npnpm build    (Runs tasks sequentially in background)")
         con.print("  kp -c pnpm build:app\\npnpm build:docs         (Runs build tasks concurrently in parallel)\n")
         return 0
 
@@ -262,6 +264,15 @@ def _handle_kp_command(
     elif sub.startswith("-c\n") or sub.startswith("--concurrent\n"):
         is_concurrent = True
         body = sub.split("\n", 1)[1]
+    elif sub.startswith("-s ") or sub.startswith("--sequential "):
+        is_concurrent = False
+        body = sub.split(" ", 1)[1]
+    elif sub == "-s" or sub == "--sequential":
+        con.print("[bold #f43f5e]Error:[/] Please provide commands to execute with 'kp -s'.\n")
+        return 1
+    elif sub.startswith("-s\n") or sub.startswith("--sequential\n"):
+        is_concurrent = False
+        body = sub.split("\n", 1)[1]
 
     commands = split_commands(body)
     if not commands:

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/core/block/runner.py

@@ -20,19 +20,114 @@ from kapsel.core.block.model import BlockStatus, CommandBlock
 from kapsel.core.block.registry import get_block_registry
 
 
+def _normalize_continuation_spaces(text: str) -> str:
+    """Replaces unquoted newlines (from continuation lines) with spaces and collapses indentation."""
+    if "\n" not in text:
+        return text
+
+    result = []
+    in_single = False
+    in_double = False
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if (ch == "\\" or ch == "`") and not in_single and i + 1 < len(text):
+            result.append(ch)
+            result.append(text[i + 1])
+            i += 2
+            continue
+        if ch == "'" and not in_double:
+            in_single = not in_single
+            result.append(ch)
+        elif ch == '"' and not in_single:
+            in_double = not in_double
+            result.append(ch)
+        elif ch == "\n" and not in_single and not in_double:
+            if result and result[-1] != " ":
+                result.append(" ")
+            while i + 1 < len(text) and text[i + 1] in (" ", "\t"):
+                i += 1
+        else:
+            result.append(ch)
+        i += 1
+
+    return "".join(result).strip()
+
+
 def split_commands(raw_text: str) -> List[str]:
     """
-    Parses multi-line or delimited text into individual commands,
-    ignoring empty lines and pure comments.
+    Parses multi-line or delimited text into individual executable commands.
+    - Preserves newlines within unclosed quotes ('', "").
+    - Handles line continuation characters ('\\' in POSIX/Bash, '`' in PowerShell)
+      by joining them into a single command with continuation characters stripped.
+    - Handles trailing pipeline ('|') and logical ('&&', '||') continuations.
+    - Ignores empty whitespace lines.
+    - Does NOT filter '#' lines (leaves comments/commands intact for the shell).
     """
-    lines = raw_text.strip().splitlines()
-    result: List[str] = []
+    if not raw_text or not raw_text.strip():
+        return []
+
+    lines = raw_text.splitlines()
+    commands: List[str] = []
+    current_parts: List[str] = []
+    in_single_quote = False
+    in_double_quote = False
+
     for line in lines:
-        cleaned = line.strip()
-        if not cleaned or cleaned.startswith("#"):
+        stripped = line.strip()
+        if not stripped and not current_parts and not in_single_quote and not in_double_quote:
+            continue
+
+        # Count quotes in this line, ignoring escaped quotes
+        i = 0
+        while i < len(line):
+            ch = line[i]
+            if (ch == "\\" or ch == "`") and not in_single_quote and i + 1 < len(line):
+                i += 2
+                continue
+            if ch == "'" and not in_double_quote:
+                in_single_quote = not in_single_quote
+            elif ch == '"' and not in_single_quote:
+                in_double_quote = not in_double_quote
+            i += 1
+
+        # If currently inside an open quote, line continues unconditionally
+        if in_single_quote or in_double_quote:
+            current_parts.append(line)
             continue
-        result.append(cleaned)
-    return result
+
+        # Outside quotes: check if line ends with a continuation token
+        r_stripped = line.rstrip()
+        is_continuation = False
+        continuation_clean = line
+
+        if r_stripped.endswith("\\"):
+            is_continuation = True
+            continuation_clean = r_stripped[:-1].rstrip()
+        elif r_stripped.endswith("`"):
+            is_continuation = True
+            continuation_clean = r_stripped[:-1].rstrip()
+        elif r_stripped.endswith("|") or r_stripped.endswith("&&") or r_stripped.endswith("||"):
+            is_continuation = True
+            continuation_clean = r_stripped
+
+        if is_continuation:
+            current_parts.append(continuation_clean)
+        else:
+            current_parts.append(line)
+            full_cmd = "\n".join(current_parts).strip()
+            full_cmd = _normalize_continuation_spaces(full_cmd)
+            if full_cmd:
+                commands.append(full_cmd)
+            current_parts = []
+
+    if current_parts:
+        leftover = "\n".join(current_parts).strip()
+        leftover = _normalize_continuation_spaces(leftover)
+        if leftover:
+            commands.append(leftover)
+
+    return commands
 
 
 def _run_single_command_process(cmd: str, cwd: str) -> Tuple[int, str, int]:

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/core/executor.py

@@ -81,6 +81,11 @@ class CommandExecutor:
 
     def _handle_builtin(self, cmd: str) -> Optional[ExecutionSummary]:
         """Intercepts built-ins like cd, clear, cls."""
+        # Multi-line commands/scripts must bypass single-line built-in interception
+        # to prevent cmd.split() from collapsing lines into space-separated arguments.
+        if "\n" in cmd:
+            return None
+
         parts = cmd.split()
         if not parts:
             return None
@@ -220,7 +225,12 @@ class CommandExecutor:
             args = [exe, "-NoLogo", "-Command", cmd]
         elif shell == "cmd":
             exe = self.shell_path if self.shell_path and Path(self.shell_path).exists() else "cmd.exe"
-            args = [exe, "/c", cmd]
+            effective_cmd = (
+                " & ".join(line.strip() for line in cmd.splitlines() if line.strip())
+                if "\n" in cmd
+                else cmd
+            )
+            args = [exe, "/c", effective_cmd]
         else:
             # Unix shells (bash, zsh, fish, sh)
             exe = self.shell_path if self.shell_path and Path(self.shell_path).exists() else "/bin/sh"

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/core/update_check.py

@@ -125,16 +125,7 @@ def get_pypi_upgrade_notice() -> Optional[str]:
             return latest_ver
         return None
 
-    # If no cache exists, launch a quick worker thread with a fast join limit
-    worker = threading.Thread(target=_background_fetch_worker, daemon=True)
-    worker.start()
-    worker.join(timeout=0.6)
-
-    # Re-check cache after fast join
-    cached_after = _read_cached_info()
-    if cached_after is not None:
-        latest_ver = str(cached_after.get("latest_version", ""))
-        if parse_semver(latest_ver) > parse_semver(CURRENT_KAPSEL_VERSION):
-            return latest_ver
-
+    # If no cache exists, launch worker asynchronously in the background without blocking startup
+    threading.Thread(target=_background_fetch_worker, daemon=True).start()
     return None
+

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel/ui/prompt.py

@@ -187,12 +187,13 @@ class BlockRoamingController:
 
     def enter_roaming(self, buffer) -> None:
         blocks = self.get_blocks()
+        self.is_active = True
+        self.saved_buffer_text = buffer.text
         if not blocks:
+            self.current_index = -1
             self.status_msg = "No command blocks in session history."
             return
 
-        self.is_active = True
-        self.saved_buffer_text = buffer.text
         self.current_index = len(blocks) - 1
         self.status_msg = ""
         self._sync_buffer_to_block(buffer)
@@ -467,21 +468,10 @@ def create_key_bindings(
     @kb.add("c-b")
     def _(event: KeyPressEvent) -> None:
         """
-        Ctrl+B: Always opens Block Navigator / Roaming,
-        allowing the user to roam across all blocks even if blocks are running in background.
-        Pressing Enter on a running block inside the navigator enters the live sub-terminal.
+        Ctrl+B: Toggles inline Block Roaming Mode directly in the prompt line,
+        without launching a disruptive full-screen viewport.
         """
-        from prompt_toolkit.application.run_in_terminal import in_terminal
-        from kapsel.ui.viewport import run_block_viewport_async
-
-        async def _launch() -> None:
-            async with in_terminal():
-                cmd = await run_block_viewport_async()
-                if cmd is not None:
-                    event.current_buffer.text = cmd
-                    event.current_buffer.cursor_position = len(cmd)
-
-        event.app.create_background_task(_launch())
+        roam_ctrl.toggle(event.current_buffer)
 
     @kb.add("up", filter=is_roaming)
     @kb.add("k", filter=is_roaming)

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapsel-cli
-Version: 0.6.8
+Version: 0.7.2
 Summary: Next-generation cross-platform terminal capsule & ergonomic shell multiplexer with context-aware command translation and 1,000+ CLI completions.
 Author-email: MrEiu <k648888@vip.qq.com>
 License: MIT

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/kapsel_cli.egg-info/SOURCES.txt

@@ -96,10 +96,12 @@ tests/test_ai_spec_sanitizer.py
 tests/test_block_system.py
 tests/test_carapace_installer.py
 tests/test_config.py
+tests/test_ctrl_b_roaming.py
 tests/test_dir_nav.py
 tests/test_history.py
 tests/test_i18n.py
-tests/test_kssh_input_bar.py
+tests/test_kp_enhanced.py
+tests/test_multiline_passthrough.py
 tests/test_plugin_ai.py
 tests/test_plugin_alias.py
 tests/test_plugin_autopilot.py
@@ -109,6 +111,8 @@ tests/test_plugin_fetcher.py
 tests/test_plugin_help.py
 tests/test_plugin_init.py
 tests/test_plugin_install.py
+tests/test_plugin_install_batch.py
+tests/test_plugin_kssh.py
 tests/test_plugin_lang.py
 tests/test_plugin_mend.py
 tests/test_plugin_portal.py

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kapsel-cli"
-version = "0.6.8"
+version = "0.7.2"
 description = "Next-generation cross-platform terminal capsule & ergonomic shell multiplexer with context-aware command translation and 1,000+ CLI completions."
 readme = "README.md"
 requires-python = ">=3.9"

{kapsel_cli-0.6.8 → kapsel_cli-0.7.2}/tests/test_carapace_installer.py

@@ -45,16 +45,16 @@ def test_ensure_carapace_installed_when_available():
         mock_install.assert_not_called()
 
 
-def test_ensure_carapace_installed_auto_bootstraps():
-    """Verifies that ensure_carapace_installed triggers install_carapace on first run."""
+def test_ensure_carapace_installed_when_missing_does_not_block():
+    """Verifies that ensure_carapace_installed does not trigger blocking network install when missing."""
     mock_engine = MagicMock()
     mock_engine.is_available.return_value = False
 
     with patch("kapsel.completion.carapace_engine.get_carapace_engine", return_value=mock_engine), \
-         patch("kapsel.completion.carapace_installer.install_carapace", return_value=True) as mock_install:
+         patch("kapsel.completion.carapace_installer.install_carapace") as mock_install:
         res = ensure_carapace_installed()
-        assert res is True
-        mock_install.assert_called_once_with(console=mock_install.call_args[1]["console"], force=False)
+        assert res is False
+        mock_install.assert_not_called()
 
 
 def test_kps_registry_has_setup_completion():

kapsel_cli-0.7.2/tests/test_ctrl_b_roaming.py

@@ -0,0 +1,69 @@
+"""
+Unit tests for Ctrl+B inline Block Roaming Mode.
+Ensures Ctrl+B toggles inline roaming toolbar rather than launching full-screen viewport.
+"""
+
+from unittest.mock import MagicMock
+import pytest
+
+from kapsel.core.block.model import BlockStatus, CommandBlock
+from kapsel.core.block.registry import get_block_registry
+from kapsel.storage.config import KapselConfig
+from kapsel.ui.prompt import BlockRoamingController, create_key_bindings
+
+
+def test_roam_ctrl_toggle_enters_and_exits():
+    """Toggling roam_ctrl activates inline roaming and then cleanly exits and restores buffer."""
+    reg = get_block_registry()
+    reg.clear_for_test() if hasattr(reg, "clear_for_test") else None
+
+    # Register a sample block
+    reg.add_block(command="echo test_block", exit_code=0, duration_ms=10)
+
+    roam = BlockRoamingController()
+    dummy_buffer = MagicMock()
+    dummy_buffer.text = "typing something"
+    dummy_buffer.cursor_position = len(dummy_buffer.text)
+
+    # 1. Toggle ON: enters roaming mode
+    roam.toggle(dummy_buffer)
+    assert roam.is_active is True
+    assert roam.saved_buffer_text == "typing something"
+    assert dummy_buffer.text == "echo test_block"
+
+    # 2. Toggle OFF: exits roaming mode and restores buffer text
+    roam.toggle(dummy_buffer)
+    assert roam.is_active is False
+    assert dummy_buffer.text == "typing something"
+
+
+def test_ctrl_b_keybinding_triggers_toggle():
+    """Ctrl+B keybinding must trigger roam_ctrl.toggle without launching full-screen viewport."""
+    config = KapselConfig()
+    roam = BlockRoamingController()
+    kb = create_key_bindings(config, roaming=roam)
+
+    # Find the c-b binding
+    cb_binding = None
+    for binding in kb.bindings:
+        # Check if keys contain 'c-b'
+        keys_str = [str(k) for k in binding.keys]
+        if any("c-b" in k or k == "c-b" or "c-b" in str(binding.keys) for k in keys_str):
+            cb_binding = binding
+            break
+
+    assert cb_binding is not None, "Ctrl+B key binding should exist"
+
+    # Simulate pressing Ctrl+B
+    event = MagicMock()
+    event.current_buffer = MagicMock()
+    event.current_buffer.text = "current input"
+
+    # Roaming should initially be inactive
+    assert roam.is_active is False
+
+    # Call the c-b handler
+    cb_binding.call(event)
+
+    # Roaming should now be active directly in line (no full-screen launch)
+    assert roam.is_active is True

kapsel_cli-0.7.2/tests/test_kp_enhanced.py

@@ -0,0 +1,111 @@
+"""
+Unit tests for enhanced kp block runner:
+- Robust command splitting (line continuations, unclosed quotes, keeping # lines)
+- Concurrent (-c) vs Sequential (-s) block dispatching
+"""
+
+import pytest
+from kapsel.core.block.runner import split_commands
+from kapsel.completion.kps.dispatcher import dispatch_kps
+
+
+def test_split_commands_retains_hash_lines():
+    """Lines starting with # must NOT be filtered out, leaving them for the shell."""
+    text = "echo hello\n# this is a comment or root command\necho world"
+    cmds = split_commands(text)
+    assert cmds == ["echo hello", "# this is a comment or root command", "echo world"]
+
+
+def test_split_commands_backslash_continuation():
+    """POSIX/Bash trailing backslash joins lines and removes the backslash."""
+    text = """docker run -d \\
+  --name web \\
+  -p 80:80 \\
+  nginx"""
+    cmds = split_commands(text)
+    assert len(cmds) == 1
+    assert cmds[0] == "docker run -d --name web -p 80:80 nginx"
+
+
+def test_split_commands_powershell_backtick_continuation():
+    """PowerShell trailing backtick joins lines and removes the backtick."""
+    text = """Get-ChildItem `
+  -Filter *.py `
+  -Recurse"""
+    cmds = split_commands(text)
+    assert len(cmds) == 1
+    assert cmds[0] == "Get-ChildItem -Filter *.py -Recurse"
+
+
+def test_split_commands_pipeline_and_logical_continuation():
+    """Trailing |, &&, and || lines automatically join with the subsequent line."""
+    text = """cat file.txt |
+  grep foo &&
+  wc -l"""
+    cmds = split_commands(text)
+    assert len(cmds) == 1
+    assert cmds[0] == "cat file.txt | grep foo && wc -l"
+
+
+def test_split_commands_multiline_quotes_preserved():
+    """Newlines inside unclosed quotes are preserved as string data."""
+    text = """git commit -m "first line
+second line"
+git push"""
+    cmds = split_commands(text)
+    assert len(cmds) == 2
+    assert cmds[0] == 'git commit -m "first line\nsecond line"'
+    assert cmds[1] == "git push"
+
+
+def test_dispatch_kp_sequential_flag(monkeypatch):
+    """'kp -s <cmd>' must dispatch with is_concurrent=False."""
+    captured = {}
+
+    def mock_async(commands, is_concurrent, **kwargs):
+        captured["commands"] = commands
+        captured["is_concurrent"] = is_concurrent
+
+    monkeypatch.setattr("kapsel.core.block.runner.execute_block_async", mock_async)
+    code = dispatch_kps("kp -s echo 1\necho 2")
+    assert code == 0
+    assert captured["is_concurrent"] is False
+    assert captured["commands"] == ["echo 1", "echo 2"]
+
+
+def test_dispatch_kp_concurrent_flag(monkeypatch):
+    """'kp -c <cmd>' must dispatch with is_concurrent=True."""
+    captured = {}
+
+    def mock_async(commands, is_concurrent, **kwargs):
+        captured["commands"] = commands
+        captured["is_concurrent"] = is_concurrent
+
+    monkeypatch.setattr("kapsel.core.block.runner.execute_block_async", mock_async)
+    code = dispatch_kps("kp -c echo 1\necho 2")
+    assert code == 0
+    assert captured["is_concurrent"] is True
+    assert captured["commands"] == ["echo 1", "echo 2"]
+
+
+def test_dispatch_kp_default_sequential(monkeypatch):
+    """'kp <cmd>' without flag defaults to is_concurrent=False."""
+    captured = {}
+
+    def mock_async(commands, is_concurrent, **kwargs):
+        captured["commands"] = commands
+        captured["is_concurrent"] = is_concurrent
+
+    monkeypatch.setattr("kapsel.core.block.runner.execute_block_async", mock_async)
+    code = dispatch_kps("kp echo 1\necho 2")
+    assert code == 0
+    assert captured["is_concurrent"] is False
+    assert captured["commands"] == ["echo 1", "echo 2"]
+
+
+def test_dispatch_kp_empty_flag_errors():
+    """'kp -s' or 'kp -c' alone with no commands returns error code 1."""
+    assert dispatch_kps("kp -s") == 1
+    assert dispatch_kps("kp -c") == 1
+    assert dispatch_kps("kp --sequential") == 1
+    assert dispatch_kps("kp --concurrent") == 1

kapsel_cli-0.7.2/tests/test_multiline_passthrough.py

@@ -0,0 +1,83 @@
+"""
+Unit tests for multi-line command pass-through and built-in isolation in Kapsel.
+Ensures multi-line commands are not broken or space-collapsed by single-line built-in handlers.
+"""
+
+import os
+from pathlib import Path
+import pytest
+
+from kapsel.core.executor import CommandExecutor, ExecutionSummary
+
+
+def test_builtin_single_line_cd_intercepted():
+    """Single-line 'cd' command must be intercepted by _handle_builtin."""
+    executor = CommandExecutor(shell_name="pwsh")
+    res = executor._handle_builtin("cd .")
+    assert res is not None
+    assert isinstance(res, ExecutionSummary)
+    assert res.is_builtin is True
+
+
+def test_builtin_multiline_bypasses_interception():
+    """
+    Multi-line pasted commands (e.g. containing newlines) must bypass _handle_builtin
+    even if the first line starts with 'cd' or another builtin, preventing cmd.split()
+    from collapsing subsequent lines into space-delimited arguments.
+    """
+    executor = CommandExecutor(shell_name="pwsh")
+    multiline_cmd = "cd mydir\nnpm install\nnpm run dev"
+    res = executor._handle_builtin(multiline_cmd)
+    assert res is None
+
+
+def test_builtin_touch_multiline_bypasses_interception():
+    """Multi-line text starting with touch must not be collapsed by touch handler."""
+    executor = CommandExecutor(shell_name="pwsh")
+    multiline_touch = "touch file.txt\necho hello"
+    res = executor._handle_builtin(multiline_touch)
+    assert res is None
+
+
+def test_multiline_cmd_exe_formatting(monkeypatch):
+    """
+    In cmd.exe shell, multi-line commands should have non-empty lines joined
+    with ' & ' so cmd.exe /c executes them sequentially instead of truncating at newline.
+    """
+    executor = CommandExecutor(shell_name="cmd")
+    captured_args = []
+
+    def mock_run(args, **kwargs):
+        captured_args.extend(args)
+        class DummyProc:
+            returncode = 0
+        return DummyProc()
+
+    monkeypatch.setattr("subprocess.run", mock_run)
+    executor._run_in_host_shell("echo 1\necho 2\n\necho 3")
+
+    assert "cmd.exe" in captured_args[0]
+    assert captured_args[1] == "/c"
+    assert captured_args[2] == "echo 1 & echo 2 & echo 3"
+
+
+def test_multiline_pwsh_raw_passthrough(monkeypatch):
+    """
+    In PowerShell or POSIX shells, multi-line scripts should pass through intact
+    as raw text to preserve native multi-line syntax (loops, here-docs, etc.).
+    """
+    executor = CommandExecutor(shell_name="pwsh")
+    captured_args = []
+
+    def mock_run(args, **kwargs):
+        captured_args.extend(args)
+        class DummyProc:
+            returncode = 0
+        return DummyProc()
+
+    monkeypatch.setattr("subprocess.run", mock_run)
+    raw_script = "Write-Host 'line1'\nWrite-Host 'line2'"
+    executor._run_in_host_shell(raw_script)
+
+    assert "-Command" in captured_args
+    assert captured_args[-1] == raw_script