minder-cli 0.6.2__tar.gz → 0.6.3__tar.gz

{minder_cli-0.6.2 → minder_cli-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minder-cli
-Version: 0.6.2
+Version: 0.6.3
 Summary: Minder CLI is the command-line interface for the Minder self-hosted MCP platform.
 Project-URL: Homepage, https://github.com/hiimtrung/minder
 Project-URL: Repository, https://github.com/hiimtrung/minder

{minder_cli-0.6.2 → minder_cli-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "minder-cli"
-version = "0.6.2"
+version = "0.6.3"
 description = "Minder CLI is the command-line interface for the Minder self-hosted MCP platform."
 readme = "README.md"
 requires-python = ">=3.14"

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/bootstrap/transport.py

@@ -315,12 +315,13 @@ def build_transport(
         return await session_tools.minder_session_cleanup(user_id=authenticated_user.id)
 
     async def minder_workflow_get(
-        *, user=None, repo_id: str, repo_path: str
+        *, user=None, repo_id: str, repo_path: str, branch: str = "main"
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_get(
             repo_id=await _resolve_repo_uuid(repo_id),
             repo_path=repo_path,
+            branch=branch,
         )
 
     async def minder_workflow_step(
@@ -330,6 +331,7 @@ def build_transport(
         repo_path: str | None = None,
         session_id: str | None = None,
         decision: dict[str, Any] | None = None,
+        branch: str = "main",
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_step(
@@ -337,6 +339,7 @@ def build_transport(
             repo_path=repo_path,
             session_id=uuid.UUID(session_id) if session_id else None,
             decision=decision,
+            branch=branch,
         )
 
     async def minder_workflow_update(
@@ -347,6 +350,7 @@ def build_transport(
         completed_step: str,
         artifact_name: str | None = None,
         artifact_content: str | None = None,
+        branch: str = "main",
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_update(
@@ -355,88 +359,104 @@ def build_transport(
             completed_step=completed_step,
             artifact_name=artifact_name,
             artifact_content=artifact_content,
+            branch=branch,
         )
 
     async def minder_workflow_guard(
-        *, user=None, repo_id: str, requested_step: str, action: str | None = None
+        *, user=None, repo_id: str, requested_step: str, action: str | None = None, branch: str = "main"
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_guard(
             repo_id=await _resolve_repo_uuid(repo_id),
             requested_step=requested_step,
             action=action,
+            branch=branch,
         )
 
     async def minder_memory_store(
         *,
         user=None,
+        principal: Principal | None = None,
         title: str,
         content: str,
         tags: list[str],
         language: str,  # noqa: ANN001
+        scope: str = "private",
     ) -> dict[str, Any]:
-        del user
+        owner_id = principal.principal_id if principal else (user.id if user else None)
         return await memory_tools.minder_memory_store(
             title=title,
             content=content,
             tags=tags,
             language=language,
+            owner_id=owner_id,
+            scope=scope,
         )
 
     async def minder_memory_recall(
         *,
         user=None,
+        principal: Principal | None = None,
         query: str,
         limit: int = 5,
         current_step: str | None = None,
         artifact_type: str | None = None,
     ) -> list[dict[str, Any]]:  # noqa: ANN001
-        del user
+        owner_id = principal.principal_id if principal else (user.id if user else None)
         return await memory_tools.minder_memory_recall(
             query,
             limit=limit,
             current_step=current_step,
             artifact_type=artifact_type,
+            owner_id=owner_id,
         )
 
-    async def minder_memory_list(*, user=None) -> list[dict[str, Any]]:  # noqa: ANN001
-        del user
-        return await memory_tools.minder_memory_list()
+    async def minder_memory_list(
+        *,
+        user=None,
+        principal: Principal | None = None,
+    ) -> list[dict[str, Any]]:  # noqa: ANN001
+        owner_id = principal.principal_id if principal else (user.id if user else None)
+        return await memory_tools.minder_memory_list(owner_id=owner_id)
 
     async def minder_memory_update(
         *,
         user=None,
+        principal: Principal | None = None,
         memory_id: str,
         title: str | None = None,
         content: str | None = None,
         tags: list[str] | None = None,
     ) -> dict[str, Any]:  # noqa: ANN001
-        del user
+        owner_id = principal.principal_id if principal else (user.id if user else None)
         return await memory_tools.minder_memory_update(
             memory_id,
             title=title,
             content=content,
             tags=tags,
+            owner_id=owner_id,
         )
 
     async def minder_memory_delete(
-        *, user=None, skill_id: str
+        *, user=None, principal: Principal | None = None, skill_id: str
     ) -> dict[str, bool]:  # noqa: ANN001
-        del user
-        return await memory_tools.minder_memory_delete(skill_id)
+        owner_id = principal.principal_id if principal else (user.id if user else None)
+        return await memory_tools.minder_memory_delete(skill_id, owner_id=owner_id)
 
     async def minder_memory_compact(
         *,
         user=None,
+        principal: Principal | None = None,
         memory_ids: list[str],
         similarity_threshold: float = 0.92,
         dry_run: bool = True,
     ) -> dict[str, Any]:  # noqa: ANN001
-        del user
+        owner_id = principal.principal_id if principal else (user.id if user else None)
         return await memory_tools.minder_memory_compact(
             memory_ids=memory_ids,
             similarity_threshold=similarity_threshold,
             dry_run=dry_run,
+            owner_id=owner_id,
         )
 
     async def minder_skill_store(

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/models/repository.py

@@ -40,6 +40,7 @@ class Repository(Base):
 class RepositoryWorkflowStateSchema(BaseModelMeta):
     id: uuid.UUID = Field(default_factory=uuid.uuid4)
     repo_id: uuid.UUID
+    branch: str = "main"
     session_id: Optional[uuid.UUID] = None
     current_step: str
     completed_steps: List[str] = Field(default_factory=list)
@@ -53,6 +54,7 @@ class RepositoryWorkflowState(Base):
 
     id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     repo_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), index=True)
+    branch: Mapped[str] = mapped_column(String, index=True, default="main", server_default="main")
     session_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), nullable=True, index=True)
     current_step: Mapped[str] = mapped_column(String)
     completed_steps: Mapped[Dict[str, Any]] = mapped_column(JSON, default=list)  # stored as JSON list

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/models/skill.py

@@ -21,6 +21,8 @@ class SkillSchema(BaseModelMeta):
     deprecated: bool = False
     source_metadata: Optional[Dict[str, Any]] = None
     excerpt_kind: str = "none"
+    owner_id: Optional[uuid.UUID] = None  # principal who created this entry (None = team/legacy)
+    scope: str = "private"  # 'private' = owner-only, 'team' = visible to all principals
     created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
@@ -46,6 +48,13 @@ class Skill(Base):
         JSON, nullable=True
     )
     excerpt_kind: Mapped[str] = mapped_column(String, default="none")
+    # Multi-developer isolation: owner_id is the principal who created this entry.
+    # None means team/legacy (visible to all). Indexed for efficient filtering.
+    owner_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True), nullable=True, index=True
+    )
+    # 'private' = only visible to owner, 'team' = visible to all principals
+    scope: Mapped[str] = mapped_column(String, default="private", server_default="private")
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now()
     )

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/store/interfaces.py

@@ -64,6 +64,7 @@ class ISkillRepository(Protocol):
         *,
         is_memory: bool,
         exclude_deprecated: bool = True,
+        owner_id: uuid.UUID | None = None,
     ) -> list[Any]: ...
     async def update_skill(self, skill_id: uuid.UUID, **kwargs: Any) -> Any | None: ...
     async def delete_skill(self, skill_id: uuid.UUID) -> None: ...
@@ -144,7 +145,7 @@ class IRepositoryRepo(Protocol):
 class IWorkflowStateRepository(Protocol):
     async def create_workflow_state(self, **kwargs: Any) -> Any: ...
     async def get_workflow_state_by_id(self, state_id: uuid.UUID) -> Any | None: ...
-    async def get_workflow_state_by_repo(self, repo_id: uuid.UUID) -> Any | None: ...
+    async def get_workflow_state_by_repo(self, repo_id: uuid.UUID, *, branch: str = "main") -> Any | None: ...
     async def update_workflow_state(
         self, state_id: uuid.UUID, **kwargs: Any
     ) -> Any | None: ...

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/store/qdrant/operational_store.py

@@ -131,7 +131,7 @@ class QdrantOperationalStore:
         return await self._col("skills").find_many()
 
     async def list_skills_by_kind(
-        self, *, is_memory: bool, exclude_deprecated: bool = True
+        self, *, is_memory: bool, exclude_deprecated: bool = True, owner_id: uuid.UUID | None = None
     ) -> list[Any]:
         all_skills = await self.list_skills()
         _mem_langs = {"markdown", "text", "en", "vi", "", None}
@@ -140,6 +140,14 @@ class QdrantOperationalStore:
             sm = s._data.get("source_metadata")
             lang = s._data.get("language")
             is_mem = sm is None and lang in _mem_langs
+            
+            # Apply owner filtering
+            if owner_id is not None:
+                s_owner = s._data.get("owner_id")
+                s_scope = s._data.get("scope", "team")
+                if s_owner is not None and s_owner != str(owner_id) and s_scope != "team":
+                    continue
+
             if is_memory and is_mem:
                 result.append(s)
             elif not is_memory and not is_mem:
@@ -326,6 +334,7 @@ class QdrantOperationalStore:
         for uf in ("repo_id", "session_id"):
             if uf in kw and isinstance(kw[uf], uuid.UUID):
                 kw[uf] = _uid(kw[uf])
+        kw.setdefault("branch", "main")
         kw.setdefault("completed_steps", [])
         kw.setdefault("blocked_by", [])
         kw.setdefault("artifacts", {})
@@ -335,8 +344,12 @@ class QdrantOperationalStore:
     async def get_workflow_state_by_id(self, state_id: uuid.UUID) -> Any:
         return await self._col("workflow_states").get(_uid(state_id))
 
-    async def get_workflow_state_by_repo(self, repo_id: uuid.UUID) -> Any:
-        return await self._col("workflow_states").find_one("repo_id", _uid(repo_id))
+    async def get_workflow_state_by_repo(self, repo_id: uuid.UUID, *, branch: str = "main") -> Any:
+        states = await self._col("workflow_states").find_many({"repo_id": _uid(repo_id)})
+        for state in states:
+            if state._data.get("branch", "main") == branch:
+                return state
+        return None
 
     async def update_workflow_state(self, state_id: uuid.UUID, **kw: Any) -> Any:
         if not kw:

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/store/relational.py

@@ -125,6 +125,22 @@ class RelationalStore:
                 sync_conn.execute(
                     text("ALTER TABLE skills ADD COLUMN deprecated BOOLEAN NOT NULL DEFAULT 0")
                 )
+            # skills.owner_id + skills.scope (multi-developer isolation)
+            if "owner_id" not in existing:
+                sync_conn.execute(
+                    text("ALTER TABLE skills ADD COLUMN owner_id VARCHAR(36) DEFAULT NULL")
+                )
+            if "scope" not in existing:
+                sync_conn.execute(
+                    text("ALTER TABLE skills ADD COLUMN scope VARCHAR(10) NOT NULL DEFAULT 'team'")
+                )
+
+        if "repository_workflow_states" in inspector.get_table_names():
+            existing = {col["name"] for col in inspector.get_columns("repository_workflow_states")}
+            if "branch" not in existing:
+                sync_conn.execute(
+                    text("ALTER TABLE repository_workflow_states ADD COLUMN branch VARCHAR(255) NOT NULL DEFAULT 'main'")
+                )
 
     async def dispose(self) -> None:
         """Dispose the engine connection pool."""
@@ -266,6 +282,7 @@ class RelationalStore:
         *,
         is_memory: bool,
         exclude_deprecated: bool = True,
+        owner_id: uuid.UUID | None = None,
     ) -> List[Skill]:
         _memory_langs = ["markdown", "text", "en", "vi", ""]
         _is_memory_cond = Skill.source_metadata.is_(None) & (
@@ -278,6 +295,16 @@ class RelationalStore:
                 stmt = select(Skill).where(~_is_memory_cond)
                 if exclude_deprecated:
                     stmt = stmt.where(Skill.deprecated.isnot(True))
+            
+            if owner_id is not None:
+                # Can see their own private memories + team scope memories + legacy memories
+                stmt = stmt.where(
+                    or_(
+                        Skill.owner_id == owner_id,
+                        Skill.scope == "team",
+                        Skill.owner_id.is_(None)
+                    )
+                )
             result = await sess.execute(stmt)
             return list(result.scalars().all())
 
@@ -775,12 +802,13 @@ class RelationalStore:
             return result.scalar_one_or_none()
 
     async def get_workflow_state_by_repo(
-        self, repo_id: uuid.UUID
+        self, repo_id: uuid.UUID, *, branch: str = "main"
     ) -> Optional[RepositoryWorkflowState]:
         async with self._session() as sess:
             result = await sess.execute(
                 select(RepositoryWorkflowState).where(
-                    RepositoryWorkflowState.repo_id == repo_id
+                    RepositoryWorkflowState.repo_id == repo_id,
+                    RepositoryWorkflowState.branch == branch
                 )
             )
             return result.scalar_one_or_none()

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/store/repo_state.py

@@ -9,8 +9,8 @@ class RepoStateStore:
     def __init__(self, state_dir_name: str = ".minder") -> None:
         self._state_dir_name = state_dir_name
 
-    async def read_all(self, repo_path: str) -> dict[str, Any]:
-        state_dir = self._ensure_state_dir(repo_path)
+    async def read_all(self, repo_path: str, branch: str = "main") -> dict[str, Any]:
+        state_dir = self._ensure_state_dir(repo_path, branch)
         return {
             "workflow": self._read_json(state_dir / "workflow.json", default={}),
             "context": self._read_json(state_dir / "context.json", default={}),
@@ -18,22 +18,33 @@ class RepoStateStore:
             "artifacts": self._read_artifacts(state_dir / "artifacts"),
         }
 
-    async def write_workflow_state(self, repo_path: str, payload: dict[str, Any]) -> None:
-        self._write_json(self._ensure_state_dir(repo_path) / "workflow.json", payload)
+    async def write_workflow_state(self, repo_path: str, payload: dict[str, Any], branch: str = "main") -> None:
+        self._write_json(self._ensure_state_dir(repo_path, branch) / "workflow.json", payload)
 
-    async def write_context(self, repo_path: str, payload: dict[str, Any]) -> None:
-        self._write_json(self._ensure_state_dir(repo_path) / "context.json", payload)
+    async def write_context(self, repo_path: str, payload: dict[str, Any], branch: str = "main") -> None:
+        self._write_json(self._ensure_state_dir(repo_path, branch) / "context.json", payload)
 
-    async def write_relationships(self, repo_path: str, payload: dict[str, Any]) -> None:
-        self._write_json(self._ensure_state_dir(repo_path) / "relationships.json", payload)
+    async def write_relationships(self, repo_path: str, payload: dict[str, Any], branch: str = "main") -> None:
+        self._write_json(self._ensure_state_dir(repo_path, branch) / "relationships.json", payload)
 
-    async def write_artifact(self, repo_path: str, name: str, content: str) -> None:
-        artifacts_dir = self._ensure_state_dir(repo_path) / "artifacts"
+    async def write_artifact(self, repo_path: str, name: str, content: str, branch: str = "main") -> None:
+        artifacts_dir = self._ensure_state_dir(repo_path, branch) / "artifacts"
         artifacts_dir.mkdir(parents=True, exist_ok=True)
         (artifacts_dir / name).write_text(content, encoding="utf-8")
 
-    def _ensure_state_dir(self, repo_path: str) -> Path:
-        state_dir = Path(repo_path) / self._state_dir_name
+    def _ensure_state_dir(self, repo_path: str, branch: str = "main") -> Path:
+        base_dir = Path(repo_path) / self._state_dir_name
+        
+        # Phase 3: Auto-generate .gitignore in the base directory to prevent merge conflicts
+        if not base_dir.exists():
+            base_dir.mkdir(parents=True, exist_ok=True)
+            gitignore = base_dir / ".gitignore"
+            if not gitignore.exists():
+                gitignore.write_text("*\n", encoding="utf-8")
+                
+        # Branch isolation: normalize branch name to be safe for file system
+        safe_branch = "".join(c if c.isalnum() or c in "-_" else "_" for c in branch)
+        state_dir = base_dir / safe_branch
         state_dir.mkdir(parents=True, exist_ok=True)
         return state_dir
 

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/tools/memory.py

@@ -65,6 +65,7 @@ class MemoryTools:
         limit: int,
         current_step: str | None,
         artifact_type: str | None,
+        owner_id: uuid.UUID | None = None,
     ) -> list[dict[str, Any]]:
         graph = self._get_agentic_graph()
         result = await graph.run(
@@ -72,6 +73,7 @@ class MemoryTools:
                 "original_query": query,
                 "current_step": current_step,
                 "artifact_type": artifact_type,
+                "owner_id": owner_id,
                 "target_count": limit,
                 "min_score": float(self._config.memory.recall_min_score),
                 "all_memories": [],
@@ -95,9 +97,10 @@ class MemoryTools:
         current_step: str | None,
         artifact_type: str | None,
         include_raw_scores: bool = False,
+        owner_id: uuid.UUID | None = None,
     ) -> list[dict[str, Any]]:
         query_embedding = self._embedder.embed(query)
-        skills = await self._store.list_skills_by_kind(is_memory=True)
+        skills = await self._store.list_skills_by_kind(is_memory=True, owner_id=owner_id)
         vector_results: list[dict[str, Any]] = []
         corpus: list[dict[str, Any]] = []
         for skill in skills:
@@ -162,6 +165,8 @@ class MemoryTools:
         content: str,
         tags: list[str],
         language: str,
+        owner_id: uuid.UUID | None = None,
+        scope: str = "private",
     ) -> dict[str, Any]:
         # Normalize the language to a memory-eligible value so that
         # is_memory_record() always identifies this entry as a memory.
@@ -183,6 +188,8 @@ class MemoryTools:
             embedding=self._embedder.embed(f"{title}\n{content}"),
             usage_count=0,
             quality_score=0.0,
+            owner_id=owner_id,
+            scope=scope,
         )
 
         # Record persistent audit event
