meridian-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/.gitignore

@@ -22,10 +22,12 @@ plan/
 .codex/
 .opencode/
 .pi/
+.cursor/
 
 err
 out
 .mars/
+mars.local.toml
 *.log
 .claude/scheduled_tasks.lock
 

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Orchestrate CLI + MCP server for multi-model agent workflows
 Project-URL: Homepage, https://github.com/haowjy/meridian-cli
 Project-URL: Repository, https://github.com/haowjy/meridian-cli
@@ -24,7 +24,7 @@ Requires-Dist: coolname>=4.0.0
 Requires-Dist: cyclopts>=3.0
 Requires-Dist: fastapi>=0.115
 Requires-Dist: markdown-it-py>=4.0
-Requires-Dist: mars-agents==0.6.1
+Requires-Dist: mars-agents==0.7.0
 Requires-Dist: mcp>=1.0
 Requires-Dist: pathspec>=1.1.0
 Requires-Dist: psutil>=7.2.2

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/pyproject.toml

@@ -24,7 +24,7 @@ dependencies = [
   "cyclopts>=3.0",
   "fastapi>=0.115",
   "markdown-it-py>=4.0",
-  "mars-agents==0.6.1",
+  "mars-agents==0.7.0",
   "mcp>=1.0",
   "pathspec>=1.1.0",
   "psutil>=7.2.2",
@@ -145,4 +145,5 @@ pythonpath = ["src"]
 [dependency-groups]
 dev = [
     "pytest-xdist>=3.8.0",
+    "ruff>=0.15.11",
 ]

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/app_tree.py

@@ -20,7 +20,7 @@ app = App(
         "  --fork preserves agent/model/skills identity. --fork-fresh allows\n"
         "  identity changes and may reduce prompt-cache locality. --from starts\n"
         "  fresh with prior context as reference material only.\n\n"
-        "Global harness selection: --harness (or prefix with claude/codex/opencode)\n\n"
+        "Global harness selection: --harness (or prefix with claude/codex/cursor/opencode)\n\n"
         "Bundled package manager: meridian mars ARGS...\n\n"
         'Run "meridian spawn -h" for subagent usage.\n'
     ),

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/bootstrap.py

@@ -56,7 +56,7 @@ _TOP_LEVEL_BOOL_FLAGS = frozenset(
         "--no-dry-run",
     }
 )
-HARNESS_SHORTCUT_NAMES = frozenset({"claude", "codex", "opencode", "pi"})
+HARNESS_SHORTCUT_NAMES = frozenset({"claude", "codex", "cursor", "opencode", "pi"})
 _CHAT_MANAGEMENT_SUBCOMMANDS = frozenset({"ls", "show", "log", "close"})
 _TOP_LEVEL_COMMAND_TOKENS = frozenset(COMMAND_CATALOG.top_level_names()) | HARNESS_SHORTCUT_NAMES
 

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/bootstrap_cmd.py

