meridian-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/.gitignore

@@ -17,6 +17,7 @@ smoke/
 tmp/
 .tmp-*/
 plan/
+temp/
 
 .orchestrate/
 .scratch/

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.3.2
+Version: 0.3.3
 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
@@ -54,18 +54,6 @@ Orchestrate AI coding agents across Claude Code, Codex, and OpenCode. Each model
 
 > **Early development.** Meridian is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
 
-## v0.1.0 Migration
-
-v0.1.0 removes all legacy state format support in the state layer.
-
-If you are upgrading from any pre-0.1.0 build, run:
-
-```bash
-rm -rf ~/.meridian
-```
-
-This is a clean break. There is no automatic migration.
-
 ## Why
 
 Claude Code is (supposed to be) the best way to run Claude. Codex CLI is often the best way to run GPT. Each provider's harness is optimized for their models — sandboxing, tool use, context handling, everything (supposedly).

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/README.md

@@ -4,18 +4,6 @@ Orchestrate AI coding agents across Claude Code, Codex, and OpenCode. Each model
 
 > **Early development.** Meridian is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
 
-## v0.1.0 Migration
-
-v0.1.0 removes all legacy state format support in the state layer.
-
-If you are upgrading from any pre-0.1.0 build, run:
-
-```bash
-rm -rf ~/.meridian
-```
-
-This is a clean break. There is no automatic migration.
-
 ## Why
 
 Claude Code is (supposed to be) the best way to run Claude. Codex CLI is often the best way to run GPT. Each provider's harness is optimized for their models — sandboxing, tool use, context handling, everything (supposedly).

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/harness/connections/.context/CONTEXT.md

@@ -45,12 +45,16 @@ Required abstract methods — every subclass must implement all of these:
 - `harness_id`, `spawn_id`, `capabilities` properties
 - `session_id` → `str | None` (None until the transport delivers a session identifier)
 - `subprocess_pid` → `int | None`
+- `resident_backend` → `ResidentBackendControl | None`; Codex/OpenCode expose
+  this for resident-until-done structured liveness and follow-up turns;
+  non-resident transports return None. This is the only public resident control
+  seam — callers do not reach for adapter-specific backend objects.
+- `scope_snapshot` → `ProcessScopeSnapshot | None`; managed backends expose the
+  process-scope facts captured at launch so primary attach and cleanup paths do
+  not reconstruct containment from PID fields.
 - `start(config, spec)` → async; raises if already started
 - `stop()` → async; idempotent
 - `health()` → bool
-- `resident_backend` → `ResidentBackendControl | None`; Codex/OpenCode expose
-  this for resident-until-done structured liveness and follow-up turns;
-  non-resident transports return None.
 - `send_user_message(text)` → async
 - `send_cancel()` → async
 - `events()` → `AsyncIterator[HarnessEvent]`
@@ -61,9 +65,6 @@ supports the capability:
 - `start_observer(config, spec)` — observer mode; guard with `capabilities.supports_primary_observer`
 - `configure_primary_runtime_requests(policy, event_sink, request_handler)`
 - `inject_runtime_event(event)`
-- `inject_turn(message)` — compatibility wrapper that delegates to
-  `resident_backend.begin_followup_turn`; transports should implement follow-up
-  turns through the resident backend seam instead of overriding this directly.
 - `respond_request(request_id, decision, payload)` — Codex only
 - `respond_user_input(request_id, answers)` — Codex only
 

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/harness/connections/AGENTS.md

@@ -11,12 +11,13 @@ Each transport wraps a long-lived process and turns its output into a stream of
 `HarnessEvent` objects consumed by the drain loop. The drain loop calls
 `terminal_outcome(event)` on each event; when that returns non-None, it breaks.
 
-Three transports exist, each different at the wire level:
+Transports differ at the wire level:
 - **Claude** (`claude_ws.py`): stdin/stdout NDJSON. No WebSocket despite the filename.