@@ -209,6 +216,7 @@ class MemoryTools:
         current_step: str | None = None,
         artifact_type: str | None = None,
         skip_synthesis: bool = False,
+        owner_id: uuid.UUID | None = None,
     ) -> list[dict[str, Any]]:
         if skip_synthesis:
             limited = await self._recall_candidates(
@@ -216,6 +224,7 @@ class MemoryTools:
                 limit=limit,
                 current_step=current_step,
                 artifact_type=artifact_type,
+                owner_id=owner_id,
             )
             for item in limited:
                 item.pop("_step_compat", None)
@@ -229,6 +238,7 @@ class MemoryTools:
                     limit=limit,
                     current_step=current_step,
                     artifact_type=artifact_type,
+                    owner_id=owner_id,
                 )
             except Exception:
                 pass
@@ -238,6 +248,7 @@ class MemoryTools:
             limit=limit,
             current_step=current_step,
             artifact_type=artifact_type,
+            owner_id=owner_id,
         )
 
         try:
@@ -283,8 +294,12 @@ class MemoryTools:
             item.pop("continuity_reasons", None)
         return limited
 
-    async def minder_memory_list(self) -> list[dict[str, Any]]:
-        skills = await self._store.list_skills_by_kind(is_memory=True)
+    async def minder_memory_list(
+        self,
+        *,
+        owner_id: uuid.UUID | None = None,
+    ) -> list[dict[str, Any]]:
+        skills = await self._store.list_skills_by_kind(is_memory=True, owner_id=owner_id)
         return [
             {
                 "id": str(skill.id),
@@ -302,10 +317,16 @@ class MemoryTools:
         title: str | None = None,
         content: str | None = None,
         tags: list[str] | None = None,
+        owner_id: uuid.UUID | None = None,
     ) -> dict[str, Any]:
         existing = await self._store.get_skill_by_id(uuid.UUID(memory_id))
         if existing is None or not is_memory_record(existing):
             raise ValueError(f"Memory not found: {memory_id}")
+            
+        if owner_id is not None:
+            existing_owner = getattr(existing, "owner_id", None)
+            if existing_owner is not None and str(existing_owner) != str(owner_id):
+                raise ValueError(f"Access denied: you do not own memory {memory_id}")
 
         update_data: dict[str, Any] = {}
         next_title = title if title is not None else str(existing.title)
@@ -343,7 +364,15 @@ class MemoryTools:
             "updated": True,
         }
 
