worktree-for-agents 0.0.0-stage → 1.0.0

package/worktree_manager/git_repository.py

@@ -0,0 +1,72 @@
+"""All Git subprocess interaction is centralized here."""
+from __future__ import annotations
+
+import re
+import os
+import signal
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from .models import ManagerError
+
+_SHA = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
+
+
+@dataclass(frozen=True)
+class GitOutput:
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+class GitRepository:
+    def __init__(self, root: str | Path):
+        self.root = Path(root).expanduser()
+        if not self.root.is_absolute() or not self.root.is_dir():
+            raise ManagerError("invalid_repository", "Repository must be an existing absolute directory", 3)
+        self.root = self.root.resolve()
+        out = self.run(("rev-parse", "--show-toplevel"), check=False)
+        if out.returncode:
+            raise ManagerError("invalid_repository", "Directory is not a Git repository", 3)
+        self.root = Path(out.stdout.strip()).resolve()
+
+    def run(self, args: Sequence[str], *, check: bool = True, timeout: float = 60) -> GitOutput:
+        if not args or any(not isinstance(arg, str) or "\x00" in arg for arg in args):
+            raise ManagerError("invalid_argument", "Invalid Git argument", 2)
+        try:
+            result = subprocess.run(["git", "-C", str(self.root), *args], text=True,
+                                    stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                    timeout=timeout, check=False)
+        except FileNotFoundError as exc:
+            raise ManagerError("dependency_unavailable", "Git executable is unavailable", 6) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise ManagerError("git_timeout", "Git command timed out", 5) from exc
+        output = GitOutput(result.stdout, result.stderr, result.returncode)
+        # Test-only crash barrier: terminate this CLI process only after Git has
+        # returned successfully, leaving durable Git effects and held locks as
+        # they would be after an abrupt process loss.
+        trigger = os.environ.get("WORKTREE_MANAGER_TEST_CRASH_AFTER_GIT")
+        if result.returncode == 0 and trigger and trigger in " ".join(args):
+            os.kill(os.getpid(), signal.SIGKILL)
+        if check and result.returncode:
+            # Preserve causal stderr for diagnostics without exposing unrelated data.
+            detail = result.stderr.strip() or "Git operation failed"
+            raise ManagerError("operation_failed", detail, 5)
+        return output
+
+    def head(self) -> str:
+        value = self.run(("rev-parse", "HEAD")).stdout.strip()
+        if not _SHA.fullmatch(value):
+            raise ManagerError("invalid_repository", "Git returned an invalid object id", 3)
+        return value
+
+    def status(self) -> str:
+        return self.run(("status", "--porcelain=v2", "--branch", "--untracked-files=all")).stdout
+
+    def worktrees(self) -> str:
+        return self.run(("worktree", "list", "--porcelain")).stdout
+
+    def index_entries(self) -> str:
+        return self.run(("ls-files", "--stage", "-z")).stdout

package/worktree_manager/lock_manager.py

