wydcode 0.4.3

package/socra_harness/central_traces.py

@@ -0,0 +1,627 @@
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import fcntl
+import hashlib
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .job.events import JobEvent, read_events
+from .recurrence import (
+    normalize_repository,
+    select_exact_behavior,
+    sha256_json as recurrence_sha256_json,
+    task_instance_sha256,
+    validate_behavior_preference,
+    validate_gene_evidence,
+)
+
+
+TRACE_SCHEMA_VERSION = 1
+DEFAULT_TRACE_HOME = Path("~/.wydcode/traces")
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def trace_home() -> Path:
+    configured = os.environ.get("WYDCODE_TRACE_HOME")
+    return Path(configured or DEFAULT_TRACE_HOME).expanduser().resolve()
+
+
+def _git(project: Path, *args: str) -> str | None:
+    result = subprocess.run(
+        ["git", *args], cwd=project, text=True, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, check=False
+    )
+    return result.stdout.strip() if result.returncode == 0 and result.stdout.strip() else None
+
+
+def _sanitize_remote(remote: str | None) -> str | None:
+    if not remote:
+        return None
+    value = remote.strip()
+    if value.startswith("git@") and ":" in value:
+        host_path = value[4:].replace(":", "/", 1)
+        value = f"https://{host_path}"
+    elif "://" in value:
+        scheme, rest = value.split("://", 1)
+        if "@" in rest:
+            rest = rest.split("@", 1)[1]
+        value = f"{scheme.lower()}://{rest}"
+    return value.removesuffix(".git").rstrip("/")
+
+
+def project_identity(project: Path) -> dict[str, Any]:
+    remote = _sanitize_remote(_git(project, "remote", "get-url", "origin"))
+    root_commit = _git(project, "rev-list", "--max-parents=0", "HEAD")
+    head_commit = _git(project, "rev-parse", "HEAD")
+    identity_material = remote or f"local:{project.name}:{root_commit or 'unborn'}"
+    return {
+        "project_scope_id": hashlib.sha256(identity_material.encode("utf-8")).hexdigest(),
+        "repository": remote,
+        "repository_name": (remote.rsplit("/", 1)[-1] if remote else project.name),
+        "root_commit": root_commit,
+        "head_commit_at_promotion": head_commit,
+        "identity_source": "canonical_origin_remote" if remote else "local_name_and_root_commit",
+    }
+
+
+def _event_dict(event: JobEvent | dict[str, Any]) -> dict[str, Any]:
+    return event.to_json() if isinstance(event, JobEvent) else event
+
+
+def _latest(events: list[JobEvent], event_type: str, task_id: str | None = None) -> dict[str, Any] | None:
+    for event in reversed(events):
+        if event.type != event_type:
+            continue
+        if task_id is not None and str(event.payload.get("task_id")) != task_id:
+            continue
+        return _event_dict(event)
+    return None
+
+
+def build_promoted_trace(
+    project: Path,
+    job_dir: Path,
+    task: dict[str, Any],
+    events: list[JobEvent],
+    promotion_event: JobEvent,
+) -> dict[str, Any]:
+    task_id = str(task.get("id") or promotion_event.payload.get("task_id") or "")
+    receipt_rel = str(promotion_event.payload.get("receipt_path") or "")
+    receipt = json.loads((job_dir / receipt_rel).read_text(encoding="utf-8")) if receipt_rel else {}
+    changed_files = [
+        {
+            "path": str(item.get("path") or ""),
+            "new_sha256": item.get("new_sha256"),
+            "source_task_id": item.get("source_task_id"),
+        }
+        for item in receipt.get("applied") or []
+    ]
+    creator = _latest(events, "creator_output_received", task_id) or {}
+    task_passed = _latest(events, "task_passed", task_id) or {}
+    milestone = _latest(events, "milestone_runner_passed") or {}
+    review = _latest(events, "promotion_diff_presented", task_id) or {}
+    authorization = _latest(events, "promotion_human_authorized", task_id) or {}
+    behavior_binding = _latest(events, "promotion_behavior_preference_bound", task_id) or {}
+    retrieval = _latest(events, "retrieval_fired", task_id) or {}
+    identity = project_identity(project)
+    source_ref = {
+        "job_id": promotion_event.job_id,
+        "task_id": task_id,
+        "bundle_sha256": promotion_event.payload.get("bundle_sha256"),
+        "receipt_sha256": promotion_event.payload.get("receipt_sha256"),
+    }
+    trace = {
+        "trace_type": "validated_fix_promoted",
+        "dedupe_key": sha256_json({"project_scope_id": identity["project_scope_id"], **source_ref}),
+        "project": identity,
+        "source": {
+            **source_ref,
+            "local_promotion_event_seq": promotion_event.seq,
+            "local_promotion_event_id": promotion_event.event_id,
+        },
+        "task": {
+            "description": task.get("description"),
+            "acceptance": task.get("acceptance") or [],
+            "risk_tier": task.get("risk_tier"),
+            "declared_files": task.get("declared_files") or [],
+            "task_instance_sha256": task_instance_sha256(task),
+        },
+        "model_attempt": {
+            key: creator.get("payload", {}).get(key)
+            for key in [
+                "request_model",
+                "response_model",
+                "finish_reason",
+                "content_chars",
+                "reasoning_chars",
+                "creator_call_ms",
+                "usage",
+                "parser_repair_applied",
+            ]
+        },
+        "validation": {
+            "task_passed_event_seq": task_passed.get("seq"),
+            "review_level": task_passed.get("payload", {}).get("review_level"),
+            "milestone_event_seq": milestone.get("seq"),
+            "milestone_command": milestone.get("payload", {}).get("command"),
+            "milestone_returncode": milestone.get("payload", {}).get("returncode"),
+            "promotion_diff_event_seq": review.get("seq"),
+            "authorization_event_seq": authorization.get("seq"),
+            "authorization_sha256": authorization.get("payload", {}).get("authorization_sha256"),
+            "dry_run_diff_sha256": review.get("payload", {}).get("dry_run_diff_sha256"),
+            "bundle_sha256": promotion_event.payload.get("bundle_sha256"),
+            "apply_receipt_sha256": promotion_event.payload.get("receipt_sha256"),
+            "rollback_snapshot_sha256": promotion_event.payload.get("rollback_content_snapshot_sha256"),
+        },
+        "changed_files": changed_files,
+        "recurrence_fields": {
+            "owning_paths": [item["path"] for item in changed_files if item["path"]],
+            "symbol": None,
+            "visible_error_class": None,
+            "relation": "validated_fix_promoted",
+            "completeness": "partial_path_and_relation_only",
+            "policy": "unavailable fields are null; no semantic family is inferred during trace collection",
+        },
+        "privacy": {
+            "source_content_stored": False,
+            "patch_content_stored": False,
+            "absolute_paths_stored": False,
+        },
+    }
+    recurrence = task.get("recurrence") if isinstance(task.get("recurrence"), dict) else {}
+    preference = behavior_binding.get("payload", {}).get("preference")
+    binding_payload = behavior_binding.get("payload", {})
+    admission_errors: list[str] = []
+    validated_preference = None
+    validated_evidence = None
+    if behavior_binding:
+        try:
+            validated_preference = validate_behavior_preference(preference)
+        except ValueError as exc:
+            admission_errors.append(f"invalid_behavior:{exc}")
+        raw_evidence = binding_payload.get("heldout_evidence")
+        if isinstance(raw_evidence, dict):
+            evidence_fields = {
+                key: raw_evidence.get(key)
+                for key in ("status", "probe_sha256", "hidden_feedback_used", "description")
+            }
+            try:
+                validated_evidence = validate_gene_evidence(evidence_fields)
+            except ValueError as exc:
+                admission_errors.append(f"invalid_heldout_evidence:{exc}")
+        else:
+            admission_errors.append("heldout_evidence_missing")
+        if recurrence.get("status") != "assignable":
+            admission_errors.append("recurrence_key_unassignable")
+        if binding_payload.get("bundle_sha256") != promotion_event.payload.get("bundle_sha256"):
+            admission_errors.append("behavior_bundle_mismatch")
+        if validated_preference and binding_payload.get("preference_sha256") != recurrence_sha256_json(validated_preference):
+            admission_errors.append("behavior_hash_mismatch")
+        if not task_passed:
+            admission_errors.append("task_gate_missing")
+        if not milestone:
+            admission_errors.append("full_suite_milestone_missing")
+        elif task_passed and not (task_passed.get("seq", 0) < milestone.get("seq", 0) < promotion_event.seq):
+            admission_errors.append("full_suite_temporal_order_invalid")
+        if not authorization:
+            admission_errors.append("human_authorization_missing")
+        elif not (behavior_binding.get("seq", 0) < authorization.get("seq", 0) < promotion_event.seq):
+            admission_errors.append("behavior_authorization_temporal_order_invalid")
+        try:
+            repository = identity.get("repository")
+            if not repository or normalize_repository(repository) != recurrence.get("recurrence_key", {}).get("canonical_repository_identity"):
+                admission_errors.append("project_identity_mismatch")
+        except ValueError:
+            admission_errors.append("project_identity_unassignable")
+        trace["behavior_gene_admission"] = {
+            "status": "admitted" if not admission_errors else "abstained",
+            "errors": admission_errors,
+        }
+    if behavior_binding and not admission_errors and validated_preference and validated_evidence:
+        preference_sha256 = recurrence_sha256_json(validated_preference)
+        trace["behavior_gene"] = {
+            "gene_id": (
+                f"project-fix::{identity['project_scope_id']}::"
+                f"{recurrence['recurrence_key_sha256']}::v1"
+            ),
+            "brp_type": "PREFER",
+            "project_scope_id": identity["project_scope_id"],
+            "recurrence_key": recurrence.get("recurrence_key"),
+            "recurrence_key_sha256": recurrence.get("recurrence_key_sha256"),
+            "preference": validated_preference,
+            "preference_sha256": preference_sha256,
+            "source_task_instance_sha256": task_instance_sha256(task),
+            "provenance": {
+                "source_job_id": promotion_event.job_id,
+                "source_task_id": task_id,
+                "promotion_event_seq": promotion_event.seq,
+                "bundle_sha256": promotion_event.payload.get("bundle_sha256"),
+                "authorization_sha256": authorization.get("payload", {}).get("authorization_sha256"),
+                "behavior_binding_sha256": behavior_binding.get("payload", {}).get("preference_sha256"),
+                "focused_gate_event_seq": task_passed.get("seq"),
+                "full_suite_event_seq": milestone.get("seq"),
+                "heldout_probe_sha256": validated_evidence.get("probe_sha256"),
+                "heldout_evidence_artifact_sha256": binding_payload.get("heldout_evidence", {}).get("artifact_sha256"),
+            },
+            "lifecycle": {"state": "probationary", "validated_reuse_count": 0, "requires_n_star": 3},
+            "privacy": {"contains_patch_or_source": False},
+        }
+    if retrieval:
+        trace["retrieval_attribution"] = {
+            "fired": True,
+            "local_event_seq": retrieval.get("seq"),
+            "local_event_sha256": recurrence_sha256_json(retrieval),
+            "source_central_event_sha256": retrieval.get("payload", {}).get("source_central_event_sha256"),
+            "gene_id": retrieval.get("payload", {}).get("gene_id"),
+            "recurrence_key_sha256": retrieval.get("payload", {}).get("recurrence_key_sha256"),
+            "preference_sha256": retrieval.get("payload", {}).get("preference_sha256"),
+            "classification": "retrieval_backed_promotion_not_paired_capability_lift",
+        }
+    return trace
+
+
+def build_failed_trace(
+    project: Path,
+    task: dict[str, Any],
+    events: list[JobEvent],
+    failed_event: JobEvent,
+) -> dict[str, Any]:
+    task_id = str(task.get("id") or failed_event.payload.get("task_id") or "")
+    creator = None
+    for event in reversed(events):
+        if event.seq >= failed_event.seq:
+            continue
+        if event.type == "creator_output_received" and str(event.payload.get("task_id")) == task_id:
+            creator = event.to_json()
+            break
+    identity = project_identity(project)
+    failure_class = failed_event.payload.get("failure_class") or failed_event.payload.get("error") or "task_failed"
+    source_ref = {
+        "job_id": failed_event.job_id,
+        "task_id": task_id,
+        "local_failure_event_seq": failed_event.seq,
+        "failure_class": failure_class,
+    }
+    return {
+        "trace_type": "fix_attempt_rejected",
+        "dedupe_key": sha256_json({"project_scope_id": identity["project_scope_id"], **source_ref}),
+        "project": identity,
+        "source": {**source_ref, "local_failure_event_id": failed_event.event_id},
+        "task": {
+            "description": task.get("description"),
+            "acceptance": task.get("acceptance") or [],
+            "risk_tier": task.get("risk_tier"),
+            "declared_files": task.get("declared_files") or [],
+        },
+        "model_attempt": {
+            key: (creator or {}).get("payload", {}).get(key)
+            for key in [
+                "request_model",
+                "response_model",
+                "finish_reason",
+                "content_chars",
+                "reasoning_chars",
+                "creator_call_ms",
+                "usage",
+                "parser_repair_applied",
+            ]
+        },
+        "failure": {
+            "class": failure_class,
+            "error": failed_event.payload.get("error"),
+            "reason": failed_event.payload.get("reason"),
+            "reviewer_name": failed_event.payload.get("reviewer_name"),
+            "attempt": failed_event.payload.get("attempt"),
+            "finish_reason": failed_event.payload.get("finish_reason"),
+            "task_wall_ms": failed_event.payload.get("task_wall_ms"),
+            "creator_call_ms": failed_event.payload.get("creator_call_ms"),
+            "bundle_sha256": failed_event.payload.get("bundle_sha256"),
+            "dry_run_diff_sha256": failed_event.payload.get("dry_run_diff_sha256"),
+            "presentation_event_seq": failed_event.payload.get("presentation_event_seq"),
+        },
+        "recurrence_fields": {
+            "owning_paths": task.get("declared_files") or [],
+            "symbol": None,
+            "visible_error_class": failure_class,
+            "relation": "fix_attempt_rejected",
+            "completeness": "partial_path_error_and_relation",
+            "policy": "unavailable fields are null; no semantic family is inferred during trace collection",
+        },
+        "privacy": {
+            "source_content_stored": False,
+            "patch_content_stored": False,
+            "absolute_paths_stored": False,
+        },
+    }
+def read_central_events(home: Path | None = None) -> list[dict[str, Any]]:
+    path = (home or trace_home()) / "events.jsonl"
+    if not path.exists():
+        return []
+    result: list[dict[str, Any]] = []
+    previous_hash = None
+    for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        event = json.loads(line)
+        supplied_hash = event.pop("event_sha256", None)
+        actual_hash = sha256_json(event)
+        if supplied_hash != actual_hash:
+            raise RuntimeError(f"central_trace_hash_mismatch at line {line_no}")
+        if event.get("previous_event_sha256") != previous_hash:
+            raise RuntimeError(f"central_trace_chain_mismatch at line {line_no}")
+        event["event_sha256"] = supplied_hash
+        result.append(event)
+        previous_hash = supplied_hash
+    return result
+
+
+def retrieve_validated_behavior(
+    project: Path, task: dict[str, Any], home: Path | None = None
+) -> dict[str, Any]:
+    identity = project_identity(project)
+    result = select_exact_behavior(read_central_events(home), identity["project_scope_id"], task)
+    return {**result, "project_scope_id": identity["project_scope_id"]}
+
+
+def append_central_trace(trace: dict[str, Any], home: Path | None = None) -> tuple[dict[str, Any], bool]:
+    root = home or trace_home()
+    root.mkdir(parents=True, exist_ok=True)
+    ledger = root / "events.jsonl"
+    lock_path = root / ".lock"
+    with lock_path.open("a+", encoding="utf-8") as lock:
+        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        events = read_central_events(root)
+        for event in events:
+            if event.get("payload", {}).get("dedupe_key") == trace.get("dedupe_key"):
+                return event, False
+        seq = len(events) + 1
+        event = {
+            "schema_version": TRACE_SCHEMA_VERSION,
+            "seq": seq,
+            "event_id": f"trace-{seq:08d}",
+            "timestamp": dt.datetime.now(dt.timezone.utc).isoformat(),
+            "type": str(trace.get("trace_type") or "trace_recorded"),
+            "previous_event_sha256": events[-1]["event_sha256"] if events else None,
+            "payload": trace,
+        }
+        event["event_sha256"] = sha256_json(event)
+        with ledger.open("a", encoding="utf-8") as handle:
+            handle.write(canonical_json(event) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        return event, True
+
+
+def index_trace_with_mumpix(event: dict[str, Any], home: Path | None = None) -> dict[str, Any]:
+    root = home or trace_home()
+    index_receipts = root / "mumpix-indexed.jsonl"
+    with (root / ".mumpix.lock").open("a+", encoding="utf-8") as lock:
+        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        indexed_hashes: set[str] = set()
+        if index_receipts.exists():
+            for line in index_receipts.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    indexed_hashes.add(str(json.loads(line).get("central_event_sha256") or ""))
+        if event["event_sha256"] in indexed_hashes:
+            return {"ok": True, "already_indexed": True}
+        bridge = Path(__file__).with_name("mumpix_trace_bridge.cjs")
+        result = subprocess.run(
+            ["node", str(bridge), str(root / "traces.mumpix")],
+            input=json.dumps(event),
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        if result.returncode != 0:
+            return {"ok": False, "error": (result.stderr or result.stdout).strip()[:1000], "returncode": result.returncode}
+        try:
+            payload = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            payload = {"ok": False, "error": "mumpix_bridge_invalid_json"}
+        if payload.get("ok"):
+            receipt = {
+                "central_event_sha256": event["event_sha256"],
+                "record_id": payload.get("record_id"),
+                "indexed_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+            }
+            with index_receipts.open("a", encoding="utf-8") as handle:
+                handle.write(canonical_json(receipt) + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+        return payload
+
+
+def export_promoted_trace(
+    project: Path,
+    job_dir: Path,
+    task: dict[str, Any],
+    events: list[JobEvent],
+    promotion_event: JobEvent,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    trace = build_promoted_trace(project, job_dir, task, events, promotion_event)
+    event, appended = append_central_trace(trace, home)
+    index_result = index_trace_with_mumpix(event, home)
+    return {
+        "ok": bool(index_result.get("ok")),
+        "ledger_ok": True,
+        "index_ok": bool(index_result.get("ok")),
+        "central_event_id": event["event_id"],
+        "central_event_seq": event["seq"],
+        "central_event_sha256": event["event_sha256"],
+        "deduplicated": not appended,
+        "mumpix_index": index_result,
+    }
+
+
+def export_failed_trace(
+    project: Path,
+    task: dict[str, Any],
+    events: list[JobEvent],
+    failed_event: JobEvent,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    trace = build_failed_trace(project, task, events, failed_event)
+    event, appended = append_central_trace(trace, home)
+    index_result = index_trace_with_mumpix(event, home)
+    return {
+        "ok": bool(index_result.get("ok")),
+        "ledger_ok": True,
+        "index_ok": bool(index_result.get("ok")),
+        "central_event_id": event["event_id"],
+        "central_event_seq": event["seq"],
+        "central_event_sha256": event["event_sha256"],
+        "deduplicated": not appended,
+        "mumpix_index": index_result,
+    }
+
+
+def sync_job_traces(project: Path, job_dir: Path, home: Path | None = None) -> dict[str, int]:
+    events = read_events(job_dir / "events.jsonl")
+    plan_path = job_dir / "plan.json"
+    plan = json.loads(plan_path.read_text(encoding="utf-8")) if plan_path.exists() else {"tasks": []}
+    tasks = {str(item.get("id")): item for item in plan.get("tasks") or []}
+    result = {"exported": 0, "deduplicated": 0, "index_failed": 0}
+    for event in events:
+        task_id = str(event.payload.get("task_id") or "")
+        task = tasks.get(task_id, {"id": task_id})
+        if event.type == "promotion_applied":
+            exported = export_promoted_trace(project, job_dir, task, events, event, home)
+        elif event.type in {"task_failed", "promotion_human_rejected"}:
+            exported = export_failed_trace(project, task, events, event, home)
+        else:
+            continue
+        if exported.get("deduplicated"):
+            result["deduplicated"] += 1
+        else:
+            result["exported"] += 1
+        if not exported.get("index_ok"):
+            result["index_failed"] += 1
+    return result
+
+
+def indexed_event_hashes(home: Path | None = None) -> set[str]:
+    path = (home or trace_home()) / "mumpix-indexed.jsonl"
+    if not path.exists():
+        return set()
+    hashes: set[str] = set()
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            hashes.add(str(json.loads(line).get("central_event_sha256") or ""))
+    return hashes
+
+
+def retry_pending_index_events(home: Path | None = None) -> dict[str, Any]:
+    root = home or trace_home()
+    events = read_central_events(root)
+    indexed = indexed_event_hashes(root)
+    pending = [event for event in events if event["event_sha256"] not in indexed]
+    result: dict[str, Any] = {
+        "pending_before": len(pending),
+        "indexed": 0,
+        "failed": 0,
+        "errors": [],
+    }
+    for event in pending:
+        indexed_result = index_trace_with_mumpix(event, root)
+        if indexed_result.get("ok"):
+            result["indexed"] += 1
+            continue
+        result["failed"] += 1
+        result["errors"].append(
+            {
+                "event_id": event.get("event_id"),
+                "event_sha256": event.get("event_sha256"),
+                "error": indexed_result.get("error") or "mumpix_index_failed",
+                "returncode": indexed_result.get("returncode"),
+            }
+        )
+    final_indexed = indexed_event_hashes(root)
+    result["pending_after"] = sum(event["event_sha256"] not in final_indexed for event in events)
+    return result
+
+
+def traces_status_main(args: argparse.Namespace) -> int:
+    root = trace_home()
+    events = read_central_events(root)
+    indexed_hashes = indexed_event_hashes(root)
+    pending_index_count = sum(event["event_sha256"] not in indexed_hashes for event in events)
+    projects = {event.get("payload", {}).get("project", {}).get("project_scope_id") for event in events}
+    payload = {
+        "schema_version": TRACE_SCHEMA_VERSION,
+        "trace_home": str(root),
+        "ledger": str(root / "events.jsonl"),
+        "event_count": len(events),
+        "validated_promotions": sum(event.get("type") == "validated_fix_promoted" for event in events),
+        "rejected_attempts": sum(event.get("type") == "fix_attempt_rejected" for event in events),
+        "retrieval_ready_genes": sum(
+            isinstance(event.get("payload", {}).get("behavior_gene"), dict) for event in events
+        ),
+        "retrieval_backed_promotions": sum(
+            bool(event.get("payload", {}).get("retrieval_attribution", {}).get("fired")) for event in events
+        ),
+        "project_count": len(projects - {None}),
+        "chain_head_sha256": events[-1]["event_sha256"] if events else None,
+        "mumpix_index_exists": (root / "traces.mumpix").exists(),
+        "indexed_event_count": len(events) - pending_index_count,
+        "pending_index_count": pending_index_count,
+        "index_complete": pending_index_count == 0,
+    }
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"Trace home: {payload['trace_home']}")
+        print(f"Validated promotions: {payload['validated_promotions']}")
+        print(f"Rejected attempts: {payload['rejected_attempts']}")
+        print(f"Retrieval-ready genes: {payload['retrieval_ready_genes']}")
+        print(f"Retrieval-backed promotions: {payload['retrieval_backed_promotions']}")
+        print(f"Projects: {payload['project_count']}")
+        print(f"Chain head: {payload['chain_head_sha256'] or 'none'}")
+        print(f"Mumpix index: {'ready' if payload['mumpix_index_exists'] else 'not built'}")
+        print(f"Indexed events: {payload['indexed_event_count']}/{payload['event_count']}")
+        print(f"Pending index: {payload['pending_index_count']}")
+    return 2 if pending_index_count else 0
+
+
+def traces_sync_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    jobs = project / ".socra" / "jobs"
+    exported = deduplicated = failed = 0
+    pending_result = retry_pending_index_events()
+    print(
+        "Central index retry: "
+        f"{pending_result['indexed']} indexed, {pending_result['failed']} failed, "
+        f"{pending_result['pending_after']} pending"
+    )
+    for error in pending_result["errors"]:
+        print(
+            "Central index failed for "
+            f"{error['event_id']} ({str(error['event_sha256'])[:12]}): {error['error']}"
+        )
+    if jobs.exists():
+        for event_path in sorted(jobs.glob("*/events.jsonl")):
+            try:
+                result = sync_job_traces(project, event_path.parent)
+                exported += result["exported"]
+                deduplicated += result["deduplicated"]
+                failed += result["index_failed"]
+            except Exception as exc:  # noqa: BLE001 - all failures are counted and surfaced.
+                failed += 1
+                print(f"Trace sync failed for {event_path.parent.name}: {exc}")
+    print(f"Trace sync: {exported} exported, {deduplicated} already present, {failed} failed")
+    final_events = read_central_events()
+    final_indexed = indexed_event_hashes()
+    pending_after = sum(event["event_sha256"] not in final_indexed for event in final_events)
+    return 2 if failed or pending_result["failed"] or pending_after else 0