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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.3.1
+Version: 0.3.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
@@ -41,6 +41,7 @@ Requires-Dist: httpx>=0.28; extra == 'app'
 Provides-Extra: dev
 Requires-Dist: pyright>=1.1.400; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
 Requires-Dist: pytest>=8.4.0; extra == 'dev'
 Requires-Dist: ruff>=0.12.0; extra == 'dev'
 Provides-Extra: templates

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/pyproject.toml

@@ -56,6 +56,7 @@ dev = [
   "pyright>=1.1.400",
   "pytest>=8.4.0",
   "pytest-asyncio>=0.24.0",
+  "pytest-timeout>=2.4.0",
   "ruff>=0.12.0",
 ]
 templates = [
@@ -140,9 +141,11 @@ ignore = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-ra -n auto"
+addopts = "-ra -n 4"
 asyncio_mode = "auto"
 pythonpath = ["src"]
+timeout = 60
+timeout_method = "thread"
 
 [dependency-groups]
 dev = [

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

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

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/cli/agent_help.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 _SPAWN_SUPPLEMENT = (
     "Agent Notes:\n\n"
-    "Lifecycle: queued → running → finalizing → succeeded | failed | cancelled.\n"
+    "Lifecycle: queued → running → finalizing → succeeded | failed | cancelled | timed_out.\n"
     "'finalizing' is transient — treat as active when polling.\n\n"
     "Which subcommand when:\n\n"
     "  show ID        Status, report, cost — first check for any spawn\n\n"

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/cli/spawn.py

@@ -37,6 +37,7 @@ from meridian.lib.ops.spawn.api import (
     SpawnForkInput,
     SpawnListInput,
     SpawnShowInput,
+    SpawnSignalInput,
     SpawnStatsInput,
     SpawnStatusInput,
     SpawnWaitInput,
@@ -46,9 +47,11 @@ from meridian.lib.ops.spawn.api import (
     spawn_children_sync,
     spawn_continue_sync,
     spawn_create_sync,
+    spawn_done_sync,
     spawn_files_sync,
     spawn_fork_sync,
     spawn_list_sync,
+    spawn_rearm_sync,
     spawn_show_sync,
     spawn_stats_sync,
     spawn_status_sync,
@@ -85,6 +88,20 @@ def _prepare_spawn_runtime_write() -> RuntimeWriteContext:
     return prepare_for_runtime_write(require_established_project_root())
 
 
+def _foreground_spawn_id_notifier(*, quiet: bool) -> Callable[[str], None] | None:
+    if quiet or _get_global_options().output.format == "json":
+        return None
+    sink = _current_output_sink()
+
+    def _notify(spawn_id: str) -> None:
+        sink.status(f"Spawn id: {spawn_id}")
+        from meridian.cli.output import flush_sink
+
+        flush_sink(sink)
+
+    return _notify
+
+
 def _spawn_create_exit_code(result: SpawnActionOutput) -> int:
     if result.exit_code is not None:
         return result.exit_code
@@ -558,6 +575,7 @@ def _spawn_create(
             ),
             sink=_current_output_sink(),
             prepared=_prepare_spawn_runtime_write(),
+            on_spawn_id=_foreground_spawn_id_notifier(quiet=quiet),
         )
     output_format = _get_global_options().output.format
     if output_format != "json" and metadata:
@@ -581,7 +599,10 @@ def _spawn_list(
         str | None,
         Parameter(
             name="--status",
-            help="Filter by status: queued, running, finalizing, succeeded, failed, cancelled.",
+            help=(
+                "Filter by status: queued, running, finalizing, succeeded, "
+                "failed, cancelled, timed_out."
+            ),
         ),
     ] = None,
     view: Annotated[
@@ -590,7 +611,7 @@ def _spawn_list(
             name="--view",
             help=(
                 "Preset list view: active, recent (recent active spawns), "
-                "all, running, queued, completed, failed, cancelled. "
+                "all, running, queued, completed, failed, cancelled, timed_out. "
                 "Default: active."
             ),
         ),
@@ -635,6 +656,7 @@ def _spawn_list(
         "completed": ("succeeded",),
         "failed": ("failed",),
         "cancelled": ("cancelled",),
+        "timed_out": ("timed_out",),
     }
     if normalized_view not in view_map:
         supported = ", ".join(view_map)
@@ -969,6 +991,42 @@ def _spawn_cancel_all(
         raise SystemExit(1)
 
 
+def _spawn_done(
+    emit: Any,
+    spawn_id: Annotated[
+        str | None,
+        Parameter(help="Spawn ID to finish (defaults to MERIDIAN_SPAWN_ID)."),
+    ] = None,
+) -> None:
+    result = spawn_done_sync(
+        SpawnSignalInput(spawn_id=spawn_id),
+        ctx=RuntimeContext.from_environment(),
+        sink=_current_output_sink(),
+        prepared=_prepare_spawn_runtime_write(),
+    )
+    emit(result)
+    if result.status == "failed":
+        raise SystemExit(1)
+
+
+def _spawn_rearm(
+    emit: Any,
+    spawn_id: Annotated[
+        str | None,
+        Parameter(help="Spawn ID to keep resident (defaults to MERIDIAN_SPAWN_ID)."),
+    ] = None,
+) -> None:
+    result = spawn_rearm_sync(
+        SpawnSignalInput(spawn_id=spawn_id),
+        ctx=RuntimeContext.from_environment(),
+        sink=_current_output_sink(),
+        prepared=_prepare_spawn_runtime_write(),
+    )
+    emit(result)
+    if result.status == "failed":
+        raise SystemExit(1)
+
+
 def _spawn_inject(
     spawn_id: Annotated[
         str,
@@ -1021,6 +1079,20 @@ def register_spawn_commands(app: App, emit: Emitter) -> tuple[set[str], dict[str
         emit=emit,
         default_handler=partial(_spawn_create, emit),
     )
+    app.command(
+        partial(_spawn_done, emit),
+        name="done",
+        help="Signal a resident spawn to finish successfully.",
+    )
+    registered.add("spawn.done")
+    descriptions["meridian.spawn.done"] = "Signal a resident spawn to finish successfully."
+    app.command(
+        partial(_spawn_rearm, emit),
+        name="rearm",
+        help="Signal a resident spawn to keep running.",
+    )
+    registered.add("spawn.rearm")
+    descriptions["meridian.spawn.rearm"] = "Signal a resident spawn to keep running."
     app.command(
         _spawn_inject,
         name="inject",

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/cli/utils.py

@@ -98,7 +98,6 @@ def missing_fork_session_error_with_discovery(
         return missing_fork_session_error(normalized_ref)
 
     from meridian.lib.ops.runtime import resolve_runtime_root_for_read
-    from meridian.lib.state import spawn_store
     from meridian.lib.state.primary_meta import read_primary_harness_session_discovery
 
     runtime_root = resolve_runtime_root_for_read(project_root)
@@ -111,7 +110,13 @@ def missing_fork_session_error_with_discovery(
             else (source_chat_id or "").strip()
         )
         if chat_ref:
-            chat_spawns = spawn_store.list_spawns(runtime_root, filters={"chat_id": chat_ref})
+            from meridian.lib.state import session_identity
+
+            owner_chat_id = session_identity.get_owner_chat_for_session(runtime_root, chat_ref)
+            lookup_chat_id = owner_chat_id or chat_ref
+            chat_spawns = session_identity.list_spawns_for_owner_chat(
+                runtime_root, lookup_chat_id
+            )
             pi_primary_spawns = [
                 row for row in chat_spawns if row.kind == "primary" and row.harness == "pi"
             ]

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/lib/config/settings.py

@@ -1337,6 +1337,30 @@ class MeridianConfig(BaseSettings):
             env_vars=("MERIDIAN_PI_CHILD_WAVE_TIMEOUT_SECONDS",),
         ),
     ] = None
+    resident_deadline_seconds: Annotated[
+        float | None,
+        config_field(
+            "timeouts.resident_deadline_seconds",
+            value_kind="float",
+            file_aliases=(
+                file_alias("timeouts", "resident_deadline_seconds"),
+                file_alias(None, "resident_deadline_seconds"),
+            ),
+            env_vars=("MERIDIAN_RESIDENT_DEADLINE_SECONDS",),
+        ),
+    ] = None
+    resident_poll_seconds: Annotated[
+        float | None,
+        config_field(
+            "timeouts.resident_poll_seconds",
+            value_kind="float",
+            file_aliases=(
+                file_alias("timeouts", "resident_poll_seconds"),
+                file_alias(None, "resident_poll_seconds"),
+            ),
+            env_vars=("MERIDIAN_RESIDENT_POLL_SECONDS",),
+        ),
+    ] = None
     pi_task_ping_interval_seconds: Annotated[
         float | None,
         config_field(

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/lib/core/domain.py

@@ -11,7 +11,9 @@ from meridian.lib.core.types import (
 )
 from meridian.lib.core.util import FormatContext
 
-SpawnStatus = Literal["queued", "running", "finalizing", "succeeded", "failed", "cancelled"]
+SpawnStatus = Literal[
+    "queued", "running", "finalizing", "succeeded", "failed", "cancelled", "timed_out"
+]
 
 
 class TokenUsage(BaseModel):

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/lib/core/lifecycle.py

@@ -35,6 +35,7 @@ from uuid import UUID
 import psutil
 import structlog
 
+from meridian.lib.core.spawn_lifecycle import TERMINAL_SPAWN_STATUSES, is_active_spawn_status
 from meridian.lib.core.spawn_start import SpawnStartMetadata
 from meridian.lib.core.telemetry import (
     CORE_EVENTS,
@@ -58,7 +59,6 @@ if TYPE_CHECKING:
     from meridian.lib.core.launch_policy_snapshot import LaunchPolicySnapshot
     from meridian.lib.hooks.dispatch import HookDispatcher
     from meridian.lib.launch.types import PrimarySessionMetadata
-    from meridian.lib.platform.process_scope.base import ProcessScopeSnapshot
     from meridian.lib.state.spawn.model import (
         LaunchMode,
         SpawnOrigin,
@@ -99,14 +99,14 @@ def _spawn_transitions() -> Any:
 # ---------------------------------------------------------------------------
 
 EventType = Literal["spawn.created", "spawn.running", "spawn.finalized"]
-TerminalStatus = Literal["succeeded", "failed", "cancelled"]
+TerminalStatus = Literal["succeeded", "failed", "cancelled", "timed_out"]
 TerminalOrigin = Literal["runner", "launcher", "cancel", "reconciler", "launch_failure"]
 
 
 type TerminalOutcomeCategory = Literal["succeeded"] | SpawnFailureCategory
 
 
-_TERMINAL_STATUS_VALUES: frozenset[str] = frozenset({"succeeded", "failed", "cancelled"})
+_TERMINAL_STATUS_VALUES: frozenset[str] = TERMINAL_SPAWN_STATUSES
 
 # ---------------------------------------------------------------------------
 # Event ID generation
@@ -235,6 +235,7 @@ class SpawnLifecycleService:
         self,
         *,
         chat_id: str,
+        owner_chat_id: str | None = None,
         parent_id: str | None = None,
         session_metadata: PrimarySessionMetadata,
         kind: str = "child",
@@ -262,6 +263,7 @@ class SpawnLifecycleService:
             result_id = _spawn_store().start_spawn(
                 self._runtime_root,
                 chat_id=chat_id,
+                owner_chat_id=owner_chat_id,
                 parent_id=parent_id,
                 model=session_metadata.model,
                 agent=session_metadata.agent,
@@ -306,13 +308,8 @@ class SpawnLifecycleService:
         worker_pid: int | None = None,
         runner_pid: int | None = None,
         runner_created_at_epoch: float | None = None,
-        scope_snapshot: ProcessScopeSnapshot | None = None,
     ) -> None:
-        """Mark a spawn as running and dispatch spawn.running.
-
-        ``scope_snapshot`` is accepted here as a threading seam for Phase 2
-        persistence; it is not used in the current phase.
-        """
+        """Mark a spawn as running and dispatch spawn.running."""
         with bind_lifecycle_correlation(
             self._correlation(operation="mark_running", spawn_id=spawn_id)
         ):
@@ -421,7 +418,7 @@ class SpawnLifecycleService:
             resolved_exited_at = exited_at or _utc_now_iso(clock)
             if self._owns_record(spawn_id):
                 assert self._record is not None
-                if self._record.status not in {"queued", "running", "finalizing"}:
+                if not is_active_spawn_status(self._record.status):
                     return False
                 updated = _spawn_transitions().apply_runner_exit(
                     self._record,
@@ -811,6 +808,7 @@ class SpawnLifecycleService:
             "spawn.succeeded",
             "spawn.failed",
             "spawn.cancelled",
+            "spawn.timed_out",
         }:
             payload = _terminal_telemetry_payload(record)
         _emit_lifecycle_event(event_name, record, payload=payload)

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/lib/core/process_cleanup.py

@@ -13,7 +13,11 @@ import structlog
 
 from meridian.lib.core.types import SpawnId
 from meridian.lib.platform.process_scope import terminate_scope_sync, terminate_tree_sync
-from meridian.lib.platform.process_scope.base import CleanupResult, ProcessScopeSnapshot
+from meridian.lib.platform.process_scope.base import (
+    CleanupResult,
+    ProcessScopeSnapshot,
+    birth_time_unverified,
+)
 from meridian.lib.state.process_scope_projection import (
     is_scope_released,
     mark_scope_released,
@@ -362,12 +366,17 @@ def reclaim_session_owned_scopes_for_chat(
     chat_id: str,
     *,
     grace_seconds: float = 5.0,
+    require_live_root: bool = False,
 ) -> list[CleanupResult]:
     """Reclaim all session_owned scopes on spawns belonging to a chat.
 
     Called at session exit. Terminates all unreleased session_owned scopes
     on spawns whose chat_id matches, regardless of which specific
     harness_session_id they reference.
+
+    Crash repair passes ``require_live_root=True`` because it runs after a
+    stale lease has been declared terminal; this keeps repair fail-closed when
+    the recorded root is gone or the PID has been reused.
     """
     from meridian.lib.state.spawn_store import list_spawns
 
@@ -381,6 +390,34 @@ def reclaim_session_owned_scopes_for_chat(
                 continue
             if is_scope_released(runtime_root, spawn_id, scope.release_id):
                 continue
+            if require_live_root:
+                skip_reason = _live_root_skip_reason(scope)
+                if skip_reason is not None:
+                    result = CleanupResult(
+                        scope_id=scope.scope_id,
+                        root_pid=scope.root_pid,
+                        descendant_count=None,
+                        reason="session_exit",
+                        grace_seconds=0.0,
+                        kill_escalated=False,
+                        degraded_fallback=False,
+                        skip_reason=skip_reason,
+                    )
+                    logger.debug(
+                        "Skipped session-owned scope reclaim during crash repair.",
+                        spawn_id=record.id,
+                        scope_id=scope.scope_id,
+                        root_pid=scope.root_pid,
+                        descendant_count=None,
+                        reason="session_exit",
+                        grace_seconds=0.0,
+                        kill_escalated=False,
+                        degraded_fallback=False,
+                        skip_reason=skip_reason,
+                        chat_id=chat_id,
+                    )
+                    results.append(result)
+                    continue
             result = terminate_scope_sync(scope, grace_seconds=grace_seconds, reason="session_exit")
             mark_scope_released(runtime_root, spawn_id, scope.release_id)
             logger.debug(
@@ -400,6 +437,18 @@ def reclaim_session_owned_scopes_for_chat(
     return results
 
 
+def _live_root_skip_reason(scope: ProcessScopeSnapshot) -> str | None:
+    if birth_time_unverified(scope.root_created_at_epoch):
+        return "birth_time_unverified_skip_crash_reclaim_to_avoid_pid_reuse_kill"
+    try:
+        actual = psutil.Process(scope.root_pid).create_time()
+    except (psutil.NoSuchProcess, psutil.AccessDenied, OSError):
+        return "root_not_alive"
+    if abs(actual - scope.root_created_at_epoch) > 1.0:
+        return "pid_reuse_detected"
+    return None
+
+
 __all__ = [
     "cancel_managed_primary",
     "reclaim_session_owned_scopes_for_chat",

{meridian_cli-0.3.1 → meridian_cli-0.3.2}/src/meridian/lib/core/spawn_lifecycle.py

@@ -12,13 +12,20 @@ from typing import cast
 
 from meridian.lib.core.domain import SpawnStatus
 
+# TODO(status-authority): SpawnStatus Literal in core/domain.py duplicates these sets.
+ALL_SPAWN_STATUSES: frozenset[str] = frozenset(
+    {"queued", "running", "finalizing", "succeeded", "failed", "cancelled", "timed_out"}
+)
 ACTIVE_SPAWN_STATUSES: frozenset[str] = frozenset({"queued", "running", "finalizing"})
-TERMINAL_SPAWN_STATUSES: frozenset[str] = frozenset({"succeeded", "failed", "cancelled"})
+TERMINAL_SPAWN_STATUSES: frozenset[str] = frozenset(
+    {"succeeded", "failed", "cancelled", "timed_out"}
+)
+FAILURE_SPAWN_STATUSES: frozenset[str] = frozenset({"failed", "timed_out"})
 
 _ALLOWED_TRANSITIONS: dict[str, frozenset[str]] = {
-    "queued": frozenset({"running", "succeeded", "failed", "cancelled"}),
-    "running": frozenset({"finalizing", "succeeded", "failed", "cancelled"}),
-    "finalizing": frozenset({"succeeded", "failed", "cancelled"}),
+    "queued": frozenset({"running", "succeeded", "failed", "cancelled", "timed_out"}),
+    "running": frozenset({"finalizing", "succeeded", "failed", "cancelled", "timed_out"}),
+    "finalizing": frozenset({"succeeded", "failed", "cancelled", "timed_out"}),
 }
 _CONTROL_EVENT_NAMES: frozenset[str] = frozenset(
     {"cancelled", "error", "error.connectionclosed"}
@@ -73,6 +80,7 @@ class ExecutionTerminalFacts:
     failure_reason: str | None = None
     cancellation_observed: bool = False
     durable_report_completion: bool = False
+    terminal_status: SpawnStatus | None = None
 
 
 @dataclass(frozen=True)
@@ -154,6 +162,18 @@ def is_active_spawn_status(status: str) -> bool:
     return status in ACTIVE_SPAWN_STATUSES
 
 
+def is_terminal_spawn_status(status: str) -> bool:
+    return status in TERMINAL_SPAWN_STATUSES
+
+
+def coerce_spawn_status(status: str) -> SpawnStatus:
+    """Preserve every known spawn status; recover unknown persisted values as failed."""
+
+    if status in ALL_SPAWN_STATUSES:
+        return cast("SpawnStatus", status)
+    return "failed"
+
+
 def validate_transition(from_status: SpawnStatus, to_status: SpawnStatus) -> None:
     allowed = _ALLOWED_TRANSITIONS.get(from_status, frozenset())
     if to_status not in allowed:
@@ -202,11 +222,16 @@ def resolve_execution_terminal_state(
     failure_reason: str | None,
     cancelled: bool = False,
     durable_report_completion: bool = False,
+    terminal_status: SpawnStatus | None = None,
 ) -> tuple[SpawnStatus, int, str | None]:
     """Normalize one execution outcome into the persisted terminal state."""
 
+    if terminal_status is not None and terminal_status != "succeeded":
+        return terminal_status, exit_code, failure_reason
     if durable_report_completion:
         return "succeeded", 0, None
+    if terminal_status is not None:
+        return terminal_status, exit_code, failure_reason
     if cancelled:
         resolved_exit_code = exit_code if exit_code != 0 else 130
         return "cancelled", resolved_exit_code, failure_reason
@@ -225,6 +250,7 @@ def resolve_execution_terminal_outcome(
         failure_reason=facts.failure_reason,
         cancelled=facts.cancellation_observed,
         durable_report_completion=facts.durable_report_completion,
+        terminal_status=facts.terminal_status,
     )
     return ExecutionTerminalOutcome(
         status=status,