@@ -36,7 +36,10 @@ def register_bootstrap_command(
         ] = "",
         harness: Annotated[
             str | None,
-            Parameter(name="--harness", help="Force harness id (claude, codex, or opencode)."),
+            Parameter(
+                name="--harness",
+                help="Force harness id (claude, codex, cursor, opencode, or pi).",
+            ),
         ] = None,
         agent: Annotated[
             str | None,

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/chat_cmd.py

@@ -72,7 +72,7 @@ def _chat(
     ] = None,
     harness: Annotated[
         str | None,
-        Parameter(name="--harness", help="Harness id: claude, codex, or opencode."),
+        Parameter(name="--harness", help="Harness id: claude, codex, cursor, or opencode."),
     ] = None,
     agent: Annotated[
         str | None,

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/main.py

@@ -308,7 +308,10 @@ def root(
     ] = "",
     harness: Annotated[
         str | None,
-        Parameter(name="--harness", help="Force harness id (claude, codex, or opencode)."),
+        Parameter(
+            name="--harness",
+            help="Force harness id (claude, codex, cursor, opencode, or pi).",
+        ),
     ] = None,
     agent: Annotated[
         str | None,

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/misc_commands.py

@@ -88,7 +88,7 @@ def register_misc_commands(
         ] = "",
         harness: Annotated[
             str | None,
-            Parameter(name="--harness", help="Harness id: claude, codex, or opencode."),
+            Parameter(name="--harness", help="Harness id: claude, codex, cursor, or opencode."),
         ] = None,
         model: Annotated[
             str | None,

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/cli/startup/help.py

@@ -136,7 +136,7 @@ Options:
   --json            Emit command output as JSON.
   --format TEXT     Set output format: text or json.
   --config TEXT     Path to a user config TOML overlay.
-  --harness TEXT    Force harness id (claude, codex, or opencode).
+  --harness TEXT    Force harness id (claude, codex, cursor, opencode, or pi).
   --model, -m TEXT  Model id or alias for primary harness.
 
 Commands:
@@ -160,7 +160,7 @@ Primary launch/resume:
   identity changes and may reduce prompt-cache locality. --from starts
   fresh with prior context as reference material only.
 
-Global harness selection: --harness (or prefix with claude/codex/opencode)
+Global harness selection: --harness (or prefix with claude/codex/cursor/opencode)
 
 Bundled package manager: meridian mars ARGS...
 

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/catalog/model_aliases.py

@@ -63,13 +63,6 @@ class AliasEntry(BaseModel):
     def mars_provided_harness(self) -> HarnessId | None:
         return self.resolved_harness
 
-    def harness_model_id_for(self, harness: str) -> str | None:
-        """Return the harness-specific model ID for a given harness, or None."""
-        for path in self.runnable_paths:
-            if path.harness == harness:
-                return path.harness_model_id
-        return None
-
     def format_text(self, ctx: object | None = None) -> str:
         _ = ctx
         from meridian.lib.core.formatting import kv_block

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/core/types.py

@@ -9,6 +9,7 @@ class HarnessId(StrEnum):
 
     CLAUDE = "claude"
     CODEX = "codex"
+    CURSOR = "cursor"
     OPENCODE = "opencode"
     PI = "pi"
 

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/.context/CONTEXT.md

@@ -40,7 +40,8 @@ Per-harness mapping:
 - Claude connection: `claude -p --input-format stream-json --output-format stream-json --verbose` (stdin/stdout NDJSON, not WebSocket despite `claude_ws.py` name)
 - Codex subprocess: `codex exec --json`; connection: `codex app-server` (real WebSocket, JSON-RPC 2.0)
 - OpenCode subprocess: `opencode run`; connection: `opencode serve` (HTTP+SSE)
-- Pi subprocess: `pi rpc --mode rpc` (JSON-RPC stdio); Pi has no subprocess-only path — the RPC mode is the connection
+- Cursor subprocess: `cursor agent <prompt>` (stdout NDJSON, no connection path — subprocess-only)
+- Pi subprocess/connection: `pi rpc --mode rpc` (JSON-RPC stdio); Pi has no subprocess-only path — the RPC mode is the connection
 
 ### Pi: Extension-Based Architecture
 
@@ -107,12 +108,18 @@ Every `SpawnParams` field must appear in each adapter's `consumed_fields` **or**
 Currently ignored fields:
 - Claude ignores `report_output_path`, `task_cwd`, `context_from_payload`, `reference_items`
 - Codex ignores `skills`, `agent`, `task_cwd`, `context_from_payload`, `reference_items`
+- Cursor ignores `skills`, `agent`, `adhoc_agent_payload`, `control_root`,
+  `appended_system_prompt`, `report_output_path`, `user_turn_content`,
+  `context_from_payload`, `reference_items`, `continue_harness_session_id`,
+  `continue_fork`, `effort`
 
-`task_cwd` is ignored by harness adapters because the `control_root`/`task_cwd` split
+`task_cwd` is ignored by most harness adapters because the `control_root`/`task_cwd` split
 assigns different responsibilities to different layers: adapters consume `control_root`
 for spawn directory resolution and `--add-dir` roots, while `task_cwd` is injected into
 the agent's working context via system prompt in `bind_launch_context()` at the composition
-layer. The harness command never needs the raw `task_cwd` value.
+layer. The harness command never needs the raw `task_cwd` value. **Exception:** Cursor
+consumes `task_cwd` directly and projects it as `--workspace` — Cursor uses it as the
+working directory for the agent subprocess, not as a system-prompt injection.
 
 ### Projection Drift Guard
 
@@ -157,6 +164,8 @@ Key mappings:
 - Claude: `result` event with `is_error=True` → failed; `subtype in ("", "success")` and `terminal_reason in ("", "completed")` → succeeded
 - Codex: `turn/completed` → succeeded; `error/connectionClosed` → failed
 - OpenCode: `session.idle` → succeeded; `session.error` → failed
+- Cursor: `error/connectionClosed` → failed; no explicit success event — stdout EOF
+  + process exit code 0 is the success boundary (see `CursorSubprocessConnection.events()`).
 - Pi: `agent_end` → succeeded with quiescence check; `cancelled`/`error` → failed.
   The `agent_end` → success mapping is conditional: the drain loop only breaks when
   quiescence is also confirmed (no pending children/notifications). See `PiRpcQuiescenceDrainPolicy`.
@@ -209,6 +218,26 @@ was still initializing. The module only depends on `core.types` — it never dep
 on harness internals. `opencode_http.py` now imports `OPENCODE_CONFIG_CONTENT_ENV`
 from `meridian.lib.launch.workspace_projection`.
 
+### Cursor: Subprocess-Only, Read-Only stdout
+
+Cursor is a single-turn, subprocess-only harness. `cursor agent <prompt>` streams
+NDJSON events to stdout then exits — there is no stdin injection, no session resume,
+and no bidirectional transport. `CursorSubprocessConnection` is a connection adapter
+in name only: it reads stdout until EOF and process exit, then reports done.
+
+`task_cwd` is projected as `--workspace` rather than delegated to the system-prompt
+composition layer. Cursor's agent subprocess needs the workspace path as a CLI flag
+to set its working directory — system-prompt injection alone is insufficient.
+
+`effort` appears in `_DELEGATED_FIELDS` because Mars resolves `model + effort` →
+`harness_model` at bundle-build time. By the time `project_cursor_spec_to_cli_args()`
+runs, `spec.model` already contains the effort-resolved model string; `effort` has
+served its purpose and is not passed to the CLI.
+
+MVP scope exclusions (enforced by `_assert_supported_for_mvp()`): per-spawn
+`mcp_tools`, `continue_fork`, `continue_session_id`, and `interactive` all raise
+`HarnessCapabilityMismatch` at projection time.
+
 ### Pi: Quiescence Instead of Process Exit
 
 Pi spawned sessions don't exit when a task completes — they stay alive to track

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/AGENTS.md

@@ -39,6 +39,8 @@ Per-harness commands:
 - Claude connection: stdin/stdout NDJSON (not WebSocket despite `claude_ws.py` name)
 - Codex subprocess: `codex exec --json`; connection: `codex app-server` (real WebSocket, JSON-RPC 2.0)
 - OpenCode subprocess: `opencode run`; connection: `opencode serve` (HTTP+SSE)
+- Cursor subprocess: `cursor agent <prompt>` (stdout NDJSON, no connection path — subprocess-only)
+- Pi subprocess/connection: `pi rpc --mode rpc` (JSON-RPC stdio; Pi has no subprocess-only path — the RPC mode is the connection)
 
 ## Bootstrap Sequence Is Load-Bearing
 
@@ -74,7 +76,7 @@ unique — always check `event.harness_id`. `turn/completed` is Codex; OpenCode
 - `adapter.py` — `SpawnParams`, `HarnessAdapter`, `HarnessContract` and sub-models.
   Source of truth for what every adapter must implement.
 - `registry.py` — `HarnessRegistry`, `with_defaults()`. The global singleton.
-- `claude.py` / `codex.py` / `opencode.py` — concrete adapter implementations.
+- `claude.py` / `codex.py` / `opencode.py` / `cursor.py` — concrete adapter implementations.
 - `__init__.py` — `HARNESS_EXTENSION_TOUCHPOINTS` and `ensure_bootstrap()`.
   Read before adding a harness — lists every file that must be touched.
 - `semantics.py` — `terminal_outcome()`, `activity_transition()`, `clears_signal()`.

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/__init__.py

@@ -66,10 +66,12 @@ def _run_bootstrap() -> None:
     # 4) Cross-adapter SpawnParams accounting runs after all registrations.
     from meridian.lib.harness import claude as _claude
     from meridian.lib.harness import codex as _codex
+    from meridian.lib.harness import cursor as _cursor
     from meridian.lib.harness import opencode as _opencode
     from meridian.lib.harness import pi as _pi
 
     from meridian.lib.harness.projections import project_claude as _project_claude
+    from meridian.lib.harness.projections import project_cursor as _project_cursor
     from meridian.lib.harness.projections import (
         project_codex_streaming as _project_codex_streaming,
     )
@@ -86,6 +88,7 @@ def _run_bootstrap() -> None:
 
     from meridian.lib.harness.extractors import claude as _claude_extractor
     from meridian.lib.harness.extractors import codex as _codex_extractor
+    from meridian.lib.harness.extractors import cursor as _cursor_extractor
     from meridian.lib.harness.extractors import opencode as _opencode_extractor
     from meridian.lib.harness.extractors import pi as _pi_extractor
 
@@ -94,9 +97,11 @@ def _run_bootstrap() -> None:
     _bootstrap_imports = (
         _claude,
         _codex,
+        _cursor,
         _opencode,
         _pi,
         _project_claude,
+        _project_cursor,
         _project_codex_subprocess,
         _project_codex_streaming,
         _project_opencode_subprocess,
@@ -104,6 +109,7 @@ def _run_bootstrap() -> None:
         _project_pi_rpc,
         _claude_extractor,
         _codex_extractor,
+        _cursor_extractor,
         _opencode_extractor,
         _pi_extractor,
     )

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/adapter.py

@@ -46,8 +46,13 @@ def _empty_env_overrides() -> dict[str, str]:
 class ProjectionMode(StrEnum):
     """How one adapter projects semantic launch content onto harness channels."""
 
+    # Prompt is written to a temp prompt file and system instructions are
+    # appended into that file content before launch.
     PROMPT_FILE_APPEND_SYSTEM = "prompt_file_append_system"
+    # Harness accepts structured system/user fields separately.
     SYSTEM_FIELD_WITH_USER_TURN = "system_field_with_user_turn"
+    # Prompt is projected as one positional CLI argument.
+    POSITIONAL_PROMPT = "positional_prompt"
 
 
 class RuntimeHitlMode(StrEnum):

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/claude.py

@@ -268,7 +268,12 @@ class ClaudeAdapter(BaseHarnessAdapter[ResolvedLaunchSpec]):
         }
     )
     _EXPLICITLY_IGNORED_FIELDS: ClassVar[frozenset[str]] = frozenset(
-        {"report_output_path", "context_from_payload", "reference_items", "task_cwd"}
+        {
+            "report_output_path",
+            "context_from_payload",
+            "reference_items",
+            "task_cwd",
+        }
     )
 
     @property

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/codex.py

@@ -279,7 +279,13 @@ class CodexAdapter(BaseHarnessAdapter[ResolvedLaunchSpec]):
         }
     )
     _EXPLICITLY_IGNORED_FIELDS: ClassVar[frozenset[str]] = frozenset(
-        {"skills", "agent", "context_from_payload", "reference_items", "task_cwd"}
+        {
+            "skills",
+            "agent",
+            "context_from_payload",
+            "reference_items",
+            "task_cwd",
+        }
     )
 
     @property

