nexo-brain 2.6.13 → 2.6.15

package/src/bootstrap_docs.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+"""Managed bootstrap documents for Claude Code and Codex."""
+
+import json
+import os
+import re
+from pathlib import Path
+
+from client_preferences import (
+    BACKEND_NONE,
+    CLIENT_CLAUDE_CODE,
+    CLIENT_CODEX,
+    INTERACTIVE_CLIENT_KEYS,
+    normalize_backend_key,
+    normalize_client_key,
+    normalize_client_preferences,
+)
+
+def _resolve_templates_dir(module_file: str | os.PathLike[str]) -> Path:
+    module_dir = Path(module_file).resolve().parent
+    direct = module_dir / "templates"
+    if direct.is_dir():
+        return direct
+    parent = module_dir.parent / "templates"
+    if parent.is_dir():
+        return parent
+    return direct
+
+
+TEMPLATES_DIR = _resolve_templates_dir(__file__)
+
+CORE_LABEL = "******CORE******"
+USER_LABEL = "******USER******"
+CORE_START = "<!-- nexo:core:start -->"
+CORE_END = "<!-- nexo:core:end -->"
+USER_START = "<!-- nexo:user:start -->"
+USER_END = "<!-- nexo:user:end -->"
+
+BOOTSTRAP_SPECS = {
+    CLIENT_CLAUDE_CODE: {
+        "label": "Claude Code",
+        "template": TEMPLATES_DIR / "CLAUDE.md.template",
+        "target_parts": (".claude", "CLAUDE.md"),
+        "version_pattern": r"nexo-claude-md-version:\s*([\d.]+)",
+        "version_file": "claude_md_version.txt",
+    },
+    CLIENT_CODEX: {
+        "label": "Codex",
+        "template": TEMPLATES_DIR / "CODEX.AGENTS.md.template",
+        "target_parts": (".codex", "AGENTS.md"),
+        "version_pattern": r"nexo-codex-agents-version:\s*([\d.]+)",
+        "version_file": "codex_agents_version.txt",
+    },
+}
+
+
+def _user_home() -> Path:
+    return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
+
+
+def _default_nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))).expanduser()
+
+
+def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
+    explicit = (explicit or "").strip()
+    if explicit:
+        return explicit
+    env_name = os.environ.get("NEXO_NAME", "").strip()
+    if env_name:
+        return env_name
+    version_file = nexo_home / "version.json"
+    if version_file.is_file():
+        try:
+            return str(json.loads(version_file.read_text()).get("operator_name", "")).strip()
+        except Exception:
+            pass
+    return "NEXO"
+
+
+def _read_version(text: str, pattern: str) -> str:
+    match = re.search(pattern, text)
+    return match.group(1) if match else ""
+
+
+def _template_version_comment(text: str) -> str:
+    first_line = text.splitlines()[0] if text else ""
+    return first_line if first_line.startswith("<!--") and "version:" in first_line else ""
+
+
+def _strip_version_comment(text: str) -> str:
+    return re.sub(r"^<!--\s*nexo-[^-]+(?:-[^-]+)*-version:\s*[\d.]+\s*-->\s*\n?", "", text, count=1)
+
+
+def _extract_block(text: str, start: str, end: str) -> str:
+    pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.DOTALL)
+    match = pattern.search(text)
+    return match.group(0) if match else ""
+
+
+def _replace_block(text: str, start: str, end: str, replacement: str) -> str:
+    pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.DOTALL)
+    if pattern.search(text):
+        return pattern.sub(replacement, text, count=1)
+    return text.rstrip() + "\n\n" + replacement.rstrip() + "\n"
+
+
+def _build_user_block(user_payload: str, template_text: str) -> str:
+    template_user = _extract_block(template_text, USER_START, USER_END)
+    if not user_payload.strip():
+        return template_user
+    return f"{USER_START}\n{user_payload.rstrip()}\n{USER_END}"
+
+
+def _legacy_user_payload(existing_text: str) -> str:
+    cleaned = re.sub(r"<!--\s*nexo-[^-]+-[^-]+-version:\s*[\d.]+\s*-->\s*", "", existing_text)
+    if "<!-- nexo:start:" in cleaned:
+        first_section = re.search(r"<!-- nexo:start:\w+ -->", cleaned)
+        prefix = cleaned[: first_section.start()] if first_section else ""
+        remainder = cleaned[first_section.start() :] if first_section else ""
+        remainder = re.sub(
+            r"<!-- nexo:start:\w+ -->.*?<!-- nexo:end:\w+ -->",
+            "",
+            remainder,
+            flags=re.DOTALL,
+        )
+        residue = "\n".join([prefix, remainder]).strip()
+        filtered_lines: list[str] = []
+        for line in residue.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                filtered_lines.append("")
+                continue
+            if stripped.startswith("# ") and "Cognitive Co-Operator" in stripped:
+                continue
+            if stripped.startswith("I am ") and "powered by NEXO Brain" in stripped:
+                continue
+            if "Tool-coupled behavioral rules" in stripped:
+                continue
+            filtered_lines.append(line)
+        residue = "\n".join(filtered_lines).strip()
+        return residue
+    return cleaned.strip()
+
+
+def _target_path(client: str, *, user_home: Path | None = None) -> Path:
+    spec = BOOTSTRAP_SPECS[client]
+    home = user_home or _user_home()
+    return home.joinpath(*spec["target_parts"])
+
+
+def _version_tracker_path(nexo_home: Path, client: str) -> Path:
+    return nexo_home / "data" / BOOTSTRAP_SPECS[client]["version_file"]
+
+
+def render_bootstrap_template(
+    client: str,
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    operator_name: str = "",
+) -> str:
+    client_key = normalize_client_key(client)
+    spec = BOOTSTRAP_SPECS[client_key]
+    template_text = spec["template"].read_text()
+    nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
+    name = _resolve_operator_name(nexo_home_path, explicit=operator_name)
+    return (
+        template_text
+        .replace("{{NAME}}", name)
+        .replace("{{NEXO_HOME}}", str(nexo_home_path))
+    )
+
+
+def load_bootstrap_prompt(
+    client: str,
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> str:
+    client_key = normalize_client_key(client)
+    if client_key not in BOOTSTRAP_SPECS:
+        return ""
+
+    home_path = Path(user_home).expanduser() if user_home else _user_home()
+    target_path = _target_path(client_key, user_home=home_path)
+    if target_path.exists():
+        text = target_path.read_text()
+        if text.strip():
+            return _strip_version_comment(text).strip()
+
+    rendered = render_bootstrap_template(
+        client_key,
+        nexo_home=nexo_home,
+        operator_name=operator_name,
+    )
+    return _strip_version_comment(rendered).strip()
+
+
+def sync_client_bootstrap(
+    client: str,
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    client_key = normalize_client_key(client)
+    if client_key not in BOOTSTRAP_SPECS:
+        return {"ok": False, "client": client_key or str(client), "error": "unsupported bootstrap target"}
+
+    nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
+    home_path = Path(user_home).expanduser() if user_home else _user_home()
+    target_path = _target_path(client_key, user_home=home_path)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    rendered = render_bootstrap_template(
+        client_key,
+        nexo_home=nexo_home_path,
+        operator_name=operator_name,
+    )
+    template_version = _read_version(rendered, BOOTSTRAP_SPECS[client_key]["version_pattern"])
+    rendered_core = _extract_block(rendered, CORE_START, CORE_END)
+    if not rendered_core:
+        return {"ok": False, "client": client_key, "path": str(target_path), "error": "template missing CORE block"}
+
+    if not target_path.exists() or not target_path.read_text().strip():
+        target_path.write_text(rendered)
+        if template_version:
+            tracker = _version_tracker_path(nexo_home_path, client_key)
+            tracker.parent.mkdir(parents=True, exist_ok=True)
+            tracker.write_text(template_version)
+        return {
+            "ok": True,
+            "client": client_key,
+            "action": "created",
+            "path": str(target_path),
+            "version": template_version,
+        }
+
+    existing = target_path.read_text()
+    if CORE_START in existing and CORE_END in existing and USER_START in existing and USER_END in existing:
+        user_block = _extract_block(existing, USER_START, USER_END) or _extract_block(rendered, USER_START, USER_END)
+        updated = _replace_block(existing, CORE_START, CORE_END, rendered_core)
+        updated = _replace_block(updated, USER_START, USER_END, user_block)
+        action = "updated" if updated != existing else "unchanged"
+    else:
+        legacy_user = _legacy_user_payload(existing)
+        updated = _replace_block(rendered, USER_START, USER_END, _build_user_block(legacy_user, rendered))
+        action = "migrated"
+
+    if template_version:
+        comment = _template_version_comment(rendered)
+        if comment:
+            updated = re.sub(r"<!--\s*nexo-[^-]+-[^-]+-version:\s*[\d.]+\s*-->", comment, updated, count=1)
+            if comment not in updated:
+                updated = comment + "\n" + updated.lstrip()
+
+    if updated != existing:
+        backup_path = target_path.with_suffix(target_path.suffix + ".bak")
+        try:
+            backup_path.write_text(existing)
+        except Exception:
+            pass
+        target_path.write_text(updated)
+
+    if template_version:
+        tracker = _version_tracker_path(nexo_home_path, client_key)
+        tracker.parent.mkdir(parents=True, exist_ok=True)
+        tracker.write_text(template_version)
+
+    return {
+        "ok": True,
+        "client": client_key,
+        "action": action,
+        "path": str(target_path),
+        "version": template_version,
+    }
+
+
+def sync_enabled_bootstraps(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+    enabled_clients: list[str] | tuple[str, ...] | set[str] | None = None,
+    preferences: dict | None = None,
+) -> dict[str, dict]:
+    if enabled_clients is None:
+        if preferences is None:
+            enabled = {CLIENT_CLAUDE_CODE, CLIENT_CODEX}
+        else:
+            prefs = normalize_client_preferences(preferences)
+            enabled = {
+                key
+                for key in INTERACTIVE_CLIENT_KEYS
+                if prefs.get("interactive_clients", {}).get(key, False)
+                and key in BOOTSTRAP_SPECS
+            }
+            backend = normalize_backend_key(prefs.get("automation_backend"))
+            if prefs.get("automation_enabled", True) and backend and backend != BACKEND_NONE:
+                if backend in BOOTSTRAP_SPECS:
+                    enabled.add(backend)
+            if not enabled:
+                enabled.add(CLIENT_CLAUDE_CODE)
+    else:
+        enabled = {normalize_client_key(item) for item in enabled_clients if normalize_client_key(item) in BOOTSTRAP_SPECS}
+        if not enabled:
+            enabled = {CLIENT_CLAUDE_CODE}
+
+    results: dict[str, dict] = {}
+    for client_key in (CLIENT_CLAUDE_CODE, CLIENT_CODEX):
+        if client_key not in enabled:
+            results[client_key] = {
+                "ok": True,
+                "client": client_key,
+                "skipped": True,
+                "reason": "disabled in client preferences",
+                "path": str(_target_path(client_key, user_home=Path(user_home).expanduser() if user_home else None)),
+            }
+            continue
+        try:
+            results[client_key] = sync_client_bootstrap(
+                client_key,
+                nexo_home=nexo_home,
+                operator_name=operator_name,
+                user_home=user_home,
+            )
+        except Exception as exc:
+            results[client_key] = {"ok": False, "client": client_key, "error": str(exc)}
+    return results
+
+
+def get_bootstrap_status(
+    client: str,
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    client_key = normalize_client_key(client)
+    if client_key not in BOOTSTRAP_SPECS:
+        return {"client": client_key or str(client), "supported": False}
+
+    nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
+    home_path = Path(user_home).expanduser() if user_home else _user_home()
+    target_path = _target_path(client_key, user_home=home_path)
+    template_text = render_bootstrap_template(client_key, nexo_home=nexo_home_path)
+    template_version = _read_version(template_text, BOOTSTRAP_SPECS[client_key]["version_pattern"])
+    status = {
+        "client": client_key,
+        "path": str(target_path),
+        "exists": target_path.exists(),
+        "supported": True,
+        "template_version": template_version,
+        "version": "",
+        "markers_ok": False,
+        "user_block_ok": False,
+    }
+    if not target_path.exists():
+        return status
+
+    text = target_path.read_text()
+    status["version"] = _read_version(text, BOOTSTRAP_SPECS[client_key]["version_pattern"])
+    status["markers_ok"] = CORE_START in text and CORE_END in text and USER_START in text and USER_END in text
+    status["user_block_ok"] = USER_START in text and USER_END in text
+    return status

package/src/cli.py

@@ -859,6 +859,8 @@ def _chat(args):
             print(f"[NEXO] {preflight['git_update']}", file=sys.stderr)
         elif preflight.get("npm_notice"):
             print(f"[NEXO] {preflight['npm_notice']}", file=sys.stderr)
+        for message in preflight.get("client_bootstrap_updates", []):
+            print(f"[NEXO] {message}", file=sys.stderr)
         if preflight.get("error"):
             print(f"[NEXO] Startup preflight warning: {preflight['error']}", file=sys.stderr)
     except Exception:
@@ -1017,7 +1019,7 @@ Commands:
   nexo scripts list|create|classify|sync|reconcile|ensure-schedules|schedules|run|doctor|call|unschedule|remove
                                                       Personal scripts
   nexo skills list|apply|sync|approve                  Executable skills
-  nexo clients sync                                    Sync Claude Code/Desktop/Codex MCP configs
+  nexo clients sync                                    Sync Claude/Codex shared-brain configs and bootstrap files
   nexo update                                          Update installed runtime
   nexo contributor status|on|off                       Public Draft PR contribution mode
   nexo dashboard on|off|status                         Web dashboard control

package/src/client_sync.py

@@ -10,6 +10,8 @@ import subprocess
 import sys
 from pathlib import Path
 
+from bootstrap_docs import sync_client_bootstrap
+
 try:
     from client_preferences import (
         BACKEND_NONE,
@@ -202,11 +204,22 @@ def sync_claude_code(
         python_path=python_path,
         operator_name=operator_name,
     )
-    return _sync_json_client(
+    result = _sync_json_client(
         _claude_code_settings_path(Path(user_home).expanduser() if user_home else None),
         server_config,
         "claude_code",
     )
+    bootstrap_result = sync_client_bootstrap(
+        "claude_code",
+        nexo_home=nexo_home,
+        operator_name=operator_name,
+        user_home=user_home,
+    )
+    result["bootstrap"] = bootstrap_result
+    if not bootstrap_result.get("ok"):
+        result["ok"] = False
+        result["error"] = bootstrap_result.get("error", "Claude bootstrap sync failed")
+    return result
 
 
 def sync_claude_desktop(
@@ -249,13 +262,21 @@ def sync_codex(
     codex_bin = shutil.which("codex")
     config_path = _codex_config_path(home_path)
     if not codex_bin:
-        return {
+        result = {
             "ok": True,
             "client": "codex",
             "skipped": True,
             "reason": "codex binary not found in PATH",
             "path": str(config_path),
         }
+        bootstrap_result = sync_client_bootstrap(
+            "codex",
+            nexo_home=nexo_home,
+            operator_name=operator_name,
+            user_home=user_home,
+        )
+        result["bootstrap"] = bootstrap_result
+        return result
 
     cmd = [codex_bin, "mcp", "add", "nexo"]
     for key, value in sorted(server_config.get("env", {}).items()):
@@ -270,19 +291,40 @@ def sync_codex(
         env=env,
     )
     if result.returncode != 0:
-        return {
+        result = {
             "ok": False,
             "client": "codex",
             "path": str(config_path),
             "error": (result.stderr or result.stdout or "codex mcp add failed").strip(),
         }
-    return {
+        bootstrap_result = sync_client_bootstrap(
+            "codex",
+            nexo_home=nexo_home,
+            operator_name=operator_name,
+            user_home=user_home,
+        )
+        result["bootstrap"] = bootstrap_result
+        if not bootstrap_result.get("ok"):
+            result["error"] = f"{result['error']}; bootstrap: {bootstrap_result.get('error', 'unknown error')}"
+        return result
+    sync_result = {
         "ok": True,
         "client": "codex",
         "action": "updated",
         "path": str(config_path),
         "mode": "cli",
     }
+    bootstrap_result = sync_client_bootstrap(
+        "codex",
+        nexo_home=nexo_home_path,
+        operator_name=operator_name,
+        user_home=home_path,
+    )
+    sync_result["bootstrap"] = bootstrap_result
+    if not bootstrap_result.get("ok"):
+        sync_result["ok"] = False
+        sync_result["error"] = bootstrap_result.get("error", "Codex bootstrap sync failed")
+    return sync_result
 
 
 def sync_all_clients(
@@ -363,9 +405,19 @@ def format_sync_summary(result: dict) -> str:
         item = result.get("clients", {}).get(key, {})
         label = labels[key]
         if item.get("skipped"):
-            lines.append(f"  {label}: skipped ({item.get('reason', 'not available')})")
+            bootstrap = item.get("bootstrap", {})
+            if bootstrap.get("ok") and not bootstrap.get("skipped"):
+                lines.append(
+                    f"  {label}: skipped ({item.get('reason', 'not available')}); bootstrap {bootstrap.get('action', 'synced')} -> {bootstrap.get('path', '')}"
+                )
+            else:
+                lines.append(f"  {label}: skipped ({item.get('reason', 'not available')})")
         elif item.get("ok"):
-            lines.append(f"  {label}: {item.get('action', 'synced')} -> {item.get('path', '')}")
+            bootstrap = item.get("bootstrap", {})
+            suffix = ""
+            if bootstrap.get("ok"):
+                suffix = f"; bootstrap {bootstrap.get('action', 'synced')} -> {bootstrap.get('path', '')}"
+            lines.append(f"  {label}: {item.get('action', 'synced')} -> {item.get('path', '')}{suffix}")
         else:
             lines.append(f"  {label}: ERROR -> {item.get('error', 'unknown error')}")
     return "\n".join(lines)

package/src/doctor/providers/runtime.py

@@ -982,6 +982,176 @@ def check_client_backend_preferences() -> DoctorCheck:
     )
 
 
+def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
+    """Check managed Claude/Codex bootstrap documents and CORE/USER markers."""
+    try:
+        from bootstrap_docs import get_bootstrap_status, sync_enabled_bootstraps
+    except Exception as e:
+        return DoctorCheck(
+            id="runtime.client_bootstrap",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary=f"Bootstrap check unavailable: {e}",
+        )
+
+    try:
+        schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
+    except Exception:
+        schedule = {}
+    prefs = normalize_client_preferences(schedule)
+    detected = detect_installed_clients()
+
+    relevant: set[str] = set()
+    default_terminal = prefs["default_terminal_client"]
+    if default_terminal in {"claude_code", "codex"}:
+        relevant.add(default_terminal)
+    if prefs.get("automation_enabled", True):
+        backend = prefs.get("automation_backend")
+        if backend in {"claude_code", "codex"}:
+            relevant.add(backend)
+    for client_key, enabled in prefs.get("interactive_clients", {}).items():
+        if enabled and client_key in {"claude_code", "codex"}:
+            relevant.add(client_key)
+    if not relevant:
+        relevant.add("claude_code")
+
+    evidence: list[str] = []
+    repair_plan: list[str] = []
+    status = "healthy"
+    severity = "info"
+
+    def _evaluate() -> list[tuple[str, dict]]:
+        return [
+            (client_key, get_bootstrap_status(client_key, nexo_home=NEXO_HOME, user_home=Path.home()))
+            for client_key in sorted(relevant)
+        ]
+
+    evaluated = _evaluate()
+    for client_key, info in evaluated:
+        installed = detected.get(client_key, {}).get("installed", False)
+        if not installed and client_key in {default_terminal, prefs.get("automation_backend")}:
+            status = "degraded"
+            severity = "warn"
+            evidence.append(f"`{client_key}` selected but not installed; bootstrap parity cannot be verified")
+            continue
+        if not info.get("exists"):
+            status = "degraded"
+            severity = "warn"
+            evidence.append(f"`{client_key}` bootstrap missing at {info.get('path')}")
+            repair_plan.append("Run `nexo clients sync` or `nexo update` to regenerate client bootstrap files")
+            continue
+        if not info.get("markers_ok"):
+            status = "degraded"
+            severity = "warn"
+            evidence.append(f"`{client_key}` bootstrap lacks CORE/USER markers")
+            repair_plan.append("Migrate bootstrap files so NEXO owns CORE and preserves USER")
+            continue
+        if info.get("template_version") and info.get("version") != info.get("template_version"):
+            status = "degraded"
+            severity = "warn"
+            evidence.append(
+                f"`{client_key}` bootstrap version {info.get('version') or 'unknown'} != template {info.get('template_version')}"
+            )
+            repair_plan.append("Refresh bootstrap files from the current NEXO templates")
+
+    if fix and status != "healthy":
+        sync_enabled_bootstraps(
+            nexo_home=NEXO_HOME,
+            user_home=Path.home(),
+            preferences=prefs,
+        )
+        post = check_client_bootstrap_parity(fix=False)
+        if post.status == "healthy":
+            post.fixed = True
+            post.summary += " (fixed)"
+            return post
+
+    return DoctorCheck(
+        id="runtime.client_bootstrap",
+        tier="runtime",
+        status=status,
+        severity=severity,
+        summary="Client bootstrap parity OK" if status == "healthy" else "Client bootstrap parity needs attention",
+        evidence=evidence or [
+            f"{client_key}: {info.get('path')}"
+            for client_key, info in evaluated
+        ],
+        repair_plan=repair_plan,
+        escalation_prompt=(
+            "Claude/Codex startup bootstrap files are missing, outdated, or lack the CORE/USER contract. "
+            "Repair them so updates can refresh product rules without clobbering operator-specific instructions."
+        ) if status != "healthy" else "",
+    )
+
+
+def check_transcript_source_parity() -> DoctorCheck:
+    """Check whether Deep Sleep can see transcript sources for the selected clients."""
+    try:
+        schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
+    except Exception:
+        schedule = {}
+    prefs = normalize_client_preferences(schedule)
+
+    wants_codex = bool(
+        prefs.get("interactive_clients", {}).get("codex")
+        or prefs.get("default_terminal_client") == "codex"
+        or (prefs.get("automation_enabled", True) and prefs.get("automation_backend") == "codex")
+    )
+    wants_claude = bool(
+        prefs.get("interactive_clients", {}).get("claude_code")
+        or prefs.get("default_terminal_client") == "claude_code"
+        or (prefs.get("automation_enabled", True) and prefs.get("automation_backend") == "claude_code")
+    )
+
+    claude_root = Path.home() / ".claude" / "projects"
+    codex_roots = [
+        Path.home() / ".codex" / "sessions",
+        Path.home() / ".codex" / "archived_sessions",
+    ]
+
+    evidence = []
+    status = "healthy"
+    severity = "info"
+    if wants_claude:
+        evidence.append(f"claude_code transcripts: {'present' if claude_root.exists() else 'missing'} at {claude_root}")
+    if wants_codex:
+        codex_present = any(root.exists() for root in codex_roots)
+        evidence.append(
+            "codex transcripts: "
+            + ("present" if codex_present else "missing")
+            + f" at {', '.join(str(root) for root in codex_roots)}"
+        )
+        if not codex_present:
+            status = "degraded"
+            severity = "warn"
+
+    summary = "Deep Sleep transcript sources available"
+    repair_plan = []
+    escalation_prompt = ""
+    if status != "healthy":
+        summary = "Deep Sleep transcript source parity needs attention"
+        repair_plan = [
+            "Start at least one Codex session so ~/.codex/sessions is created",
+            "If Codex sessions already exist elsewhere, update the collector before relying on Codex-only transcript analysis",
+        ]
+        escalation_prompt = (
+            "Codex is selected, but no durable Codex session store is visible under ~/.codex. "
+            "Deep Sleep can still use DB artifacts, but transcript-level overnight analysis will be limited until Codex session files exist."
+        )
+
+    return DoctorCheck(
+        id="runtime.transcript_sources",
+        tier="runtime",
+        status=status,
+        severity=severity,
+        summary=summary,
+        evidence=evidence,
+        repair_plan=repair_plan,
+        escalation_prompt=escalation_prompt,
+    )
+
+
 def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all runtime-tier checks. Read-only by default."""
     return [
@@ -990,6 +1160,8 @@ def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
         check_stale_sessions(),
         check_cron_freshness(),
         check_client_backend_preferences(),
+        check_client_bootstrap_parity(fix=fix),
+        check_transcript_source_parity(),
         check_launchagent_integrity(fix=fix),
         check_personal_script_registry(fix=fix),
         check_skill_health(fix=fix),