@@ -0,0 +1,50 @@
+"""Process-safe directory locks acquired in deterministic order."""
+from __future__ import annotations
+import os, socket, json, tempfile
+from pathlib import Path
+from .models import ManagerError
+class LockManager:
+    def __init__(self,lock_root: str|Path): self.root=Path(lock_root).resolve(); self.held=[]; self.barrier=os.environ.get('WORKTREE_MANAGER_TEST_LOCK_BARRIER_DIR')
+    def _mark(self, phase):
+        if not self.barrier: return
+        root=Path(self.barrier); root.mkdir(parents=True,exist_ok=True)
+        path=root/phase; fd,name=tempfile.mkstemp(prefix='.tmp-',dir=root)
+        try:
+            with os.fdopen(fd,'w') as stream: json.dump({'phase':phase,'pid':os.getpid()},stream); stream.flush(); os.fsync(stream.fileno())
+            os.replace(name,path)
+        finally:
+            if os.path.exists(name): os.unlink(name)
+    def acquire(self,names: list[str],operation: str)->None:
+        if self.held: raise ManagerError('resource_locked','Lock manager already owns locks',4)
+        self._mark('pre_lock_validation')
+        for name in sorted(set(names)):
+            if not name or name.startswith('/') or '..' in Path(name).parts:
+                self.release(); raise ManagerError('invalid_identity','Invalid lock name',3)
+            path=self.root/name; path.parent.mkdir(parents=True,exist_ok=True)
+            try: path.mkdir()
+            except FileExistsError as exc:
+                # A process crash can leave a directory lock behind. Reclaim
+                # only when its recorded local owner is demonstrably gone.
+                owner=path/'owner'
+                try:
+                    pid=int(owner.read_text(encoding='utf-8').splitlines()[0])
+                    os.kill(pid,0)
+                except ProcessLookupError:
+                    try: owner.unlink(missing_ok=True); path.rmdir(); path.mkdir()
+                    except OSError:
+                        self.release(); raise ManagerError('resource_locked',f"Resource '{name}' is locked",5) from exc
+                except (OSError, ValueError, IndexError):
+                    self.release(); raise ManagerError('resource_locked',f"Resource '{name}' is locked",5) from exc
+                except PermissionError:
+                    self.release(); raise ManagerError('resource_locked',f"Resource '{name}' is locked",5) from exc
+                else:
+                    self.release(); raise ManagerError('resource_locked',f"Resource '{name}' is locked",5) from exc
+            self.held.append(path); (path/'owner').write_text(f'{os.getpid()}\n{socket.gethostname()}\n{operation}\n',encoding='utf-8')
+        self._mark('lock_acquired')
+    def release(self)->None:
+        for path in reversed(self.held):
+            try: (path/'owner').unlink(missing_ok=True); path.rmdir()
+            except OSError: pass
+        self.held.clear()
+    def __enter__(self): return self
+    def __exit__(self,*_): self.release()

package/worktree_manager/mcp_contract.py