{meridian_cli-0.2.0 → meridian_cli-0.2.2}/src/meridian/lib/harness/connections/.context/CONTEXT.md

@@ -2,13 +2,14 @@
 
 ## Architecture
 
-Three concrete transports share the `HarnessConnection[SpecT]` ABC from `base.py`:
+Four concrete transports share the `HarnessConnection[SpecT]` ABC from `base.py`:
 
 | File | Class | Transport | Protocol |
 |---|---|---|---|
 | `claude_ws.py` | `ClaudeConnection` | stdin/stdout NDJSON | stream-json |
 | `codex_ws.py` | `CodexConnection` | WebSocket | JSON-RPC 2.0 |
 | `opencode_http.py` | `OpenCodeConnection` | HTTP + SSE | REST + event stream |
+| `cursor_subprocess.py` | `CursorSubprocessConnection` | stdout NDJSON (read-only) | stream-json |
 | `pi_rpc.py` | `PiRpcConnection` | stdin/stdout JSONL | JSON-RPC (pi rpc mode) |
 
 **`claude_ws.py` is not a WebSocket.** The filename is a historical artifact. The connection
@@ -72,7 +73,10 @@ event classification table.
 Frozen dataclass declared as `_CAPABILITIES` on each concrete class. Set once at class
 definition, not per-instance. Fields:
 
