wydcode 0.4.3

package/socra_harness/recurrence.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import posixpath
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+IDENTIFIER_RE = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$.#:\-/]*$")
+SPACE_RE = re.compile(r"\s+")
+LINE_COLUMN_RE = re.compile(r":\d+(?::\d+)?$")
+FORBIDDEN_BEHAVIOR_MARKERS = ("```", "@@ ", "=>", "{", "}", ";")
+MAX_BEHAVIOR_CHARS = 2400
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
+
+
+def sha256_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("ascii")).hexdigest()
+
+
+def normalize_repository(value: object) -> str:
+    text = str(value or "").strip()
+    text = re.sub(r"^(?:https?://|ssh://git@|git@)", "", text, flags=re.I)
+    text = text.replace(":", "/", 1) if text.lower().startswith("github.com:") else text
+    text = text.rstrip("/")
+    if text.endswith(".git"):
+        text = text[:-4]
+    text = text.lower()
+    match = re.fullmatch(r"github\.com/([^/]+)/([^/]+)", text)
+    if not match:
+        raise ValueError("repository_identity must be github.com/<owner>/<repo>")
+    return f"github.com/{match.group(1)}/{match.group(2)}"
+
+
+def normalize_path(value: object) -> str:
+    text = str(value or "").strip().replace("\\", "/")
+    text = LINE_COLUMN_RE.sub("", text)
+    if not text or text.startswith("/") or re.match(r"^[A-Za-z]:/", text):
+        raise ValueError("owning_path must be a non-empty repository-relative path")
+    normalized = posixpath.normpath(text)
+    if normalized in (".", "..") or normalized.startswith("../"):
+        raise ValueError("owning_path escapes repository root")
+    if any(part in ("", ".", "..") for part in PurePosixPath(normalized).parts):
+        raise ValueError("owning_path is not canonical")
+    return normalized
+
+
+def normalize_symbol(value: object) -> str:
+    text = str(value or "").strip()
+    if not text or not IDENTIFIER_RE.fullmatch(text):
+        raise ValueError("owning_symbol_or_api must be one exact identifier")
+    return text
+
+
+def normalize_invariant_part(value: object, field: str) -> str:
+    text = SPACE_RE.sub(" ", str(value or "").strip().lower())
+    if not text:
+        raise ValueError(f"invariant.{field} is required")
+    if any(char in text for char in "\r\n\t"):
+        raise ValueError(f"invariant.{field} contains control whitespace")
+    return text
+
+
+def compile_recurrence_card(card: object) -> dict[str, Any]:
+    if not isinstance(card, dict):
+        return {"status": "recurrence_key_unassignable", "reason": "card_not_object"}
+    card_id = str(card.get("card_id") or "").strip()
+    if not card_id:
+        return {"status": "recurrence_key_unassignable", "reason": "card_id_missing"}
+    try:
+        invariant = card.get("invariant")
+        if not isinstance(invariant, dict):
+            raise ValueError("invariant must be a structured object")
+        key = {
+            "canonical_repository_identity": normalize_repository(card.get("repository_identity")),
+            "repository_relative_owning_production_path": normalize_path(card.get("owning_path")),
+            "owning_production_symbol_or_exported_api": normalize_symbol(card.get("owning_symbol_or_api")),
+            "normalized_violated_invariant_signature": {
+                "error_or_assertion_class": normalize_invariant_part(
+                    invariant.get("error_or_assertion_class"), "error_or_assertion_class"
+                ),
+                "operation": normalize_invariant_part(invariant.get("operation"), "operation"),
+                "expected_relation": normalize_invariant_part(
+                    invariant.get("expected_relation"), "expected_relation"
+                ),
+            },
+        }
+    except ValueError as error:
+        return {"card_id": card_id, "status": "recurrence_key_unassignable", "reason": str(error)}
+    return {
+        "card_id": card_id,
+        "status": "assignable",
+        "recurrence_key": key,
+        "recurrence_key_sha256": sha256_json(key),
+        "compiler": "exact_recurrence_normalization_v1",
+    }
+
+
+def load_recurrence_card(path: Path) -> dict[str, Any]:
+    result = compile_recurrence_card(json.loads(path.read_text(encoding="utf-8")))
+    if result.get("status") != "assignable":
+        raise ValueError(str(result.get("reason") or "recurrence_key_unassignable"))
+    return result
+
+
+def validate_behavior_preference(value: object) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("behavior card must be a JSON object")
+    allowed = {"approach", "invariants_to_preserve", "checks_to_run", "known_nonmatches"}
+    if set(value) - allowed:
+        raise ValueError(f"behavior card has unknown fields: {sorted(set(value) - allowed)}")
+    approach = str(value.get("approach") or "").strip()
+    if not approach:
+        raise ValueError("behavior approach is required")
+    result: dict[str, Any] = {"approach": approach}
+    for field in ("invariants_to_preserve", "checks_to_run", "known_nonmatches"):
+        items = value.get(field)
+        if not isinstance(items, list) or not items or not all(isinstance(item, str) and item.strip() for item in items):
+            raise ValueError(f"behavior {field} must be a non-empty string list")
+        result[field] = [item.strip() for item in items]
+    strings = [approach, *result["invariants_to_preserve"], *result["checks_to_run"], *result["known_nonmatches"]]
+    for text in strings:
+        if "\n" in text or "\r" in text:
+            raise ValueError("behavior entries must be single-line prose")
+        if text.startswith(("+", "-")) or any(marker in text for marker in FORBIDDEN_BEHAVIOR_MARKERS):
+            raise ValueError("behavior card appears to contain source or patch text")
+    rendered = canonical_json(result)
+    if len(rendered) > MAX_BEHAVIOR_CHARS:
+        raise ValueError(f"behavior card exceeds {MAX_BEHAVIOR_CHARS} characters")
+    return result
+
+
+def load_behavior_preference(path: Path) -> dict[str, Any]:
+    return validate_behavior_preference(json.loads(path.read_text(encoding="utf-8")))
+
+
+def behavior_overlaps_patch(preference: dict[str, Any], patch_text: str) -> bool:
+    haystack = SPACE_RE.sub(" ", patch_text).lower()
+    strings = [
+        preference["approach"],
+        *preference["invariants_to_preserve"],
+        *preference["checks_to_run"],
+        *preference["known_nonmatches"],
+    ]
+    return any(len(text) >= 20 and SPACE_RE.sub(" ", text).lower() in haystack for text in strings)
+
+
+def validate_gene_evidence(value: object) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("gene evidence must be a JSON object")
+    allowed = {"status", "probe_sha256", "hidden_feedback_used", "description"}
+    if set(value) - allowed:
+        raise ValueError(f"gene evidence has unknown fields: {sorted(set(value) - allowed)}")
+    if value.get("status") != "passed":
+        raise ValueError("gene evidence status must be passed")
+    probe_sha256 = str(value.get("probe_sha256") or "").lower()
+    if not SHA256_RE.fullmatch(probe_sha256):
+        raise ValueError("gene evidence probe_sha256 must be 64 lowercase hex characters")
+    if value.get("hidden_feedback_used") is not False:
+        raise ValueError("gene evidence hidden_feedback_used must be false")
+    description = str(value.get("description") or "").strip()
+    if len(description) > 500 or "\n" in description or "\r" in description:
+        raise ValueError("gene evidence description must be at most 500 single-line characters")
+    return {
+        "status": "passed",
+        "probe_sha256": probe_sha256,
+        "hidden_feedback_used": False,
+        "description": description,
+    }
+
+
+def load_gene_evidence(path: Path) -> dict[str, Any]:
+    raw = path.read_bytes()
+    evidence = validate_gene_evidence(json.loads(raw.decode("utf-8")))
+    return {**evidence, "artifact_sha256": hashlib.sha256(raw).hexdigest()}
+
+
+def task_instance_sha256(task: dict[str, Any]) -> str:
+    return sha256_json(
+        {
+            "description": task.get("description"),
+            "acceptance": task.get("acceptance") or [],
+            "declared_files": task.get("declared_files") or [],
+        }
+    )
+
+
+def injection_budget_decision(
+    context_budget_tokens: int,
+    reserved_output_tokens: int,
+    base_input_tokens_estimate: int,
+    injection_tokens_estimate: int,
+    safety_margin_tokens: int = 256,
+) -> dict[str, Any]:
+    available = (
+        context_budget_tokens
+        - reserved_output_tokens
+        - base_input_tokens_estimate
+        - safety_margin_tokens
+    )
+    return {
+        "fits": available >= injection_tokens_estimate,
+        "available_injection_tokens": available,
+        "safety_margin_tokens": safety_margin_tokens,
+    }
+
+
+def select_exact_behavior(
+    central_events: list[dict[str, Any]], project_scope_id: str, task: dict[str, Any]
+) -> dict[str, Any]:
+    recurrence = task.get("recurrence") if isinstance(task.get("recurrence"), dict) else {}
+    key_sha = str(recurrence.get("recurrence_key_sha256") or "")
+    target_key = recurrence.get("recurrence_key")
+    if recurrence.get("status") != "assignable" or not key_sha:
+        return {"status": "recurrence_key_unassignable", "fired": False}
+    target_instance = task_instance_sha256(task)
+    matches: list[dict[str, Any]] = []
+    exact_replays = 0
+    for event in central_events:
+        if event.get("type") != "validated_fix_promoted":
+            continue
+        payload = event.get("payload") if isinstance(event.get("payload"), dict) else {}
+        gene = payload.get("behavior_gene") if isinstance(payload.get("behavior_gene"), dict) else None
+        if not gene:
+            continue
+        if gene.get("project_scope_id") != project_scope_id or gene.get("recurrence_key_sha256") != key_sha:
+            continue
+        if gene.get("recurrence_key") != target_key:
+            continue
+        if gene.get("privacy", {}).get("contains_patch_or_source") is not False:
+            continue
+        try:
+            preference = validate_behavior_preference(gene.get("preference"))
+        except ValueError:
+            continue
+        if gene.get("preference_sha256") != sha256_json(preference):
+            continue
+        if gene.get("source_task_instance_sha256") == target_instance:
+            exact_replays += 1
+            continue
+        matches.append({"event": event, "gene": gene})
+    if len(matches) > 1:
+        return {"status": "recurrence_key_collision_abstain", "fired": False, "match_count": len(matches)}
+    if not matches:
+        return {
+            "status": "exact_instance_replay_abstain" if exact_replays else "exact_recurrence_miss",
+            "fired": False,
+            "match_count": 0,
+        }
+    selected = matches[0]
+    return {
+        "status": "exact_recurrence_match",
+        "fired": True,
+        "match_count": 1,
+        "source_central_event_sha256": selected["event"].get("event_sha256"),
+        "gene": selected["gene"],
+    }

