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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.2.2
+Version: 0.2.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
@@ -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.7.0
+Requires-Dist: mars-agents==0.7.1
 Requires-Dist: mcp>=1.0
 Requires-Dist: pathspec>=1.1.0
 Requires-Dist: psutil>=7.2.2
@@ -192,7 +192,7 @@ graph TB
 uv sync --extra dev
 uv run ruff check .
 uv run pytest-llm
-uv run pyright
+uv run --extra dev python -m pyright
 ```
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for full dev setup.

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/README.md

@@ -144,7 +144,7 @@ graph TB
 uv sync --extra dev
 uv run ruff check .
 uv run pytest-llm
-uv run pyright
+uv run --extra dev python -m pyright
 ```
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for full dev setup.

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

@@ -24,7 +24,7 @@ dependencies = [
   "cyclopts>=3.0",
   "fastapi>=0.115",
   "markdown-it-py>=4.0",
-  "mars-agents==0.7.0",
+  "mars-agents==0.7.1",
   "mcp>=1.0",
   "pathspec>=1.1.0",
   "psutil>=7.2.2",
@@ -44,7 +44,6 @@ Issues = "https://github.com/haowjy/meridian-cli/issues"
 
 [project.scripts]
 meridian = "meridian.cli.entrypoint:main"
-pyright = "pyright.cli:entrypoint"
 pytests = "meridian.dev.pytests:main"
 pytest-llm = "meridian.dev.pytests:main"
 

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

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

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/cli/spawn.py

@@ -275,7 +275,10 @@ def _spawn_create(
         bool | None,
         Parameter(
             name="--worktree",
-            help="Require and use the selected work item's configured worktree path as task cwd.",
+            help=(
+                "Ensure and use the selected work item's Meridian-managed canonical "
+                "worktree as task cwd."
+            ),
         ),
     ] = None,
     no_worktree: Annotated[
@@ -285,6 +288,16 @@ def _spawn_create(
             help="Force authority root as task cwd, ignoring any configured worktree path.",
         ),
     ] = False,
+    repo: Annotated[
+        str | None,
+        Parameter(
+            name="--repo",
+            help=(
+                "Target implementation repository path or workspace alias for first "
+                "managed worktree ensure."
+            ),
+        ),
+    ] = None,
     dry_run: Annotated[
         bool,
         Parameter(name="--dry-run", help="Preview without executing harness."),
@@ -478,6 +491,7 @@ def _spawn_create(
                 desc=desc,
                 work=work,
                 worktree=worktree_intent,
+                repo=repo,
                 **shared_launch_kwargs,
             ),
             sink=_current_output_sink(),
@@ -497,6 +511,7 @@ def _spawn_create(
                 desc=desc,
                 work=work,
                 worktree=worktree_intent,
+                repo=repo,
                 **shared_launch_kwargs,
             ),
             sink=_current_output_sink(),
@@ -516,6 +531,7 @@ def _spawn_create(
                 goal=resolved_goal,
                 work=work,
                 worktree=worktree_intent,
+                repo=repo,
                 **shared_launch_kwargs,
             ),
             sink=_current_output_sink(),

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/cli/startup/catalog.py

@@ -383,6 +383,11 @@ _COMMAND_DESCRIPTORS: tuple[CommandDescriptor, ...] = (
     _write_runtime(("work", "delete"), "Delete work item.", extension_ref="meridian.work.delete"),
     _write_runtime(("work", "rename"), "Rename work item.", extension_ref="meridian.work.rename"),
     _write_runtime(("work", "clear"), "Clear current work.", extension_ref="meridian.work.clear"),
+    _write_runtime(
+        ("work", "worktree"),
+        "Show or ensure canonical managed worktree state.",
+        extension_ref="meridian.work.worktree",
+    ),
     _write_runtime(
         ("work", "set-worktree"),
         "Assign an existing worktree path to a work item.",

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/cli/work_cmd.py

@@ -37,6 +37,7 @@ from meridian.lib.ops.work_lifecycle import (
     WorkStartInput,
     WorkSwitchInput,
     WorkUpdateInput,
+    WorkWorktreeInput,
     work_clear_sync,
     work_clear_worktree_sync,
     work_delete_sync,
@@ -47,6 +48,7 @@ from meridian.lib.ops.work_lifecycle import (
     work_start_sync,
     work_switch_sync,
     work_update_sync,
+    work_worktree_sync,
 )
 
 Emitter = Callable[[Any], None]
@@ -76,12 +78,22 @@ def _work_start(
     ] = None,
     worktree: Annotated[
         bool | None,
-        Parameter(name="--worktree", help="Create a git worktree for this work item."),
+        Parameter(
+            name="--worktree",
+            help="Ensure Meridian-managed canonical isolation for this work item.",
+        ),
     ] = None,
     no_worktree: Annotated[
         bool,
         Parameter(name="--no-worktree", help="Skip worktree creation even if default is set."),
     ] = False,
+    repo: Annotated[
+        str | None,
+        Parameter(
+            name="--repo",
+            help="Target implementation repository path or [workspace.<name>] alias.",
+        ),
+    ] = None,
 ) -> None:
     # Resolve explicit worktree intent from the two flags.
     # --no-worktree wins over --worktree if both are passed (degenerate case).
@@ -100,6 +112,7 @@ def _work_start(
                 goal=goal,
                 chat_id=_runtime_chat_id(),
                 worktree=worktree_intent,
+                repo=repo,
             )
         )
     )
@@ -277,6 +290,39 @@ def _work_clear(emit: Emitter) -> None:
     emit(work_clear_sync(WorkClearInput(chat_id=_runtime_chat_id())))
 
 
+def _work_worktree(
+    emit: Emitter,
+    work_id: Annotated[
+        str,
+        Parameter(help="Optional work item id. Defaults to active work for this session."),
+    ] = "",
+    ensure: Annotated[
+        bool,
+        Parameter(
+            name="--ensure",
+            help="Create/recover Meridian's canonical managed worktree if needed.",
+        ),
+    ] = False,
+    repo: Annotated[
+        str | None,
+        Parameter(
+            name="--repo",
+            help="Target implementation repository path or [workspace.<name>] alias.",
+        ),
+    ] = None,
+) -> None:
+    emit(
+        work_worktree_sync(
+            WorkWorktreeInput(
+                work_id=work_id,
+                ensure=ensure,
+                repo=repo,
+                chat_id=_runtime_chat_id(),
+            )
+        )
+    )
+
+
 def _work_set_worktree(
     emit: Emitter,
     work_id: Annotated[
@@ -326,6 +372,7 @@ def register_work_commands(app: App, emit: Emitter) -> tuple[set[str], dict[str,
         "meridian.work.reopen": lambda: partial(_work_reopen, emit),
         "meridian.work.rename": lambda: partial(_work_rename, emit),
         "meridian.work.clear": lambda: partial(_work_clear, emit),
+        "meridian.work.worktree": lambda: partial(_work_worktree, emit),
         "meridian.work.set-worktree": lambda: partial(_work_set_worktree, emit),
         "meridian.work.clear-worktree": lambda: partial(_work_clear_worktree, emit),
     }

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/.context/CONTEXT.md

@@ -77,9 +77,13 @@ use `SPEC_ONLY`. Do not set `REQUIRED` on execution paths.
 
 ### Worktree Lifecycle Protection
 
-`ops/worktree_lifecycle.py` coordinates git worktree creation, restoration, cleanup,
-and crash recovery. It is intentionally limited to git/worktree concerns and returns
-structured results for callers (`work_lifecycle.py`) to persist and present elsewhere.
+`ops/worktree_lifecycle.py` is the raw git worktree layer — it owns creation,
+restoration, cleanup, and crash recovery. It is intentionally limited to git/worktree
+concerns and returns structured results for callers to persist elsewhere.
+
+`ops/worktree_ensure.py` sits above it and provides high-level ensure semantics used
+by `work_worktree.py` and spawn logic. The split is: lifecycle owns raw git operations,
+ensure owns state management and idempotency.
 
 **Destructive operations guard against three conditions:**
 
@@ -124,6 +128,45 @@ type (e.g., `{"agents": [...], "skills": [...]}`). This avoids coupling Python
 to the mars JSON report shape — new content types (hooks, MCP servers, etc.) are
 automatically counted without Python model changes.
 
+### ops/worktree_ensure.py — Managed Worktree Orchestration
+
+`worktree_ensure.py` sits above `worktree_lifecycle.py` and provides high-level
+ensure semantics with state management, dry-run support, and session-scoped temporary
+worktrees. Used by `work_worktree.py` and `spawn/api.py`.
+
+**Key contracts:**
+
+`ensure_work_item_worktree()` is idempotent — calling twice returns `already_available`
+on the second call. Once managed metadata (repo_path + name) is persisted, subsequent
+calls reuse it regardless of `--repo` or cwd. Accepts dry-run mode and `allow_missing_dry_run`
+for work items that don't exist yet. Returns `WorktreeEnsureResult` with status, metadata,
+repo_root, canonical_path, and optional warning.
+
+`ensure_temporary_worktree()` provides session-scoped isolation keyed by spawn_id/chat_id
+(via `_temporary_key(ctx)` → `worktree-temp/` store). Uses same pending/rollback discipline:
+set pending before git, clear on failure, upgrade to ready on success.
+
+`get_temporary_worktree_status()` is read-only; heals pending-but-dir-exists records.
+
+Repo resolution (`_resolve_target_repo()`, `_resolve_repo_root()`) supports path selectors,
+workspace aliases, and cwd-based inference. Dry-run mode uses `.git` marker scanning
+without running git commands.
+
+Managed path policy: `_canonical_target()` derives `<repo>.worktrees/<name>`. Non-canonical
+paths are detected as drift and fail clearly.
+
+### ops/work_worktree.py — Work Worktree Command Orchestration
+
+`work_worktree.py` orchestrates `meridian work worktree` command logic. Accepts
+`WorkWorktreeInput` (work_id, ensure, repo, chat_id, project_root), returns
+`WorkWorktreeOutput` with worktree path, branch, name, repo_root, managed status,
+exists flag, temporary flag, ensured flag, message, and warning.
+
+Routes based on whether a work item is active: calls `ensure_work_item_worktree()`
+if present, else delegates to `ensure_temporary_worktree()`. When `ensure=False`,
+returns status-only response (no-op) if path already exists. When work_id is empty
+and no active work item, uses temporary worktree path.
+
 ## Contracts
 
 ### OperationRuntime

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/commands.py

@@ -166,6 +166,8 @@ from meridian.lib.ops.work_lifecycle import (
     WorkSwitchOutput,
     WorkUpdateInput,
     WorkUpdateOutput,
+    WorkWorktreeInput,
+    WorkWorktreeOutput,
     work_clear,
     work_clear_sync,
     work_clear_worktree,
@@ -186,6 +188,8 @@ from meridian.lib.ops.work_lifecycle import (
     work_switch_sync,
     work_update,
     work_update_sync,
+    work_worktree,
+    work_worktree_sync,
 )
 from meridian.lib.ops.workspace import (
     WorkspaceInitInput,
@@ -569,6 +573,19 @@ _OP_SPECS: tuple[ExtensionCommandSpec, ...] = (
         agent_default_format="text",
         surfaces=frozenset({ExtensionSurface.CLI, ExtensionSurface.HTTP}),
     ),
+    ExtensionCommandSpec.from_op(
+        extension_id="meridian.work",
+        command_id="worktree",
+        summary="Show or ensure worktree state for an active or explicit work item.",
+        handler=work_worktree,
+        sync_handler=work_worktree_sync,
+        input_type=WorkWorktreeInput,
+        output_type=WorkWorktreeOutput,
+        cli_group="work",
+        cli_name="worktree",
+        agent_default_format="text",
+        surfaces=frozenset({ExtensionSurface.CLI, ExtensionSurface.HTTP}),
+    ),
     ExtensionCommandSpec.from_op(
         extension_id="meridian.work",
         command_id="set-worktree",

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/runtime.py

@@ -126,6 +126,7 @@ class ResolvedRoots:
     project_root: Path
     project_state_dir: Path
     runtime_root: Path
+    execution_cwd: Path
 
 
 def runtime_context(ctx: RuntimeContext | None) -> RuntimeContext:
@@ -361,6 +362,7 @@ def resolve_roots(project_root: str | None) -> ResolvedRoots:
         project_root=authority.project_root,
         project_state_dir=authority.project_state_dir,
         runtime_root=authority.runtime_root,
+        execution_cwd=authority.execution_cwd,
     )
 
 
@@ -370,6 +372,7 @@ def resolve_roots_for_read(project_root: str | None) -> ResolvedRoots:
         project_root=authority.project_root,
         project_state_dir=authority.project_state_dir,
         runtime_root=authority.runtime_root or authority.project_state_dir,
+        execution_cwd=authority.execution_cwd,
     )
 
 

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/spawn/api.py

@@ -19,6 +19,7 @@ from meridian.lib.core.spawn_lifecycle import ACTIVE_SPAWN_STATUSES, is_active_s
 from meridian.lib.core.spawn_service import CancelOutcome
 from meridian.lib.core.telemetry import register_debug_trace_observer
 from meridian.lib.core.types import SpawnId
+from meridian.lib.launch.cwd import TaskCwdResolution
 from meridian.lib.launch.request import SessionRequest
 from meridian.lib.ops.reference import ResolvedSessionReference, resolve_session_reference
 from meridian.lib.ops.runtime import (
@@ -33,6 +34,8 @@ from meridian.lib.ops.runtime import (
     resolve_runtime_root_for_read,
     runtime_context,
 )
+from meridian.lib.ops.work_attachment import ensure_explicit_work_item
+from meridian.lib.ops.worktree_ensure import ensure_work_item_worktree
 from meridian.lib.state import session_store, spawn_store, work_store
 from meridian.lib.state.paths import resolve_project_paths
 from meridian.lib.state.primary_meta import (
@@ -247,6 +250,30 @@ def _merge_warnings(*warnings: str | None) -> str | None:
     return " ".join(merged)
 
 
+def _resolve_selected_work_item(
+    *,
+    payload_work: str,
+    context: RuntimeContext,
+    runtime_root: Path,
+) -> str | None:
+    explicit_work_id = payload_work.strip() or None
+    if explicit_work_id is not None:
+        return explicit_work_id
+
+    ambient_work_id = (context.work_id or "").strip() or None
+    if ambient_work_id is not None:
+        return ambient_work_id
+
+    chat_id = (context.chat_id or "").strip()
+    if not chat_id:
+        return None
+    try:
+        active_work_id = session_store.get_session_active_work_id(runtime_root, chat_id) or ""
+        return active_work_id.strip() or None
+    except Exception:
+        return None
+
+
 def spawn_create_sync(
     payload: SpawnCreateInput,
     ctx: RuntimeContext | None = None,
@@ -290,11 +317,57 @@ def spawn_create_sync(
             work_id=payload.work,
         )
         payload = payload.model_copy(update={"work": resolved_work_id})
-        if not work_exists:
+        if not work_exists and payload.worktree is not True:
             dry_run_work_warning = (
                 f"Work item '{resolved_work_id}' does not exist. "
                 "Dry-run leaves state unchanged; it would be created on launch."
             )
+    ensure_warning: str | None = None
+    forced_task_cwd_resolution: TaskCwdResolution | None = None
+    if payload.worktree is True:
+        resolved_runtime_root = (
+            _runtime_root_from_prepared_for_read(
+                prepared_context,
+                project_root=resolved_root,
+            )
+            if prepared_context is not None
+            else (
+                authority.runtime_root
+                if authority.runtime_root is not None
+                else resolve_runtime_root_for_read(resolved_root)
+            )
+        )
+        selected_work_id = _resolve_selected_work_item(
+            payload_work=payload.work,
+            context=resolved_context,
+            runtime_root=resolved_runtime_root,
+        )
+        if selected_work_id is not None:
+            project_state_dir = resolve_project_paths(resolved_root).root_dir
+            explicit_work_requested = bool(payload.work.strip())
+            if explicit_work_requested and not payload.dry_run:
+                selected_work_id = ensure_explicit_work_item(
+                    project_state_dir,
+                    selected_work_id,
+                )
+                payload = payload.model_copy(update={"work": selected_work_id})
+            ensured = ensure_work_item_worktree(
+                project_root=resolved_root,
+                project_state_dir=project_state_dir,
+                work_id=selected_work_id,
+                target_repo=payload.repo,
+                execution_cwd=authority.execution_cwd,
+                dry_run=payload.dry_run,
+                allow_missing_dry_run=explicit_work_requested,
+            )
+            ensure_warning = ensured.warning
+            if payload.dry_run:
+                forced_task_cwd_resolution = TaskCwdResolution(
+                    task_cwd=ensured.worktree_path,
+                    source="forced-worktree",
+                    work_item=selected_work_id,
+                )
+    preflight_warning = _merge_warnings(preflight_warning, ensure_warning)
 
     runtime = None
     if not payload.dry_run:
@@ -322,6 +395,7 @@ def spawn_create_sync(
         runtime=runtime,
         preflight_warning=preflight_warning,
         ctx=resolved_context,
+        forced_task_cwd_resolution=forced_task_cwd_resolution,
     )
     forked_from = _forked_from_output(payload)
     if payload.dry_run:
@@ -1528,6 +1602,7 @@ def _build_fork_create_input(
     inherited_skills: tuple[str, ...],
     requested_work: str,
     requested_worktree: bool | None,
+    requested_repo: str | None,
     requested_goal: str | None,
     harness: str | None,
 ) -> SpawnCreateInput:
@@ -1543,6 +1618,7 @@ def _build_fork_create_input(
         desc=payload.desc,
         work=requested_work or (resolved_reference.source_work_id or ""),
         worktree=requested_worktree,
+        repo=requested_repo,
         goal=requested_goal,
         session=SessionRequest(
             requested_harness_session_id=resolved_reference.harness_session_id,
@@ -1609,6 +1685,7 @@ def spawn_fork_sync(
     requested_agent = (payload.agent or "").strip() or None
     requested_work = payload.work.strip()
     requested_worktree = payload.worktree
+    requested_repo = payload.repo
     requested_goal = payload.goal
     if requested_goal is None and _looks_like_spawn_ref(normalized_source_ref):
         source_row = read_spawn_row(
@@ -1636,6 +1713,7 @@ def spawn_fork_sync(
         inherited_skills=inherited_skills,
         requested_work=requested_work,
         requested_worktree=requested_worktree,
+        requested_repo=requested_repo,
         requested_goal=requested_goal,
         harness=requested_harness,
     )
@@ -1721,6 +1799,7 @@ def spawn_continue_sync(
         desc=payload.desc,
         work=payload.work,
         worktree=payload.worktree,
+        repo=payload.repo,
         session=SessionRequest(
             requested_harness_session_id=resolved_reference.harness_session_id,
             continue_harness=resolved_reference.harness,

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/spawn/models.py

@@ -123,6 +123,7 @@ class SpawnCreateInput(SpawnLaunchOptions):
     desc: str = ""
     work: str = ""
     worktree: bool | None = None
+    repo: str | None = None
     session: SessionRequest = SessionRequest()
 
     @field_validator("goal", mode="before")
@@ -1051,6 +1052,7 @@ class SpawnContinueInput(SpawnLaunchOptions):
     desc: str = ""
     work: str = ""
     worktree: bool | None = None
+    repo: str | None = None
     fork: bool = False
 
     @field_validator("goal", mode="before")
@@ -1074,6 +1076,7 @@ class SpawnForkInput(SpawnLaunchOptions):
     desc: str = ""
     work: str = ""
     worktree: bool | None = None
+    repo: str | None = None
 
     @field_validator("goal", mode="before")
     @classmethod

{meridian_cli-0.2.2 → meridian_cli-0.2.3}/src/meridian/lib/ops/spawn/prepare.py

@@ -7,7 +7,7 @@ from meridian.lib.core.overrides import RuntimeOverrides
 from meridian.lib.diagnostics import capture_library_diagnostics
 from meridian.lib.harness.registry import get_default_harness_registry
 from meridian.lib.launch.context import build_launch_context
-from meridian.lib.launch.cwd import LaunchDirectoryContext, resolve_task_cwd
+from meridian.lib.launch.cwd import LaunchDirectoryContext, TaskCwdResolution, resolve_task_cwd
 from meridian.lib.launch.reference import parse_template_assignments, validate_reference_paths
 from meridian.lib.launch.request import (
     ExecutionBudget,
@@ -48,6 +48,7 @@ def build_create_payload(
     runtime: OperationRuntime | None = None,
     preflight_warning: str | None = None,
     ctx: RuntimeContext | None = None,
+    forced_task_cwd_resolution: TaskCwdResolution | None = None,
 ) -> SpawnRequest:
     """Build a spawn request without leaking library warnings to stderr."""
 
@@ -84,14 +85,18 @@ def build_create_payload(
                 ).strip() or None
             except Exception:
                 ambient_work_id = None
-        task_cwd_resolution = resolve_task_cwd(
-            project_root,
-            project_state_dir=resolve_project_paths(project_root).root_dir,
-            explicit_work_id=explicit_work_id,
-            ambient_work_id=ambient_work_id,
-            force_worktree=payload.worktree is True,
-            force_no_worktree=payload.worktree is False,
-        )
+        project_state_dir = resolve_project_paths(project_root).root_dir
+        if forced_task_cwd_resolution is not None:
+            task_cwd_resolution = forced_task_cwd_resolution
+        else:
+            task_cwd_resolution = resolve_task_cwd(
+                project_root,
+                project_state_dir=project_state_dir,
+                explicit_work_id=explicit_work_id,
+                ambient_work_id=ambient_work_id,
+                force_worktree=payload.worktree is True,
+                force_no_worktree=payload.worktree is False,
+            )
         directory_context = LaunchDirectoryContext.from_task_cwd_resolution(
             authority_root=project_root,
             task_cwd_resolution=task_cwd_resolution,
@@ -148,7 +153,7 @@ def build_create_payload(
             template_vars=parsed_template_vars,
             goal=payload.goal,
             work_id_hint=payload.work.strip() or None,
-            warning=preflight_warning,
+            warning=preflight_warning.strip() if preflight_warning is not None else None,
             authority_root=directory_context.authority_root.as_posix(),
             task_cwd=directory_context.logical_task_cwd.as_posix(),
             reference_anchor=directory_context.reference_anchor.as_posix(),