meridian-cli 0.2.16__tar.gz → 0.2.18__tar.gz

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.2.16
+Version: 0.2.18
 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

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.16"
+__version__ = "0.2.18"

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/cli/main.py

@@ -1117,7 +1117,8 @@ def main(argv: Sequence[str] | None = None) -> None:
 
     if cleaned_args and cleaned_args[0] == "mars":
         _emit_usage_command_invoked(cleaned_args)
-        _run_mars_passthrough(cleaned_args[1:], output_format=options.output.format)
+        with _directory_env_scope(options.project_root, options.directory_explicit):
+            _run_mars_passthrough(cleaned_args[1:], output_format=options.output.format)
 
     if effective_agent_mode and (not cleaned_args or _is_root_help_request(cleaned_args)):
         _print_agent_root_help()

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/harness/.context/CONTEXT.md

@@ -41,7 +41,7 @@ Per-harness mapping:
 - 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
+- Pi subprocess/connection: `pi --mode rpc` (JSON-RPC stdio); Pi has no subprocess-only path — the RPC mode is the connection
 
 ### Pi: Extension-Based Architecture
 

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/harness/AGENTS.md

@@ -40,7 +40,7 @@ Per-harness commands:
 - 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)
+- Pi subprocess/connection: `pi --mode rpc` (JSON-RPC stdio; Pi has no subprocess-only path — the RPC mode is the connection)
 
 ## Bootstrap Sequence Is Load-Bearing
 
@@ -103,7 +103,7 @@ unique — always check `event.harness_id`. `turn/completed` is Codex; OpenCode
 
 ## Adding a Harness
 
-Full guide: [`docs/harness-integration.md`](../../../docs/harness-integration.md) —
+Full guide: [`docs/harness-integration.md`](../../../../docs/harness-integration.md) —
 end-to-end with Pi as the worked example. Covers probing, adapter, projection,
 extraction, connection, semantics, wrapper/runtime, session parity, model/catalog,
 and verification.

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/harness/connections/.context/CONTEXT.md

@@ -2,7 +2,7 @@
 
 ## Architecture
 
-Four concrete transports share the `HarnessConnection[SpecT]` ABC from `base.py`:
+Five concrete transports share the `HarnessConnection[SpecT]` ABC from `base.py`:
 
 | File | Class | Transport | Protocol |
 |---|---|---|---|
@@ -10,30 +10,30 @@ Four concrete transports share the `HarnessConnection[SpecT]` ABC from `base.py`
 | `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) |
+| `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
-writes NDJSON to the subprocess stdin and reads NDJSON from stdout. The `--input-format
-stream-json --output-format stream-json` flags select this mode. Do not reach for a WS
-library when reading this file.
+**`claude_ws.py` is not a WebSocket.** The filename is historical. The connection
+writes NDJSON to subprocess stdin and reads NDJSON from stdout. The `--input-format
+stream-json --output-format stream-json` flags select this mode.
 
-**`pi_rpc.py` (`PiRpcConnection`) has two event sources.** Primary events arrive on stdout
-(JSON-RPC protocol). Lifecycle events arrive via a sidecar JSONL file (`pi_lifecycle_file.py`,
-`PiLifecycleEventTailer`). The `events()` async iterator merges both sources: it reads stdout
-lines and polls the sidecar file at 50ms intervals, yielding lifecycle events as they appear.
-Lifecycle events on stdout are silently dropped — the sidecar is authoritative.
+**`pi_rpc.py` is transport-only.** It reads Pi stdout JSONL, writes prompt/abort JSON,
+normalizes startup/error/session events, and emits Meridian phase diagnostics. It does
+not tail a separate lifecycle event file. Pi background-work authority lives in disk files written
+by Pi extensions and consumed by `lib/streaming/` (`PiDiskWatcher` / `PiQuiescenceTracker`).
+If a canonical Pi lifecycle event appears on stdout, `PiRpcConnection` logs and drops it;
+stdout is not the quiescence authority.
 
 **Pi startup requires an initial prompt.** Unlike other harnesses that can start in a
 listening state, spawned Pi RPC sessions must receive an initial user message. The
 connection validates this (`_validate_initial_prompt_requirement()`) and enforces a