-- `mid_turn_injection`: `"queue"` (Claude), `"interrupt_restart"` (Codex), `"http_post"` (OpenCode)
+- `mid_turn_injection`: `"queue"` (Claude), `"interrupt_restart"` (Codex), `"http_post"` (OpenCode),
+  `"queue"` (Cursor — **but `send_user_message` always raises**; injection is not implemented
+  for MVP. The type does not have an "unsupported" literal, so `"queue"` is used as a
+  placeholder. Do not call `send_user_message` on a Cursor connection.)
 - `supports_cancel`, `supports_steer`, `runtime_model_switch`, `structured_reasoning`
 - `supports_primary_observer` — only Codex and OpenCode
 - `supports_runtime_hitl` — runtime HITL through the connection; only Codex

meridian_cli-0.2.2/src/meridian/lib/harness/connections/cursor_subprocess.py

@@ -0,0 +1,273 @@
+"""Cursor subprocess transport connection over stdout NDJSON."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from asyncio.subprocess import DEVNULL, PIPE, Process
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from io import BufferedWriter
+from typing import Final, cast
+
+from meridian.lib.core.types import HarnessId, SpawnId
+from meridian.lib.harness.bundle import project_subprocess_spec
+from meridian.lib.harness.connections.base import (
+    ConnectionCapabilities,
+    ConnectionConfig,
+    ConnectionState,
+    HarnessConnection,
+    HarnessEvent,
+    StopProgressCallback,
+    StopResult,
+    validate_prompt_size,
+)
+from meridian.lib.launch.constants import BASE_COMMAND_CURSOR_SUBPROCESS, BLOCKED_CHILD_ENV_VARS
+from meridian.lib.launch.env import inherit_child_env
+from meridian.lib.launch.launch_types import ResolvedLaunchSpec
+from meridian.lib.state.paths import resolve_spawn_log_dir
+
+logger = logging.getLogger(__name__)
+
+_HARNESS_NAME: Final[str] = HarnessId.CURSOR.value
+_PROCESS_STOP_TIMEOUT_SECONDS: Final[float] = 10.0
+
+
+class CursorSubprocessConnection(HarnessConnection[ResolvedLaunchSpec]):
+    """Subprocess Cursor harness connection over stdout NDJSON."""
+
+    _CAPABILITIES = ConnectionCapabilities(
+        # Literal["queue"|"interrupt_restart"|"http_post"] has no "none"; Cursor is
+        # single-turn — send_user_message always raises, so injection is not usable.
+        mid_turn_injection="queue",
+        supports_steer=False,
+        supports_cancel=True,
+        runtime_model_switch=False,
+        structured_reasoning=False,
+        supports_primary_observer=False,
+        supports_runtime_hitl=False,
+    )
+
+    def __init__(self) -> None:
+        self._state: ConnectionState = "created"
+        self._spawn_id: SpawnId = SpawnId("")
+        self._process: Process | None = None
+        self._stderr_handle: BufferedWriter | None = None
+        self._event_stream_started = False
+        self._protocol_validated = False
+        self._stop_lock = asyncio.Lock()
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._state
+
+    @property
+    def harness_id(self) -> HarnessId:
+        return HarnessId.CURSOR
+
+    @property
+    def spawn_id(self) -> SpawnId:
+        return self._spawn_id
+
+    @property
+    def capabilities(self) -> ConnectionCapabilities:
+        return self._CAPABILITIES
+
+    @property
+    def session_id(self) -> str | None:
+        return None
+
+    @property
+    def subprocess_pid(self) -> int | None:
+        process = self._process
+        if process is None:
+            return None
+        return process.pid
+
+    async def start(self, config: ConnectionConfig, spec: ResolvedLaunchSpec) -> None:
+        if self._state != "created":
+            raise RuntimeError(f"Cannot start Cursor connection from state '{self._state}'")
+
+        validate_prompt_size(config)
+        self._spawn_id = config.spawn_id
+        self._set_state("starting")
+
+        spawn_dir = resolve_spawn_log_dir(config.control_root, config.spawn_id)
+        spawn_dir.mkdir(parents=True, exist_ok=True)
+        self._stderr_handle = (spawn_dir / "stderr.log").open("ab")
+
+        command = project_subprocess_spec(
+            self.harness_id,
+            spec,
+            base_command=BASE_COMMAND_CURSOR_SUBPROCESS,
+        )
+        env = inherit_child_env(
+            os.environ,
+            config.env_overrides,
+            blocked=BLOCKED_CHILD_ENV_VARS,
+        )
+
+        try:
+            self._process = await asyncio.create_subprocess_exec(
+                *command,
+                cwd=str(config.control_root),
+                env=env,
+                stdin=DEVNULL,
+                stdout=PIPE,
+                stderr=self._stderr_handle,
+            )
+            self._set_state("connected")
+        except Exception:
+            self._set_state("failed")
+            await self._cleanup_resources(terminate_process=True)
+            raise
+
+    async def stop(
+        self,
+        *,
+        reason: str | None = None,
+        progress: StopProgressCallback | None = None,
+    ) -> StopResult:
+        _ = reason, progress
+        async with self._stop_lock:
+            if self._state == "stopped":
+                return StopResult()
+            if self._state not in {"stopping", "failed"}:
+                self._set_state("stopping")
+            await self._cleanup_resources(terminate_process=True)
+            self._set_state("stopped")
+            return StopResult()
+
+    def health(self) -> bool:
+        return self._state == "connected"
+
+    async def send_user_message(self, text: str) -> None:
+        _ = text
+        raise RuntimeError(
+            "Cursor subprocess transport does not support live user-message injection"
+        )
+
+    async def send_cancel(self) -> None:
+        if self._state == "stopped":
+            return
+        if self._state != "failed":
+            self._set_state("stopping")
+        await self._terminate_process()
+
+    async def events(self) -> AsyncIterator[HarnessEvent]:
+        process = self._process
+        if process is None:
+            return
+        stdout = process.stdout
+        if stdout is None:
+            return
+        if self._event_stream_started:
+            raise RuntimeError("events() iterator already consumed")
+        self._event_stream_started = True
+
+        while True:
+            try:
+                line_bytes = await stdout.readline()
+            except Exception as exc:
+                if self._state not in {"stopping", "stopped"}:
+                    detail = f"Failed to read Cursor stdout: {exc}"
+                    self._set_state("failed")
+                    yield self._error_event(detail)
+                return
+
+            if not line_bytes:
+                return_code = process.returncode
+                if return_code is None:
+                    return_code = await process.wait()
+                if return_code != 0 and self._state not in {"stopping", "stopped"}:
+                    detail = f"Cursor subprocess exited with code {return_code}."
+                    self._set_state("failed")
+                    yield self._error_event(detail)
+                return
+
+            raw_text = line_bytes.decode("utf-8", errors="replace").rstrip("\n")
+            if not raw_text.strip():
+                continue
+            event = self._parse_stdout_line(raw_text)
+            if event is None:
+                if self._protocol_validated:
+                    continue
+                detail = (
+                    "Cursor protocol mismatch: expected NDJSON object with non-empty string "
+                    f"'type', got: {raw_text.strip()!r}"
+                )
+                self._set_state("failed")
+                yield self._error_event(detail, raw_text=raw_text)
+                return
+
+            self._protocol_validated = True
+            yield event
+
+    def _parse_stdout_line(self, raw_text: str) -> HarnessEvent | None:
+        payload_text = raw_text.strip()
+        if not payload_text:
+            return None
+        try:
+            payload_obj = json.loads(payload_text)
+        except json.JSONDecodeError:
+            logger.warning("Skipping malformed Cursor stdout line: %s", payload_text)
+            return None
+        if not isinstance(payload_obj, dict):
+            logger.warning("Skipping non-object Cursor stdout line: %s", payload_text)
+            return None
+
+        payload = cast("dict[str, object]", payload_obj)
+        raw_event_type = payload.get("type")
+        if not isinstance(raw_event_type, str) or not raw_event_type.strip():
+            logger.warning(
+                "Skipping Cursor stdout line without string 'type': %s",
+                payload_text,
+            )
+            return None
+
+        return HarnessEvent(
+            event_type=raw_event_type,
+            payload=payload,
+            harness_id=_HARNESS_NAME,
+            raw_text=raw_text,
+        )
+
+    def _set_state(self, next_state: ConnectionState) -> None:
+        if self._state == next_state:
+            return
+        self._state = next_state
+
+    async def _cleanup_resources(self, *, terminate_process: bool) -> None:
+        if terminate_process:
+            await self._terminate_process()
+        if self._stderr_handle is not None:
+            self._stderr_handle.close()
+            self._stderr_handle = None
+
+    async def _terminate_process(self) -> None:
+        process = self._process
+        if process is None:
+            return
+        if process.returncode is None:
+            with suppress(ProcessLookupError):
+                process.terminate()
+            try:
+                await asyncio.wait_for(process.wait(), timeout=_PROCESS_STOP_TIMEOUT_SECONDS)
+            except TimeoutError:
+                with suppress(ProcessLookupError):
+                    process.kill()
+                await process.wait()
+        self._process = None
+
+    def _error_event(self, message: str, *, raw_text: str | None = None) -> HarnessEvent:
+        return HarnessEvent(
+            event_type="error/connectionClosed",
+            payload={"type": "error", "message": message},
+            harness_id=_HARNESS_NAME,
+            raw_text=raw_text,
+        )
+
+
+__all__ = ["CursorSubprocessConnection"]