@@ -0,0 +1,93 @@
+"""Strict, versioned JSON contracts for the worktree management service."""
+from __future__ import annotations
+
+import pathlib
+
+CONTRACT_VERSION = 1
+from . import __version__ as TOOL_VERSION
+TOOL_NAMES = (
+    "worktree_create", "worktree_complete", "worktree_cleanup",
+    "worktree_recover", "worktree_list", "worktree_prune", "worktree_status",
+)
+FIELDS = {
+    "worktree_create": {"repo", "work_id", "base", "dry_run", "parent_repo", "submodule_path", "confirm", "plan_hash", "init_submodules", "prepare", "verify"},
+    "worktree_complete": {"repo", "work_id", "base", "dry_run", "authorization", "confirm", "plan_hash", "transaction_id", "preserve_dirty", "target_direct", "parent_repo", "commit_title", "commit_body"},
+    "worktree_cleanup": {"repo", "work_id", "base", "dry_run", "authorization", "confirm", "plan_hash", "discard", "discard_consent"},
+    "worktree_recover": {"repo", "transaction_id", "dry_run", "authorization", "confirm", "target_direct", "parent_repo"},
+    "worktree_list": {"repo"}, "worktree_prune": {"repo", "dry_run", "authorization", "confirm", "plan_hash"},
+    "worktree_status": {"repo", "work_id"},
+}
+REQUIRED = {
+    "worktree_create": {"repo", "work_id"}, "worktree_complete": {"repo", "work_id"},
+    "worktree_cleanup": {"repo", "work_id"}, "worktree_recover": {"repo"},
+    "worktree_list": {"repo"}, "worktree_prune": {"repo"},
+    "worktree_status": {"repo", "work_id"},
+}
+
+def validate_request(tool: str, request: dict) -> dict:
+    if tool not in FIELDS:
+        raise ValueError("unknown_tool")
+    if not isinstance(request, dict):
+        raise ValueError("invalid_request")
+    unknown = set(request) - FIELDS[tool]
+    if unknown:
+        raise ValueError("unknown_fields: " + ", ".join(sorted(unknown)))
+    if not REQUIRED[tool] <= request.keys():
+        raise ValueError("missing_required_fields: " + ", ".join(sorted(REQUIRED[tool] - request.keys())))
+    repo = request["repo"]
+    if not isinstance(repo, str) or not repo or not __import__("pathlib").Path(repo).is_absolute():
+        raise ValueError("repo_must_be_absolute")
+    for key in ("dry_run", "discard", "preserve_dirty", "discard_consent", "target_direct", "confirm", "init_submodules", "prepare", "verify"):
+        if key in request and type(request[key]) is not bool:
+            raise ValueError(f"{key}_must_be_boolean")
+    for key in ("work_id", "base", "transaction_id", "authorization", "parent_repo", "submodule_path", "commit_title", "commit_body"):
+        if key in request and not isinstance(request[key], str):
+            raise ValueError(f"{key}_must_be_string")
+    if tool in {"worktree_create", "worktree_complete", "worktree_cleanup", "worktree_status"} and not request.get("work_id"):
+        raise ValueError("work_id_required")
+    if tool == "worktree_create" and bool(request.get("parent_repo")) != bool(request.get("submodule_path")):
+        raise ValueError("target_direct_requires_parent_and_submodule_path")
+    if request.get("target_direct") and not request.get("parent_repo"):
+        raise ValueError("target_direct_requires_parent_repo")
+    normalized = dict(request)
+    has_confirm = "confirm" in normalized
+    confirm = normalized.pop("confirm", False)
+    if confirm:
+        if normalized.get("authorization") not in (None, "I_AUTHORIZE_THIS_CALL"):
+            raise ValueError("authorization_mismatch")
+        normalized["authorization"] = "I_AUTHORIZE_THIS_CALL"
+    elif has_confirm and normalized.get("authorization") == "I_AUTHORIZE_THIS_CALL":
+        raise ValueError("authorization_mismatch")
+    if "plan_hash" in normalized and (not isinstance(normalized["plan_hash"], str) or len(normalized["plan_hash"]) != 64 or any(c not in "0123456789abcdef" for c in normalized["plan_hash"])):
+        raise ValueError("plan_hash_must_be_sha256")
+    return normalized
+
+def output_schema():
+    return {"type": "object", "required": ["contract_version", "tool_version", "operation", "repository", "result", "data", "warnings", "error", "transaction_id"], "properties": {
+        "contract_version": {"type": "integer"}, "tool_version": {"type": "string"},
+        "operation": {"type": "string"}, "repository": {"type": "string"},
+        "result": {"type": "string"}, "data": {"type": "object"}, "warnings": {"type": "array"},
+        "error": {"type": ["object", "null"]}, "transaction_id": {"type": ["string", "null"]}}, "additionalProperties": False}
+
+def envelope(operation, repo, result="success", data=None, warnings=None, error=None, transaction_id=None):
+    return {"contract_version": CONTRACT_VERSION, "tool_version": TOOL_VERSION,
+            "operation": operation, "repository": repo, "result": result,
+            "data": data or {}, "warnings": warnings or [], "error": error,
+            "transaction_id": transaction_id}
+
+def absolute_repository(value):
+    """Absolute form of a requested repository, or an empty string when unknown."""
+    if not isinstance(value, str) or not value:
+        return ""
+    path = pathlib.Path(value).expanduser()
+    try:
+        return str(path.resolve())
+    except (OSError, RuntimeError):
+        return str(path.absolute())
+
+def error_envelope(operation, repository, code, message, exit_code):
+    """Canonical envelope for a failed operation, shared by every transport."""
+    result = "pending_intervention" if code == "intervention_required" else "failure"
+    return envelope(operation, repository or "", result, data={}, warnings=[],
+                    error={"code": code, "message": message, "exit_code": exit_code},
+                    transaction_id=None)