-30-second timeout for the first response (`_FIRST_STDOUT_AFTER_INITIAL_PROMPT_TIMEOUT_SECONDS`).
+30-second timeout for the first stdout event after the prompt
+(`_FIRST_STDOUT_AFTER_INITIAL_PROMPT_TIMEOUT_SECONDS`).
 
 **`opencode_http.py` imports `OPENCODE_CONFIG_CONTENT_ENV` from
 `meridian.lib.launch.workspace_projection`** — a cross-layer dependency on `launch/`
 rather than `harness/`. This is intentional: `workspace_projection.py` was moved to
 `launch/` to break a circular bootstrap dependency. Connections modules may import
-shared constants from `launch/` when those constants live there by architecture
-necessity.
+shared constants from `launch/` when those constants live there by architecture necessity.
 
 ## Contracts
 
@@ -41,7 +41,7 @@ necessity.
 
 Required abstract methods — every subclass must implement all of these:
 
-- `state` property → `ConnectionState` (lifecycle: `created → starting → connected → stopping → stopped / failed`)
+- `state` property → `ConnectionState` (`created → starting → connected → stopping → stopped / failed`)
 - `harness_id`, `spawn_id`, `capabilities` properties
 - `session_id` → `str | None` (None until the transport delivers a session identifier)
 - `subprocess_pid` → `int | None`
@@ -65,40 +65,41 @@ supports the capability:
 
 `event_type` is scoped to the producing harness — it is **not globally unique**.
 Always qualify with `harness_id` before branching on `event_type`. Same-named events
-across harnesses have different semantics. See parent `.context/` for the full terminal
-event classification table.
+across harnesses have different semantics. See parent `.context/` for terminal event
+classification.
 
 ### ConnectionCapabilities
 
 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),
-  `"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.)
+- `mid_turn_injection`: `"queue"` (Claude/Pi), `"interrupt_restart"` (Codex), `"http_post"` (OpenCode),
+  `"queue"` (Cursor placeholder; `send_user_message` raises)
 - `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
-- `supported_startup_phases` — frozenset of phase names the adapter can observe
+- `supported_startup_phases` — phase names the adapter can observe
 
-### Pi Lifecycle Sidecar (pi_lifecycle_file.py)
+### Pi RPC Stdout Path
 
-`PiLifecycleEventTailer` provides incremental reading of the JSONL sidecar file
-written by Pi extensions. Key design points:
+`PiRpcConnection.events()` consumes exactly one stdout reader task. The event loop:
 
-- **Open/close lifecycle**: `open()` resets offset and partial buffer; `close()` releases
-  the file handle. The tailer is opened in `events()` and closed in `finally`.
-- **Incremental reading**: `read_ready_events()` seeks to the last-known offset and reads
-  new bytes. Partial lines (no trailing newline) are buffered for the next read.
-- **Catch-up at EOF**: `catch_up_to_eof()` reads all remaining events — called at
-  `agent_end` and at process exit to ensure no lifecycle events are missed.
-- **Parse validation**: each line goes through `parse_pi_lifecycle_event_line()` which
-  validates schema version, parent spawn ID, correlation ID, and event type allowlist.
-  Invalid lines become `meridian.lifecycle.parse_error` events on the stream.
+1. yields queued Meridian phase events (`process_spawned`, `initial_prompt_sent`, etc.);
+2. waits for the first stdout event with a 30-second deadline after the initial prompt;
+3. parses each stdout line as a Pi JSON object;
+4. emits `first_pi_event_received` and `session_event_seen` / `session_event_absent` phase events;
+5. yields normalized `HarnessEvent` objects to the streaming drain loop.
 
-The file is prepared by `prepare_pi_lifecycle_event_file()` — creates the file in the
-spawn log dir and sets `PI_LIFECYCLE_EVENT_FILE_ENV` for the Pi subprocess.
+Malformed stdout becomes `meridian.lifecycle.parse_error` so bad protocol output fails
+closed and stays visible. Canonical lifecycle-looking stdout events are ignored because
+current Pi coordination is disk-backed.
+
+### Pi Stop Path
+
+`stop(reason="quiescent")` sends `{"type": "abort"}` to the Pi subprocess, waits a
+5-second abort grace period, then escalates to process termination if Pi is still alive.
+The streaming layer records cleanup phases (`cleanup_running`, `cleanup_completed`,
+`cleanup_escalated`, `cleanup_failed`) around this transport stop.
 
 ### ServerRequestHandler — Policy Boundary
 