-- **Codex** (`codex_ws.py`): real WebSocket to `codex app-server`, JSON-RPC 2.0.
+- **Codex** (`codex_ws.py`): real WebSocket to a managed `codex app-server`, JSON-RPC 2.0.
   Codex's `requestApproval` and `requestUserInput` messages are dispatched to
   either `AutoAcceptHandler` (spawn paths) or `InteractiveHandler` (managed-primary attach).
-- **OpenCode** (`opencode_http.py`): HTTP+SSE to `opencode serve`.
+- **OpenCode** (`opencode_http.py`): HTTP+SSE to managed `opencode serve`.
+- **Cursor/Pi**: narrower spawned-session transports; no resident backend seam.
 
 ## Key Rules
 
@@ -31,6 +32,14 @@ distinction.
 implement all abstract methods, register in the bundle. Missing registration →
 `KeyError` at lookup time.
 
+**Resident control goes through `resident_backend`.** Do not add connection-level
+turn-injection or managed-backend shims. Codex/OpenCode return a
+`ResidentBackendControl`; callers use `begin_followup_turn()` through that seam.
+
+**Managed backend liveness belongs to `BackendLivenessPolicy`.** Adapters feed it
+activity, active turns, active requests, backend pid, and birth time; callers consume
+its structured decisions instead of inventing per-adapter alive checks.
+
 ## Entry Points
 
 - `base.py` — `HarnessConnection` ABC, `HarnessEvent`, `ConnectionCapabilities`,
@@ -39,6 +48,11 @@ implement all abstract methods, register in the bundle. Missing registration →
   `ResidentDrainCoordinator` for structured liveness, awaiting-done signaling,
   and follow-up turns. This seam's presence, not the harness id, selects the
   resident drain coordinator.
+- `liveness.py` — `BackendLivenessPolicy`, the shared managed-backend liveness
+  classifier for Codex/OpenCode.
+- `managed_backend.py` — single helper for launching managed backend subprocesses,
+  building `ProcessScopeSnapshot`, linking parent-death behavior when possible,
+  and recording `process_scopes.json`.
 - `__init__.py` — `get_connection_class(harness_id, transport_id)`.
 
 ## Depth

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/harness/projections/project_pi_native_tui.py

