@scemoon/cdh 1.0.3 → 1.0.5

package/onecode/config.py

@@ -1,13 +1,16 @@
+import logging
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Optional
 
 import yaml
 
+logger = logging.getLogger("onecode.config")
 
-CLOUD_DEV_HARNESS_DIR = Path.home() / ".cdh"
-GLOBAL_CONFIG_PATH = CLOUD_DEV_HARNESS_DIR / "onecode.config.yaml"
+
+ONECODE_DIR = Path.home() / ".onecode"
+GLOBAL_CONFIG_PATH = ONECODE_DIR / "onecode.config.yaml"
 
 
 @dataclass
@@ -22,7 +25,7 @@ class ObservabilityConfig:
     trace_enabled: bool = True
     trace_exporter: str = "file"
     otlp_endpoint: str = "http://localhost:4317"
-    trace_dir: str = "~/.cdh/traces"
+    trace_dir: str = "~/.onecode/traces"
 
 
 @dataclass
@@ -86,6 +89,13 @@ class CodebaseConfig:
     ])
 
 
+@dataclass
+class MemoryConfig:
+    enabled: bool = True
+    auto_recall: bool = True
+    top_k: int = 5
+
+
 @dataclass
 class GlobalConfig:
     default_mode: str = "build"
@@ -102,6 +112,7 @@ class GlobalConfig:
     log_level: str = "info"
     session_auto_save: bool = True
     codebase: CodebaseConfig = field(default_factory=CodebaseConfig)
+    memory: MemoryConfig = field(default_factory=MemoryConfig)
 
 
 def _dict_to_dataclass(cls, data: dict):
@@ -133,22 +144,40 @@ def _dict_to_dataclass(cls, data: dict):
 
 def ensure_dirs():
     dirs = [
-        CLOUD_DEV_HARNESS_DIR,
-        CLOUD_DEV_HARNESS_DIR / "sessions",
-        CLOUD_DEV_HARNESS_DIR / "skills",
-        CLOUD_DEV_HARNESS_DIR / "mcps",
-        CLOUD_DEV_HARNESS_DIR / "traces",
-        CLOUD_DEV_HARNESS_DIR / "logs",
-        CLOUD_DEV_HARNESS_DIR / "models",
+        ONECODE_DIR,
+        ONECODE_DIR / "sessions",
+        ONECODE_DIR / "skills",
+        ONECODE_DIR / "mcps",
+        ONECODE_DIR / "traces",
+        ONECODE_DIR / "logs",
+        ONECODE_DIR / "models",
+        ONECODE_DIR / "codebase" / "indexes",
+        ONECODE_DIR / "memory",
     ]
     for d in dirs:
         d.mkdir(parents=True, exist_ok=True)
 
+    # One-time migration from legacy ~/.cdh/ to ~/.onecode/
+    try:
+        from onecode.migrate import migrate_legacy_cdh_to_onecode
+        result = migrate_legacy_cdh_to_onecode()
+        if result:
+            logger.warning("Legacy migration: %s", result)
+    except Exception as exc:
+        logger.warning("Legacy migration failed: %s", exc)
+
 
 def load_config() -> GlobalConfig:
     ensure_dirs()
     if not GLOBAL_CONFIG_PATH.exists():
         _write_default_config()
+    # Bootstrap ai-dlc-skill from source into cdh platform pool
+    try:
+        from onecode.skills.bootstrap import ensure_ai_dlc_skill, ensure_onecode_default_skills
+        ensure_onecode_default_skills()
+        ensure_ai_dlc_skill()
+    except Exception:
+        pass
     raw = yaml.safe_load(GLOBAL_CONFIG_PATH.read_text()) or {}
     return _dict_to_dataclass(GlobalConfig, raw)
 
@@ -201,7 +230,7 @@ def _write_default_config():
             "trace_enabled": True,
             "trace_exporter": "file",
             "otlp_endpoint": "http://localhost:4317",