package/socra_harness/scan/__init__.py

@@ -0,0 +1 @@
+

package/socra_harness/scan/repo.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from ..events import EventLog
+
+
+SOURCE_EXTS = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".swift", ".go", ".rs", ".java", ".kt", ".m", ".mm",
+    ".css", ".scss", ".json", ".yaml", ".yml", ".toml",
+}
+SKIP_PARTS = {"node_modules", ".git", "dist", "build", ".next", "DerivedData", "__pycache__", "vendor"}
+
+
+def family_for(path: Path, text: str) -> str:
+    name = path.name.lower()
+    suffix = path.suffix.lower()
+    if suffix in {".tsx", ".jsx", ".swift"} and ("view" in name or "component" in text.lower() or "struct " in text):
+        return "ui_component"
+    if "route" in name or "/api/" in str(path).lower():
+        return "api_or_route_handler"
+    if suffix in {".json", ".yaml", ".yml", ".toml"}:
+        return "config"
+    if "test" in name or "spec" in name:
+        return "test"
+    return "source"
+
+
+def shape_key(family: str, rel: str, text: str) -> str:
+    lines = [line.strip() for line in text.splitlines() if line.strip() and not line.strip().startswith("//")]
+    skeleton = "\n".join(lines[:80])
+    digest = hashlib.sha256((family + "\n" + skeleton).encode("utf-8", "ignore")).hexdigest()[:24]
+    return f"fsm-{digest}"
+
+
+def scan_main(args: Any) -> int:
+    root = args.folder.resolve()
+    events = EventLog(args.event_log)
+    groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    source_count = 0
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in SKIP_PARTS for part in path.parts):
+            continue
+        if path.suffix.lower() not in SOURCE_EXTS:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        source_count += 1
+        rel = str(path.relative_to(root))
+        family = family_for(path, text)
+        key = shape_key(family, rel, text)
+        groups[family].append({"path": rel, "shape_key": key, "bytes": len(text.encode("utf-8", "ignore"))})
+    candidates = []
+    for family, files in groups.items():
+        if len(files) < 2:
+            continue
+        total_bytes = sum(item["bytes"] for item in files)
+        candidates.append({
+            "family": family,
+            "file_count": len(files),
+            "score_estimate": len(files) * 10 + min(total_bytes // 1024, 100),
+            "evidence": "static_estimate",
+            "shape_keys": sorted({item["shape_key"] for item in files})[:8],
+            "samples": files[:8],
+        })
+    candidates.sort(key=lambda item: item["score_estimate"], reverse=True)
+    payload = {
+        "folder": str(root),
+        "source_files": source_count,
+        "candidate_count": len(candidates),
+        "candidates": candidates,
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+    events.emit("scan_complete", folder=str(root), source_files=source_count, candidate_count=len(candidates))
+    print(json.dumps({"source_files": source_count, "candidate_count": len(candidates), "out": str(args.out)}, indent=2))
+    return 0

package/socra_harness/serve/__init__.py

@@ -0,0 +1 @@
+

package/socra_harness/serve/local_proxy.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import json
+import re
+import signal
+import subprocess
+import threading
+import time
+import urllib.error
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+from ..events import EventLog
+
+
+LOOPBACK = {"127.0.0.1", "localhost", "::1"}
+
+HARNESS_SYSTEM_PROMPT = """You are running behind Socra Harness.
+For coding work, prefer direct, complete, editable code.
+Do not include hidden reasoning.
+When asked for code, return clean code or a concise patch-oriented answer.
+Avoid Markdown fences unless the user explicitly asks for them."""
+
+
+def post_json(url: str, payload: dict[str, Any], timeout: int = 600) -> tuple[int, dict[str, str], bytes]:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, dict(res.headers), res.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, dict(exc.headers), exc.read()
+
+
+def get_bytes(url: str, timeout: int = 30) -> tuple[int, dict[str, str], bytes]:
+    req = urllib.request.Request(url, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, dict(res.headers), res.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, dict(exc.headers), exc.read()
+    except urllib.error.URLError as exc:
+        payload = {"error": {"code": 503, "message": str(exc), "type": "backend_unavailable"}}
+        return 503, {"Content-Type": "application/json"}, json.dumps(payload).encode("utf-8")
+
+
+def split_reasoning_text(text: str) -> tuple[str, str]:
+    parts: list[str] = []
+
+    def collect(match: re.Match[str]) -> str:
+        parts.append(match.group(1).strip())
+        return ""
+
+    text = re.sub(r"(?is)<think>(.*?)</think>", collect, text)
+    text = re.sub(r"(?is)<reasoning>(.*?)</reasoning>", collect, text)
+    return text.strip(), "\n\n".join(part for part in parts if part)
+
+
+def strip_reasoning_text(text: str) -> str:
+    cleaned, _reasoning = split_reasoning_text(text)
+    return cleaned
+
+
+def clean_code_wrappers(text: str) -> tuple[str, str]:
+    stripped, reasoning = split_reasoning_text(text)
+    fence = re.fullmatch(r"\s*```(?:\w+)?\s*([\s\S]*?)```\s*", stripped)
+    if fence:
+        return fence.group(1).strip("\n"), reasoning
+    return stripped, reasoning
+
+
+def apply_socra_response_harness(body: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+    changed = False
+    for choice in body.get("choices", []):
+        message = choice.get("message")
+        if not isinstance(message, dict):
+            continue
+        content = message.get("content")
+        if isinstance(content, str):
+            cleaned, extracted_reasoning = clean_code_wrappers(content)
+            if cleaned != content:
+                message["content"] = cleaned
+                changed = True
+            if extracted_reasoning and not isinstance(message.get("reasoning_content"), str):
+                message["reasoning_content"] = extracted_reasoning
+                changed = True
+        reasoning = message.get("reasoning_content")
+        if isinstance(reasoning, str) and not reasoning.strip():
+            message.pop("reasoning_content", None)
+            changed = True
+    return body, changed
+
+
+def apply_socra_request_harness(body: dict[str, Any], model_alias: str) -> tuple[dict[str, Any], bool]:
+    patched = dict(body)
+    patched["model"] = model_alias
+    messages = list(patched.get("messages") or [])
+    has_system = any(message.get("role") == "system" for message in messages if isinstance(message, dict))
+    if not has_system:
+        messages.insert(0, {"role": "system", "content": HARNESS_SYSTEM_PROMPT})
+    patched["messages"] = messages
+    return patched, patched != body
+
+
+class SocraProxyHandler(BaseHTTPRequestHandler):
+    server: "SocraProxyServer"
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        return
+
+    def write_json(self, status: int, payload: dict[str, Any]) -> None:
+        data = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("X-Socra-Harness", "active")
+        self.end_headers()
+        self.wfile.write(data)
+
+    def read_json(self) -> dict[str, Any]:
+        length = int(self.headers.get("Content-Length", "0"))
+        raw = self.rfile.read(length) if length else b"{}"
+        return json.loads(raw.decode("utf-8") or "{}")
+
+    def do_GET(self) -> None:
+        if self.path == "/health":
+            self.write_json(200, {"status": "ready", "backend": self.server.backend_url, "model": self.server.model_alias})
+            return
+        if self.path == "/runtime/stats":
+            self.write_json(200, self.server.metrics)
+            return
+        if self.path == "/v1/models":
+            status, _headers, data = get_bytes(f"{self.server.backend_url}/v1/models")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("X-Socra-Harness", "active")
+            self.end_headers()
+            self.wfile.write(data)
+            return
+        self.write_json(404, {"error": "not found"})
+
+    def do_POST(self) -> None:
+        if self.path != "/v1/chat/completions":
+            self.write_json(404, {"error": "not found"})
+            return
+        body = self.read_json()
+        stream = bool(body.get("stream"))
+        patched, request_changed = apply_socra_request_harness(body, self.server.model_alias)
+        self.server.metrics["chat_requests_total"] += 1
+        if request_changed:
+            self.server.metrics["request_harness_applied_total"] += 1
+        self.server.events.emit("chat_request", stream=stream, request_harness=request_changed)
+
+        if stream:
+            status, headers, data = post_json(f"{self.server.backend_url}/v1/chat/completions", patched)
+            self.send_response(status)
+            self.send_header("Content-Type", headers.get("Content-Type", "text/event-stream"))
+            self.send_header("X-Socra-Harness", "active")
+            self.send_header("X-Socra-Mode", "stream_passthrough")
+            self.end_headers()
+            self.wfile.write(data)
+            self.server.metrics["stream_passthrough_total"] += 1
+            return
+
+        status, _headers, data = post_json(f"{self.server.backend_url}/v1/chat/completions", patched)
+        try:
+            payload = json.loads(data.decode("utf-8"))
+        except json.JSONDecodeError:
+            self.send_response(status)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("X-Socra-Harness", "active")
+            self.end_headers()
+            self.wfile.write(data)
+            return
+        payload, response_changed = apply_socra_response_harness(payload)
+        if response_changed:
+            self.server.metrics["response_harness_applied_total"] += 1
+        self.server.events.emit("chat_response", status=status, response_harness=response_changed)
+        self.write_json(status, payload)
+
+
+class SocraProxyServer(ThreadingHTTPServer):
+    def __init__(self, addr: tuple[str, int], backend_url: str, model_alias: str, events: EventLog):
+        super().__init__(addr, SocraProxyHandler)
+        self.backend_url = backend_url.rstrip("/")
+        self.model_alias = model_alias
+        self.events = events
+        self.metrics = {
+            "local_first_enforced": True,
+            "hosted_fallback_total": 0,
+            "external_code_requests_total": 0,
+            "chat_requests_total": 0,
+            "request_harness_applied_total": 0,
+            "response_harness_applied_total": 0,
+            "stream_passthrough_total": 0,
+        }
+
+
+def wait_for_backend(url: str, timeout_seconds: int = 120) -> bool:
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        try:
+            status, _headers, _data = get_bytes(f"{url}/v1/models", timeout=5)
+            if status < 500:
+                return True
+        except Exception:
+            pass
+        time.sleep(1)
+    return False
+
+
+def serve_main(args: Any) -> int:
+    if args.host not in LOOPBACK:
+        raise SystemExit("Socra Harness is local-first: --host must be loopback")
+    if args.backend_host not in LOOPBACK:
+        raise SystemExit("Socra Harness is local-first: --backend-host must be loopback")
+
+    events = EventLog(args.event_log)
+    state_dir = args.event_log.parent
+    state_dir.mkdir(parents=True, exist_ok=True)
+    model_alias = args.alias or Path(args.model).stem
+    backend_url = f"http://{args.backend_host}:{args.backend_port}"
+    frontend_url = f"http://{args.host}:{args.port}"
+
+    state = {
+        "model": str(args.model),
+        "model_alias": model_alias,
+        "llama_server": str(args.llama_server),
+        "host": args.host,
+        "port": args.port,
+        "endpoint": f"{frontend_url}/v1",
+        "backend_endpoint": f"{backend_url}/v1",
+        "local_first": True,
+        "hosted_fallback": False,
+        "harness": "socra_request_response",
+    }
+    (state_dir / "server-state.json").write_text(json.dumps(state, indent=2) + "\n")
+    events.emit("server_start", **state)
+
+    backend = None
+    if not getattr(args, "reuse_backend", False):
+        cmd = [
+            str(args.llama_server),
+            "-m",
+            str(args.model),
+            "--host",
+            args.backend_host,
+            "--port",
+            str(args.backend_port),
+            "--ctx-size",
+            str(args.ctx_size),
+            "--gpu-layers",
+            str(args.gpu_layers),
+        ]
+        print("Starting backend llama-server:")
+        print(" ".join(cmd))
+        backend = subprocess.Popen(cmd)
+    else:
+        print(f"Reusing existing backend llama-server at {backend_url}")
+
+    def stop_backend(*_: Any) -> None:
+        if backend is not None and backend.poll() is None:
+            backend.terminate()
+
+    signal.signal(signal.SIGINT, stop_backend)
+    signal.signal(signal.SIGTERM, stop_backend)
+
+    if not wait_for_backend(backend_url):
+        stop_backend()
+        raise SystemExit(f"backend did not become ready: {backend_url}")
+
+    print(f"Socra Harness endpoint: {frontend_url}/v1")
+    print("Use this endpoint for Codex/vibe coding tools. Press Ctrl+C to stop.")
+    server = SocraProxyServer((args.host, args.port), backend_url, model_alias, events)
+    try:
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        if backend is None:
+            while True:
+                time.sleep(0.5)
+        while backend.poll() is None:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()
+        stop_backend()
+        if backend is not None:
+            backend.wait(timeout=10)
+        events.emit("server_stop", model=model_alias)
+    return 0