@@ -52,6 +52,7 @@ _DELEGATED_FIELDS: frozenset[str] = frozenset(
 
 _MANAGED_FLAG_ALIASES: dict[str, tuple[str, ...]] = {
     "--model": ("--model", "-m"),
+    "--thinking": ("--thinking",),
     "--append-system-prompt": ("--append-system-prompt",),
     "--session": ("--session",),
     "--fork": ("--fork",),
@@ -148,12 +149,13 @@ def _project_model_arg(spec: ResolvedLaunchSpec) -> str | None:
     if not model:
         return None
 
-    thinking = _EFFORT_TO_THINKING.get((spec.effort or "").strip().lower())
-    if thinking:
-        return f"{model}:{thinking}"
     return model
 
 
+def _project_thinking_level(spec: ResolvedLaunchSpec) -> str | None:
+    return _EFFORT_TO_THINKING.get((spec.effort or "").strip().lower())
+
+
 def project_pi_native_tui_spec_to_cli_args(
     spec: ResolvedLaunchSpec,
     *,
@@ -162,19 +164,26 @@ def project_pi_native_tui_spec_to_cli_args(
     """Project one ``ResolvedLaunchSpec`` into an ordered native Pi TUI command list."""
 
     command: list[str] = list(base_command)
+    passthrough_tail = spec.extra_args
 
     model_arg = _project_model_arg(spec)
     if model_arg is not None:
         command.extend(("--model", model_arg))
 
+    thinking_level = _project_thinking_level(spec)
+    model_override_in_passthrough = any(
+        _has_flag(passthrough_tail, alias) for alias in _MANAGED_FLAG_ALIASES["--model"]
+    )
+    emit_thinking = thinking_level is not None and not model_override_in_passthrough
+    if emit_thinking and thinking_level is not None:
+        command.extend(("--thinking", thinking_level))
+
     if spec.appended_system_prompt:
         command.extend(("--append-system-prompt", spec.appended_system_prompt))
 
     continue_session_id = (spec.continue_session_id or "").strip()
     has_continue_session = bool(continue_session_id)
     has_continue_fork = has_continue_session and spec.continue_fork
-
-    passthrough_tail = spec.extra_args
     _reject_mode_collisions(passthrough_tail)
     _reject_continue_collisions(passthrough_tail)
     _reject_extension_collisions(passthrough_tail)
@@ -184,6 +193,11 @@ def project_pi_native_tui_spec_to_cli_args(
         has_managed_value=model_arg is not None,
         passthrough_tail=passthrough_tail,
     )
+    _log_collision_if_needed(
+        managed_flag="--thinking",
+        has_managed_value=emit_thinking,
+        passthrough_tail=passthrough_tail,
+    )
     _log_collision_if_needed(
         managed_flag="--append-system-prompt",
         has_managed_value=bool(spec.appended_system_prompt),

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/harness/projections/project_pi_rpc.py

@@ -53,6 +53,7 @@ _DELEGATED_FIELDS: frozenset[str] = frozenset(
 
 _MANAGED_FLAG_ALIASES: dict[str, tuple[str, ...]] = {
     "--model": ("--model", "-m"),
+    "--thinking": ("--thinking",),
     "--append-system-prompt": ("--append-system-prompt",),
     "--session": ("--session",),
     "--fork": ("--fork",),
@@ -143,12 +144,13 @@ def _project_model_arg(spec: ResolvedLaunchSpec) -> str | None:
     if not model:
         return None
 
-    thinking = _EFFORT_TO_THINKING.get((spec.effort or "").strip().lower())
-    if thinking:
-        return f"{model}:{thinking}"
     return model
 
 
+def _project_thinking_level(spec: ResolvedLaunchSpec) -> str | None:
+    return _EFFORT_TO_THINKING.get((spec.effort or "").strip().lower())
+
+
 def _default_pi_session_dir() -> str:
     return str(resolve_pi_spawn_session_root())
 
@@ -161,19 +163,26 @@ def project_pi_spec_to_cli_args(
     """Project one ``ResolvedLaunchSpec`` into an ordered Pi RPC command list."""
 
     command: list[str] = list(base_command)
+    passthrough_tail = spec.extra_args
 
     model_arg = _project_model_arg(spec)
     if model_arg is not None:
         command.extend(("--model", model_arg))
 
+    thinking_level = _project_thinking_level(spec)
+    model_override_in_passthrough = any(
+        _has_flag(passthrough_tail, alias) for alias in _MANAGED_FLAG_ALIASES["--model"]
+    )
+    emit_thinking = thinking_level is not None and not model_override_in_passthrough
+    if emit_thinking and thinking_level is not None:
+        command.extend(("--thinking", thinking_level))
+
     if spec.appended_system_prompt:
         command.extend(("--append-system-prompt", spec.appended_system_prompt))
 
     continue_session_id = (spec.continue_session_id or "").strip()
     has_continue_session = bool(continue_session_id)
     has_continue_fork = has_continue_session and spec.continue_fork
-
-    passthrough_tail = spec.extra_args
     _reject_mode_collisions(passthrough_tail)
     _reject_extension_collisions(passthrough_tail)
     _reject_session_dir_collisions(passthrough_tail)
@@ -183,6 +192,11 @@ def project_pi_spec_to_cli_args(
         has_managed_value=model_arg is not None,
         passthrough_tail=passthrough_tail,
     )
+    _log_collision_if_needed(
+        managed_flag="--thinking",
+        has_managed_value=emit_thinking,
+        passthrough_tail=passthrough_tail,
+    )
     _log_collision_if_needed(
         managed_flag="--append-system-prompt",
         has_managed_value=bool(spec.appended_system_prompt),

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/state/.context/CONTEXT.md

@@ -124,8 +124,10 @@ Up to 10 retries; raises `RuntimeError` if exhausted.
 
 `spawn/terminal_policy.py:decide_terminal_write()` implements the projection
 authority rule: a runner-origin terminal write supersedes a reconciler-origin write
-on the same spawn. The reaper checks this before finalizing — it will not overwrite
-a spawn that the runner already terminated with a higher-authority origin.
+on the same spawn. Terminal statuses are `succeeded`, `failed`, `cancelled`, and
+`timed_out`; `timed_out` is a terminal failure class distinct from generic
+`failed`. The reaper checks authority before finalizing — it will not overwrite a
+spawn that the runner already terminated with a higher-authority origin.
 
 ### Reaper Behavior
 
@@ -137,13 +139,15 @@ Liveness check sequence per active spawn:
 1. Skip if status is already terminal.
 2. Skip if not a root-side-effect process (`is_root_side_effect_process()`).
 3. Skip if heartbeat age < 120s (recently alive).
-4. If status = `finalizing`: check `runner_exit_status`, then `cancel_intent`, then
-   durable report through `_completion_or_cancel_decision()`. If none apply → mark
-   failed (`orphan_finalization`).
-5. If status = `running` or `queued`: check if `runner_pid` is alive (using
+4. If status = `finalizing`: prefer durable report / cancel precedence and recorded
+   `runner_exit_status`; if neither proves a terminal outcome and activity is stale,
+   mark failed (`orphan_finalization`).
+5. If `runner_exit_status` is already recorded outside `finalizing`, preserve the
+   runner's terminal tuple after the short post-runner-exit grace.
+6. If status = `running` or `queued`: check if `runner_pid` is alive (using
    `liveness.py:is_process_alive()` with PID reuse guard via recorded start time).
-   If dead, check completion/cancel precedence, then recent activity, startup grace,
-   and finally mark failed (`orphan_run` or `missing_runner_pid`).
+   If dead, check completion/cancel precedence, recent activity, startup grace, and
+   finally mark failed (`orphan_run` or `missing_runner_pid`).
 
 `spawn_report_has_durable_completion(runtime_root, spawn_id)` reads `report.md` and returns True
 for non-empty report content that is not a terminal control frame (`cancelled`/`error`
@@ -160,9 +164,9 @@ violating the rule can let a late cancel downgrade a completed spawn.
 **Managed-primary orphan cleanup:**
 
 When a spawn is flagged as a potential managed primary (Codex / OpenCode kind=primary)
-and must be finalized as failed, `reconcile_active_spawn()` attempts process cleanup
-before writing the terminal state. The tier used depends on how much metadata is
-readable:
+and must be finalized as failed, `reconcile_active_spawn()` first uses recorded
+`process_scopes.json` cleanup, then attempts managed-primary cleanup before writing
+the terminal state. The managed tier used depends on how much metadata is readable:
 
 1. **Managed snapshot available** (`read_managed_primary_snapshot()` succeeded):
    `terminate_managed_primary_processes(managed_snapshot.metadata)` — terminates

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/state/AGENTS.md

@@ -79,8 +79,9 @@ Liveness sequence per active spawn:
 1. Skip if already terminal.
 2. Skip if heartbeat age < 120s.
 3. `finalizing` with durable report → mark succeeded.
-4. `finalizing` without durable report → mark failed (`orphan_finalization`).
+4. `finalizing` without durable report or recorded runner terminal tuple → mark failed (`orphan_finalization`).
 5. `running`/`queued` with dead PID (checked with start-time reuse guard) → mark failed (`orphan_run`).
+6. Timeouts are terminal `timed_out`, a failure class distinct from generic `failed`.
 
 ## Entry Points
 

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/streaming/.context/CONTEXT.md

@@ -12,6 +12,12 @@ SpawnManager
   ├─ _observers: EventObserverRegistry
   └─ _heartbeat_tasks: dict[SpawnId, Task]
 
+DrainPlan
+  ├─ coordinator: DrainCoordinator | None
+  ├─ policy: DrainPolicy
+  ├─ aux_wake / handle_aux_wake
+  └─ finalizer
+
 SpawnSession
   ├─ connection: HarnessConnection   ← live harness connection
   ├─ drain_task: Task                ← background drain loop
@@ -27,7 +33,9 @@ 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
+- `drain_coordinator.py` — `DrainPlan` plus the narrow `DrainCoordinator` seam
 - `spawn_session.py` — `SpawnSession` and `DrainOutcome` carriers
+- `resident_drain.py` — resident-backend descendant waiting and done-nudge model
 - `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
@@ -48,6 +56,18 @@ Persistence is synchronous and happens before any notification. 10 consecutive
 write failures abort the loop with a `failed` outcome. Do not reorder these stages
 — observers and the subscriber must only see events that are durably written.
 
+### DrainPlan Selection
+
+`SpawnManager._select_drain_plan()` returns the whole drain-loop configuration for
+one active spawn. Codex/OpenCode resident backends get a `ResidentDrainCoordinator`;
+Pi RPC gets `PiDrainCoordinator` plus disk-watcher aux wakes; plain streaming
+harnesses intentionally run with `DrainPlan(coordinator=None)`. There is no public
+no-op coordinator class — absence of a coordinator is the plain path.
+
+`DrainCoordinator` stays narrow: it observes events, handles terminal events,
+provides timeouts, classifies stream close, and handles stream exit. Constant
+configuration belongs in `DrainPlan`, not in coordinator methods.
+
 ### DrainOutcome Priority
 
 When the drain loop exits, the outcome is determined in this order:
@@ -130,9 +150,9 @@ Generic policies control terminal event behavior:
 
 `SingleTurnDrainPolicy` is the default. Pass `PersistentDrainPolicy` to
 `start_spawn(drain_policy=...)` for chat sessions where the harness stays alive
-across turns. Pi spawned-session behavior is intentionally not another generic
-policy flag: it is delegated to `PiDrainCoordinator`, because it needs disk-backed
-background-work state, child-wave deadlines, notification state, and cleanup decisions.
+across turns. Pi spawned-session behavior and resident descendant waiting are not
+generic policy flags: `SpawnManager` selects coordinators through `DrainPlan` when
+the connection exposes the needed seam.
 
 ## Pi RPC Quiescence Drain
 

{meridian_cli-0.3.2 → meridian_cli-0.3.3}/src/meridian/lib/streaming/AGENTS.md

@@ -5,10 +5,12 @@ The async backbone between a live harness connection and the rest of the system.
 core mechanism that moves events from the harness outward to persistence, observers,
 and the subscriber queue.
 
-Mostly mechanism. Generic terminal behavior lives in `DrainPolicy`; Pi spawned-session
-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`.
+Mostly mechanism. Generic terminal behavior lives in `DrainPolicy`; harness-specific
+completion waiting enters through `DrainPlan`. Plain streaming harnesses intentionally
+run with `coordinator=None`; Pi and resident Codex/OpenCode paths get narrow
+coordinators only when their connection exposes the needed seam. Keep Pi child-wave,
+notification, disk-state, resident-done nudges, and tracked-process cleanup policy
+behind the coordinator/tracker modules instead of growing `SpawnManager`.
 
 Resident drain selection is capability-driven: a connection participates in the
 resident descendant-wait path only when `connection.resident_backend` is present.
@@ -53,9 +55,9 @@ CLI paths: one short-lived instance per run.
 events are dropped on `QueueFull` (with telemetry). The sentinel evicts one item if
 needed to guarantee it gets through — without it, the subscriber hangs forever.
 
-## DrainPolicy
+## DrainPlan / DrainPolicy
 
-Governs terminal event behavior:
+`DrainPlan` carries the selected coordinator, policy, aux wake, and finalizer for one active spawn. Its `coordinator=None` value is the plain path. `DrainPolicy` governs terminal event behavior:
 
 | Policy | On terminal event | Action |
 |---|---|---|