meridian-cli 0.2.26__tar.gz → 0.2.28__tar.gz

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.2.26
+Version: 0.2.28
 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.26 → meridian_cli-0.2.28}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.26"
+__version__ = "0.2.28"

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/core/.context/CONTEXT.md

@@ -148,6 +148,60 @@ root has already died must be reclaimed, not silently preserved forever.
 This function was removed — it had zero callers and was fully superseded by
 `reclaim_session_owned_scopes_for_chat()`. Do not reference it.
 
+## Spawn Lifecycle Decisions (`spawn_lifecycle.py`)
+
+`spawn_lifecycle.py` owns lifecycle resolution rules — pure stateless functions shared by the
+runner, reaper, and spawn application service. It does not own persistence or side effects.
+
+### Has Durable Report Completion
+
+`has_durable_report_completion(report_text)` returns True when a non-empty final report
+exists on disk and its content is not a terminal control frame:
+
+- Returns `False` for empty/whitespace strings, `None`, or `"# Spawn failed"` generated
+  markdown (runner-produced failure wrappers do not constitute durable completion).
+- Returns `False` for JSON payloads whose top-level or nested `event_type` / `event` /
+  `type` is `"cancelled"` or `"error"`.
+- Returns `True` for all other non-empty content (plain markdown, JSON payloads with
+  neutral/completion event types).
+
+### Centralized Completion-vs-Cancel Precedence
+
+`resolve_completion_cancel_precedence(*, durable_report_completion, cancel_requested, ...)`
+is the **single** shared resolution rule for the durable-completion-wins-over-late-cancel
+policy:
+
+- If a durable report exists → `ExecutionTerminalOutcome(status="succeeded", exit_code=0)`.
+- Else if cancellation was requested → `ExecutionTerminalOutcome(status="cancelled", ...)`.
+- Else → `None` (no opinion — caller must fall back to its own outcome).
+
+This helper is consumed by `SpawnApplicationService._force_cancel_convergence()`,
+`SpawnApplicationService.complete_execution()`, and `reaper._completion_or_cancel_decision()`.
+All three converge on the same precedence rule.
+
+### Execution Terminal State Resolution
+
+`resolve_execution_terminal_state()` normalizes raw execution facts into a terminal tuple
+`(status, exit_code, error)`. It takes `exit_code`, `failure_reason`, `cancelled`, and
+`durable_report_completion`:
+
+| durable completion | cancelled | exit_code | Result |
+|---|---|---|---|
+| True | any | any | `succeeded`, 0, None |
+| False | True | 143 | `cancelled`, 143, failure_reason |
+| False | True | 0 | `cancelled`, 130, failure_reason |
+| False | False | 0 | `succeeded`, 0, failure_reason |
+| False | False | non-zero | `failed`, exit_code, failure_reason |
+
+`resolve_execution_terminal_outcome(facts: ExecutionTerminalFacts)` wraps this for the
+runner path.
+
+### Reaper-Specific Resolved State
+
+`resolve_reconciled_terminal_state(*, durable_report_completion, fallback_error)` produces
+the terminal state for read-path reconciliation. Durable completion → `succeeded`; otherwise
+→ `failed` with the supplied fallback error.
+
 ## Related KB
 
 → [KB: codebase/guide.md](/home/jimyao/.meridian/git/meridian-flow-docs/kb/codebase/guide.md) — core module orientation and codebase navigation

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/core/lifecycle.py

@@ -468,6 +468,48 @@ class SpawnLifecycleService:
             )
             return True
 
