typedef-data-intelligence 0.35.0__tar.gz → 0.37.0__tar.gz

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.37.0](https://github.com/typedef-ai/typedef/compare/typedef-data-intelligence-v0.36.0...typedef-data-intelligence-v0.37.0) (2026-07-08)
+
+
+### Features
+
+* **observability:** retention & rotation policy for local logs/traces (TD-3813) ([#1123](https://github.com/typedef-ai/typedef/issues/1123)) ([48dc274](https://github.com/typedef-ai/typedef/commit/48dc274d2e8182a0a2417abf3ba4028278cf8939))
+
+## [0.36.0](https://github.com/typedef-ai/typedef/compare/typedef-data-intelligence-v0.35.0...typedef-data-intelligence-v0.36.0) (2026-07-07)
+
+
+### Features
+
+* **observability:** enable local desktop span export (TD-3805) ([#1114](https://github.com/typedef-ai/typedef/issues/1114)) ([32cf196](https://github.com/typedef-ai/typedef/commit/32cf196272f658a639ef3d6ae9ce3599c79078eb))
+
+
+### Bug Fixes
+
+* **observability:** classify + clean customer data in retained/exported logs (TD-3825) ([#1107](https://github.com/typedef-ai/typedef/issues/1107)) ([cac553d](https://github.com/typedef-ai/typedef/commit/cac553d50a84275a734d198baca25a7290c6ab70))
+
 ## [0.35.0](https://github.com/typedef-ai/typedef/compare/typedef-data-intelligence-v0.34.0...typedef-data-intelligence-v0.35.0) (2026-07-06)
 
 

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typedef-data-intelligence
-Version: 0.35.0
+Version: 0.37.0
 Summary: Unified lineage management and AI-powered analytics platform for dbt projects
 Project-URL: Homepage, https://typedef.ai
 Project-URL: Repository, https://github.com/typedef-ai/data-intelligence

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typedef-data-intelligence"
-version = "0.35.0"
+version = "0.37.0"
 description = "Unified lineage management and AI-powered analytics platform for dbt projects"
 readme = "README.pypi.md"
 license = "LicenseRef-Proprietary"

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/api/app.py

@@ -6,9 +6,8 @@ import sys
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
-import logfire
 import yaml
 from agent.api import shutdown_event
 from agent.api.profiles import (
@@ -37,6 +36,10 @@ from core.backends.unified_graph.surreal.reader import SurrealUnifiedGraphReader
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
 from lineage.api.auth_context import resolve_user_context
+from lineage.observability.desktop_logfire import (
+    configure_desktop_logfire,
+    shutdown_desktop_logfire,
+)
 from lineage.utils.env import load_env_file
 from pydantic import ValidationError
 
@@ -250,6 +253,34 @@ class AppState:
     unified_reader: Optional[SurrealUnifiedGraphReader] = None
 
 
+# ============================================================================
+# Observability Retention (TD-3813)
+# ============================================================================
+
+if TYPE_CHECKING:
+    from core.observability.retention import RetentionPolicy
+
+
+async def _periodic_retention_sweep(policy: "RetentionPolicy") -> None:
+    """Run the observability retention sweep periodically, off the event loop.
+
+    Sleeps ``policy.periodic_interval_seconds`` between sweeps. Best-effort;
+    only cancellation stops it.
+    """
+    import asyncio
+
+    from core.observability.retention import sweep_observability
+
+    while True:
+        try:
+            await asyncio.sleep(policy.periodic_interval_seconds)
+            await asyncio.to_thread(sweep_observability, policy)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.debug("periodic observability retention sweep failed", exc_info=True)
+
+
 # ============================================================================
 # Middleware for Request Logging and User Context Extraction
 # ============================================================================
@@ -305,10 +336,7 @@ async def lifespan(app: FastAPI):
             logger.debug("gold-build temp dir cleanup failed", exc_info=True)
 
     try:
-        from core.paths import (
-            cleanup_stale_frontend_logs,
-            cleanup_stale_wizard_scratch,
-        )
+        from core.paths import cleanup_stale_wizard_scratch
 
         removed_wizard_scratch = cleanup_stale_wizard_scratch()
         if removed_wizard_scratch:
@@ -317,13 +345,25 @@ async def lifespan(app: FastAPI):
                 len(removed_wizard_scratch),
             )
 
-        # TD-3711: prune captured frontend (webview) logs by age + total size
-        # so optional capture can never grow unbounded.
-        removed_frontend_logs = cleanup_stale_frontend_logs()
-        if removed_frontend_logs:
+        # TD-3813: one unified age+size retention sweep over the whole logs/
+        # tree (traces, index, ops, streams tails, frontend), then a periodic
+        # task so an always-on session can't grow unbounded between restarts.
+        import asyncio
+
+        from core.observability.retention import RetentionPolicy, sweep_observability
+
+        _obs_policy = RetentionPolicy.from_env()
+        swept = sweep_observability(_obs_policy)
+        _swept_total = sum(len(v) for v in swept.values())
+        if _swept_total:
             logger.info(
-                "Removed %d stale frontend log file(s) on startup",
-                len(removed_frontend_logs),
+                "Observability retention: removed %d unit(s) on startup (%s)",
+                _swept_total,
+                ", ".join(f"{k}={len(v)}" for k, v in swept.items() if v),
+            )
+        if not _obs_policy.disabled:
+            app.state._obs_retention_task = asyncio.create_task(
+                _periodic_retention_sweep(_obs_policy)
             )
 
         try:
@@ -396,9 +436,9 @@ async def lifespan(app: FastAPI):
     # If user opts out via the consent modal or Settings, takes effect on next launch.
     from lineage.api.desktop_setup import _read_telemetry_prefs
 
-    logfire_token = os.getenv("LOGFIRE_TOKEN")
-    if logfire_token and not _read_telemetry_prefs().get("telemetry_opted_out"):
-        logfire.configure(token=logfire_token, console=False)
+    configure_desktop_logfire(
+        telemetry_opted_out=bool(_read_telemetry_prefs().get("telemetry_opted_out"))
+    )
 
     # Startup: no maintained API route initializes the legacy state path.
     if _NEEDS_LEGACY_STATE:
@@ -746,6 +786,19 @@ async def lifespan(app: FastAPI):
                 "Failed to terminate active gold workers", exc_info=True
             )
 
+    _obs_task = getattr(app.state, "_obs_retention_task", None)
+    if _obs_task is not None:
+        import asyncio
+
+        _obs_task.cancel()
+        try:
+            await _obs_task
+        except (asyncio.CancelledError, Exception):
+            # await of a just-cancelled task re-raises CancelledError (a BaseException,
+            # NOT Exception in 3.12), so both must be caught; do not simplify to bare
+            # except Exception.
+            pass
+
     try:
         from core.observability.manifest import finalize_open_ops
 
@@ -759,6 +812,7 @@ async def lifespan(app: FastAPI):
         shutdown_shared_posthog_client()
     except Exception:
         logger.debug("Failed to shut down PostHog analytics client", exc_info=True)
+    shutdown_desktop_logfire()
 
     # Close standalone data backend (e.g. DuckDB file handle)
     standalone_db = getattr(app.state, "standalone_data_backend", None)

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/api/desktop_quickstart.py

@@ -743,13 +743,19 @@ def _quickstart_worker(
         "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
-    _fh = _logging.FileHandler(str(_log_file), mode="a")
-    _fh.setLevel(_logging.INFO)
-    _fh.setFormatter(_fmt)
+    from core.observability.retention import (
+        RetentionPolicy,
+        attach_rotating_stream_handler,
+    )
 
     root = _logging.getLogger()
     root.setLevel(_logging.INFO)
-    root.addHandler(_fh)
+    attach_rotating_stream_handler(
+        root,
+        _log_file,
+        max_head_bytes=RetentionPolicy.from_env().stream_head_max_bytes,
+        formatter=_fmt,
+    )
     from lineage.utils.logging import quiet_sync_dependency_loggers
 
     quiet_sync_dependency_loggers()

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/api/desktop_semdiff_provision.py

@@ -78,17 +78,22 @@ def _attach_diff_log_handler() -> None:
     (``type_inference.*``, ``ingest.*``, ``core.backends.unified_graph.*``)
     propagates to the child's root and lands in ``diff.log``.
     """
-    handler = logging.FileHandler(str(_diff_log_path()), mode="a")
-    handler.setLevel(logging.INFO)
-    handler.setFormatter(
-        logging.Formatter(
-            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-            datefmt="%Y-%m-%d %H:%M:%S",
-        )
+    from core.observability.retention import (
+        RetentionPolicy,
+        attach_rotating_stream_handler,
     )
+
     root = logging.getLogger()
     root.setLevel(logging.INFO)
-    root.addHandler(handler)
+    attach_rotating_stream_handler(
+        root,
+        _diff_log_path(),
+        max_head_bytes=RetentionPolicy.from_env().stream_head_max_bytes,
+        formatter=logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        ),
+    )
 
 
 def _load_env() -> None:

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/api/desktop_sync.py

@@ -2873,12 +2873,19 @@ def _sync_worker(
         "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
-    _fh = _logging.FileHandler(str(_logs / "sync.log"), mode="a")
-    _fh.setLevel(_logging.INFO)
-    _fh.setFormatter(_fmt)
+    from core.observability.retention import (
+        RetentionPolicy,
+        attach_rotating_stream_handler,
+    )
+
     root = _logging.getLogger()
     root.setLevel(_logging.INFO)
-    root.addHandler(_fh)
+    attach_rotating_stream_handler(
+        root,
+        _logs / "sync.log",
+        max_head_bytes=RetentionPolicy.from_env().stream_head_max_bytes,
+        formatter=_fmt,
+    )
 
     from lineage.utils.logging import quiet_sync_dependency_loggers
 

typedef_data_intelligence-0.37.0/src/lineage/observability/__init__.py

@@ -0,0 +1 @@
+"""Local observability helpers for the desktop backend."""

typedef_data_intelligence-0.37.0/src/lineage/observability/desktop_logfire.py

@@ -0,0 +1,97 @@
+"""Desktop Logfire setup with local trace export processors."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Final
+
+import logfire
+from opentelemetry.sdk.trace import SpanProcessor
+
+from lineage.observability.local_otlp_export import make_local_otlp_span_processor
+from lineage.observability.local_span_export import make_local_span_processor
+
+logger = logging.getLogger(__name__)
+
+_OTEL_EXPORTER_ENV_KEYS: Final = (
+    "OTEL_TRACES_EXPORTER",
+    "OTEL_METRICS_EXPORTER",
+    "OTEL_LOGS_EXPORTER",
+)
+_OTEL_REMOTE_EXPORT_ENV_KEYS: Final = (
+    *_OTEL_EXPORTER_ENV_KEYS,
+    "OTEL_EXPORTER_OTLP_ENDPOINT",
+    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
+)
+_local_only_previous_otel_exporters: dict[str, str | None] | None = None
+
+
+def configure_desktop_logfire(*, telemetry_opted_out: bool) -> None:
+    """Configure cloud-gated Logfire and local desktop span processors."""
+    logfire_token = os.getenv("LOGFIRE_TOKEN") or None
+    span_processors = _desktop_span_processors()
+    send_to_logfire = logfire_token is not None and not telemetry_opted_out
+    if send_to_logfire:
+        logfire.configure(
+            token=logfire_token,
+            send_to_logfire=True,
+            console=False,
+            additional_span_processors=span_processors,
+        )
+        return
+
+    _disable_otel_exporters_for_local_only()
+    logfire.configure(
+        token=None,
+        send_to_logfire=False,
+        metrics=False,
+        console=False,
+        additional_span_processors=span_processors,
+    )
+
+
+def shutdown_desktop_logfire() -> None:
+    """Flush configured Logfire processors and restore local-only OTEL env changes."""
+    try:
+        logfire.shutdown()
+    except Exception:
+        logger.debug("Failed to shut down Logfire", exc_info=True)
+    finally:
+        _restore_local_only_otel_exporters()
+
+
+def _desktop_span_processors() -> list[SpanProcessor]:
+    processors: list[SpanProcessor] = [make_local_span_processor()]
+    local_otlp_processor = make_local_otlp_span_processor()
+    if local_otlp_processor is not None:
+        processors.append(local_otlp_processor)
+    return processors
+
+
+def _disable_otel_exporters_for_local_only() -> None:
+    global _local_only_previous_otel_exporters
+    if _local_only_previous_otel_exporters is not None:
+        _restore_local_only_otel_exporters()
+    if not any(os.getenv(key) for key in _OTEL_REMOTE_EXPORT_ENV_KEYS):
+        return
+    _local_only_previous_otel_exporters = {
+        key: os.environ.get(key) for key in _OTEL_EXPORTER_ENV_KEYS
+    }
+    for key in _OTEL_EXPORTER_ENV_KEYS:
+        os.environ[key] = "none"
+
+
+def _restore_local_only_otel_exporters() -> None:
+    global _local_only_previous_otel_exporters
+    previous_exporters = _local_only_previous_otel_exporters
+    if previous_exporters is None:
+        return
+    for key, value in previous_exporters.items():
+        if value is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = value
+    _local_only_previous_otel_exporters = None

typedef_data_intelligence-0.37.0/src/lineage/observability/local_otlp_export.py

@@ -0,0 +1,109 @@
+"""Local OTLP/HTTP export for explicitly enabled desktop development traces."""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+from typing import Final
+from urllib.parse import SplitResult, urlsplit, urlunsplit
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+_LOCAL_OTLP_EXPORT_ENV: Final = "TYPEDEF_ENABLE_LOCAL_OTLP_EXPORT"
+_GENERIC_ENDPOINT_ENV: Final = "OTEL_EXPORTER_OTLP_ENDPOINT"
+_TRACES_ENDPOINT_ENV: Final = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
+_GENERIC_PROTOCOL_ENV: Final = "OTEL_EXPORTER_OTLP_PROTOCOL"
+_TRACES_PROTOCOL_ENV: Final = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
+_DEFAULT_TRACES_ENDPOINT: Final = "http://127.0.0.1:4318/v1/traces"
+_TRACES_PATH: Final = "/v1/traces"
+_HTTP_PROTOBUF_PROTOCOL: Final = "http/protobuf"
+_ENABLED_VALUES: Final = frozenset({"1", "true", "yes", "on"})
+_LOOPBACK_HOSTNAMES: Final = frozenset({"localhost"})
+_EXPORT_TIMEOUT_SECONDS: Final = 2.0
+
+
+def resolve_local_otlp_traces_endpoint() -> str | None:
+    """Resolve a loopback OTLP/HTTP traces endpoint from development env config."""
+    if not _local_otlp_export_enabled():
+        return None
+    if _resolved_protocol() != _HTTP_PROTOBUF_PROTOCOL:
+        return None
+    traces_endpoint = _clean_env(_TRACES_ENDPOINT_ENV)
+    if traces_endpoint is not None:
+        return _validated_loopback_endpoint(traces_endpoint)
+    generic_endpoint = _clean_env(_GENERIC_ENDPOINT_ENV)
+    if generic_endpoint is None:
+        return _DEFAULT_TRACES_ENDPOINT
+    return _validated_loopback_endpoint(_with_traces_path(generic_endpoint))
+
+
+def make_local_otlp_span_processor() -> BatchSpanProcessor | None:
+    """Create a local OTLP/HTTP span processor when development export is enabled."""
+    endpoint = resolve_local_otlp_traces_endpoint()
+    if endpoint is None:
+        return None
+    return BatchSpanProcessor(
+        OTLPSpanExporter(endpoint=endpoint, timeout=_EXPORT_TIMEOUT_SECONDS)
+    )
+
+
+def _local_otlp_export_enabled() -> bool:
+    value = _clean_env(_LOCAL_OTLP_EXPORT_ENV)
+    return value is not None and value.lower() in _ENABLED_VALUES
+
+
+def _resolved_protocol() -> str:
+    traces_protocol = _clean_env(_TRACES_PROTOCOL_ENV)
+    if traces_protocol is not None:
+        return traces_protocol.lower()
+    generic_protocol = _clean_env(_GENERIC_PROTOCOL_ENV)
+    if generic_protocol is not None:
+        return generic_protocol.lower()
+    return _HTTP_PROTOBUF_PROTOCOL
+
+
+def _clean_env(key: str) -> str | None:
+    value = os.getenv(key)
+    if value is None:
+        return None
+    clean_value = value.strip()
+    if clean_value:
+        return clean_value
+    return None
+
+
+def _with_traces_path(endpoint: str) -> str:
+    parsed = urlsplit(endpoint)
+    clean_path = parsed.path.rstrip("/")
+    if clean_path.endswith(_TRACES_PATH):
+        return endpoint
+    traces_path = f"{clean_path}{_TRACES_PATH}" if clean_path else _TRACES_PATH
+    return urlunsplit(
+        SplitResult(
+            scheme=parsed.scheme,
+            netloc=parsed.netloc,
+            path=traces_path,
+            query=parsed.query,
+            fragment=parsed.fragment,
+        )
+    )
+
+
+def _validated_loopback_endpoint(endpoint: str) -> str | None:
+    parsed = urlsplit(endpoint)
+    if parsed.scheme not in {"http", "https"}:
+        return None
+    if parsed.username is not None or parsed.password is not None:
+        return None
+    if parsed.query or parsed.fragment:
+        return None
+    hostname = parsed.hostname
+    if hostname is None:
+        return None
+    if hostname.lower() in _LOOPBACK_HOSTNAMES:
+        return endpoint
+    try:
+        return endpoint if ipaddress.ip_address(hostname).is_loopback else None
+    except ValueError:
+        return None

typedef_data_intelligence-0.37.0/src/lineage/observability/local_span_export.py

@@ -0,0 +1,93 @@
+"""OpenTelemetry span export for local desktop traces."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Final
+
+from core.paths import logs_dir
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ReadableSpan,
+    SpanExporter,
+    SpanExportResult,
+)
+
+_TRACE_FILE_PREFIX: Final = "spans"
+_DEFAULT_TRACE_CHUNK_BYTES: Final = 64 * 1024 * 1024
+
+
+class NdjsonFileSpanExporter(SpanExporter):
+    """Write OpenTelemetry spans to per-process NDJSON chunks, rolling to a new chunk.
+
+    Chunks rotate when the current one crosses ``max_file_bytes`` so a long-lived
+    process (the backend) never grows one unbounded file (TD-3813 blocker #2).
+    """
+
+    def __init__(
+        self, traces_dir: Path, max_file_bytes: int = _DEFAULT_TRACE_CHUNK_BYTES
+    ) -> None:
+        """Create an exporter rooted at the configured traces directory."""
+        self._traces_dir = traces_dir
+        self._pid = os.getpid()
+        # per-instance uniqueness key: (pid, start_ns, seq) names each chunk; one
+        # exporter per process, so start_ns never collides across restarts.
+        self._start_ns = time.time_ns()
+        self._seq = 0
+        self._max_file_bytes = max_file_bytes
+        self._path = self._chunk_path()
+        self._lock = threading.Lock()
+        self._closed = False
+
+    def _chunk_path(self) -> Path:
+        return (
+            self._traces_dir
+            / f"{_TRACE_FILE_PREFIX}-{self._pid}-{self._start_ns}-{self._seq:04d}.ndjson"
+        )
+
+    def _maybe_rotate(self) -> None:
+        try:
+            if self._path.exists() and self._path.stat().st_size >= self._max_file_bytes:
+                self._seq += 1
+                self._path = self._chunk_path()
+        except OSError:
+            pass
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        """Append spans as one JSON object per line, rolling chunks by size."""
+        with self._lock:
+            if self._closed:
+                return SpanExportResult.FAILURE
+            try:
+                self._traces_dir.mkdir(parents=True, exist_ok=True)
+                self._maybe_rotate()
+                with self._path.open("a", encoding="utf-8") as trace_file:
+                    for span in spans:
+                        trace_file.write(span.to_json(indent=None))
+                        trace_file.write("\n")
+            except (OSError, TypeError, ValueError):
+                return SpanExportResult.FAILURE
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """Stop accepting new spans."""
+        with self._lock:
+            self._closed = True
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Report that file writes are already flushed."""
+        return True
+
+
+def make_local_span_processor() -> BatchSpanProcessor:
+    """Create the always-on local span processor for desktop startup."""
+    from core.observability.retention import RetentionPolicy
+
+    chunk_bytes = RetentionPolicy.from_env().stream_head_max_bytes
+    return BatchSpanProcessor(
+        NdjsonFileSpanExporter(logs_dir() / "traces", max_file_bytes=chunk_bytes)
+    )

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/typedef_cli.py

@@ -461,13 +461,19 @@ def sync(projects: tuple[str, ...], all: bool, full: bool, verbose: bool):
     log_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
     log_datefmt = "%Y-%m-%d %H:%M:%S"
 
-    file_handler = logging.FileHandler(str(log_file), mode="a")
-    file_handler.setLevel(logging.INFO)
-    file_handler.setFormatter(logging.Formatter(log_format, datefmt=log_datefmt))
+    from core.observability.retention import (
+        RetentionPolicy,
+        attach_rotating_stream_handler,
+    )
 
     root_logger = logging.getLogger()
     root_logger.setLevel(logging.INFO)
-    root_logger.addHandler(file_handler)
+    attach_rotating_stream_handler(
+        root_logger,
+        log_file,
+        max_head_bytes=RetentionPolicy.from_env().stream_head_max_bytes,
+        formatter=logging.Formatter(log_format, datefmt=log_datefmt),
+    )
 
     if verbose:
         console_handler = logging.StreamHandler()

{typedef_data_intelligence-0.35.0 → typedef_data_intelligence-0.37.0}/src/lineage/utils/git.py

@@ -10,6 +10,8 @@ from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from pathlib import Path
 
+from core.models.observability import sanitize_diagnostic_text
+
 logger = logging.getLogger(__name__)
 
 
@@ -69,7 +71,6 @@ class CloneProgress:
 # Regex to parse git progress lines like:
 # "Receiving objects:  67% (835/1247)"
 _PROGRESS_RE = re.compile(r"(Counting|Compressing|Receiving|Resolving)[^:]*:\s*(\d+)%")
-_URL_CREDENTIALS_RE = re.compile(r"(?P<scheme>https?://)(?:[^/\s@]+(?::[^/\s@]*)?@)")
 
 
 def _handle_clone_stderr_line(
@@ -91,19 +92,36 @@ def _handle_clone_stderr_line(
 
 
 def _build_clone_failure_message(stderr_lines: list[str], exit_code: int) -> str:
-    """Return the cleaned clone failure text to surface to callers."""
+    """Return the clone failure text to surface to callers.
+
+    Credential shapes are stripped here (TD-3825) so every downstream consumer
+    inherits clean text: the raised ``RuntimeError``, the error ``CloneProgress``
+    event, the ``logger.debug`` full-stderr line, and anything that logs the
+    exception into ``sync.log`` / ``quickstart.log`` / ``backend-stdout.log``.
+    A token-bearing remote URL (``https://TOKEN@host/repo.git``) never reaches
+    disk from this path.
+    """
     stderr_detail = "\n".join(line.strip() for line in stderr_lines if line.strip())
-    return stderr_detail or f"git clone failed (exit {exit_code})"
+    if not stderr_detail:
+        return f"git clone failed (exit {exit_code})"
+    sanitized, _ = sanitize_diagnostic_text(stderr_detail)
+    return sanitized
 
 
 def _build_clone_failure_log_summary(stderr_message: str, exit_code: int) -> str:
-    """Return a redacted one-line summary safe for error logs."""
+    """Return a one-line summary safe for error logs.
+
+    ``stderr_message`` is already credential-stripped by
+    :func:`_build_clone_failure_message`; this re-runs the sanitizer defensively
+    in case a caller passes raw text.
+    """
     first_line = next(
         (line.strip() for line in stderr_message.splitlines() if line.strip()), ""
     )
     if not first_line:
         return f"git clone failed (exit {exit_code})"
-    return _URL_CREDENTIALS_RE.sub(r"\g<scheme>", first_line)
+    sanitized, _ = sanitize_diagnostic_text(first_line)
+    return sanitized
 
 
 async def clone_repo_with_progress(