-    async def minder_memory_delete(self, skill_id: str) -> dict[str, bool]:
+    async def minder_memory_delete(self, skill_id: str, *, owner_id: uuid.UUID | None = None) -> dict[str, bool]:
+        if owner_id is not None:
+            existing = await self._store.get_skill_by_id(uuid.UUID(skill_id))
+            if existing is None or not is_memory_record(existing):
+                raise ValueError(f"Memory not found: {skill_id}")
+            existing_owner = getattr(existing, "owner_id", None)
+            if existing_owner is not None and str(existing_owner) != str(owner_id):
+                raise ValueError(f"Access denied: you do not own memory {skill_id}")
+                
         await self._store.delete_skill(uuid.UUID(skill_id))
 
         # Record persistent audit event
@@ -367,6 +396,7 @@ class MemoryTools:
         memory_ids: list[str],
         similarity_threshold: float = 0.92,
         dry_run: bool = True,
+        owner_id: uuid.UUID | None = None,
     ) -> dict[str, Any]:
         normalized_ids = self._normalize_memory_ids(memory_ids)
         if len(normalized_ids) < 2:
@@ -377,6 +407,11 @@ class MemoryTools:
             skill = await self._store.get_skill_by_id(uuid.UUID(memory_id))
             if skill is None:
                 raise ValueError(f"Memory not found: {memory_id}")