-            "trace_dir": "~/.cdh/traces",
+            "trace_dir": "~/.onecode/traces",
         },
         "attachments": {
             "max_size_mb": 10,

package/onecode/config_screen.py

@@ -7,7 +7,7 @@ from textual.containers import Horizontal, Vertical
 from textual.reactive import var
 from textual.screen import ModalScreen
 from textual.widget import Widget
-from textual.widgets import Button, Input, Label, Select, Static
+from textual.widgets import Button, Input, Label, Static
 
 from onecode.config import GlobalConfig, load_config, resolve_env, save_config
 
@@ -143,7 +143,7 @@ class EditFieldScreen(ModalScreen[str]):
     EditFieldScreen { background: rgba(0,0,0,0.7); align: center middle; }
     #edit-dialog { width: 50; height: 7; background: #111; border: solid #555; }
     #edit-label { height: 1; background: #333; color: #fff; padding: 0 1; }
-    #edit-input { height: 3; padding: 0 1; }
+    #edit-input { height: 3; padding: 0 1; background: #111; color: #fff; }
     #edit-buttons { height: 3; background: #222; align: center middle; }
     Button { margin: 0 1; background: #444; color: #fff; }
     Button:hover { background: #666; }
@@ -158,6 +158,11 @@ class EditFieldScreen(ModalScreen[str]):
                 yield Button("Cancel", id="edit-cancel")
                 yield Button("Save", id="edit-save")
 
+    def on_mount(self) -> None:
+        inp = self.query_one("#edit-input", Input)
+        inp.selection_color = "#000"
+        inp.selection_background = "#fff"
+
     @on(Button.Pressed, "#edit-save")
     def on_save(self) -> None:
         value = self.query_one("#edit-input", Input).value.strip()
@@ -333,7 +338,6 @@ class ConfigScreen(App):
                 self._section_fields.append(ConfigItem("log_level", "Log", cfg.log_level))
             case "providers":
                 for pid, pcfg in cfg.providers.items():
-                    n_models = len(pcfg.models)
                     ak = _truncate(_display_val(pcfg.api_key), 24)
                     ep = _truncate(_display_val(pcfg.endpoint), 20)
                     status = f"ep:{ep} ak:{ak}"

package/onecode/mcp/manager.py

@@ -3,13 +3,12 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
-from pathlib import Path
 from typing import Any, Optional
 
 import httpx
 import yaml
 
-from onecode.config import CLOUD_DEV_HARNESS_DIR
+from onecode.config import ONECODE_DIR
 from onecode.mcp.client import MCPClient, MCPTool
 
 logger = logging.getLogger("onecode.mcp")
@@ -83,7 +82,7 @@ class MCPSSEClient:
 
 class MCPManager:
     def __init__(self):
-        self.config_dir = CLOUD_DEV_HARNESS_DIR / "mcps"
+        self.config_dir = ONECODE_DIR / "mcps"
         self.config_dir.mkdir(parents=True, exist_ok=True)
         self.config_path = self.config_dir / "mcps.yaml"
         self._data: dict = {}

package/onecode/memory/__init__.py

@@ -1,18 +1,9 @@
 """
-CDH Memory - Layered Long-term Memory for AI Agents
+CDH Memory - Long-term Conversation Memory for AI Agents
 
-Based on TencentDB-Agent-Memory architecture:
-- L0: Raw conversation
-- L1: Atomic facts
-- L2: Scenarios
-- L3: Personas
-
-With symbolic short-term memory (Mermaid canvas + context offloading)
+L0: Raw conversation storage with BM25 keyword recall.
 """
-
 from onecode.memory.pyramid import MemoryPyramid, MemoryLayer, MemoryEntry
-from onecode.memory.symbolic import SymbolicMemory, MermaidCanvas, NodeType
-from onecode.memory.offload import ContextOffloader, OffloadConfig, ToolCallExtractor
 from onecode.memory.recall import HybridRecall, BM25, RecallResult
 from onecode.memory.backend import MemoryBackend
 
@@ -20,32 +11,25 @@ __all__ = [
     "MemoryPyramid",
     "MemoryLayer",
     "MemoryEntry",
-    "SymbolicMemory",
-    "MermaidCanvas",
-    "NodeType",
-    "ContextOffloader",
-    "OffloadConfig",
-    "ToolCallExtractor",
     "HybridRecall",
     "BM25",
     "RecallResult",
     "MemoryBackend",
+    "AgentMemory",
 ]
 
 
 class AgentMemory:
     """
-    Unified memory interface combining layered long-term memory
-    with symbolic short-term memory and hybrid recall.
+    Unified memory interface combining persistent L0 conversation storage
+    with BM25 keyword recall for long-term context.
     """
 
     def __init__(self, storage_path=None):
-        from onecode.config import CLOUD_DEV_HARNESS_DIR
-        self.storage_path = storage_path or (CLOUD_DEV_HARNESS_DIR / "memory")
+        from onecode.config import ONECODE_DIR
+        self.storage_path = storage_path or (ONECODE_DIR / "memory")
         self.backend = MemoryBackend(self.storage_path / "memory.db")
         self.pyramid = MemoryPyramid(self.storage_path)
-        self.symbolic = SymbolicMemory()
-        self.offloader = ContextOffloader(self.storage_path / "refs")
         self.recall = HybridRecall()
 
     def remember(self, layer: MemoryLayer, content: str, metadata: dict = None, parent_id: str = None) -> MemoryEntry:
@@ -63,33 +47,3 @@ class AgentMemory:
 
     def search_memories(self, query: str, top_k: int = 5) -> list[RecallResult]:
         return self.recall.hybrid_recall(query, top_k)
-
-    def remember_conversation(self, conversation_id: str, messages: list[dict]) -> MemoryEntry:
-        content = "\n".join(f"{m.get('role', 'user')}: {m.get('content', '')}" for m in messages)
-        entry = self.remember(MemoryLayer.L0_CONVERSATION, content, {"conversation_id": conversation_id})
-        return entry
-
-    def extract_atoms(self, conversation_id: str, max_atoms: int = 20) -> list[MemoryEntry]:
-        return self.pyramid.extract_atoms_from_conversation(conversation_id, max_atoms)
-
-    def build_scenario(self, name: str, atom_ids: list[str]) -> MemoryEntry:
-        scenario = self.pyramid.build_scenario_from_atoms(atom_ids, name)
-        self.backend.add_entry(scenario.id, MemoryLayer.L2_SCENARIO.value, scenario.content, scenario.metadata)
-        return scenario
-
-    def build_persona(self, name: str, scenario_ids: list[str]) -> MemoryEntry:
-        persona = self.pyramid.build_persona_from_scenarios(scenario_ids, name)
-        self.backend.add_entry(persona.id, MemoryLayer.L3_PERSONA.value, persona.content, persona.metadata)
-        return persona
-
-    def offload_and_symbolize(self, node_id: str, verbose_content: str, task_label: str) -> str:
-        ref_path = self.symbolic.offload_log(node_id, verbose_content)
-        self.backend.save_ref(node_id, verbose_content)
-        self.symbolic.create_result_node(task_label, verbose_content)
-        return ref_path
-
-    def get_canvas(self) -> str:
-        return self.symbolic.get_canvas_markdown()
-
-    def drill_down(self, entry_id: str) -> list[MemoryEntry]:
-        return self.pyramid.drill_down(entry_id)

package/onecode/memory/backend.py

@@ -1,9 +1,6 @@
 from __future__ import annotations
 
-import json
-import uuid
 from contextlib import contextmanager
-from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -11,7 +8,7 @@ from typing import Optional
 from sqlalchemy import Column, String, Text, DateTime, JSON, create_engine, Index
 from sqlalchemy.orm import declarative_base, sessionmaker, Session
 
-from onecode.config import CLOUD_DEV_HARNESS_DIR
+from onecode.config import ONECODE_DIR
 
 
 Base = declarative_base()
@@ -34,20 +31,10 @@ class MemoryRecord(Base):
     )
 
 
-class RefRecord(Base):
-    __tablename__ = "ref_records"
-
-    id = Column(String(16), primary_key=True)
-    node_id = Column(String(16), nullable=False, index=True)
-    content = Column(Text, nullable=False)
-    file_path = Column(String(512), nullable=True)
-    created_at = Column(DateTime, nullable=False)
-
-
 class MemoryBackend:
     def __init__(self, db_path: Optional[Path] = None):
         if db_path is None:
-            db_path = CLOUD_DEV_HARNESS_DIR / "memory" / "memory.db"
+            db_path = ONECODE_DIR / "memory" / "memory.db"
         db_path.parent.mkdir(parents=True, exist_ok=True)
         self.engine = create_engine(f"sqlite:///{db_path}", echo=False)
         Base.metadata.create_all(self.engine)
@@ -87,12 +74,20 @@ class MemoryBackend:
             s.merge(record)
             return True
 
-    def get_entry(self, entry_id: str) -> Optional[MemoryRecord]:
+    def get_entry(self, entry_id: str) -> Optional[dict]:
         with self.session() as s:
             record = s.query(MemoryRecord).filter_by(id=entry_id).first()
             if record:
-                s.refresh(record)
-            return record
+                return {
+                    "id": record.id,
+                    "layer": record.layer,
+                    "content": record.content,
+                    "timestamp": record.timestamp.isoformat() if record.timestamp else "",
+                    "metadata_json": record.metadata_json,
+                    "parent_id": record.parent_id,
+                    "result_ref": record.result_ref,
+                }
+            return None
 
     def get_entries_by_layer(self, layer: str, limit: int = 100) -> list[MemoryRecord]:
         with self.session() as s:
@@ -103,8 +98,6 @@ class MemoryBackend:
                 .limit(limit)
                 .all()
             )
-            for r in records:
-                s.refresh(r)
             return records
 
     def get_entries_by_parent(self, parent_id: str) -> list[MemoryRecord]:
@@ -123,23 +116,6 @@ class MemoryBackend:
                 query = query.filter_by(layer=layer)
             return query.limit(limit).all()
 
-    def save_ref(self, node_id: str, content: str, file_path: Optional[str] = None) -> bool:
-        with self.session() as s:
-            record = RefRecord(
-                id=str(uuid.uuid4())[:16],
-                node_id=node_id,
-                content=content,
-                file_path=file_path,
-                created_at=datetime.now(timezone.utc),
-            )
-            s.merge(record)
-            return True
-
-    def get_ref(self, node_id: str) -> Optional[str]:
-        with self.session() as s:
-            record = s.query(RefRecord).filter_by(node_id=node_id).order_by(RefRecord.created_at.desc()).first()
-            return record.content if record else None
-
     def search_content(self, query: str, layer: Optional[str] = None, limit: int = 10) -> list[MemoryRecord]:
         with self.session() as s:
             q = s.query(MemoryRecord)
@@ -149,8 +125,6 @@ class MemoryBackend:
             pattern = f"%{escaped}%"
             q = q.filter(MemoryRecord.content.like(pattern, escape="\\"))
             records = q.order_by(MemoryRecord.timestamp.desc()).limit(limit).all()
-            for r in records:
-                s.refresh(r)
             return records
 
     def delete_entry(self, entry_id: str) -> bool:

package/onecode/memory/pyramid.py

@@ -11,9 +11,6 @@ from typing import Optional
 
 class MemoryLayer(Enum):
     L0_CONVERSATION = "l0_conversation"
-    L1_ATOM = "l1_atom"
-    L2_SCENARIO = "l2_scenario"
-    L3_PERSONA = "l3_persona"
 
 
 @dataclass
@@ -69,8 +66,8 @@ class MemoryEntry:
 
 class MemoryPyramid:
     def __init__(self, storage_path: Optional[Path] = None):
-        from onecode.config import CLOUD_DEV_HARNESS_DIR
-        self.storage_path = storage_path or (CLOUD_DEV_HARNESS_DIR / "memory")
+        from onecode.config import ONECODE_DIR
+        self.storage_path = storage_path or (ONECODE_DIR / "memory")
         self.storage_path.mkdir(parents=True, exist_ok=True)
         self._layers = {layer: [] for layer in MemoryLayer}
         self._load_index()
@@ -134,69 +131,3 @@ class MemoryPyramid:
     def list_recent(self, layer: MemoryLayer, limit: int = 10) -> list[MemoryEntry]:
         entries = self._layers.get(layer, [])
         return sorted(entries, key=lambda e: e.timestamp, reverse=True)[:limit]
-
-    def drill_down(self, entry_id: str) -> list[MemoryEntry]:
-        chain = []
-        current = self._find_entry_anywhere(entry_id)
-        while current:
-            chain.append(current)
-            if current.parent_id:
-                current = self._find_entry_anywhere(current.parent_id)
-            else:
-                current = None
-        return list(reversed(chain))
-
-    def _find_entry_anywhere(self, entry_id: str) -> Optional[MemoryEntry]:
-        for entries in self._layers.values():
-            for entry in entries:
-                if entry.id == entry_id:
-                    return entry
-        return None
-
-    def extract_atoms_from_conversation(
-        self, conversation_id: str, max_atoms: int = 20
-    ) -> list[MemoryEntry]:
-        l0_entries = [e for e in self._layers[MemoryLayer.L0_CONVERSATION] if e.parent_id == conversation_id]
-        atoms = []
-        for l0 in l0_entries:
-            content = self.get_content(l0)
-            if len(content) > 100:
-                atom_content = content[:200] + "..."
-            else:
-                atom_content = content
-            atom = self.add(
-                MemoryLayer.L1_ATOM,
-                atom_content,
-                metadata={"source": "auto_extract", "source_id": l0.id},
-                parent_id=l0.id,
-            )
-            atoms.append(atom)
-            if len(atoms) >= max_atoms:
-                break
-        return atoms
-
-    def build_scenario_from_atoms(self, atom_ids: list[str], name: str) -> MemoryEntry:
-        atom_contents = []
-        for atom_id in atom_ids:
-            atom = self._find_entry_anywhere(atom_id)
-            if atom:
-                atom_contents.append(f"- {atom.content}")
-        content = f"## {name}\n\n" + "\n".join(atom_contents)
-        return self.add(
-            MemoryLayer.L2_SCENARIO,
-            content,
-            metadata={"atom_count": len(atom_ids)},
-        )
-
-    def build_persona_from_scenarios(self, scenario_ids: list[str], name: str) -> MemoryEntry:
-        scenario_contents = []
-        for sc_id in scenario_ids:
-            sc = self._find_entry_anywhere(sc_id)
-            if sc:
-                scenario_contents.append(f"### {sc.content[:100]}...\n{sc.content}")
-        content = f"# {name}\n\n" + "\n".join(scenario_contents)
-        return self.add(
-            MemoryLayer.L3_PERSONA,
-            content,
-            metadata={"scenario_count": len(scenario_ids)},
-        )

package/onecode/memory/recall.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import math
 import re
-from collections import Counter
 from dataclasses import dataclass
 from typing import Optional
 
@@ -17,6 +16,16 @@ class RecallResult:
 
 
 class BM25:
+    # Hard cap above which ``index()`` refuses to build the inverted index.
+    # The original O(V × N) construction of ``doc_freqs`` (set membership
+    # over Python lists) becomes effectively uncallable above a few
+    # thousand docs — a 79k-chunk corpus (observed in production where
+    # sessions kept re-indexing without cleaning the SQLite store) took
+    # ~1 hour, blocking the event loop and freezing streaming + cancel.
+    # Above this cap we degrade to a no-op index so callers fall back to
+    # other retrievers / explicit search instead of hanging the process.
+    _MAX_DOCS = 5000
+
     def __init__(self, k1: float = 1.5, b: float = 0.75):
         self.k1 = k1
         self.b = b
@@ -25,17 +34,43 @@ class BM25:
         self.doc_freqs: dict[str, int] = {}
         self.num_docs: int = 0
         self.doc_tokens: list[list[str]] = []
+        # Tokenize once per doc as ``set`` (not list) so the
+        # ``token in doc`` membership check inside the doc_freqs
+        # comprehension is O(1) instead of O(doc_len).  This alone takes
+        # the 79k-doc construction from ~hours to ~seconds; the hard cap
+        # above is a safety net for pathological corpora.
+        self._doc_token_sets: list[set[str]] = []
 
     def index(self, documents: list[str]) -> None:
+        if len(documents) > self._MAX_DOCS:
+            import logging
+            logging.getLogger(__name__).warning(
+                "BM25.index refused: %d docs exceeds cap=%d (would block "
+                "the event loop for minutes); BM25 search will return no "
+                "results. Clean the codebase index or use a smaller "
+                "project scope.", len(documents), self._MAX_DOCS,
+            )
+            self.doc_tokens = []
+            self._doc_token_sets = []
+            self.doc_lengths = []
+            self.avgdl = 0
+            self.num_docs = 0
+            self.doc_freqs = {}
+            return
+
         self.doc_tokens = [self._tokenize(doc) for doc in documents]
+        self._doc_token_sets = [set(t) for t in self.doc_tokens]
         self.doc_lengths = [len(tokens) for tokens in self.doc_tokens]
         self.avgdl = sum(self.doc_lengths) / len(self.doc_lengths) if self.doc_lengths else 0
         self.num_docs = len(documents)
 
         all_tokens = set()
-        for tokens in self.doc_tokens:
+        for tokens in self._doc_token_sets:
             all_tokens.update(tokens)
-        self.doc_freqs = {token: sum(1 for doc in self.doc_tokens if token in doc) for token in all_tokens}
+        self.doc_freqs = {
+            token: sum(1 for ts in self._doc_token_sets if token in ts)
+            for token in all_tokens
+        }
 
     def _tokenize(self, text: str) -> list[str]:
         text = text.lower()

package/onecode/migrate.py

@@ -0,0 +1,122 @@
+"""onecode legacy migration — move onecode's private state from ~/.cdh/ to ~/.onecode/.
+
+This is a ONE-TIME migration triggered at first startup after upgrade.
+It only moves directories owned by onecode (logs, traces, memory,
+snapshots, mcps, models, onecode.config.yaml). cdh platform directories
+(skills, projects, state, sessions) are left untouched.  Session JSON is owned
+by the cdh platform layer (B mapping mode), not by individual engines.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger("onecode.migrate")
+
+# Directories/state that belong to onecode and should be migrated
+# NOTE: sessions is deliberately excluded — it belongs to the cdh
+# platform layer (B mapping mode), not to any individual engine.
+_ONECODE_PRIVATE_DIRS = {
+    "logs",
+    "traces",
+    "memory",
+    "snapshots",
+    "mcps",
+    "models",
+}
+
+# cdh platform directories — NEVER touch
+_CDH_PLATFORM_DIRS = {"skills", "projects", "state"}
+
+# Dotfiles that belong to onecode (at the ~/.cdh/ root level)
+_ONECODE_DOTFILES = {"onecode.config.yaml"}
+
+
+def migrate_legacy_cdh_to_onecode(
+    legacy_dir: Path | None = None,
+    target_dir: Path | None = None,
+) -> str | None:
+    """Migrate onecode's private state from ~/.cdh/ to ~/.onecode/.
+
+    Args:
+        legacy_dir: Source directory (default ~/.cdh/).
+        target_dir: Target directory (default ~/.onecode/).
+
+    Returns:
+        Info/warning message string, or None if no migration needed.
+    """
+    legacy = (legacy_dir or Path.home() / ".cdh").resolve()
+    target = (target_dir or Path.home() / ".onecode").resolve()
+
+    # Nothing to migrate
+    if not legacy.exists():
+        return None
+
+    # Already migrated (marker exists)
+    migrated_marker = target / ".migrated_from"
+    if migrated_marker.exists():
+        return None
+
+    # Both exist but no marker → user may have manually set up ~/.onecode/
+    if target.exists():
+        # Check if target has any onecode dirs already
+        has_content = any(
+            (target / d).exists() for d in _ONECODE_PRIVATE_DIRS
+        ) or target / "onecode.config.yaml" in target.iterdir()
+        if has_content:
+            return None  # 各自独立运行，无需迁移
+        # Target exists but empty — safe to proceed
+
+    # Perform migration
+    target.mkdir(parents=True, exist_ok=True)
+    migrated_items = []
+
+    # Migrate private subdirectories
+    for dir_name in _ONECODE_PRIVATE_DIRS:
+        src = legacy / dir_name
+        if src.exists() and src.is_dir():
+            dst = target / dir_name
+            if dst.exists():
+                # Merge contents (don't overwrite existing)
+                for item in src.iterdir():
+                    dst_item = dst / item.name
+                    if not dst_item.exists():
+                        shutil.move(str(item), str(dst_item))
+            else:
+                shutil.move(str(src), str(dst))
+            migrated_items.append(dir_name)
+
+    # Migrate onecode dotfiles
+    for fname in _ONECODE_DOTFILES:
+        src = legacy / fname
+        if src.exists() and src.is_file():
+            dst = target / fname
+            if not dst.exists():
+                shutil.move(str(src), str(dst))
+                migrated_items.append(fname)
+
+    # Write migration marker
+    marker_data = {
+        "migrated_from": str(legacy),
+        "migrated_to": str(target),
+        "items": sorted(migrated_items),
+        "preserved_on_legacy": sorted(_CDH_PLATFORM_DIRS),
+    }
+    migrated_marker.write_text(
+        json.dumps(marker_data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+    if migrated_items:
+        msg = (
+            f"⚠ Migrated onecode state from {legacy} → {target}: "
+            f"{', '.join(migrated_items)}. "
+            f"cdh platform dirs ({', '.join(_CDH_PLATFORM_DIRS)}) preserved at {legacy}."
+        )
+        logger.warning(msg)
+        return msg
+
+    return None