@@ -134,17 +135,15 @@ Both are 10 MiB uniform across adapters:
 ### Claude: Stdin/Stdout Instead of WebSocket
 
 Claude CLI supports `--input-format stream-json --output-format stream-json` for
-bidirectional NDJSON over process pipes. This avoids the need for a local HTTP server
-or WebSocket listener. The `_ws.py` filename predates this transport and was kept to
-avoid churn. The implementation has no WebSocket dependency.
+bidirectional NDJSON over process pipes. This avoids a local HTTP server or WebSocket
+listener. The `_ws.py` filename predates this transport and was kept to avoid churn.
 
 ### Codex: Port Pre-Reservation
 
 `CodexConnection` and `passthrough/codex.py` both use `socket.socket` to bind port 0
 and capture the ephemeral port before handing it to the subprocess. This is a TOCTOU
 race (the OS may reassign the port before `codex app-server` binds it). If that happens,
-`PortBindError` is raised and the caller retries with a new port. This is the intended
-recovery path — do not suppress `PortBindError`.
+`PortBindError` is raised and the caller retries with a new port.
 
 ### Observer Endpoint
 
@@ -152,38 +151,34 @@ Codex exposes a WebSocket URL (`ws://`); OpenCode exposes an HTTP URL (`http://`
 The `ObserverEndpoint` dataclass captures which transport and URL so `passthrough/` can
 build the correct TUI attach command without knowing connection internals.
 
-### Pi: Dual Event Sources
+### Pi: JSON-RPC Transport vs Quiescence State
 
-`PiRpcConnection.events()` merges two async event sources: stdout lines (primary
-JSON-RPC protocol stream) and the lifecycle sidecar file. The lifecycle sidecar is
-polled at 50ms intervals. The merge uses `asyncio.wait_for` with a unified timeout
-system — stdout reads are interleaved with sidecar polls, and timeouts trigger
-sidecar re-reads. This ensures lifecycle events are delivered promptly without
-starving the stdout stream.
+Pi's connection layer should stay a protocol adapter. It knows how to launch Pi RPC,
+send prompts/abort, read stdout JSONL, redact command history, and classify startup
+failure. It should not grow child-spawn or background-task policy. That policy belongs
+in `lib/streaming/` because it combines harness events with spawn records, bash records,
+notification markers, deadlines, and cleanup decisions.
 
 ### Pi: First-Event Timeout
 
-A spawned Pi session must respond to the initial prompt within 30 seconds. If no
-stdout event arrives in that window, the connection transitions to `failed` with
-reason `pi_rpc_no_response_after_initial_prompt`. This timeout is independent of
-the drain loop's child-wave timeout — it only applies during the connection startup
-phase, before the Pi process is known to be responsive.
+A spawned Pi session must respond to the initial prompt within 30 seconds. If no stdout
+event arrives in that window, the connection transitions to `failed` with reason
+`pi_rpc_no_response_after_initial_prompt`. This timeout is independent of the drain
+loop's child-wave timeout; it only applies before Pi is known responsive.
 
 ### Pi: Prompt Redaction
 
-PiCLI args may contain secrets (e.g., `--api-key`). `redact_pi_command_for_history()`
+Pi CLI args may contain secrets (e.g., `--api-key`). `redact_pi_command_for_history()`
 in `pi_lifecycle_events.py` scans argv tokens for secret-bearing flags and replaces
-their values with `<redacted>` before writing to the history log. This is the same
-pattern as Claude's credential redaction but operates on the raw argv list rather
-than the full command string.
+their values with `<redacted>` before writing to history.
 
 ## Related .context/
 
 - [../../.context/CONTEXT.md](../../.context/CONTEXT.md) — drain loop, terminal event semantics,
-  SpawnParams accounting
+  `SpawnParams` accounting
 - [../../passthrough/.context/CONTEXT.md](../../passthrough/.context/CONTEXT.md) — uses
   `ObserverEndpoint` and `ConnectionConfig` for TUI attach sequencing
 - [../../../../pi_runtime/.context/CONTEXT.md](../../../../pi_runtime/.context/CONTEXT.md) — Pi
-  extensions that write the lifecycle sidecar; build pipeline
-- [../../../../pi_runtime/extensions/meridian-lifecycle/.context/CONTEXT.md](../../../../pi_runtime/extensions/meridian-lifecycle/.context/CONTEXT.md) —
-  canonical lifecycle events consumed by the tailer
+  extensions that write disk-backed coordination state
+- [../../../streaming/.context/CONTEXT.md](../../../streaming/.context/CONTEXT.md) — Pi
+  quiescence drain policy that consumes disk state

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/harness/projections/.context/CONTEXT.md

@@ -13,7 +13,7 @@ project_codex_streaming.py  → CodexLaunchSpec → args + env   (codex app-serv
 project_opencode_subprocess.py → OpenCodeLaunchSpec → args + env  (opencode run)
 project_opencode_streaming.py  → OpenCodeLaunchSpec → args + env  (opencode serve)
 project_cursor.py          → ResolvedLaunchSpec → args        (cursor agent)
-project_pi_rpc.py          → ResolvedLaunchSpec → args + env (pi rpc --mode rpc)
+project_pi_rpc.py          → ResolvedLaunchSpec → args + env (pi --mode rpc)
 project_pi_native_tui.py   → ResolvedLaunchSpec → args + env (pi native TUI, primary only)
 pi_extension_projection.py → (extension dist artifacts → per-launch materialization, no spec dependency)
 ```

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/streaming/.context/CONTEXT.md

@@ -22,6 +22,18 @@ SpawnSession
   └─ control_actions: ControlActionCoordinator
 ```
 
+The implementation is split by responsibility:
+
+- `spawn_manager.py` — public registry/control API and generic live-spawn lifecycle
+- `spawn_dispatch.py` — connection creation/start dispatch
+- `spawn_drain_loop.py` — drain loop, persistence/observer/fan-out ordering, outcome priority
+- `spawn_session.py` — `SpawnSession` and `DrainOutcome` carriers
+- `pi_drain.py` — Pi spawned-session quiescence coordinator
+- `pi_subspawn_tracker.py` — Pi child-spawn and notification tracking
+- `disk_watcher.py` / `pi_quiescence.py` — disk-backed Pi quiescence inputs
+- `drain_wait.py` — bounded wait helpers for drain/cleanup paths
+- `pi_process_cleanup.py` — tracked Pi child process cleanup
+
 ## Contracts
 
 ### Drain Loop Ordering
@@ -64,7 +76,7 @@ from different event loops.
 ```
 start_spawn()
   → dispatch_start()           — creates HarnessConnection, calls connection.start()
-  → _drain_loop()              — asyncio.Task, until terminal or error
+  → SpawnDrainLoop.run()       — asyncio.Task, until terminal or error
   → ControlSocketServer.start() — binds per-spawn control endpoint
   → _start_heartbeat()         — asyncio.Task, touches sentinel every 30s
 ```
@@ -144,6 +156,12 @@ live in `pi_drain.py:PiDrainCoordinator`.
 behavior to `PiDrainCoordinator` unless the change is purely generic event persistence,
 observer dispatch, subscriber fan-out, heartbeat, or control-socket handling.
 
+`PiSubspawnTracker` owns the mutable child-spawn view inside the coordinator. It filters
+unresolved stale candidates to numeric allocated-looking `p*` directories, tracks
+active child ids, preserves idle epochs across disk wakeups, and marks whether a child
+wave needs re-arming. `PiDrainCoordinator` uses that summarized state to make deadline
+and finalization decisions.
+
 ### Disk State Authority
 
 Pi extensions coordinate with Python through disk files:
@@ -155,6 +173,11 @@ Pi extensions coordinate with Python through disk files:
 Stdout lifecycle-like messages are diagnostic. They are not the state authority for
 quiescence.
 
+Disk changes are not passive. `PiDiskWatcher` wakes the drain loop when a watched file
+changes, and the drain loop re-evaluates quiescence on those wakeups. Terminal-event
+micro-drain re-checks disk before accepting success so a just-written child row,
+bash update, or notification marker cannot be missed.
+
 ### Child Wave Timeout
 
 When the parent agent is idle and disk-backed child/background work is still pending,
@@ -168,7 +191,8 @@ When a terminal event arrives but quiescence is not yet confirmed, `PiDrainCoord
 enters micro-drain mode. It gives already-buffered or just-written disk/event activity a
 short chance to arrive before accepting the terminal event as the final outcome. This
 covers races where child state or notification markers land immediately after
-`agent_end`.
+`agent_end`. Micro-drain is disk-aware: timeout alone is not enough to finalize until
+the latest disk-backed state has been read.
 
 ### Pi Phase Events
 
@@ -195,7 +219,8 @@ These are written to `history.jsonl` alongside harness events and are visible in
 
 When the Pi process exits with active tracked children (crashed, killed, or otherwise
 terminated before quiescence), `PiDrainCoordinator` coordinates cleanup through the
-tracked child process metadata it has observed:
+tracked child process metadata it has observed. Process cleanup lives in
+`pi_process_cleanup.py` so `SpawnManager` does not own Pi-specific process-tree policy:
 
 - **POSIX**: iterates captured process group IDs, sends `SIGTERM` via `os.killpg()`,
   waits 250ms, confirms liveness with `os.killpg(pgid, 0)`, then sends `SIGKILL` if

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/streaming/AGENTS.md

@@ -6,8 +6,9 @@ core mechanism that moves events from the harness outward to persistence, observ
 and the subscriber queue.
 
 Mostly mechanism. Generic terminal behavior lives in `DrainPolicy`; Pi spawned-session
-quiescence is the explicit exception, isolated in `pi_drain.py` so Pi child-wave,
-notification, and disk-state policy does not sprawl through `SpawnManager`.
+quiescence is the explicit exception. Keep Pi child-wave, notification, disk-state,
+and tracked-process cleanup policy behind the Pi coordinator/tracker modules instead
+of growing `SpawnManager`.
 
 ## Mental Model
 
@@ -69,9 +70,15 @@ means the manager died or the spawn is orphaned.
 
 ## Entry Points
 
-- `spawn_manager.py` — `SpawnManager`: generic live-spawn lifecycle and event drain
+- `spawn_manager.py` — `SpawnManager`: public live-spawn registry/control API
+- `spawn_dispatch.py` — connection creation/start dispatch
+- `spawn_drain_loop.py` — event drain, persistence/observer/fan-out ordering, outcome priority
+- `spawn_session.py` — `SpawnSession`, `DrainOutcome`
 - `pi_drain.py` — `PiDrainCoordinator`: Pi spawned-session quiescence policy
+- `pi_subspawn_tracker.py` — Pi child-spawn, notification, and wave tracking
 - `disk_watcher.py` / `pi_quiescence.py` — disk-backed Pi background-work state
+- `drain_wait.py` — bounded drain/cleanup wait helpers
+- `pi_process_cleanup.py` — tracked Pi child process cleanup
 - `drain_policy.py` — `DrainPolicy`, `SingleTurnDrainPolicy`, `PersistentDrainPolicy`
 - `control_socket.py` — per-spawn inject endpoint
 - `event_observers.py` — `EventObserverRegistry`, `EventObserver`, `CallbackObserver`

{meridian_cli-0.2.16 → meridian_cli-0.2.18}/src/meridian/lib/streaming/__init__.py

@@ -6,7 +6,8 @@ from meridian.lib.streaming.types import ControlMessage, InjectResult
 
 if TYPE_CHECKING:
     from meridian.lib.streaming.control_socket import ControlSocketServer
-    from meridian.lib.streaming.spawn_manager import SpawnManager, SpawnSession
+    from meridian.lib.streaming.spawn_manager import SpawnManager
+    from meridian.lib.streaming.spawn_session import SpawnSession
 
 __all__ = [
     "ControlMessage",
@@ -23,7 +24,8 @@ def __getattr__(name: str) -> object:
 
         return ControlSocketServer
     if name in {"SpawnManager", "SpawnSession"}:
-        from meridian.lib.streaming.spawn_manager import SpawnManager, SpawnSession
+        from meridian.lib.streaming.spawn_manager import SpawnManager
+        from meridian.lib.streaming.spawn_session import SpawnSession
 
         return {"SpawnManager": SpawnManager, "SpawnSession": SpawnSession}[name]
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")