+    def request_cancel(
+        self,
+        spawn_id: str,
+        *,
+        exit_code: int = 130,
+        error: str | None = "cancelled",
+        requested_by: Literal["user", "system"] = "user",
+        requested_at: str | None = None,
+        clock: Clock | None = None,
+    ) -> SpawnRecord | None:
+        """Persist pre-terminal spawn-level cancel intent."""
+
+        with bind_lifecycle_correlation(
+            self._correlation(operation="request_cancel", spawn_id=spawn_id)
+        ):
+            record = _spawn_store().record_cancel_intent(
+                self._runtime_root,
+                spawn_id,
+                exit_code=exit_code,
+                error=error,
+                requested_by=requested_by,
+                requested_at=requested_at,
+                clock=clock,
+            )
+            if record is None:
+                return None
+            self._emit_telemetry_event(
+                "spawn.updated",
+                record,
+                payload={
+                    "cancel_intent": {
+                        "requested_at": record.cancel_intent.requested_at,
+                        "exit_code": record.cancel_intent.exit_code,
+                        "error": record.cancel_intent.error,
+                        "requested_by": record.cancel_intent.requested_by,
+                    }
+                    if record.cancel_intent is not None
+                    else None,
+                },
+            )
+            return record
+
     def finalize(
         self,
         spawn_id: str,

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/core/process_cleanup.py

@@ -55,7 +55,7 @@ def terminate_spawn_scopes(
 
     spawn_id = SpawnId(spawn_record.id)
     for scope in scopes:
-        if is_scope_released(runtime_root, spawn_id, scope.scope_id):
+        if is_scope_released(runtime_root, spawn_id, scope.release_id):
             result = CleanupResult(
                 scope_id=scope.scope_id,
                 root_pid=scope.root_pid,
@@ -108,7 +108,7 @@ def terminate_spawn_scopes(
             continue
 
         result = terminate_scope_sync(scope, grace_seconds=grace_seconds, reason=reason)
-        mark_scope_released(runtime_root, spawn_id, scope.scope_id)
+        mark_scope_released(runtime_root, spawn_id, scope.release_id)
         logger.debug(
             "Terminated process scope.",
             spawn_id=spawn_record.id,
@@ -241,10 +241,10 @@ def cancel_managed_primary(
     # 1. Terminate launcher scope first (spawn_owned).
     for scope in scopes:
         if scope.scope_id == "launcher":
-            if is_scope_released(runtime_root, spawn_id, scope.scope_id):
+            if is_scope_released(runtime_root, spawn_id, scope.release_id):
                 continue
             result = terminate_scope_sync(scope, grace_seconds=grace_seconds, reason="cancel")
-            mark_scope_released(runtime_root, spawn_id, scope.scope_id)
+            mark_scope_released(runtime_root, spawn_id, scope.release_id)
             logger.debug(
                 "Terminated managed primary launcher scope.",
                 spawn_id=spawn_record.id,
@@ -267,7 +267,7 @@ def cancel_managed_primary(
     for scope in scopes:
         if scope.scope_id not in {"backend", "tui"}:
             continue
-        if is_scope_released(runtime_root, spawn_id, scope.scope_id):
+        if is_scope_released(runtime_root, spawn_id, scope.release_id):
             result = CleanupResult(
                 scope_id=scope.scope_id,
                 root_pid=scope.root_pid,
@@ -293,7 +293,7 @@ def cancel_managed_primary(
             results.append(result)
             continue
         result = terminate_scope_sync(scope, grace_seconds=grace_seconds, reason="cancel")
-        mark_scope_released(runtime_root, spawn_id, scope.scope_id)
+        mark_scope_released(runtime_root, spawn_id, scope.release_id)
         logger.debug(
             "Terminated managed primary runtime scope.",
             spawn_id=spawn_record.id,
@@ -333,10 +333,10 @@ def reclaim_session_owned_scopes_for_chat(
         for scope in scopes:
             if scope.owner_policy != "session_owned":
                 continue
-            if is_scope_released(runtime_root, spawn_id, scope.scope_id):
+            if is_scope_released(runtime_root, spawn_id, scope.release_id):
                 continue
             result = terminate_scope_sync(scope, grace_seconds=grace_seconds, reason="session_exit")
-            mark_scope_released(runtime_root, spawn_id, scope.scope_id)
+            mark_scope_released(runtime_root, spawn_id, scope.release_id)
             logger.debug(
                 "Reclaimed session-owned scope at session exit.",
                 spawn_id=record.id,

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/core/spawn_lifecycle.py

@@ -29,7 +29,6 @@ class ExecutionTerminalFacts:
     failure_reason: str | None = None
     cancellation_observed: bool = False
     durable_report_completion: bool = False
-    terminated_after_completion: bool = False
 
 
 @dataclass(frozen=True)
@@ -58,6 +57,9 @@ def has_durable_report_completion(report_text: str | None) -> bool:
         return False
 
     stripped = report_text.strip()
+    if stripped.lower().startswith("# spawn failed"):
+        return False
+
     try:
         payload_obj = json.loads(stripped)
     except json.JSONDecodeError:
@@ -98,11 +100,10 @@ def resolve_execution_terminal_state(
     failure_reason: str | None,
     cancelled: bool = False,
     durable_report_completion: bool = False,
-    terminated_after_completion: bool = False,
 ) -> tuple[SpawnStatus, int, str | None]:
     """Normalize one execution outcome into the persisted terminal state."""
 
-    if durable_report_completion and terminated_after_completion:
+    if durable_report_completion:
         return "succeeded", 0, None
     if cancelled:
         resolved_exit_code = exit_code if exit_code != 0 else 130
@@ -122,7 +123,6 @@ def resolve_execution_terminal_outcome(
         failure_reason=facts.failure_reason,
         cancelled=facts.cancellation_observed,
         durable_report_completion=facts.durable_report_completion,
-        terminated_after_completion=facts.terminated_after_completion,
     )
     return ExecutionTerminalOutcome(
         status=status,
@@ -131,6 +131,26 @@ def resolve_execution_terminal_outcome(
     )
 
 
+def resolve_completion_cancel_precedence(
+    *,
+    durable_report_completion: bool,
+    cancel_requested: bool,
+    cancel_exit_code: int = 130,
+    cancel_error: str | None = "cancelled",
+) -> ExecutionTerminalOutcome | None:
+    """Resolve the shared durable-completion-vs-late-cancel precedence rule."""
+
+    if durable_report_completion:
+        return ExecutionTerminalOutcome(status="succeeded", exit_code=0, error=None)
+    if cancel_requested:
+        return ExecutionTerminalOutcome(
+            status="cancelled",
+            exit_code=cancel_exit_code,
+            error=cancel_error,
+        )
+    return None
+
+
 def resolve_reconciled_terminal_state(
     *,
     durable_report_completion: bool,

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/core/spawn_service.py

@@ -17,6 +17,8 @@ from meridian.lib.core.lifecycle import SpawnLifecycleService
 from meridian.lib.core.spawn_lifecycle import (
     ExecutionTerminalFacts,
     ExecutionTerminalOutcome,
+    has_durable_report_completion,
+    resolve_completion_cancel_precedence,
     resolve_execution_terminal_outcome,
 )
 from meridian.lib.core.spawn_start import SpawnStartMetadata
@@ -48,7 +50,7 @@ from meridian.lib.launch.types import PrimarySessionMetadata
 from meridian.lib.state import spawn_store
 from meridian.lib.state.liveness import is_process_alive
 from meridian.lib.state.paths import RuntimePaths
-from meridian.lib.state.spawn.model import LaunchMode, SpawnOrigin
+from meridian.lib.state.spawn.model import APP_LAUNCH_MODE, LaunchMode, SpawnOrigin
 from meridian.lib.streaming.signal_canceller import CancelOutcome as SignalCancelOutcome
 
 if TYPE_CHECKING:
@@ -511,47 +513,84 @@ class SpawnApplicationService:
                 self._cleanup_orphan_managed_primary(spawn_id, record)
                 return _cancel_outcome_from_record(str(spawn_id), record, already_terminal=True)
 
-            is_finalizing = record.status == "finalizing"
-            from meridian.lib.state.primary_meta import read_primary_metadata
-
-            primary_metadata = read_primary_metadata(self._runtime_root, str(spawn_id))
-
-            if not is_finalizing:
-                if primary_metadata is not None and primary_metadata.managed_backend:
-                    return await self._cancel_managed_primary(spawn_id, record, primary_metadata)
-
-                from meridian.lib.streaming.signal_canceller import SignalCanceller
-
-                signal_outcome = await SignalCanceller(
-                    runtime_root=self._runtime_root,
-                    manager=self._spawn_manager,
-                    complete_spawn=self._complete_spawn_unlocked,
-                ).cancel(spawn_id)
-                latest = self.get_spawn(spawn_id) or record
-                return _cancel_outcome_from_signal(str(spawn_id), signal_outcome, latest)
-
-        if is_finalizing:
-            terminal = await self._wait_for_terminal(spawn_id, timeout=5.0)
-            lock = await self._locks.acquire(str(spawn_id))
-            async with lock:
-                latest = terminal or self.get_spawn(spawn_id) or record
-                if (
-                    terminal is None
-                    and latest.status == "finalizing"
-                    and latest.runner_exit_status is None
-                    and (
-                        (primary_metadata is not None and primary_metadata.managed_backend)
-                        or _is_managed_primary_candidate(latest)
-                    )
-                ):
-                    latest = await self._ensure_cancel_timeout_intent(spawn_id, latest)
-                return _cancel_outcome_from_record(
+            record = (
+                await asyncio.to_thread(
+                    self._lifecycle.request_cancel,
                     str(spawn_id),
-                    latest,
-                    already_terminal=terminal is not None,
-                    finalizing=terminal is None,
+                    exit_code=130,
+                    error="cancelled",
+                    requested_by="user",
                 )
-        raise RuntimeError("unreachable cancel state")
+                or self.get_spawn(spawn_id)
+                or record
+            )
+
+        from meridian.lib.state.primary_meta import read_primary_metadata
+
+        primary_metadata = read_primary_metadata(self._runtime_root, str(spawn_id))
+        signal_outcome: SignalCancelOutcome | None = None
+        delivery_finalizing = False
+        if primary_metadata is not None and primary_metadata.managed_backend:
+            managed_outcome = await self._cancel_managed_primary(
+                spawn_id, record, primary_metadata
+            )
+            delivery_finalizing = managed_outcome.finalizing
+        else:
+            from meridian.lib.streaming.signal_canceller import SignalCanceller
+
+            signal_outcome = await SignalCanceller(
+                runtime_root=self._runtime_root,
+                manager=self._spawn_manager,
+            ).cancel(spawn_id)
+
+        terminal = await self._wait_for_terminal(spawn_id, timeout=1.0)
+        if terminal is not None:
+            return _cancel_outcome_from_record(str(spawn_id), terminal, already_terminal=True)
+
+        lock = await self._locks.acquire(str(spawn_id))
+        async with lock:
+            latest = self.get_spawn(spawn_id) or record
+            if self.is_terminal(latest.status):
+                return _cancel_outcome_from_record(str(spawn_id), latest, already_terminal=True)
+            if not _has_live_execution_owner(latest, primary_metadata):
+                converged = await self._force_cancel_convergence(spawn_id, latest)
+                if converged is not None:
+                    return _cancel_outcome_from_record(
+                        str(spawn_id),
+                        converged,
+                        finalizing=not self.is_terminal(converged.status),
+                    )
+            latest = self.get_spawn(spawn_id) or latest
+            if delivery_finalizing or (signal_outcome is not None and signal_outcome.finalizing):
+                return _cancel_outcome_from_record(str(spawn_id), latest, finalizing=True)
+            if signal_outcome is None:
+                return _cancel_outcome_from_record(str(spawn_id), latest)
+            return _cancel_outcome_from_signal(str(spawn_id), signal_outcome, latest)
+
+    async def _force_cancel_convergence(
+        self,
+        spawn_id: SpawnId,
+        record: SpawnRecord,
+    ) -> SpawnRecord | None:
+        if self.is_terminal(record.status):
+            return record
+        intent = record.cancel_intent
+        resolved = resolve_completion_cancel_precedence(
+            durable_report_completion=_durable_report_completed(self._runtime_root, str(spawn_id)),
+            cancel_requested=True,
+            cancel_exit_code=intent.exit_code if intent is not None else 130,
+            cancel_error=intent.error if intent is not None else "cancelled",
+        )
+        if resolved is None:
+            return None
+        outcome = await self._complete_spawn_unlocked(
+            spawn_id,
+            resolved.status,
+            resolved.exit_code,
+            origin="reconciler" if resolved.status == "succeeded" else "cancel",
+            error=resolved.error,
+        )
+        return outcome.snapshot
 
     def _cleanup_orphan_managed_primary(
         self,
@@ -663,17 +702,6 @@ class SpawnApplicationService:
 
         if latest is None:
             latest = self.get_spawn(spawn_id) or record
-            if latest.status == "finalizing":
-                latest = await self._ensure_cancel_timeout_intent(spawn_id, latest)
-                return _cancel_outcome_from_record(str(spawn_id), latest, finalizing=True)
-            if self.is_terminal(latest.status):
-                return _cancel_outcome_from_record(
-                    str(spawn_id),
-                    latest,
-                    already_terminal=True,
-                )
-
-            latest = await self._ensure_cancel_timeout_intent(spawn_id, latest)
             if latest.status == "finalizing":
                 return _cancel_outcome_from_record(str(spawn_id), latest, finalizing=True)
             if self.is_terminal(latest.status):
@@ -685,11 +713,9 @@ class SpawnApplicationService:
 
             if self._lifecycle.mark_finalizing(str(spawn_id)):
                 latest = self.get_spawn(spawn_id) or latest
-                latest = await self._ensure_cancel_timeout_intent(spawn_id, latest)
             else:
                 latest = self.get_spawn(spawn_id) or latest
                 if latest.status == "finalizing":
-                    latest = await self._ensure_cancel_timeout_intent(spawn_id, latest)
                     return _cancel_outcome_from_record(str(spawn_id), latest, finalizing=True)
                 if self.is_terminal(latest.status):
                     return _cancel_outcome_from_record(
@@ -697,14 +723,6 @@ class SpawnApplicationService:
                         latest,
                         already_terminal=True,
                     )
-                self._lifecycle.finalize(
-                    str(spawn_id),
-                    "failed",
-                    1,
-                    origin="cancel",
-                    error="cancel_timeout",
-                )
-                latest = self.get_spawn(spawn_id) or latest
 
         # Best-effort: release any Phase-3 scope records so the reaper does not
         # re-terminate processes that the metadata path already signalled.
@@ -724,22 +742,6 @@ class SpawnApplicationService:
             finalizing=latest.status == "finalizing",
         )
 
-    async def _ensure_cancel_timeout_intent(
-        self,
-        spawn_id: SpawnId,
-        record: SpawnRecord,
-    ) -> SpawnRecord:
-        if self.is_terminal(record.status) or record.runner_exit_status is not None:
-            return record
-        await asyncio.to_thread(
-            self._lifecycle.record_runner_exit,
-            str(spawn_id),
-            status=cast("TerminalStatus", "cancelled"),
-            exit_code=130,
-            error="cancel_timeout",
-        )
-        return self.get_spawn(spawn_id) or record
-
     async def complete_spawn(
         self,
         spawn_id: SpawnId,
@@ -782,6 +784,17 @@ class SpawnApplicationService:
         resolved = resolve_execution_terminal_outcome(facts)
         lock = await self._locks.acquire(str(spawn_id))
         async with lock:
+            record = self.get_spawn(spawn_id)
+            if record is not None and record.cancel_intent is not None:
+                resolved = (
+                    resolve_completion_cancel_precedence(
+                        durable_report_completion=facts.durable_report_completion,
+                        cancel_requested=True,
+                        cancel_exit_code=record.cancel_intent.exit_code,
+                        cancel_error=record.cancel_intent.error,
+                    )
+                    or resolved
+                )
             completion = await self._complete_spawn_unlocked(
                 spawn_id,
                 resolved.status,
@@ -852,7 +865,7 @@ class SpawnApplicationService:
             scopes = read_scopes_from_disk(self._runtime_root, spawn_id)
             for scope in scopes:
                 if scope.owner_policy == "spawn_owned":
-                    mark_scope_released(self._runtime_root, spawn_id, scope.scope_id)
+                    mark_scope_released(self._runtime_root, spawn_id, scope.release_id)
         return CompleteSpawnOutcome(
             wrote=outcome.wrote,
             transitioned=outcome.transitioned,
@@ -1004,6 +1017,45 @@ def _is_managed_primary_candidate(record: SpawnRecord) -> bool:
     return record.kind == "primary" and harness in {"codex", "opencode"}
 
 
+def _durable_report_completed(runtime_root: Path, spawn_id: str) -> bool:
+    report_path = runtime_root / "spawns" / spawn_id / "report.md"
+    try:
+        report_text = report_path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return False
+    return has_durable_report_completion(report_text)
+
+
+def _has_live_execution_owner(
+    record: SpawnRecord,
+    primary_metadata: PrimaryMetadata | None,
+) -> bool:
+    if record.launch_mode == APP_LAUNCH_MODE:
+        return True
+    started_epoch = _started_at_epoch(record.started_at)
+    runner_created_at_epoch = record.runner_created_at_epoch or started_epoch
+    if record.runner_pid is not None and is_process_alive(
+        record.runner_pid,
+        created_after_epoch=runner_created_at_epoch,
+    ):
+        return True
+    if record.worker_pid is not None and is_process_alive(
+        record.worker_pid,
+        created_after_epoch=started_epoch,
+    ):
+        return True
+    if primary_metadata is None:
+        return False
+    for pid in (
+        primary_metadata.launcher_pid,
+        primary_metadata.backend_pid,
+        primary_metadata.tui_pid,
+    ):
+        if pid is not None and is_process_alive(pid, created_after_epoch=started_epoch):
+            return True
+    return False
+
+
 def _started_at_epoch(started_at: str | None) -> float | None:
     normalized = (started_at or "").strip()
     if not normalized:

{meridian_cli-0.2.26 → meridian_cli-0.2.28}/src/meridian/lib/launch/process/runner.py

@@ -563,9 +563,6 @@ def _finalize_lifecycle_and_observe_session(
                 ExecutionTerminalFacts(
                     exit_code=exit_code,
                     durable_report_completion=durable_report_completion,
-                    terminated_after_completion=(
-                        durable_report_completion and exit_code in (143, -15)
-                    ),
                 ),
                 origin="launcher",
                 duration_secs=duration,