package/worktree_manager/mcp_operations.py

@@ -0,0 +1,171 @@
+"""MCP façade over the canonical Python lifecycle and recovery services."""
+from pathlib import Path
+from .configuration import Configuration
+from .git_repository import GitRepository
+from .models import ManagerError
+from .worktree_lifecycle import WorktreeLifecycle
+from .recovery_manager import RecoveryManager
+from .mcp_contract import validate_request, envelope
+from .worktree_lifecycle import validate_work_id
+from .target_direct_adapter import TargetDirectAdapter
+from .state_digest import state_digest, canonical_hash
+import hashlib
+import subprocess
+
+DESTRUCTIVE = {"worktree_complete", "worktree_cleanup", "worktree_recover", "worktree_prune"}
+
+def call(tool, request):
+    req = validate_request(tool, request)
+    root = Path(req["repo"]).resolve(strict=True)
+    git = GitRepository(root)
+    if root != git.root:
+        raise ManagerError("invalid_repository", "Repository identity mismatch", 3)
+    req["repo"] = str(root)
+    dry = req.get("dry_run", False)
+    if tool in DESTRUCTIVE and not dry and req.get("authorization") != "I_AUTHORIZE_THIS_CALL":
+        raise ManagerError("authorization_required", "Explicit authorization for this call is required", 3)
+    lifecycle = WorktreeLifecycle(Configuration.load(root))
+    if tool in {"worktree_create", "worktree_complete", "worktree_cleanup", "worktree_prune"}:
+        if tool in {"worktree_create", "worktree_complete"}:
+            req["base"] = req.get("base") or next((b for b in ("development", "main", "trunk") if lifecycle.git.run(("show-ref", "--verify", "--quiet", f"refs/heads/{b}"), check=False).returncode == 0), "main")
+        if tool == "worktree_complete" and not req.get("transaction_id") and dry:
+            req["transaction_id"] = __import__("uuid").uuid4().hex
+        fields = ["operation", "repo", "work_id", "confirm", "transaction_id", "base", "preserve_dirty", "discard", "discard_consent", "target_direct", "parent_repo", "submodule_path", "state_digest"]
+        if tool == "worktree_complete":
+            fields = fields + ["commit_title", "commit_body"]
+        def plan_for(digest):
+            return {key: (tool if key == "operation" else digest if key == "state_digest" else bool(req.get("authorization")) if key == "confirm" else req.get(key)) for key in fields}
+        if dry:
+            digest = state_digest(root, lifecycle.state_root)
+            req["_computed_plan_hash"] = canonical_hash(plan_for(digest))
+        elif req.get("plan_hash"):
+            digest = state_digest(root, lifecycle.state_root)
+            if req["plan_hash"] != canonical_hash(plan_for(digest)):
+                raise ManagerError("plan_mismatch", "Repository state or request changed since preflight", 5)
+    if "work_id" in req:
+        validate_work_id(req["work_id"])
+    def target_adapter(identity):
+        common = Path(git.run(("rev-parse", "--git-common-dir")).stdout.strip())
+        if not common.is_absolute(): common = (root / common).resolve()
+        work_id = identity[3:] if identity.startswith("wt-") else identity
+        descriptor = common / "worktree-manager" / "target-direct" / hashlib.sha256(work_id.encode()).hexdigest() / "descriptor"
+        adapter = TargetDirectAdapter(descriptor)
+        if adapter.values["target_repo"] != str(root) or adapter.values["parent_repo"] != str(Path(req["parent_repo"]).resolve()):
+            raise ManagerError("invalid_descriptor", "Target descriptor identity does not match this request", 3)
+        return adapter
+    if tool == "worktree_create" and req.get("parent_repo"):
+        if dry: raise ManagerError("unsupported_dry_run", "Target-direct creation cannot be simulated safely", 3)
+        common = Path(git.run(("rev-parse", "--git-common-dir")).stdout.strip())
+        if not common.is_absolute(): common = (root / common).resolve()
+        descriptor = common / "worktree-manager" / "target-direct" / hashlib.sha256(req["work_id"].encode()).hexdigest() / "descriptor"
+        adapter = TargetDirectAdapter.create(descriptor, root, req["parent_repo"], req["submodule_path"], req["work_id"], req.get("base", "main"))
+        return envelope(tool, str(root), data={"target_direct": True, "worktree": adapter.values["worktree_path"], "descriptor": str(adapter.path), "phase": adapter.values["phase"]}, transaction_id=adapter.values["tx_id"])
+    if tool == "worktree_complete" and req.get("target_direct"):
+        if dry: raise ManagerError("unsupported_dry_run", "Target-direct completion cannot be simulated safely", 3)
+        data = target_adapter(req["work_id"]).complete()
+        return envelope(tool, str(root), data=data, transaction_id="wt-" + req["work_id"])
+    if tool == "worktree_recover" and req.get("target_direct"):
+        if dry: raise ManagerError("unsupported_dry_run", "Target-direct recovery cannot be simulated safely", 3)
+        tx = req.get("transaction_id")
+        if not tx: raise ManagerError("transaction_id_required", "Target-direct recovery requires transaction_id", 3)
+        data = target_adapter(tx).recover()
+        return envelope(tool, str(root), data=data, transaction_id=tx)
+    if tool == "worktree_status":
+        matches = [item for item in lifecycle.list() if item["path"] == str(lifecycle._path(req["work_id"]))]
+        journal = []
+        if lifecycle.journal.root.exists():
+            for entry in sorted(lifecycle.journal.root.iterdir()):
+                if entry.is_dir():
+                    phase = lifecycle.journal.read_phase(entry.name)
+                    meta_path = entry / "meta.json"
+                    meta = __import__("json").loads(meta_path.read_text()) if meta_path.is_file() else {}
+                    if meta.get("work_id") == req["work_id"]:
+                        journal.append({"transaction_id": entry.name, "phase": phase, "metadata": meta})
+        data = {"worktree": matches[0] if matches else None, "identity_exists": bool(matches), "transactions": journal,
+                "pending_intervention": any(item["phase"] == "pending_manual" for item in journal),
+                "locks_directory": str(lifecycle.state_root / lifecycle.config.lock_dir)}
+    elif tool == "worktree_list":
+        data = {"worktrees": lifecycle.list()}
+    elif tool == "worktree_create":
+        base = req.get("base") or next((b for b in ("development", "main", "trunk") if lifecycle.git.run(("show-ref", "--verify", "--quiet", f"refs/heads/{b}"), check=False).returncode == 0), "main")
+        if dry:
+            lifecycle._base(base)
+            lifecycle._validate_create_options(bool(req.get("prepare", False)),bool(req.get("verify", False)))
+            branch, path = lifecycle._branch(req["work_id"]), lifecycle._path(req["work_id"])
+            if path.exists() or lifecycle.git.run(("show-ref", "--verify", "--quiet", f"refs/heads/{branch}"), check=False).returncode == 0:
+                raise ManagerError("operation_failed", "Worktree branch or path already exists", 5)
+            if not Path(lifecycle.config.worktrees_dir).is_absolute():
+                rel = path.relative_to(root).as_posix()
+                if lifecycle.git.run(("check-ignore", "-q", "--", rel), check=False).returncode:
+                    raise ManagerError("invalid_configuration", "Worktree path is not ignored", 3)
+            data = {"planned": True, "work_id": req["work_id"], "base": base, "path": str(path), "branch": branch, "preflight": "passed", "mutations": [], "plan_hash":req.get("_computed_plan_hash"), "state_digest":digest,
+                    "init_submodules": "true" if req.get("init_submodules") else "false",
+                    "init_submodules_result": "planned" if req.get("init_submodules") else "not_requested",
+                    "prepare": "planned" if (req.get("prepare") or lifecycle.config.prepare_enabled) else "skipped",
+                    "verify": "planned" if (req.get("verify") or lifecycle.config.verify_enabled) else "skipped"}
+        else:
+            data = lifecycle.create(req["work_id"], base,
+                                    init_submodules=bool(req.get("init_submodules", False)),
+                                    prepare=bool(req.get("prepare", False)),
+                                    verify=bool(req.get("verify", False)))
+    elif tool == "worktree_complete":
+        if dry:
+            base=req.get("base", "main"); lifecycle._base(base)
+            path=lifecycle._path(req["work_id"])
+            if str(path) not in {item["path"] for item in lifecycle.list()} or not path.is_dir(): raise ManagerError("invalid_identity", "Worktree identity does not match registration", 3)
+            if lifecycle.git.run(("symbolic-ref", "--short", "HEAD")).stdout.strip()!=base: raise ManagerError("invalid_identity", f"Current branch must be '{base}'", 3)
+            if lifecycle.git.run(("-C", str(path), "status", "--porcelain", "--untracked-files=all")).stdout: raise ManagerError("intervention_required", "Worktree has uncommitted changes; it was retained", 5)
+            from .commit_message import compose_commit_message
+            _subject, _body = compose_commit_message(req["work_id"], req.get("commit_title"), req.get("commit_body"))
+            data = {"planned": True, "work_id": req["work_id"], "transaction_id":req.get("transaction_id"), "preflight": "passed", "mutations": ["squash_merge", "remove_worktree", "delete_branch"], "plan_hash":req.get("_computed_plan_hash"), "state_digest":digest, "commit_subject": _subject, "commit_body": _body}
+        else: data = lifecycle.complete(req["work_id"], req.get("base", "main"), req.get("preserve_dirty", False), req.get("transaction_id"), req.get("plan_hash"), req)
+    elif tool == "worktree_cleanup":
+        if req.get("discard") and req.get("discard_consent") is not True:
+            raise ManagerError("discard_consent_required", "Separate explicit discard consent is required", 3)
+        if dry:
+            path=lifecycle._path(req["work_id"])
+            if str(path) not in {item["path"] for item in lifecycle.list()} or not path.exists(): raise ManagerError("invalid_identity", "Worktree identity does not match registration", 3)
+            lifecycle._base(req.get("base", "main"))
+            changed=bool(lifecycle.git.run(("-C", str(path), "status", "--porcelain", "--untracked-files=all")).stdout)
+            if changed and not req.get("discard"): raise ManagerError("intervention_required", "Worktree has changes; discard is required", 5)
+            data = {"planned": True, "work_id": req["work_id"], "discard": req.get("discard", False), "dirty": changed, "preflight": "passed", "mutations": ["remove_worktree", "delete_branch"], "plan_hash":req.get("_computed_plan_hash"), "state_digest":digest}
+        else: data = lifecycle.cleanup(req["work_id"], req.get("discard", False), req.get("base", "main"))
+    elif tool == "worktree_prune":
+        if dry:
+            # Git's dry-run reports exactly which stale administrative records
+            # would be removed, without changing them.
+            preview = lifecycle.git.run(("worktree", "prune", "--dry-run", "--verbose"))
+            eligible = [line for line in (preview.stdout + preview.stderr).splitlines() if line.strip()]
+            worktrees = lifecycle.list()
+            locks_dir = lifecycle.state_root / lifecycle.config.lock_dir
+            locks = sorted(p.name for p in locks_dir.iterdir()) if locks_dir.is_dir() else []
+            interventions = []
+            if lifecycle.journal.root.exists():
+                for entry in sorted(lifecycle.journal.root.iterdir()):
+                    if entry.is_dir() and lifecycle.journal.read_phase(entry.name) == "pending_manual":
+                        interventions.append(entry.name)
+            pending = bool(eligible)
+            data = {"planned": pending, "preflight": "passed" if pending else "no_pending_work",
+                    "worktrees": worktrees, "eligible_orphans": eligible, "locks": locks,
+                    "pending_interventions": interventions,
+                    "mutations": ["git_worktree_prune"] if pending else []}
+            if not pending:
+                return envelope(tool, str(root), "no_pending_work", data, transaction_id=None)
+        else:
+            data = lifecycle.prune()
+            if data.get("pruned", 0) == 0:
+                return envelope(tool, str(root), "no_pending_work", data, transaction_id=None)
+    else:
+        if dry:
+            entries=[]
+            if lifecycle.journal.directory.exists():
+                entries=[entry.name for entry in lifecycle.journal.directory.iterdir() if entry.is_dir()]
+            tx=req.get("transaction_id")
+            if tx and tx not in entries: raise ManagerError("invalid_identity", "Transaction does not exist", 3)
+            data = {"planned": True, "transaction_id": tx, "transactions": entries, "preflight": "passed", "mutations": ["recover_transaction"] if entries else []}
+        else:
+            git_dir = Path(git.run(("rev-parse", "--git-dir")).stdout.strip())
+            if not git_dir.is_absolute(): git_dir = (root / git_dir).resolve()
+            kind, data = RecoveryManager(git_dir / lifecycle.config.state_dir, root).recover(req.get("transaction_id"),req.get("work_id"))
+            return envelope(tool, str(root), kind, data, transaction_id=(data or {}).get("transaction_id"))
+    return envelope(tool, str(root), data=data, transaction_id=data.get("transaction_id"))