+            
+            if owner_id is not None:
+                existing_owner = getattr(skill, "owner_id", None)
+                if existing_owner is not None and str(existing_owner) != str(owner_id):
+                    raise ValueError(f"Access denied: you do not own memory {memory_id}")
             embedding = self._embedder.embed(
                 self._compaction_text(
                     title=str(skill.title),

{minder_cli-0.6.2 → minder_cli-0.6.3}/src/minder/tools/workflow.py

@@ -35,15 +35,15 @@ class WorkflowTools:
         return self._graph
 
     async def minder_workflow_get(
-        self, *, repo_id: uuid.UUID, repo_path: str
+        self, *, repo_id: uuid.UUID, repo_path: str, branch: str = "main"
     ) -> dict[str, Any]:
         repo = await self._require_repo(repo_id)
         workflow = await self._require_workflow(repo.workflow_id)
-        state = await self._store.get_workflow_state_by_repo(repo_id)
+        state = await self._require_workflow_state(repo_id, branch=branch)
         relationships = (
             dict(repo.relationships) if isinstance(repo.relationships, dict) else {}
         )
-        await self._repo_state.write_relationships(repo_path, relationships)
+        await self._repo_state.write_relationships(repo_path, relationships, branch=branch)
         if state is not None:
             await self._repo_state.write_workflow_state(
                 repo_path,
@@ -53,6 +53,7 @@ class WorkflowTools:
                     "blocked_by": list(state.blocked_by),
                     "next_step": state.next_step,
                 },
+                branch=branch,
             )
         return {
             "workflow": {
@@ -70,6 +71,7 @@ class WorkflowTools:
         repo_path: str | None = None,
         session_id: uuid.UUID | None = None,
         decision: dict[str, Any] | None = None,
+        branch: str = "main",
     ) -> dict[str, Any]:
         if session_id is not None or decision is not None:
             if session_id is None or decision is None:
@@ -100,7 +102,7 @@ class WorkflowTools:
             raise ValueError("repo_id and repo_path are required when not resuming")
         repo = await self._require_repo(repo_id)
         workflow = await self._require_workflow(repo.workflow_id)
-        state = await self._require_workflow_state(repo_id)
+        state = await self._require_workflow_state(repo_id, branch=branch)
         envelope = build_instruction_envelope(workflow=workflow, workflow_state=state)
         await self._repo_state.write_workflow_state(
             repo_path,
@@ -110,6 +112,7 @@ class WorkflowTools:
                 "blocked_by": list(state.blocked_by),
                 "next_step": state.next_step,
             },
+            branch=branch,
         )
         for _k in ("workflow_id", "workflow_version", "policies"):
             envelope.pop(_k, None)
@@ -127,10 +130,11 @@ class WorkflowTools:
         completed_step: str,
         artifact_name: str | None = None,
         artifact_content: str | None = None,
+        branch: str = "main",
     ) -> dict[str, Any]:
         repo = await self._require_repo(repo_id)
         workflow = await self._require_workflow(repo.workflow_id)
