@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/experience_pipeline.py

@@ -0,0 +1,1130 @@
+#!/usr/bin/env python3
+"""Unified structured experience event pipeline for local and server storage."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import os
+import pathlib
+import re
+import urllib.error
+import urllib.request
+
+try:  # PyYAML is optional — only the sync contribution-gate reads project.yaml.
+    import yaml
+except ImportError:  # npm-installed users may lack PyYAML; degrade, don't crash (#4363).
+    yaml = None
+
+import auth
+import project_manager as pm
+from json_utils import append_jsonl, load_json, load_jsonl, save_json
+
+API_BASE = os.environ.get("ODAI_API_URL", "https://api.0dai.dev")
+SERVER_EXPERIENCE_DIR = pathlib.Path.home() / ".0dai" / "db" / "experience"
+ARCHIVE_AFTER_DAYS = 90
+SYNC_BATCH_LIMIT = 200
+SYNC_RETENTION_IDS = 200
+SUPPORTED_EVENT_TYPES = {
+    "task_completed",
+    "task_failed",
+    "session_saved",
+    "session_resumed",
+    "graph_synced",
+    "decision_made",
+    "config_generated",
+    "doctor_run",
+}
+SUCCESS_RESULTS = {"success", "partial"}
+FAIL_RESULTS = {"failure", "timeout", "stuck"}
+CODE_PATTERNS = (
+    "```",
+    "def ",
+    "class ",
+    "function ",
+    "const ",
+    "import ",
+    "export ",
+    "return ",
+    "{",
+    "}",
+    ";",
+)
+
+
+def _detect_target(target: str | pathlib.Path = ".") -> pathlib.Path:
+    return pathlib.Path(target).resolve()
+
+
+def _now_dt() -> dt.datetime:
+    return dt.datetime.now(dt.timezone.utc).replace(microsecond=0)
+
+
+def _now() -> str:
+    return _now_dt().isoformat().replace("+00:00", "Z")
+
+
+def _dt_from_iso(value: str | None) -> dt.datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _days_ago(value: str | None) -> int | None:
+    parsed = _dt_from_iso(value)
+    if not parsed:
+        return None
+    return max(0, int((_now_dt() - parsed).total_seconds() // 86400))
+
+
+def _safe_div(num: float, den: float) -> float:
+    if not den:
+        return 0.0
+    return round(num / den, 4)
+
+
+def _looks_like_code(text: str) -> bool:
+    lowered = text.lower()
+    if "\n" in text:
+        return True
+    return any(token in lowered for token in CODE_PATTERNS)
+
+
+def sanitize_text(value: object, *, limit: int = 180) -> str:
+    text = " ".join(str(value or "").strip().split())
+    if not text or _looks_like_code(text):
+        return ""
+    return text[:limit]
+
+
+def _sanitize_result(value: object) -> str:
+    lowered = sanitize_text(value, limit=24).lower()
+    if lowered in {"success", "failure", "partial", "timeout", "stuck"}:
+        return lowered
+    if lowered in {"done", "ok", "passed"}:
+        return "success"
+    if lowered in {"failed", "error"}:
+        return "failure"
+    return "unknown"
+
+
+def _project_id(target: pathlib.Path) -> str:
+    return str(pm._identity(target).get("project_id") or "")
+
+
+def _stack(target: pathlib.Path) -> str:
+    discovery = load_json(target / "ai" / "manifest" / "discovery.json")
+    return str(discovery.get("stack") or pm._identity(target).get("stack") or "unknown")
+
+
+def _events_root(target: pathlib.Path) -> pathlib.Path:
+    return target / "ai" / "experience"
+
+
+def _events_dir(target: pathlib.Path) -> pathlib.Path:
+    return _events_root(target) / "events"
+
+
+def _archive_dir(target: pathlib.Path) -> pathlib.Path:
+    return _events_root(target) / "archive"
+
+
+def _sync_state_path(target: pathlib.Path) -> pathlib.Path:
+    return _events_root(target) / "sync_state.json"
+
+
+def _event_path_for(target: pathlib.Path, timestamp: str) -> pathlib.Path:
+    parsed = _dt_from_iso(timestamp) or _now_dt()
+    return _events_dir(target) / f"{parsed.date().isoformat()}.jsonl"
+
+
+def _server_event_path(project_id: str, timestamp: str) -> pathlib.Path:
+    parsed = _dt_from_iso(timestamp) or _now_dt()
+    return SERVER_EXPERIENCE_DIR / project_id / f"{parsed.date().isoformat()}.jsonl"
+
+
+def _iter_event_files(target: pathlib.Path, *, include_archive: bool = False) -> list[pathlib.Path]:
+    files = sorted(_events_dir(target).glob("*.jsonl"))
+    if include_archive:
+        files.extend(sorted(_archive_dir(target).glob("*.jsonl")))
+    return sorted(files)
+
+
+def rotate_archives(target: pathlib.Path, *, max_age_days: int = ARCHIVE_AFTER_DAYS) -> int:
+    moved = 0
+    events_dir = _events_dir(target)
+    archive_dir = _archive_dir(target)
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    cutoff = _now_dt().date() - dt.timedelta(days=max_age_days)
+    for path in sorted(events_dir.glob("*.jsonl")):
+        try:
+            file_date = dt.date.fromisoformat(path.stem)
+        except ValueError:
+            continue
+        if file_date >= cutoff:
+            continue
+        dest = archive_dir / path.name
+        if dest.exists():
+            with dest.open("a", encoding="utf-8") as handle:
+                handle.write(path.read_text(encoding="utf-8"))
+            path.unlink(missing_ok=True)
+        else:
+            os.replace(str(path), str(dest))
+        moved += 1
+    return moved
+
+
+def _load_sync_state(target: pathlib.Path) -> dict:
+    return load_json(_sync_state_path(target))
+
+
+def _save_sync_state(target: pathlib.Path, data: dict) -> None:
+    save_json(_sync_state_path(target), data)
+
+
+def _event_identity(event: dict) -> tuple[str, str]:
+    return str(event.get("timestamp") or ""), str(event.get("event_id") or "")
+
+
+def _event_sort_key(event: dict) -> tuple[str, str]:
+    return _event_identity(event)
+
+
+def _build_event_id(event_type: str, timestamp: str, agent: str, session_id: str, goal: str) -> str:
+    seed = json.dumps(
+        {
+            "event_type": event_type,
+            "timestamp": timestamp,
+            "agent": agent,
+            "session_id": session_id,
+            "goal": goal,
+        },
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+    return "exp_" + hashlib.sha256(seed.encode("utf-8")).hexdigest()[:12]
+
+
+def _normalize_task_type(raw: object, goal: str = "") -> str:
+    task_type = sanitize_text(raw, limit=32).lower().replace("_", "-")
+    if task_type in {"feat", "fix", "refactor", "test", "docs", "review"}:
+        return task_type
+    joined = f"{task_type} {goal}".lower()
+    if any(token in joined for token in ("test", "spec", "coverage")):
+        return "test"
+    if any(token in joined for token in ("doc", "readme", "comment")):
+        return "docs"
+    if any(token in joined for token in ("review", "audit", "analysis")):
+        return "review"
+    if any(token in joined for token in ("refactor", "cleanup", "rename")):
+        return "refactor"
+    if any(token in joined for token in ("bug", "fix", "hotfix", "regression")):
+        return "fix"
+    return "feat"
+
+
+def _read_task_counts(target: pathlib.Path) -> tuple[str, str]:
+    code = ""
+    branch = ""
+    try:
+        import subprocess
+
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=target,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+        branch = result.stdout.strip() if result.returncode == 0 else ""
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=target,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+        code = result.stdout.strip() if result.returncode == 0 else ""
+    except Exception:  # noqa: BLE001 — git metadata probe failed
+        pass
+    return branch, code
+
+
+def _active_session_id(target: pathlib.Path) -> str:
+    active = load_json(target / "ai" / "sessions" / "active.json")
+    return str(active.get("session_id") or active.get("id") or "")
+
+
+def _quality_block(task: dict) -> dict:
+    tests_passed = bool(task.get("tests_passed")) if "tests_passed" in task else _sanitize_result(task.get("result") or task.get("status")) == "success"
+    return {
+        "lint_clean": bool(task.get("lint_clean", tests_passed)),
+        "no_secrets": bool(task.get("no_secrets", True)),
+        "commit_message_valid": bool(task.get("commit_message_valid", True)),
+        "acceptance_criteria_met": bool(task.get("acceptance_criteria_met", tests_passed)),
+        "review_needed": bool(task.get("review_needed", False)),
+    }
+
+
+def _normalize_event(target: pathlib.Path, payload: dict) -> dict:
+    timestamp = str(payload.get("timestamp") or _now())
+    event_type = str(payload.get("event_type") or "").strip() or "task_completed"
+    if event_type not in SUPPORTED_EVENT_TYPES:
+        event_type = "task_completed"
+    branch, commit_hash = _read_task_counts(target)
+    task = dict(payload.get("task") or {})
+    context = dict(payload.get("context") or {})
+    quality = dict(payload.get("quality") or {})
+    goal = sanitize_text((task.get("goal") or payload.get("goal") or payload.get("summary") or payload.get("title") or ""), limit=160)
+    task_result = _sanitize_result(task.get("result") or payload.get("result") or payload.get("status"))
+    if event_type == "task_failed" and task_result == "unknown":
+        task_result = "failure"
+    if event_type == "task_completed" and task_result == "unknown":
+        task_result = "success"
+
+    normalized = {
+        "event_id": str(payload.get("event_id") or _build_event_id(
+            event_type,
+            timestamp,
+            str(payload.get("agent") or task.get("agent") or ""),
+            str(payload.get("session_id") or _active_session_id(target)),
+            goal,
+        )),
+        "timestamp": timestamp,
+        "project_id": str(payload.get("project_id") or _project_id(target)),
+        "session_id": str(payload.get("session_id") or _active_session_id(target)),
+        "event_type": event_type,
+        "agent": str(payload.get("agent") or task.get("agent") or "unknown"),
+        "model": sanitize_text(payload.get("model") or task.get("model") or "unknown", limit=48) or "unknown",
+        "effort": str(payload.get("effort") or task.get("effort") or "medium"),
+        "task": {
+            "task_id": str(task.get("task_id") or payload.get("task_id") or ""),
+            "goal": goal,
+            "task_type": _normalize_task_type(task.get("task_type") or task.get("type") or payload.get("task_type"), goal),
+            "result": task_result,
+            "elapsed_seconds": int(float(task.get("elapsed_seconds") or payload.get("elapsed_seconds") or 0) or 0),
+            "cost_usd": round(float(task.get("cost_usd") or task.get("cost") or payload.get("cost_usd") or 0) or 0, 4),
+            "tokens_in": int(float(task.get("tokens_in") or payload.get("tokens_in") or 0) or 0),
+            "tokens_out": int(float(task.get("tokens_out") or payload.get("tokens_out") or 0) or 0),
+        },
+        "context": {
+            "stack": sanitize_text(context.get("stack") or _stack(target), limit=48) or "unknown",
+            "files_touched": int(float(context.get("files_touched") or payload.get("files_touched") or 0) or 0),
+            "tests_passed": bool(context.get("tests_passed", task_result == "success")),
+            "commit_hash": sanitize_text(context.get("commit_hash") or commit_hash, limit=16),
+            "branch": sanitize_text(context.get("branch") or branch, limit=64),
+            "graph_nodes_used": int(float(context.get("graph_nodes_used") or 0) or 0),
+            "graph_edges_used": int(float(context.get("graph_edges_used") or 0) or 0),
+        },
+        "quality": {
+            **_quality_block(task),
+            **{
+                "lint_clean": bool(quality.get("lint_clean", _quality_block(task)["lint_clean"])),
+                "no_secrets": bool(quality.get("no_secrets", _quality_block(task)["no_secrets"])),
+                "commit_message_valid": bool(quality.get("commit_message_valid", _quality_block(task)["commit_message_valid"])),
+                "acceptance_criteria_met": bool(quality.get("acceptance_criteria_met", _quality_block(task)["acceptance_criteria_met"])),
+                "review_needed": bool(quality.get("review_needed", _quality_block(task)["review_needed"])),
+            },
+        },
+    }
+    return normalized
+
+
+def record_event(target: pathlib.Path | str, payload: dict) -> dict:
+    target_path = _detect_target(target)
+    rotate_archives(target_path)
+    event = _normalize_event(target_path, payload)
+    path = _event_path_for(target_path, str(event.get("timestamp") or _now()))
+    append_jsonl(path, event)
+    return event
+
+
+def build_swarm_event(target: pathlib.Path | str, task: dict, agent: str, elapsed: float, event_type: str | None = None) -> dict:
+    target_path = _detect_target(target)
+    status = str(task.get("status") or "").lower()
+    error_kind = str(task.get("agent_error_kind") or "").lower()
+    result = "success"
+    resolved_event_type = event_type
+    if error_kind == "timeout":
+        result = "timeout"
+        resolved_event_type = resolved_event_type or "task_failed"
+    elif status == "failed" or task.get("error"):
+        result = "failure"
+        resolved_event_type = resolved_event_type or "task_failed"
+    else:
+        resolved_event_type = resolved_event_type or "task_completed"
+
+    files = task.get("files") or task.get("context", {}).get("files") or []
+    if isinstance(files, str):
+        files = [files]
+    context = {
+        "stack": _stack(target_path),
+        "files_touched": len([f for f in files if f]),
+        "tests_passed": result == "success",
+        "graph_nodes_used": 1 if task.get("graph_context_used") else 0,
+        "graph_edges_used": 1 if task.get("graph_mutation_applied") else 0,
+    }
+    return {
+        "event_type": resolved_event_type,
+        "session_id": str(task.get("session_id") or _active_session_id(target_path)),
+        "agent": agent,
+        "model": str(task.get("model") or task.get("tier") or "unknown"),
+        "effort": str(task.get("effort") or "medium"),
+        "task": {
+            "task_id": str(task.get("id") or ""),
+            "goal": str(task.get("title") or task.get("goal") or ""),
+            "task_type": str(task.get("type") or ""),
+            "result": result,
+            "elapsed_seconds": int(float(elapsed or task.get("elapsed_seconds") or 0) or 0),
+            "cost_usd": float(task.get("cost") or 0),
+            "tokens_in": int(float(task.get("tokens_in") or task.get("tokens") or 0) or 0),
+            "tokens_out": int(float(task.get("tokens_out") or 0) or 0),
+        },
+        "context": context,
+        "quality": _quality_block(task),
+    }
+
+
+def build_session_event(target: pathlib.Path | str, event_type: str, payload: dict, *, agent: str | None = None) -> dict:
+    target_path = _detect_target(target)
+    goal = payload.get("goal") or {}
+    plan = payload.get("plan") or {}
+    context = payload.get("context") or {}
+    files_modified = context.get("files_modified") or []
+    return {
+        "event_type": event_type,
+        "session_id": str(payload.get("session_id") or payload.get("id") or _active_session_id(target_path)),
+        "agent": str(agent or payload.get("saved_by_agent") or payload.get("current_agent") or "unknown"),
+        "model": str(payload.get("saved_by_model") or payload.get("current_model") or "unknown"),
+        "effort": "medium",
+        "task": {
+            "task_id": str(payload.get("session_id") or payload.get("id") or ""),
+            "goal": str(goal.get("refined") or goal.get("original") or ""),
+            "task_type": "review",
+            "result": "success",
+            "elapsed_seconds": 0,
+            "cost_usd": 0,
+            "tokens_in": 0,
+            "tokens_out": 0,
+        },
+        "context": {
+            "stack": _stack(target_path),
+            "files_touched": len(files_modified) if isinstance(files_modified, list) else 0,
+            "tests_passed": True,
+            "graph_nodes_used": len((payload.get("graph_context") or {}).get("relevant_nodes") or []),
+            "graph_edges_used": len((payload.get("graph_context") or {}).get("relevant_edges") or []),
+        },
+        "quality": {
+            "lint_clean": True,
+            "no_secrets": True,
+            "commit_message_valid": True,
+            "acceptance_criteria_met": bool(plan.get("steps")),
+            "review_needed": False,
+        },
+    }
+
+
+def build_simple_event(
+    target: pathlib.Path | str,
+    event_type: str,
+    *,
+    agent: str = "unknown",
+    model: str = "unknown",
+    effort: str = "medium",
+    goal: str = "",
+    task_type: str = "feat",
+    result: str = "success",
+    files_touched: int = 0,
+    graph_nodes_used: int = 0,
+    graph_edges_used: int = 0,
+    elapsed_seconds: int = 0,
+    cost_usd: float = 0.0,
+    tests_passed: bool = True,
+) -> dict:
+    target_path = _detect_target(target)
+    return {
+        "event_type": event_type,
+        "agent": agent,
+        "model": model,
+        "effort": effort,
+        "task": {
+            "task_id": "",
+            "goal": goal,
+            "task_type": task_type,
+            "result": result,
+            "elapsed_seconds": elapsed_seconds,
+            "cost_usd": cost_usd,
+            "tokens_in": 0,
+            "tokens_out": 0,
+        },
+        "context": {
+            "stack": _stack(target_path),
+            "files_touched": files_touched,
+            "tests_passed": tests_passed,
+            "graph_nodes_used": graph_nodes_used,
+            "graph_edges_used": graph_edges_used,
+        },
+        "quality": {
+            "lint_clean": True,
+            "no_secrets": True,
+            "commit_message_valid": True,
+            "acceptance_criteria_met": result in SUCCESS_RESULTS,
+            "review_needed": False,
+        },
+    }
+
+
+def _matches_filters(
+    event: dict,
+    *,
+    since: dt.datetime | None = None,
+    until: dt.datetime | None = None,
+    agent: str = "",
+    event_type: str = "",
+    limit_task_result: str = "",
+) -> bool:
+    ts = _dt_from_iso(str(event.get("timestamp") or ""))
+    if since and (not ts or ts < since):
+        return False
+    if until and (not ts or ts > until):
+        return False
+    if agent and str(event.get("agent") or "").lower() != agent.lower():
+        return False
+    if event_type and str(event.get("event_type") or "").lower() != event_type.lower():
+        return False
+    if limit_task_result:
+        if str((event.get("task") or {}).get("result") or "").lower() != limit_task_result.lower():
+            return False
+    return True
+
+
+def _parse_period(raw: str) -> tuple[dt.datetime | None, dt.datetime | None]:
+    value = str(raw or "").strip().lower()
+    if not value or value == "all":
+        return None, None
+    if value.endswith("d"):
+        try:
+            days = max(1, int(value[:-1]))
+        except ValueError:
+            return None, None
+        return _now_dt() - dt.timedelta(days=days), None
+    return _dt_from_iso(value), None
+
+
+def load_events(
+    target: pathlib.Path | str,
+    *,
+    since: str = "",
+    until: str = "",
+    agent: str = "",
+    event_type: str = "",
+    result: str = "",
+    limit: int = 50,
+    include_archive: bool = False,
+) -> list[dict]:
+    target_path = _detect_target(target)
+    rotate_archives(target_path)
+    since_dt, _ = _parse_period(since)
+    until_dt = _dt_from_iso(until)
+    events: list[dict] = []
+    for path in _iter_event_files(target_path, include_archive=include_archive):
+        events.extend(load_jsonl(path))
+    events.sort(key=_event_sort_key, reverse=True)
+    filtered = [
+        event for event in events
+        if _matches_filters(
+            event,
+            since=since_dt,
+            until=until_dt,
+            agent=agent,
+            event_type=event_type,
+            limit_task_result=result,
+        )
+    ]
+    return filtered[: max(1, limit)]
+
+
+def _task_events(events: list[dict]) -> list[dict]:
+    return [event for event in events if str(event.get("event_type") or "").startswith("task_")]
+
+
+def _aggregate_by(events: list[dict], key: str) -> dict[str, dict]:
+    buckets: dict[str, dict] = {}
+    for event in _task_events(events):
+        if key == "agent":
+            group = str(event.get("agent") or "unknown")
+        elif key == "model":
+            group = str(event.get("model") or "unknown")
+        else:
+            group = str((event.get("task") or {}).get("task_type") or "unknown")
+        bucket = buckets.setdefault(
+            group,
+            {
+                "count": 0,
+                "success": 0,
+                "cost": 0.0,
+                "elapsed": 0.0,
+            },
+        )
+        bucket["count"] += 1
+        task = event.get("task") or {}
+        result = str(task.get("result") or "unknown")
+        if result in SUCCESS_RESULTS:
+            bucket["success"] += 1
+        bucket["cost"] += float(task.get("cost_usd") or 0)
+        bucket["elapsed"] += float(task.get("elapsed_seconds") or 0)
+    output: dict[str, dict] = {}
+    for group, bucket in sorted(buckets.items()):
+        count = bucket["count"]
+        output[group] = {
+            "count": count,
+            "success_rate": _safe_div(bucket["success"], count),
+            "total_cost": round(bucket["cost"], 4),
+            "avg_elapsed": int(bucket["elapsed"] / count) if count else 0,
+        }
+    return output
+
+
+def _recommendations(stats: dict) -> list[str]:
+    recommendations: list[str] = []
+    by_model = stats.get("by_model") or {}
+    by_task_type = stats.get("by_task_type") or {}
+    if by_model:
+        ranked = sorted(by_model.items(), key=lambda item: (-item[1]["success_rate"], item[1]["total_cost"], item[0]))
+        best_model, best_metrics = ranked[0]
+        if best_metrics.get("count", 0) >= 2:
+            recommendations.append(
+                f"Use {best_model} more often ({int(best_metrics['success_rate'] * 100)}% success, ${best_metrics['total_cost']:.2f} total)"
+            )
+    if by_task_type:
+        for task_type, metrics in sorted(by_task_type.items()):
+            if metrics.get("count", 0) >= 2 and metrics.get("success_rate", 0) < 0.7:
+                recommendations.append(
+                    f"{task_type} tasks are underperforming ({int(metrics['success_rate'] * 100)}% success) — review prompts and model choice"
+                )
+                break
+    return recommendations[:3]
+
+
+def compute_stats(target: pathlib.Path | str, *, period: str = "30d", by: str = "all") -> dict:
+    target_path = _detect_target(target)
+    events = load_events(target_path, since=period, limit=10000, include_archive=True)
+    tasks = _task_events(events)
+    success_count = sum(1 for event in tasks if str((event.get("task") or {}).get("result") or "") in SUCCESS_RESULTS)
+    fail_count = sum(1 for event in tasks if str((event.get("task") or {}).get("result") or "") in FAIL_RESULTS)
+    total_cost = round(sum(float((event.get("task") or {}).get("cost_usd") or 0) for event in tasks), 4)
+    grouped = {
+        "by_agent": _aggregate_by(events, "agent"),
+        "by_model": _aggregate_by(events, "model"),
+        "by_task_type": _aggregate_by(events, "task_type"),
+    }
+    summary = {
+        "period": period,
+        "event_count": len(events),
+        "task_count": len(tasks),
+        "success_rate": _safe_div(success_count, len(tasks)),
+        "success_count": success_count,
+        "failure_count": fail_count,
+        "total_cost": total_cost,
+        "recommendations": _recommendations(grouped),
+    }
+    if by in {"agent", "model", "task_type"}:
+        return {"summary": summary, f"by_{by}": grouped[f"by_{by}"]}
+    return {"summary": summary, **grouped}
+
+
+def format_list(events: list[dict], *, since: str = "") -> str:
+    if not events:
+        label = f" ({since})" if since else ""
+        return f"Recent experience events{label}:\n\nNo data yet."
+    success = 0
+    failure = 0
+    spent = 0.0
+    lines = [f"Recent experience events{f' ({since})' if since else ''}:\n"]
+    for event in events:
+        task = event.get("task") or {}
+        result = str(task.get("result") or "unknown")
+        if result in SUCCESS_RESULTS:
+            success += 1
+            mark = "✅"
+        elif result in FAIL_RESULTS:
+            failure += 1
+            mark = "❌"
+        else:
+            mark = "•"
+        spent += float(task.get("cost_usd") or 0)
+        agent_model = str(event.get("agent") or "—")
+        if event.get("model") and str(event.get("model")) != "unknown":
+            agent_model += f"/{event.get('model')}"
+        label = sanitize_text(task.get("goal") or event.get("event_type") or "", limit=28) or "metadata event"
+        if event.get("event_type") == "graph_synced":
+            label = f"{int((event.get('context') or {}).get('graph_nodes_used') or 0)} nodes, {int((event.get('context') or {}).get('graph_edges_used') or 0)} edges"
+        if event.get("event_type") in {"session_saved", "session_resumed"} and task.get("goal"):
+            label = sanitize_text(task.get("goal"), limit=28)
+        extras = []
+        if task.get("cost_usd"):
+            extras.append(f"${float(task.get('cost_usd')):.2f}")
+        if task.get("elapsed_seconds"):
+            extras.append(f"{int(task.get('elapsed_seconds'))}s")
+        lines.append(
+            f"{str(event.get('timestamp') or '')[:16].replace('T', ' ')} | "
+            f"{event.get('event_type') or ''!s:<14} | "
+            f"{agent_model:<20} | {label:<28} | {mark}"
+            + (f" {' '.join(extras)}" if extras else "")
+        )
+    lines.append("")
+    lines.append(f"Total: {len(events)} events | {success} ✅ {failure} ❌ | ${spent:.2f} spent")
+    return "\n".join(lines)
+
+
+def format_stats(stats: dict) -> str:
+    summary = stats.get("summary") or {}
+    if not summary.get("event_count"):
+        return f"Experience stats ({summary.get('period', '30d')}):\n\nNo data yet."
+    lines = [f"Experience stats ({summary.get('period', '30d')}):\n"]
+    for label, key in (("By agent", "by_agent"), ("By model", "by_model"), ("By task type", "by_task_type")):
+        if key not in stats:
+            continue
+        lines.append(f"{label}:")
+        groups = stats.get(key) or {}
+        if not groups:
+            lines.append("  No data")
+            lines.append("")
+            continue
+        for name, metrics in sorted(groups.items(), key=lambda item: (-item[1]["success_rate"], item[1]["total_cost"], item[0])):
+            lines.append(
+                f"  {name:<14} | {metrics['count']:>2} tasks | "
+                f"{int(metrics['success_rate'] * 100):>3}% success | "
+                f"${metrics['total_cost']:.2f} | avg {metrics['avg_elapsed']}s"
+            )
+        lines.append("")
+    if summary.get("recommendations"):
+        lines.append("Recommendations:")
+        for item in summary["recommendations"]:
+            lines.append(f"- {item}")
+    return "\n".join(lines).rstrip()
+
+
+def _auth_token() -> str:
+    state = auth.load_token() or {}
+    return str(state.get("api_key") or state.get("access_token") or state.get("token") or "")
+
+
+def _auth_ready() -> bool:
+    return bool(_auth_token())
+
+
+def _plan_name() -> str:
+    state = auth.load_token() or {}
+    license_block = state.get("license") or {}
+    return str(license_block.get("plan") or state.get("plan") or "free").lower()
+
+
+def batch_for_sync(target: pathlib.Path | str, *, limit: int = SYNC_BATCH_LIMIT) -> list[dict]:
+    target_path = _detect_target(target)
+    state = _load_sync_state(target_path)
+    last_ts = str(state.get("last_synced_timestamp") or "")
+    seen = set(str(item) for item in state.get("last_synced_ids") or [])
+    events = load_events(target_path, limit=100000, include_archive=False)
+    pending: list[dict] = []
+    for event in sorted(events, key=_event_sort_key):
+        ts, event_id = _event_identity(event)
+        if last_ts and ts < last_ts:
+            continue
+        if last_ts and ts == last_ts and event_id in seen:
+            continue
+        pending.append(event)
+        if len(pending) >= limit:
+            break
+    return pending
+
+
+def _send_http_events(events: list[dict]) -> tuple[bool, dict, bool]:
+    token = _auth_token()
+    if not token:
+        return False, {"error": "not authenticated", "hint": "run: 0dai auth login"}, False
+    body = json.dumps({"events": events}, ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(
+        f"{API_BASE}/v1/experience/ingest",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": "0dai-cli/experience",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=20) as resp:
+            return True, json.loads(resp.read().decode("utf-8")), False
+    except urllib.error.HTTPError as exc:
+        try:
+            payload = json.loads(exc.read().decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            payload = {"error": f"http_error:{exc.code}"}
+        return False, payload, exc.code >= 500
+    except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
+        return False, {"error": str(exc) or "network unavailable"}, True
+
+
+# --- Outgoing-sync gate (#4372): never let our scripts, know-how, or secrets
+# leave the client. Every event is reduced to an allowlist and dropped wholesale
+# if any retained value matches a secret pattern; internal repos can opt out. ---
+
+_SYNC_ALLOWED_TOP = {
+    "event_id", "timestamp", "schema_version", "project_id", "event_type",
+    "agent", "model", "task_type", "task", "context", "quality",
+}
+_SYNC_ALLOWED_NESTED = {
+    "task": {"goal", "result", "task_type", "tests_passed"},
+    "context": {"stack", "commit_hash", "branch"},
+    "quality": {
+        "no_secrets", "lint_clean", "commit_message_valid",
+        "acceptance_criteria_met", "review_needed",
+    },
+}
+
+_SECRET_PATTERNS = tuple(
+    re.compile(p)
+    for p in (
+        r"AKIA[0-9A-Z]{16}",
+        r"gh[pousr]_[A-Za-z0-9]{20,}",
+        r"glpat-[A-Za-z0-9_-]{20,}",
+        r"sk-(?:ant-)?[A-Za-z0-9_-]{20,}",
+        r"AGE-SECRET-KEY-1[0-9A-Z]+",
+        r"xox[baprs]-[A-Za-z0-9-]{10,}",
+        r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+        r"eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}",
+        r"(?i)\b(?:api[_-]?key|secret|token|password|passwd|bearer)\b\s*[:=]\s*\S{12,}",
+    )
+)
+
+
+def _contains_secret(value: object) -> bool:
+    if isinstance(value, str):
+        return any(pat.search(value) for pat in _SECRET_PATTERNS)
+    if isinstance(value, dict):
+        return any(_contains_secret(v) for v in value.values())
+    if isinstance(value, (list, tuple)):
+        return any(_contains_secret(v) for v in value)
+    return False
+
+
+def _allowlist(data: object, allowed: set) -> dict:
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if k in allowed}
+
+
+def gate_outgoing_event(event: dict) -> dict | None:
+    """Reduce an event to the sync allowlist; return None to drop it.
+
+    Drops the whole event if any retained value matches a secret pattern —
+    better to lose one event than leak a credential (#4372).
+    """
+    if not isinstance(event, dict):
+        return None
+    gated = _allowlist(event, _SYNC_ALLOWED_TOP)
+    for key, allowed in _SYNC_ALLOWED_NESTED.items():
+        if isinstance(gated.get(key), dict):
+            gated[key] = _allowlist(gated[key], allowed)
+    if _contains_secret(gated):
+        return None
+    return gated
+
+
+def gate_outgoing_events(events: list[dict]) -> tuple[list[dict], int]:
+    kept: list[dict] = []
+    dropped = 0
+    for event in events:
+        gated = gate_outgoing_event(event)
+        if gated is None:
+            dropped += 1
+        else:
+            kept.append(gated)
+    return kept, dropped
+
+
+def contribution_enabled(target: pathlib.Path | str = ".") -> bool:
+    """Whether this repo may contribute experience to the shared pool.
+
+    Off when ODAI_EXPERIENCE_CONTRIBUTE is falsy, or project.yaml has
+    ``experience.contribute: false``. Internal / dogfood repos opt out (#4372).
+    """
+    env = os.environ.get("ODAI_EXPERIENCE_CONTRIBUTE", "").strip().lower()
+    if env in {"0", "false", "no", "off"}:
+        return False
+    if env in {"1", "true", "yes", "on"}:
+        return True
+    # PyYAML is optional; without it the project.yaml opt-out can't be read, so
+    # fall through to the default (contribute) rather than crashing (#4363).
+    if yaml is not None:
+        proj = _detect_target(target) / "ai" / "manifest" / "project.yaml"
+        try:
+            data = yaml.safe_load(proj.read_text(encoding="utf-8")) or {}
+        except (OSError, yaml.YAMLError):
+            pass
+        else:
+            if isinstance(data, dict):
+                experience = data.get("experience")
+                if isinstance(experience, dict) and "contribute" in experience:
+                    val = experience.get("contribute")
+                    if isinstance(val, bool):
+                        return val
+                    return str(val).strip().strip("\"'").lower() not in {"false", "no", "off", "0"}
+    return True
+
+
+def sync_preflight(target: pathlib.Path | str, *, limit: int = SYNC_BATCH_LIMIT) -> dict:
+    target_path = _detect_target(target)
+    if not contribution_enabled(target_path):
+        return {
+            "ok": True,
+            "skipped": True,
+            "reason": "contribution_disabled",
+            "plan": _plan_name(),
+            "authenticated": _auth_ready(),
+            "pending": 0,
+        }
+    plan = _plan_name()
+    if plan not in {"pro", "team", "enterprise"}:
+        return {
+            "ok": False,
+            "skipped": True,
+            "reason": "plan_not_eligible",
+            "plan": plan,
+            "authenticated": _auth_ready(),
+            "pending": 0,
+        }
+
+    pending = batch_for_sync(target_path, limit=limit)
+    if not pending:
+        return {
+            "ok": True,
+            "skipped": False,
+            "reason": "",
+            "plan": plan,
+            "authenticated": _auth_ready(),
+            "pending": 0,
+        }
+
+    if not _auth_ready():
+        return {
+            "ok": False,
+            "skipped": True,
+            "reason": "auth_required",
+            "hint": "run: 0dai auth login",
+            "plan": plan,
+            "authenticated": False,
+            "pending": len(pending),
+            "transient": False,
+        }
+
+    return {
+        "ok": True,
+        "skipped": False,
+        "reason": "",
+        "plan": plan,
+        "authenticated": True,
+        "pending": len(pending),
+    }
+
+
+def sync_events(target: pathlib.Path | str, *, limit: int = SYNC_BATCH_LIMIT) -> dict:
+    target_path = _detect_target(target)
+    preflight = sync_preflight(target_path, limit=limit)
+    if preflight.get("skipped"):
+        return preflight
+    if preflight.get("pending") == 0:
+        return {"ok": True, "ingested": 0, "preflight": preflight}
+    pending = batch_for_sync(target_path, limit=limit)
+    if not pending:
+        return {"ok": True, "ingested": 0, "preflight": preflight}
+    # Gate before send: reduce each event to the allowlist and drop any event
+    # carrying a secret. Never let our scripts/know-how/credentials leave (#4372).
+    outgoing, dropped = gate_outgoing_events(pending)
+    payload: dict = {}
+    if outgoing:
+        ok, payload, transient = _send_http_events(outgoing)
+        if not ok:
+            if str(payload.get("error") or "") == "not authenticated":
+                return {
+                    "ok": False,
+                    "skipped": True,
+                    "reason": "auth_required",
+                    "hint": payload.get("hint", "run: 0dai auth login"),
+                    "plan": preflight.get("plan"),
+                    "authenticated": False,
+                    "pending": len(pending),
+                    "transient": False,
+                }
+            return {"ok": False, "error": payload.get("error", "sync failed"), "transient": transient}
+    # On success (or when every event was gate-dropped) advance the cursor past
+    # `pending`, not only `outgoing`: gate-dropped events are handled locally
+    # and should not be re-scanned every sync.
+    last = pending[-1]
+    same_ts_ids = [event.get("event_id") for event in pending if event.get("timestamp") == last.get("timestamp")]
+    _save_sync_state(
+        target_path,
+        {
+            "last_synced_timestamp": last.get("timestamp"),
+            "last_synced_ids": same_ts_ids[-SYNC_RETENTION_IDS:],
+            "last_sync_response": payload,
+            "updated_at": _now(),
+        },
+    )
+    return {"ok": True, "ingested": len(outgoing), "dropped": dropped, **payload}
+
+
+def validate_event(event: dict) -> list[str]:
+    issues: list[str] = []
+    required = ["event_id", "timestamp", "project_id", "event_type", "agent", "model", "task", "context", "quality"]
+    for key in required:
+        if key not in event:
+            issues.append(f"missing:{key}")
+    if str(event.get("event_type") or "") not in SUPPORTED_EVENT_TYPES:
+        issues.append("invalid:event_type")
+    serialized = json.dumps(event, ensure_ascii=False)
+    if any(token in serialized.lower() for token in ("```", "def ", "class ", "function ", "raw_code", "source_code", "\"content\"")):
+        issues.append("privacy:source_like_content")
+    return issues
+
+
+def ingest_events(
+    root_dir: pathlib.Path,
+    events: list[dict],
+    *,
+    user_id: str,
+    plan: str,
+    device: str = "",
+    cli_version: str = "",
+) -> dict:
+    if plan not in {"pro", "team", "enterprise"}:
+        return {"ok": False, "error": "Experience sync requires Pro plan"}
+    ingested = 0
+    for raw_event in events:
+        event = dict(raw_event)
+        event["_submitted_at"] = _now()
+        event["_submitted_by"] = user_id
+        event["_plan"] = plan
+        if device:
+            event["_device"] = device[:32]
+        if cli_version:
+            event["_cli_version"] = cli_version
+        issues = validate_event(event)
+        if issues:
+            return {"ok": False, "error": "invalid events", "issues": issues}
+        project_id = str(event.get("project_id") or "unknown")
+        path = _server_event_path(project_id, str(event.get("timestamp") or _now()))
+        append_jsonl(path, event)
+        ingested += 1
+    return {"ok": True, "ingested": ingested}
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    target = _detect_target(args.target)
+    events = load_events(
+        target,
+        since=args.since,
+        agent=args.agent,
+        event_type=args.type,
+        result=args.result,
+        limit=args.limit,
+        include_archive=True,
+    )
+    if args.json:
+        print(json.dumps({"events": events, "total": len(events)}, indent=2, ensure_ascii=False))
+    else:
+        print(format_list(events, since=args.since))
+    return 0
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    stats = compute_stats(_detect_target(args.target), period=args.period, by=args.by)
+    if args.json:
+        print(json.dumps(stats, indent=2, ensure_ascii=False))
+    else:
+        print(format_stats(stats))
+    return 0
+
+
+def cmd_record_json(args: argparse.Namespace) -> int:
+    try:
+        payload = json.loads((args.payload or os.sys.stdin.read()).strip() or "{}")
+    except json.JSONDecodeError as exc:
+        print(f"invalid payload: {exc}")
+        return 1
+    event = record_event(_detect_target(args.target), payload)
+    if args.json:
+        print(json.dumps(event, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    result = sync_events(_detect_target(args.target), limit=args.limit)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    elif result.get("ok"):
+        print(f"synced {int(result.get('ingested', 0))} event(s)")
+    elif result.get("skipped"):
+        print(f"skipped: {result.get('reason')}")
+    else:
+        print(f"error: {result.get('error', 'sync failed')}")
+    return 0 if result.get("ok") or result.get("skipped") else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="0dai experience", description="Structured experience event pipeline.")
+    sub = parser.add_subparsers(dest="command")
+
+    list_parser = sub.add_parser("list")
+    list_parser.add_argument("--target", default=".")
+    list_parser.add_argument("--since", default="7d")
+    list_parser.add_argument("--agent", default="")
+    list_parser.add_argument("--type", default="")
+    list_parser.add_argument("--result", default="")
+    list_parser.add_argument("--limit", type=int, default=50)
+    list_parser.add_argument("--json", action="store_true")
+    list_parser.set_defaults(func=cmd_list)
+
+    stats_parser = sub.add_parser("stats")
+    stats_parser.add_argument("--target", default=".")
+    stats_parser.add_argument("--period", default="30d")
+    stats_parser.add_argument("--by", default="all", choices=["all", "agent", "model", "task_type"])
+    stats_parser.add_argument("--json", action="store_true")
+    stats_parser.set_defaults(func=cmd_stats)
+
+    record_parser = sub.add_parser("record-json")
+    record_parser.add_argument("--target", default=".")
+    record_parser.add_argument("--payload", default="")
+    record_parser.add_argument("--json", action="store_true")
+    record_parser.set_defaults(func=cmd_record_json)
+
+    sync_parser = sub.add_parser("sync")
+    sync_parser.add_argument("--target", default=".")
+    sync_parser.add_argument("--limit", type=int, default=SYNC_BATCH_LIMIT)
+    sync_parser.add_argument("--json", action="store_true")
+    sync_parser.set_defaults(func=cmd_sync)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", ""):
+        parser.print_help()
+        return 1
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())