@researai/deepscientist 1.5.15 → 1.5.17

package/src/deepscientist/quest/stage_views.py

@@ -234,10 +234,11 @@ class QuestStageViewBuilder:
 
     def build(self) -> dict[str, Any]:
         selection_type = str(self.selection.get("selection_type") or "").strip()
+        explicit_stage_key = str(self.selection.get("stage_key") or "").strip()
         self.stage_key = self._resolve_effective_stage_key()
         if selection_type == "idea_candidate":
             return self._build_idea_candidate()
-        if selection_type == "branch_node" and self.stage_key not in {"experiment", "analysis", "paper"}:
+        if selection_type == "branch_node" and not explicit_stage_key:
             return self._build_branch()
         if self.stage_key == "baseline":
             return self._build_baseline()
@@ -1288,11 +1289,15 @@ class QuestStageViewBuilder:
             for item in self.artifacts
             if self._branch_matches(self._payload(item), allow_parent=True, include_unscoped=False)
         ]
+        latest_branch_payload = self._payload(branch_items[-1] if branch_items else {})
         note = (
             str(
                 latest_experiment_payload.get("summary")
                 or latest_idea_payload.get("summary")
                 or latest_idea_payload.get("reason")
+                or latest_branch_payload.get("summary")
+                or latest_branch_payload.get("message")
+                or latest_branch_payload.get("reason")
                 or self.trace.get("summary")
                 or self.selection.get("summary")
                 or ""

package/src/deepscientist/runners/codex.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import json
 import os
 import signal
-import shutil
 import subprocess
 import sys
 import threading
@@ -11,12 +10,18 @@ from pathlib import Path
 from typing import Any
 
 from ..artifact import ArtifactService
-from ..codex_cli_compat import adapt_profile_only_provider_config, normalize_codex_reasoning_effort
+from ..codex_cli_compat import (
+    active_provider_metadata_from_home,
+    materialize_codex_runtime_home,
+    normalize_codex_reasoning_effort,
+    provider_profile_metadata_from_home,
+)
 from ..config import ConfigManager
 from ..gitops import export_git_graph
+from ..process_control import process_session_popen_kwargs
 from ..prompts import PromptBuilder
 from ..runtime_logs import JsonlLogger
-from ..shared import append_jsonl, ensure_dir, generate_id, read_text, read_yaml, resolve_runner_binary, utc_now, write_json, write_text
+from ..shared import append_jsonl, ensure_dir, generate_id, read_yaml, resolve_runner_binary, utc_now, write_json, write_text
 from ..web_search import extract_web_search_payload
 from .base import RunRequest, RunResult
 
@@ -69,6 +74,12 @@ _BUILTIN_MCP_TOOL_APPROVALS: dict[str, tuple[str, ...]] = {
     ),
 }
 
+_PROVIDER_ENV_CONFLICT_KEYS = (
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+)
+_CHAT_WIRE_TOOL_CALL_GUARD_MARKER = "## Codex Chat-Wire Tool Call Compatibility"
+
 
 def _compact_text(value: object, *, limit: int = 1200) -> str:
     if value is None:
@@ -195,7 +206,9 @@ def _iter_event_texts(event: dict[str, Any]) -> list[str]:
                     if isinstance(value, str) and value.strip():
                         texts.append(value)
     delta = event.get("delta")
-    if isinstance(delta, dict):
+    if isinstance(delta, str) and delta.strip():
+        texts.append(delta)
+    elif isinstance(delta, dict):
         for key in ("text", "content"):
             value = delta.get(key)
             if isinstance(value, str) and value.strip():
@@ -222,6 +235,36 @@ def _web_search_text_payload(item: dict[str, Any]) -> str:
     return _compact_text(payload, limit=2400)
 
 
+def _message_stream_id(event: dict[str, Any], item: dict[str, Any], *, run_id: str, kind: str) -> str:
+    for value in (
+        event.get("stream_id"),
+        item.get("stream_id"),
+        event.get("message_id"),
+        item.get("message_id"),
+        event.get("item_id"),
+        item.get("id"),
+        event.get("output_item_id"),
+        event.get("response_id"),
+    ):
+        if value:
+            return str(value)
+    normalized_kind = str(kind or "message").strip().lower() or "message"
+    return f"{run_id}:{normalized_kind}"
+
+
+def _message_id(event: dict[str, Any], item: dict[str, Any], *, stream_id: str) -> str:
+    for value in (
+        event.get("message_id"),
+        item.get("message_id"),
+        event.get("item_id"),
+        item.get("id"),
+        event.get("output_item_id"),
+    ):
+        if value:
+            return str(value)
+    return stream_id
+
+
 def _message_events(
     event: dict[str, Any],
     *,
@@ -238,6 +281,8 @@ def _message_events(
 
     if item_type == "agent_message":
         texts = _dedupe_texts(_iter_event_texts(event))
+        stream_id = _message_stream_id(event, item, run_id=run_id, kind="assistant")
+        message_id = _message_id(event, item, stream_id=stream_id)
         for text in texts:
             quest_events.append(
                 {
@@ -248,6 +293,8 @@ def _message_events(
                     "source": "codex",
                     "skill_id": skill_id,
                     "text": text,
+                    "stream_id": stream_id,
+                    "message_id": message_id,
                     "created_at": created_at,
                 }
             )
@@ -255,6 +302,8 @@ def _message_events(
 
     if item_type in {"reasoning", "reasoning_summary"} or "reasoning" in event_type:
         texts = _dedupe_texts(_iter_event_texts(event))
+        stream_id = _message_stream_id(event, item, run_id=run_id, kind=item_type or "reasoning")
+        message_id = _message_id(event, item, stream_id=stream_id)
         for text in texts:
             quest_events.append(
                 {
@@ -265,6 +314,8 @@ def _message_events(
                     "source": "codex",
                     "skill_id": skill_id,
                     "text": text,
+                    "stream_id": stream_id,
+                    "message_id": message_id,
                     "kind": item_type or "reasoning",
                     "created_at": created_at,
                 }
@@ -278,6 +329,8 @@ def _message_events(
         return [], []
 
     texts = _dedupe_texts(_iter_event_texts(event))
+    stream_id = _message_stream_id(event, item, run_id=run_id, kind="assistant")
+    message_id = _message_id(event, item, stream_id=stream_id)
     for text in texts:
         quest_events.append(
             {
@@ -288,6 +341,8 @@ def _message_events(
                 "source": "codex",
                 "skill_id": skill_id,
                 "text": text,
+                "stream_id": stream_id,
+                "message_id": message_id,
                 "created_at": created_at,
             }
         )
@@ -679,6 +734,18 @@ class CodexRunner:
         self._process_lock = threading.Lock()
         self._active_processes: dict[str, subprocess.Popen[str]] = {}
 
+    @staticmethod
+    def _subprocess_popen_kwargs(*, workspace_root: Path, env: dict[str, str]) -> dict[str, Any]:
+        return {
+            "cwd": str(workspace_root),
+            "env": env,
+            "stdin": subprocess.PIPE,
+            "stdout": subprocess.PIPE,
+            "stderr": subprocess.PIPE,
+            "text": True,
+            **process_session_popen_kwargs(hide_window=True),
+        }
+
     def run(self, request: RunRequest) -> RunResult:
         workspace_root = request.worktree_root or request.quest_root
         run_root = ensure_dir(request.quest_root / ".ds" / "runs" / request.run_id)
@@ -694,6 +761,7 @@ class CodexRunner:
             turn_mode=request.turn_mode,
             retry_context=request.retry_context,
         )
+        prompt = self._apply_chat_wire_tool_call_guard(prompt, runner_config=runner_config)
         write_text(run_root / "prompt.md", prompt)
 
         codex_home = self._prepare_project_codex_home(
@@ -729,6 +797,7 @@ class CodexRunner:
                 continue
             env[env_key] = env_value
         env["CODEX_HOME"] = str(codex_home)
+        env = self._sanitize_provider_env(env, runner_config=runner_config)
         env["DEEPSCIENTIST_HOME"] = str(self.home)
         env["DS_HOME"] = str(self.home)
         env["DS_QUEST_ID"] = request.quest_id
@@ -743,18 +812,7 @@ class CodexRunner:
         env["DS_CONVERSATION_ID"] = f"quest:{request.quest_id}"
         env["DS_AGENT_ROLE"] = request.skill_id
         env["DS_TEAM_MODE"] = "single"
-        popen_kwargs: dict[str, Any] = {
-            "cwd": str(workspace_root),
-            "env": env,
-            "stdin": subprocess.PIPE,
-            "stdout": subprocess.PIPE,
-            "stderr": subprocess.PIPE,
-            "text": True,
-        }
-        if os.name == "nt" and hasattr(subprocess, "CREATE_NEW_PROCESS_GROUP"):
-            popen_kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP")
-        else:
-            popen_kwargs["start_new_session"] = True
+        popen_kwargs = self._subprocess_popen_kwargs(workspace_root=workspace_root, env=env)
         process = subprocess.Popen(command, **popen_kwargs)
         with self._process_lock:
             self._active_processes[request.quest_id] = process
@@ -975,6 +1033,8 @@ class CodexRunner:
         resolved_runner_config = runner_config if isinstance(runner_config, dict) else self._load_runner_config()
         profile = str(resolved_runner_config.get("profile") or "").strip()
         normalized_model = str(request.model or "").strip()
+        if profile and normalized_model.lower() not in {"", "inherit", "default", "codex-default"}:
+            normalized_model = "inherit"
         command = [
             resolved_binary or self.binary,
             "--search",
@@ -1010,6 +1070,46 @@ class CodexRunner:
         command.append("-")
         return command
 
+    def _apply_chat_wire_tool_call_guard(
+        self,
+        prompt: str,
+        *,
+        runner_config: dict[str, Any] | None = None,
+    ) -> str:
+        prompt_text = str(prompt or "")
+        if not prompt_text or _CHAT_WIRE_TOOL_CALL_GUARD_MARKER in prompt_text:
+            return prompt_text
+
+        resolved_runner_config = runner_config if isinstance(runner_config, dict) else self._load_runner_config()
+        profile = str(resolved_runner_config.get("profile") or "").strip()
+        if not profile:
+            return prompt_text
+        config_home = str(resolved_runner_config.get("config_dir") or os.environ.get("CODEX_HOME") or "").strip()
+        if not config_home:
+            return prompt_text
+
+        metadata = active_provider_metadata_from_home(config_home, profile=profile or None)
+        wire_api = str(metadata.get("wire_api") or "").strip().lower()
+        if wire_api != "chat":
+            return prompt_text
+
+        provider = str(metadata.get("provider") or "").strip() or "unknown"
+        guard_lines = [
+            _CHAT_WIRE_TOOL_CALL_GUARD_MARKER,
+            f"active_provider_profile: {profile}",
+            f"active_provider_name: {provider}",
+            "active_provider_wire_api: chat",
+            "single_tool_call_per_turn_rule: emit at most one tool call in each assistant message.",
+            "tool_call_serialization_rule: after each tool result, decide whether to make the next tool call or produce the answer.",
+            "no_batched_mcp_rule: never bundle multiple `artifact.*`, `memory.*`, or `bash_exec.*` calls into the same response, even when the reads look independent.",
+            "no_immediate_repeat_rule: if a tool already returned the information needed for the current subtask, do not immediately call that same tool again; move to the next tool or answer.",
+            "state_recovery_preference_rule: on a fresh quest turn, prefer `artifact.get_quest_state`, `artifact.read_quest_documents`, and `memory.list_recent` to recover context before reaching for `bash_exec`.",
+            "bash_exec_after_context_rule: use `bash_exec` only after you know the exact command you need and why the `artifact` / `memory` path is insufficient.",
+            "tool_call_json_rule: every tool call must contain exactly one complete JSON object argument with no trailing characters.",
+        ]
+        guard_block = "\n".join(guard_lines)
+        return f"{prompt_text.rstrip()}\n\n{guard_block}\n"
+
     def _prepare_project_codex_home(
         self,
         workspace_root: Path,
@@ -1019,36 +1119,16 @@ class CodexRunner:
         run_id: str,
         runner_config: dict[str, Any] | None = None,
     ) -> Path:
-        target = ensure_dir(workspace_root / ".codex")
+        target = ensure_dir(workspace_root / ".ds" / "codex-home")
         resolved_runner_config = runner_config if isinstance(runner_config, dict) else self._load_runner_config()
         configured_home = str(resolved_runner_config.get("config_dir") or os.environ.get("CODEX_HOME") or str(Path.home() / ".codex"))
         profile = str(resolved_runner_config.get("profile") or "").strip()
-        source = Path(configured_home).expanduser()
-        for filename in ("config.toml", "auth.json"):
-            source_path = source / filename
-            target_path = target / filename
-            if not source_path.exists():
-                continue
-            if source_path.resolve() == target_path.resolve():
-                continue
-            shutil.copy2(source_path, target_path)
-        config_path = target / "config.toml"
-        if profile and config_path.exists():
-            adapted_text, _ = adapt_profile_only_provider_config(read_text(config_path), profile=profile)
-            write_text(config_path, adapted_text)
-        ensure_dir(target / "skills")
-        quest_skills_root = quest_root / ".codex" / "skills"
-        if quest_skills_root.exists():
-            for source_path in sorted(quest_skills_root.rglob("*")):
-                relative = source_path.relative_to(quest_skills_root)
-                target_path = target / "skills" / relative
-                if source_path.is_dir():
-                    ensure_dir(target_path)
-                    continue
-                if source_path.resolve() == target_path.resolve():
-                    continue
-                ensure_dir(target_path.parent)
-                shutil.copy2(source_path, target_path)
+        materialize_codex_runtime_home(
+            source_home=configured_home,
+            target_home=target,
+            profile=profile,
+            quest_codex_root=quest_root / ".codex",
+        )
         self._inject_built_in_mcp(
             target,
             quest_root=quest_root,
@@ -1157,3 +1237,23 @@ class CodexRunner:
         except (TypeError, ValueError):
             return None
         return timeout if timeout > 0 else None
+
+    @staticmethod
+    def _sanitize_provider_env(
+        env: dict[str, str],
+        *,
+        runner_config: dict[str, Any] | None = None,
+    ) -> dict[str, str]:
+        resolved_runner_config = runner_config if isinstance(runner_config, dict) else {}
+        profile = str(resolved_runner_config.get("profile") or "").strip()
+        config_home = str(resolved_runner_config.get("config_dir") or env.get("CODEX_HOME") or "").strip()
+        if not config_home:
+            return env
+        metadata = active_provider_metadata_from_home(config_home, profile=profile or None)
+        requires_openai_auth = metadata.get("requires_openai_auth")
+        if requires_openai_auth is not False:
+            return env
+        sanitized = dict(env)
+        for key in _PROVIDER_ENV_CONFLICT_KEYS:
+            sanitized.pop(key, None)
+        return sanitized

package/src/deepscientist/shared.py

@@ -13,6 +13,8 @@ from pathlib import Path
 from typing import Any, Iterator
 from uuid import uuid4
 
+from .process_control import process_session_popen_kwargs
+
 try:
     import yaml
 except ModuleNotFoundError as exc:  # pragma: no cover
@@ -168,6 +170,23 @@ def run_command(
         check=check,
         text=True,
         capture_output=True,
+        **process_session_popen_kwargs(hide_window=True, new_process_group=False),
+    )
+
+
+def run_command_bytes(
+    args: list[str],
+    *,
+    cwd: Path | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(
+        args,
+        cwd=str(cwd) if cwd else None,
+        check=check,
+        text=False,
+        capture_output=True,
+        **process_session_popen_kwargs(hide_window=True, new_process_group=False),
     )
 
 

package/src/deepscientist/skills/__init__.py

@@ -1,4 +1,4 @@
 from .installer import SkillInstaller
-from .registry import SkillBundle, discover_skill_bundles
+from .registry import SkillBundle, companion_skill_ids, discover_skill_bundles, stage_skill_ids
 
-__all__ = ["SkillBundle", "SkillInstaller", "discover_skill_bundles"]
+__all__ = ["SkillBundle", "SkillInstaller", "discover_skill_bundles", "stage_skill_ids", "companion_skill_ids"]

package/src/deepscientist/skills/installer.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import hashlib
+import re
 import shutil
 from pathlib import Path
 from uuid import uuid4
@@ -8,6 +10,10 @@ from ..memory.frontmatter import load_markdown_document
 from ..shared import ensure_dir, read_json, utc_now, write_json
 from .registry import discover_skill_bundles
 
+_PROMPT_SYNC_STATE_FILENAME = ".deepscientist-prompt-sync.json"
+_PROMPT_VERSIONS_DIRNAME = "prompt_versions"
+_PROMPT_VERSIONS_INDEX_FILENAME = "index.json"
+
 
 class SkillInstaller:
     def __init__(self, repo_root: Path, home: Path) -> None:
@@ -40,9 +46,9 @@ class SkillInstaller:
             "notes": [],
         }
 
-    def sync_quest(self, quest_root: Path) -> dict:
+    def sync_quest(self, quest_root: Path, *, installed_version: str | None = None) -> dict:
+        prompt_sync = self.sync_quest_prompts(quest_root, installed_version=installed_version)
         prompts_root = ensure_dir(quest_root / ".codex" / "prompts")
-        self._sync_prompt_tree(prompts_root)
         codex_root = ensure_dir(quest_root / ".codex" / "skills")
         claude_root = ensure_dir(quest_root / ".claude" / "agents")
         copied_codex: list[str] = []
@@ -61,12 +67,13 @@ class SkillInstaller:
         self._prune_bundle_targets(claude_root, expected_claude)
         return {
             "prompts": [str(path) for path in sorted(prompts_root.rglob("*")) if path.is_file()],
+            "prompt_sync": prompt_sync,
             "codex": copied_codex,
             "claude": copied_claude,
             "notes": [],
         }
 
-    def sync_existing_quests(self) -> dict:
+    def sync_existing_quests(self, *, installed_version: str | None = None) -> dict:
         quests_root = self.home / "quests"
         synced: list[dict[str, object]] = []
         if not quests_root.exists():
@@ -79,13 +86,15 @@ class SkillInstaller:
                 continue
             if not (quest_root / "quest.yaml").exists():
                 continue
-            result = self.sync_quest(quest_root)
+            result = self.sync_quest(quest_root, installed_version=installed_version)
             synced.append(
                 {
                     "quest_id": quest_root.name,
                     "quest_root": str(quest_root),
                     "codex_count": len(result.get("codex") or []),
                     "claude_count": len(result.get("claude") or []),
+                    "prompt_backup_id": (result.get("prompt_sync") or {}).get("backup_id"),
+                    "prompt_fingerprint": (result.get("prompt_sync") or {}).get("prompt_fingerprint"),
                 }
             )
         return {
@@ -127,11 +136,193 @@ class SkillInstaller:
             summary["global"] = self.sync_global()
             summary["global_synced"] = True
         if sync_existing_quests_enabled:
-            summary["existing_quests"] = self.sync_existing_quests()
+            summary["existing_quests"] = self.sync_existing_quests(installed_version=normalized_version)
             summary["existing_quests_synced"] = True
         self._write_release_sync_state(summary)
         return summary
 
+    def sync_quest_prompts(
+        self,
+        quest_root: Path,
+        *,
+        installed_version: str | None = None,
+    ) -> dict[str, object]:
+        prompts_root = ensure_dir(quest_root / ".codex" / "prompts")
+        source_root = self.repo_root / "src" / "prompts"
+        normalized_version = self._normalized_installed_version(installed_version)
+        previous_state = self._read_prompt_sync_state(prompts_root)
+        current_fingerprint = self._prompt_tree_fingerprint(prompts_root, exclude_state_file=True)
+        source_fingerprint = self._prompt_tree_fingerprint(source_root, exclude_state_file=False)
+        backup_id: str | None = None
+        updated = False
+
+        if current_fingerprint != source_fingerprint:
+            if current_fingerprint:
+                backup_id = self._backup_prompt_tree(
+                    quest_root,
+                    prompts_root=prompts_root,
+                    installed_version=str(previous_state.get("installed_version") or normalized_version),
+                    prompt_fingerprint=current_fingerprint,
+                )
+            self._sync_prompt_tree(prompts_root)
+            updated = True
+
+        prompt_state = {
+            "installed_version": normalized_version,
+            "prompt_fingerprint": self._prompt_tree_fingerprint(prompts_root, exclude_state_file=True),
+            "synced_at": utc_now(),
+            "backup_id": backup_id,
+            "source_root": str(source_root),
+        }
+        write_json(self._prompt_sync_state_path(prompts_root), prompt_state)
+        return {
+            "updated": updated,
+            "backup_id": backup_id,
+            "prompt_fingerprint": prompt_state["prompt_fingerprint"],
+            "installed_version": normalized_version,
+            "source_root": str(source_root),
+            "active_root": str(prompts_root),
+            "versions_root": str(self._prompt_versions_root(quest_root)),
+        }
+
+    def list_prompt_versions(self, quest_root: Path) -> list[dict[str, object]]:
+        payload = read_json(self._prompt_versions_index_path(quest_root), {})
+        versions = payload.get("versions") if isinstance(payload.get("versions"), list) else []
+        return [dict(item) for item in versions if isinstance(item, dict)]
+
+    def resolve_prompt_version_root(self, quest_root: Path, selection: str) -> Path | None:
+        normalized = str(selection or "").strip()
+        if not normalized:
+            return None
+        exact_root = self._prompt_versions_root(quest_root) / normalized
+        if exact_root.exists():
+            return exact_root
+        candidates = [
+            dict(item)
+            for item in self.list_prompt_versions(quest_root)
+            if str(item.get("installed_version") or "").strip() == normalized
+        ]
+        if not candidates:
+            return None
+        candidates.sort(key=lambda item: str(item.get("created_at") or ""))
+        selected_path = Path(str(candidates[-1].get("path") or "")).expanduser()
+        return selected_path if selected_path.exists() else None
+
+    @staticmethod
+    def _normalized_installed_version(installed_version: str | None) -> str:
+        normalized = str(installed_version or "").strip()
+        if normalized:
+            return normalized
+        from .. import __version__
+
+        return str(__version__ or "").strip() or "unknown"
+
+    def _backup_prompt_tree(
+        self,
+        quest_root: Path,
+        *,
+        prompts_root: Path,
+        installed_version: str,
+        prompt_fingerprint: str,
+    ) -> str:
+        versions_root = ensure_dir(self._prompt_versions_root(quest_root))
+        backup_id = ""
+        target_root: Path | None = None
+        for _attempt in range(8):
+            backup_id = self._unique_prompt_backup_id(
+                versions_root,
+                installed_version=installed_version,
+                prompt_fingerprint=prompt_fingerprint,
+            )
+            target_root = versions_root / backup_id
+            try:
+                shutil.copytree(prompts_root, target_root)
+                break
+            except FileExistsError:
+                # Another sync run may have created the same backup directory between
+                # name selection and copy. Regenerate a fresh id and retry.
+                continue
+        else:
+            raise FileExistsError(
+                f"Failed to allocate a unique prompt backup directory under `{versions_root}` after multiple attempts."
+            )
+        assert target_root is not None
+        entry = {
+            "backup_id": backup_id,
+            "installed_version": str(installed_version or "").strip() or "unknown",
+            "prompt_fingerprint": prompt_fingerprint,
+            "created_at": utc_now(),
+            "path": str(target_root),
+        }
+        versions = self.list_prompt_versions(quest_root)
+        versions = [item for item in versions if str(item.get("backup_id") or "").strip() != backup_id]
+        versions.append(entry)
+        versions.sort(key=lambda item: str(item.get("created_at") or ""))
+        write_json(self._prompt_versions_index_path(quest_root), {"versions": versions})
+        return backup_id
+
+    @staticmethod
+    def _prompt_versions_root(quest_root: Path) -> Path:
+        return ensure_dir(quest_root / ".codex" / _PROMPT_VERSIONS_DIRNAME)
+
+    @staticmethod
+    def _prompt_versions_index_path(quest_root: Path) -> Path:
+        return SkillInstaller._prompt_versions_root(quest_root) / _PROMPT_VERSIONS_INDEX_FILENAME
+
+    @staticmethod
+    def _prompt_sync_state_path(prompts_root: Path) -> Path:
+        return prompts_root / _PROMPT_SYNC_STATE_FILENAME
+
+    def _read_prompt_sync_state(self, prompts_root: Path) -> dict[str, object]:
+        payload = read_json(self._prompt_sync_state_path(prompts_root), {})
+        return payload if isinstance(payload, dict) else {}
+
+    @staticmethod
+    def _sanitize_prompt_label(value: str) -> str:
+        normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", str(value or "").strip()).strip("-")
+        return normalized or "unknown"
+
+    def _unique_prompt_backup_id(
+        self,
+        versions_root: Path,
+        *,
+        installed_version: str,
+        prompt_fingerprint: str,
+    ) -> str:
+        version_label = self._sanitize_prompt_label(installed_version)
+        timestamp_label = self._sanitize_prompt_label(
+            utc_now().replace(":", "").replace("+00:00", "Z")
+        )
+        fingerprint_label = (str(prompt_fingerprint or "").strip() or "unknown")[:12]
+        base = f"{version_label}__prompts-{fingerprint_label}__{timestamp_label}"
+        candidate = base
+        counter = 2
+        while (versions_root / candidate).exists():
+            candidate = f"{base}__{counter}"
+            counter += 1
+        return candidate
+
+    @staticmethod
+    def _prompt_tree_fingerprint(root: Path, *, exclude_state_file: bool) -> str:
+        if not root.exists():
+            return ""
+        files = [
+            path
+            for path in sorted(root.rglob("*"))
+            if path.is_file()
+            and not (exclude_state_file and path.name == _PROMPT_SYNC_STATE_FILENAME)
+        ]
+        if not files:
+            return ""
+        hasher = hashlib.sha256()
+        for path in files:
+            relative = path.relative_to(root).as_posix()
+            hasher.update(relative.encode("utf-8"))
+            hasher.update(b"\0")
+            hasher.update(hashlib.sha256(path.read_bytes()).hexdigest().encode("ascii"))
+            hasher.update(b"\0")
+        return hasher.hexdigest()
+
     def _sync_claude_projection(self, bundle, target_root: Path) -> Path:
         target = target_root / f"deepscientist-{bundle.skill_id}.md"
         if bundle.claude_md and bundle.claude_md.exists():