package/worktree_manager/mcp_server.py

@@ -0,0 +1,61 @@
+"""Minimal stdio JSON-RPC server exposing the worktree management tools."""
+import json
+import sys
+from . import __version__
+from .mcp_contract import TOOL_NAMES, absolute_repository, error_envelope
+from .mcp_operations import call
+from .models import ManagerError
+
+MCP_INSTRUCTIONS = "Vas a implementar un cambio, ejecutar una spec o iniciar un flujo. ¿Quieres crear un worktree para hacerlo aislado?"
+
+def schemas():
+    from .mcp_contract import FIELDS, REQUIRED, output_schema
+    props = {"repo": {"type": "string"}, "work_id": {"type": "string"},
+             "base": {"type": "string"}, "transaction_id": {"type": "string"},
+              "authorization": {"type": "string", "enum": ["I_AUTHORIZE_THIS_CALL"]},
+              "confirm": {"type":"boolean"}, "plan_hash":{"type":"string"},
+              "init_submodules":{"type":"boolean"}, "prepare":{"type":"boolean"}, "verify":{"type":"boolean"},
+             "dry_run": {"type": "boolean"}, "discard": {"type": "boolean"},
+             "discard_consent": {"type": "boolean"}, "preserve_dirty": {"type": "boolean"},
+             "commit_title": {"type": "string"}, "commit_body": {"type": "string"}}
+    props.update({"parent_repo": {"type": "string"}, "submodule_path": {"type": "string"},
+                  "target_direct": {"type": "boolean"}})
+    return [{"name": name, "description": "Manage repository worktrees", "inputSchema": {
+        "type": "object", "properties": {key: props[key] for key in sorted(FIELDS[name])},
+        "required": sorted(REQUIRED[name]), "additionalProperties": False}, "outputSchema": output_schema()} for name in TOOL_NAMES]
+
+def dispatch(message):
+    method = message.get("method")
+    params = message.get("params") or {}
+    if method == "initialize":
+        return {"protocolVersion": params.get("protocolVersion", "2024-11-05"), "capabilities": {"tools": {}}, "serverInfo": {"name": "worktree-for-agents", "version": __version__}, "instructions": MCP_INSTRUCTIONS}
+    if method == "notifications/initialized": return None
+    if method == "ping": return {}
+    if method == "tools/list": return {"tools": schemas()}
+    if method == "tools/call":
+        name = params.get("name")
+        try:
+            result = call(name, params.get("arguments", {}))
+            return {"content": [{"type": "text", "text": json.dumps(result, sort_keys=True)}], "structuredContent": result, "isError": False}
+        except Exception as exc:
+            err = getattr(exc, "code", "invalid_request")
+            message = str(exc)
+            exit_code = getattr(exc, "exit_code", 3)
+            result = error_envelope(name or "", absolute_repository((params.get("arguments") or {}).get("repo")), err, message, exit_code)
+            return {"content": [{"type": "text", "text": json.dumps(result, sort_keys=True)}], "structuredContent": result, "isError": True}
+    raise ValueError("method_not_found")
+
+def main():
+    for line in sys.stdin:
+        try:
+            message = json.loads(line)
+            result = dispatch(message)
+            if "id" in message and result is not None:
+                sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": message["id"], "result": result}, separators=(",", ":")) + "\n")
+                sys.stdout.flush()
+        except Exception as exc:
+            if "id" in locals().get("message", {}):
+                response = {"jsonrpc": "2.0", "id": message["id"], "error": {"code": -32601 if str(exc) == "method_not_found" else -32600, "message": str(exc)}}
+                sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n"); sys.stdout.flush()
+            else:
+                print(f"MCP request failed: {type(exc).__name__}", file=sys.stderr)