-        state = await self._require_workflow_state(repo_id)
+        state = await self._require_workflow_state(repo_id, branch=branch)
         step_names = [
             step["name"]
             for step in workflow.steps
@@ -144,7 +148,7 @@ class WorkflowTools:
         if artifact_name and artifact_content is not None:
             artifacts[artifact_name] = artifact_content
             await self._repo_state.write_artifact(
-                repo_path, artifact_name, artifact_content
+                repo_path, artifact_name, artifact_content, branch=branch
             )
         updated = await self._store.update_workflow_state(
             state.id,
@@ -163,10 +167,12 @@ class WorkflowTools:
                 "blocked_by": list(updated.blocked_by),
                 "next_step": updated.next_step,
             },
+            branch=branch,
         )
         await self._repo_state.write_relationships(
             repo_path,
             dict(repo.relationships) if isinstance(repo.relationships, dict) else {},
+            branch=branch,
         )
         return {
             "current_step": updated.current_step,
@@ -180,10 +186,11 @@ class WorkflowTools:
         repo_id: uuid.UUID,
         requested_step: str,
         action: str | None = None,
+        branch: str = "main",
     ) -> dict[str, Any]:
         repo = await self._require_repo(repo_id)
         workflow = await self._require_workflow(repo.workflow_id)
-        state = await self._require_workflow_state(repo_id)
+        state = await self._require_workflow_state(repo_id, branch=branch)
         step_names = [
             step["name"]
             for step in workflow.steps
@@ -234,8 +241,8 @@ class WorkflowTools:
             raise ValueError(f"Workflow not found: {workflow_id}")
         return workflow
 
-    async def _require_workflow_state(self, repo_id: uuid.UUID):  # noqa: ANN202
-        state = await self._store.get_workflow_state_by_repo(repo_id)
+    async def _require_workflow_state(self, repo_id: uuid.UUID, *, branch: str = "main"):  # noqa: ANN202
+        state = await self._store.get_workflow_state_by_repo(repo_id, branch=branch)
         if state is None:
             raise ValueError(f"Workflow state not found for repo: {repo_id}")
         return state