package/worktree_manager/mcp_transport.py

@@ -0,0 +1,5 @@
+"""Stdio transport entrypoint for the optional MCP service."""
+from .mcp_server import main
+
+if __name__ == "__main__":
+    main()

package/worktree_manager/models.py

@@ -0,0 +1,69 @@
+"""Domain values shared by the command-line and lifecycle layers."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from . import __version__
+
+
+class ResultKind(str, Enum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PENDING_INTERVENTION = "pending_intervention"
+    NO_PENDING_WORK = "no_pending_work"
+
+
+@dataclass(frozen=True)
+class ManagerError(Exception):
+    code: str
+    message: str
+    exit_code: int
+
+    def __str__(self) -> str:
+        return self.message
+
+
+@dataclass
+class OperationResult:
+    operation: str
+    result: ResultKind = ResultKind.SUCCESS
+    data: dict[str, Any] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    error: ManagerError | None = None
+
+    def json_document(self) -> dict[str, Any]:
+        return {
+            "contract_version": 1,
+            "tool_version": __version__,
+            "operation": self.operation,
+            "result": self.result.value,
+            "data": self.data,
+            "warnings": self.warnings,
+            "error": None if self.error is None else {
+                "code": self.error.code,
+                "message": self.error.message,
+                "exit_code": self.error.exit_code,
+            },
+        }
+
+    @property
+    def exit_code(self) -> int:
+        return self.error.exit_code if self.error else 0
+
+
+@dataclass(frozen=True)
+class TransactionIdentity:
+    transaction_id: str
+    repository: str
+    phase: str
+    original_head: str
+
+
+@dataclass(frozen=True)
+class TargetDirectIdentity:
+    target_repo: str
+    parent_repo: str
+    submodule_path: str
+    link_parent: str = "staged-only"

package/worktree_manager/output.py

@@ -0,0 +1,11 @@
+"""Stable human and JSON contract-v1 output."""
+from __future__ import annotations
+import json,sys
+from .models import OperationResult
+
+def emit(result: OperationResult,as_json: bool)->None:
+    if as_json: print(json.dumps(result.json_document(),ensure_ascii=False,separators=(',',':')))
+    else:
+        print(f'operation: {result.operation}\nresult: {result.result.value}')
+        for key,value in result.data.items(): print(f'{key}: {value}')
+        if result.error: print(result.error.message,file=sys.stderr)