wydcode 0.4.3

package/socra_harness/cli.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import argparse
+import os
+import os
+from pathlib import Path
+
+from .eval.humaneval import humaneval_main
+from .init import init_main
+from .job.manager import (
+    job_configure_creator_main,
+    job_exam_dayjs_main,
+    job_plan_main,
+    job_promote_main,
+    job_resume_main,
+    job_review_promotion_main,
+    job_reverify_task_main,
+    job_run_milestone_main,
+    job_run_next_main,
+    job_start_main,
+)
+from .product import approve_main, fix_main, promote_main, reject_main, review_main, status_main
+from .scan.repo import scan_main
+from .serve.local_proxy import serve_main
+from .start import start_main
+from .tui.app import tui_main
+from .central_traces import traces_status_main, traces_sync_main
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog=os.environ.get("SOCRA_CLI_NAME", "wydcode"))
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    init = sub.add_parser("init", help="Initialize Socra config in a git repository")
+    init.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to initialize")
+    init.add_argument("--endpoint", default=None, help="OpenAI-compatible endpoint, defaults to SOCRA_ENDPOINT or http://127.0.0.1:11439/v1")
+    init.add_argument("--model", default=None, help="Model name to record, defaults to SOCRA_MODEL when set")
+    init.add_argument("--context-budget", type=int, default=8192)
+    init.add_argument("--max-output", type=int, default=8192)
+    init.add_argument("--skip-endpoint-probe", action="store_true")
+    init.add_argument("--force", action="store_true", help="Overwrite an existing .socra/config.json")
+    init.set_defaults(func=init_main)
+
+    status = sub.add_parser("status", help="Show initialized config and latest durable job state")
+    status.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to inspect")
+    status.set_defaults(func=status_main)
+
+    fix = sub.add_parser("fix", help="Create a durable fix job from .socra/config.json")
+    fix.add_argument("goal")
+    fix.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to work on")
+    fix.add_argument("--job-id", default=None)
+    fix.add_argument("--declared-file", action="append", default=[], help="Source file the first Creator attempt may edit; repeat for up to two files")
+    fix.add_argument("--recurrence-card", type=Path, default=None, help="Structured exact-recurrence card; missing or incomplete cards abstain")
+    fix.add_argument("--retrieval", choices=("exact", "disabled"), default="exact", help="Use exact-key retrieval or run the paired cold control")
+    fix.add_argument("--plan-only", action="store_true", help="Create the durable job without requiring a live model endpoint")
+    fix.set_defaults(func=fix_main)
+
+    review = sub.add_parser("review", help="Present the latest passed fix diff and record the presented artifact hashes")
+    review.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to inspect")
+    review.add_argument("--job-id", default=None)
+    review.add_argument("--task-id", default=None)
+    review.add_argument("--reviewer-name", default=None)
+    review.add_argument("--notes", default="")
+    review.set_defaults(func=review_main)
+
+    approve = sub.add_parser("approve", help="Authorize the previously presented promotion diff")
+    approve.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to approve")
+    approve.add_argument("--job-id", default=None)
+    approve.add_argument("--task-id", default=None)
+    approve.add_argument("--reviewer-name", default=None)
+    approve.add_argument("--notes", default="")
+    approve.add_argument("--behavior-card", type=Path, default=None, help="Reviewer-authored PREFER behavior to bind to a validated promotion")
+    approve.add_argument("--heldout-evidence", type=Path, default=None, help="Passing held-out evidence card required when minting behavior")
+    approve.set_defaults(func=approve_main)
+
+    reject = sub.add_parser("reject", help="Reject the previously presented promotion diff and export the failed attempt trace")
+    reject.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository containing the staged fix")
+    reject.add_argument("--job-id", default=None)
+    reject.add_argument("--task-id", default=None)
+    reject.add_argument("--reviewer-name", default=None)
+    reject.add_argument("--reason", required=True, help="Human-readable technical reason for rejecting the presented diff")
+    reject.add_argument("--notes", default="")
+    reject.set_defaults(func=reject_main)
+
+    promote = sub.add_parser("promote", help="Apply the approved promotion bundle to the real tree")
+    promote.add_argument("--project", type=Path, default=Path.cwd(), help="Git repository to promote into")
+    promote.add_argument("--job-id", default=None)
+    promote.add_argument("--task-id", default=None)
+    promote.add_argument("--preflight", action="store_true", help="Check authorization and bundle hashes without writing source")
+    promote.set_defaults(func=promote_main)
+
+    traces = sub.add_parser("traces", help="Inspect or repair the cross-project validated-fix trace store")
+    traces_sub = traces.add_subparsers(dest="traces_cmd", required=True)
+    traces_status = traces_sub.add_parser("status", help="Show global trace counts and hash-chain head")
+    traces_status.add_argument("--json", action="store_true")
+    traces_status.set_defaults(func=traces_status_main)
+    traces_sync = traces_sub.add_parser("sync", help="Backfill promoted fixes from this repository's local job logs")
+    traces_sync.add_argument("--project", type=Path, default=Path.cwd())
+    traces_sync.set_defaults(func=traces_sync_main)
+
+    start = sub.add_parser("start", help="Pick a model and project, then start a Socra vibe-coding session")
+    start.add_argument("--model", type=Path, default=None)
+    start.add_argument("--model-dir", action="append", default=[])
+    start.add_argument("--project", type=Path, default=None)
+    start.add_argument("--alias", default=None)
+    start.add_argument("--llama-server", type=Path, default=Path("llama-server"))
+    start.add_argument("--port", type=int, default=11439)
+    start.add_argument("--backend-port", type=int, default=11440)
+    start.add_argument("--ctx-size", type=int, default=8192)
+    start.add_argument("--gpu-layers", type=int, default=999)
+    start.add_argument("--no-scan", action="store_true")
+    start.add_argument("--no-ui", action="store_true", help="Do not open the terminal UI; block in server mode instead")
+    start.add_argument("--ui-refresh", type=float, default=1.0)
+    start.add_argument("--allow-sandbox-network", action="store_true", help="Allow agent-requested network commands inside .socra/run-sandbox only")
+    start.add_argument("--allow-sandbox-installs", action="store_true", help="Allow agent-requested install commands inside .socra/run-sandbox only")
+    start.set_defaults(func=start_main)
+
+    job = sub.add_parser("job", help="Manage durable long-running Socra jobs")
+    job_sub = job.add_subparsers(dest="job_cmd", required=True)
+    job_start = job_sub.add_parser("start", help="Create a durable job plan and event log without executing agents")
+    job_start.add_argument("goal")
+    job_start.add_argument("--project", type=Path, default=Path.cwd())
+    job_start.add_argument("--job-id", default=None)
+    job_start.set_defaults(func=job_start_main)
+
+    job_resume = job_sub.add_parser("resume", help="Replay events and resume an incomplete durable job")
+    job_resume.add_argument("--project", type=Path, default=Path.cwd())
+    job_resume.add_argument("--job-id", default=None)
+    job_resume.set_defaults(func=job_resume_main)
+
+    job_plan = job_sub.add_parser("plan", help="Emit planner task_added events and commit a hashed task DAG")
+    job_plan.add_argument("--project", type=Path, default=Path.cwd())
+    job_plan.add_argument("--job-id", default=None)
+    job_plan.add_argument("--force", action="store_true", help="Append a revised plan even when a plan is already committed")
+    job_plan.add_argument("--reason", default=None, help="Reason to record when --force appends a revised plan")
+    job_plan.set_defaults(func=job_plan_main)
+
+    job_creator = job_sub.add_parser("configure-creator", help="Pin Creator model/backend settings into the job event log")
+    job_creator.add_argument("--project", type=Path, default=Path.cwd())
+    job_creator.add_argument("--job-id", default=None)
+    job_creator.add_argument("--model-alias", default="Socra-14B-Coder")
+    job_creator.add_argument("--model", default="Socra-14B-Coder.gguf")
+    job_creator.add_argument("--expected-served-model-id", default=None)
+    job_creator.add_argument("--endpoint", default="http://127.0.0.1:11439/v1")
+    job_creator.add_argument("--backend", default="local-openai-compatible")
+    job_creator.add_argument("--temperature", type=float, default=0.7)
+    job_creator.add_argument("--seed", type=int, default=None)
+    job_creator.add_argument("--context-budget-tokens", type=int, default=8192)
+    job_creator.add_argument("--max-output-tokens", type=int, default=32768)
+    job_creator.add_argument("--hosted-fallback", action="store_true")
+    job_creator.add_argument("--notes", default=None)
+    job_creator.set_defaults(func=job_configure_creator_main)
+
+    job_exam_dayjs = job_sub.add_parser("exam-dayjs", help="Create a provenance-pinned dayjs ground-truth exam job")
+    job_exam_dayjs.add_argument("candidate", help="Candidate exam id, e.g. E1 or dayjs-2369-duration-zero-getter")
+    job_exam_dayjs.add_argument("--project", type=Path, default=Path.cwd(), help="Clean dayjs checkout at the candidate pre-fix parent")
+    job_exam_dayjs.add_argument("--job-id", default=None)
+    job_exam_dayjs.add_argument("--pack", type=Path, default=None, help="Path to dayjs_exam_set_v1.json")
+    job_exam_dayjs.add_argument("--prediction", default=None, help="Override the preregistered prediction recorded for this candidate")
+    job_exam_dayjs.add_argument("--prediction-notes", default="")
+    job_exam_dayjs.add_argument("--allow-checkout-mismatch", action="store_true", help="Record the job even if HEAD does not match the candidate pre-fix parent")
+    job_exam_dayjs.set_defaults(func=job_exam_dayjs_main)
+
+    job_run = job_sub.add_parser("run-next", help="Run the next ready task through the durable job event protocol")
+    job_run.add_argument("--project", type=Path, default=Path.cwd())
+    job_run.add_argument("--job-id", default=None)
+    job_run.add_argument("--task-id", default=None)
+    job_run.add_argument("--allow-unimplemented", action="store_true")
+    job_run.set_defaults(func=job_run_next_main)
+
+    job_reverify = job_sub.add_parser("reverify-task", help="Upgrade a smoke-reviewed task with criterion-level evidence")
+    job_reverify.add_argument("--project", type=Path, default=Path.cwd())
+    job_reverify.add_argument("--job-id", default=None)
+    job_reverify.add_argument("--task-id", required=True)
+    job_reverify.add_argument("--evidence", type=Path, required=True)
+    job_reverify.add_argument("--notes", default="")
+    job_reverify.add_argument("--allow-unpassed", action="store_true")
+    job_reverify.set_defaults(func=job_reverify_task_main)
+
+    job_milestone = job_sub.add_parser("run-milestone", help="Run a milestone gate against a sandbox overlay of passed task artifacts")
+    job_milestone.add_argument("--project", type=Path, default=Path.cwd())
+    job_milestone.add_argument("--job-id", default=None)
+    job_milestone.add_argument("--milestone-id", default=None)
+    job_milestone.add_argument("--command", default="npm run build")
+    job_milestone.add_argument("--timeout-seconds", type=int, default=120)
+    job_milestone.add_argument("--prepare-deps", choices=["none", "npm-ci", "npm-install"], default="none")
+    job_milestone.add_argument("--deps-timeout-seconds", type=int, default=300)
+    job_milestone.add_argument("--allow-partial-smoke", action="store_true", help="Run the command even when partial-smoke tasks still require explicit re-verification")
+    job_milestone.add_argument("--promotion-grade", action="store_true", help="Treat this milestone as promotion-grade; high/critical dependency vulnerabilities block it")
+    job_milestone.set_defaults(func=job_run_milestone_main)
+
+    job_review_promotion = job_sub.add_parser("review-promotion", help="Present a promotion diff and record human authorization")
+    job_review_promotion.add_argument("--project", type=Path, default=Path.cwd())
+    job_review_promotion.add_argument("--job-id", default=None)
+    job_review_promotion.add_argument("--task-id", default="task-045")
+    job_review_promotion.add_argument("--reviewer-name", required=True)
+    job_review_promotion.add_argument("--present-diff", action="store_true", help="Render the exact dry-run diff to stdout and record promotion_diff_presented; run separately before authorization")
+    job_review_promotion.add_argument("--approve-source-promotion", action="store_true", help="Human reviewer approves this dry-run bundle for real project promotion")
+    job_review_promotion.add_argument("--attest-reviewed", action="store_true", help="Record a self-attestation that the human reviewed the presented diff")
+    job_review_promotion.add_argument("--notes", default="")
+    job_review_promotion.set_defaults(func=job_review_promotion_main)
+
+    job_promote = job_sub.add_parser("promote", help="Preflight or execute a promotion bundle after human authorization")
+    job_promote.add_argument("--project", type=Path, default=Path.cwd())
+    job_promote.add_argument("--job-id", default=None)
+    job_promote.add_argument("--task-id", default="task-045")
+    job_promote.add_argument("--execute", action="store_true", help="Apply the approved bundle with preimage checks, rollback snapshot, and post-write hash verification")
+    job_promote.set_defaults(func=job_promote_main)
+
+    eval_parser = sub.add_parser("eval", help="Run benchmark harnesses")
+    eval_sub = eval_parser.add_subparsers(dest="benchmark", required=True)
+    he = eval_sub.add_parser("humaneval", help="Run HumanEval against any GGUF")
+    he.add_argument("--model", type=Path, required=True)
+    he.add_argument("--name", default="model")
+    he.add_argument("--llama-cli", type=Path, default=Path("llama-cli"))
+    he.add_argument("--tasks", type=Path, required=True)
+    he.add_argument("--out", type=Path, default=Path(".socra/humaneval"))
+    he.add_argument("--report", type=Path, default=Path(".socra/humaneval/report.md"))
+    he.add_argument("--mode", choices=["raw-full-function", "socra"], default="socra")
+    he.add_argument("--limit", type=int, default=0)
+    he.add_argument("--n-predict", type=int, default=384)
+    he.add_argument("--temp", type=float, default=0.1)
+    he.add_argument("--timeout", type=int, default=10)
+    he.add_argument("--ctx-size", type=int, default=2048)
+    he.add_argument("--gpu-layers", type=int, default=None)
+    he.add_argument("--batch-size", type=int, default=128)
+    he.add_argument("--ubatch-size", type=int, default=64)
+    he.add_argument("--cache-type-k", default="q8_0")
+    he.add_argument("--cache-type-v", default="q8_0")
+    he.add_argument("--cache-ram-mb", type=int, default=2048)
+    he.add_argument("--no-cpu-fallback", action="store_true")
+    he.add_argument("--event-log", type=Path, default=Path(".socra/events.jsonl"))
+    he.set_defaults(func=humaneval_main)
+
+    serve = sub.add_parser("serve", help="Run local OpenAI-compatible GGUF proxy")
+    serve.add_argument("--model", type=Path, required=True)
+    serve.add_argument("--alias", default=None, help="Model name exposed through the Socra endpoint")
+    serve.add_argument("--llama-server", type=Path, default=Path("llama-server"))
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=11439)
+    serve.add_argument("--backend-host", default="127.0.0.1")
+    serve.add_argument("--backend-port", type=int, default=11440)
+    serve.add_argument("--ctx-size", type=int, default=8192)
+    serve.add_argument("--gpu-layers", type=int, default=999)
+    serve.add_argument("--reuse-backend", action="store_true", help="Do not start llama-server; proxy an already-running local backend")
+    serve.add_argument("--event-log", type=Path, default=Path(".socra/events.jsonl"))
+    serve.set_defaults(func=serve_main)
+
+    scan = sub.add_parser("scan", help="Scan a repo for repeatable Socra candidates")
+    scan.add_argument("folder", type=Path)
+    scan.add_argument("--out", type=Path, default=Path(".socra/candidates.json"))
+    scan.add_argument("--event-log", type=Path, default=Path(".socra/events.jsonl"))
+    scan.set_defaults(func=scan_main)
+
+    tui = sub.add_parser("tui", help="Terminal dashboard")
+    tui.add_argument("--state-dir", type=Path, default=Path(".socra"))
+    tui.add_argument("--refresh", type=float, default=1.0)
+    tui.set_defaults(func=tui_main)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/socra_harness/eval/__init__.py

@@ -0,0 +1 @@
+

package/socra_harness/eval/humaneval.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import ast
+import json
+import os
+import re
+import subprocess
+import tempfile
+import textwrap
+import time
+from pathlib import Path
+from typing import Any
+
+from ..events import EventLog
+
+
+STOP_MARKERS = [
+    "\nclass ",
+    "\ndef ",
+    "\nif __name__",
+    "\n# Tests",
+    "\nassert ",
+    "\nprint(",
+    "\ncheck(",
+]
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
+
+
+def run(cmd: list[str], timeout: int, cwd: Path | None = None, env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, text=True, capture_output=True, timeout=timeout, cwd=str(cwd) if cwd else None, env=env)
+
+
+def generation_cmd(args: Any, prompt: str, cpu_only: bool) -> list[str]:
+    cmd = [
+        str(args.llama_cli),
+        "-m",
+        str(args.model),
+        "--single-turn",
+        "--reasoning",
+        "off",
+        "--no-display-prompt",
+        "--no-show-timings",
+        "--simple-io",
+        "-p",
+        prompt,
+        "-n",
+        str(args.n_predict),
+        "--temp",
+        str(args.temp),
+        "--ctx-size",
+        str(args.ctx_size),
+        "--batch-size",
+        str(args.batch_size),
+        "--ubatch-size",
+        str(args.ubatch_size),
+    ]
+    if cpu_only:
+        cmd.extend(["--device", "none", "--gpu-layers", "0", "--no-op-offload"])
+    elif args.gpu_layers is not None:
+        cmd.extend(["--gpu-layers", str(args.gpu_layers)])
+    if args.cache_type_k:
+        cmd.extend(["--cache-type-k", args.cache_type_k])
+    if args.cache_type_v:
+        cmd.extend(["--cache-type-v", args.cache_type_v])
+    if args.cache_ram_mb is not None:
+        cmd.extend(["--cache-ram", str(args.cache_ram_mb)])
+    return cmd
+
+
+def generate(args: Any, prompt: str, raw_path: Path) -> tuple[str, float, str]:
+    start = time.time()
+    proc = run(generation_cmd(args, prompt, cpu_only=False), timeout=240)
+    mode = "gpu"
+    first_failure = proc
+    if not args.no_cpu_fallback and proc.returncode != 0 and (
+        "ggml_metal_init" in proc.stderr
+        or "failed to create command queue" in proc.stderr
+        or "failed to allocate context" in proc.stderr
+    ):
+        proc = run(generation_cmd(args, prompt, cpu_only=True), timeout=360)
+        mode = "cpu_fallback"
+    elapsed = time.time() - start
+    raw_path.write_text(
+        f"--- MODE ---\n{mode}\n"
+        f"--- STDOUT ---\n{proc.stdout}\n"
+        f"--- STDERR ---\n{proc.stderr}"
+        + (
+            ""
+            if first_failure is proc
+            else f"\n--- FIRST_FAILURE_STDOUT ---\n{first_failure.stdout}\n"
+            f"--- FIRST_FAILURE_STDERR ---\n{first_failure.stderr}"
+        )
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"generation failed with code {proc.returncode}: {proc.stderr[-1200:]}")
+    return proc.stdout, elapsed, mode
+
+
+def build_prompt(task: dict[str, Any], mode: str) -> str:
+    if mode == "raw-full-function":
+        return "\n".join(
+            [
+                "Write a complete, valid Python function that satisfies the docstring and examples.",
+                "Return only one Python function definition.",
+                "Do not include Markdown fences, explanations, tests, or extra text.",
+                "",
+                task["prompt"],
+            ]
+        )
+    return "\n".join(
+        [
+            "Complete the following Python function.",
+            "Return only the code that should be appended after the prompt.",
+            "Do not include Markdown fences, explanations, tests, or the original prompt.",
+            "",
+            task["prompt"],
+        ]
+    )
+
+
+def strip_llama_cli_scaffold(raw: str) -> str:
+    out = raw.replace("\r\n", "\n")
+    fence = re.search(r"```(?:python)?\s*([\s\S]*?)```", out, re.I)
+    fenced = bool(fence)
+    if fence:
+        out = fence.group(1)
+    out = re.sub(r"^.*?>\s*", "", out, count=1, flags=re.S) if not fenced and "\n>" in raw[:2000] else out
+    out = re.sub(r"(?is)<think>.*?</think>", "", out)
+    out = out.replace("<|endoftext|>", "").replace("Exiting...", "")
+    skip_prefixes = (
+        "Loading model",
+        "build      :",
+        "model      :",
+        "modalities :",
+        "available commands:",
+        "/exit",
+        "/regen",
+        "/clear",
+        "/read",
+        "/glob",
+    )
+    lines = []
+    for line in out.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            lines.append(line)
+            continue
+        if any(stripped.startswith(prefix) for prefix in skip_prefixes):
+            continue
+        if "▄▄ ▄▄" in stripped or "██ ██" in stripped or "▀▀" in stripped:
+            continue
+        lines.append(line)
+    return "\n".join(lines).strip("\n")
+
+
+def trim_at_stop_markers(out: str) -> str:
+    for marker in STOP_MARKERS:
+        index = out.find(marker)
+        if index >= 0:
+            return out[:index]
+    return out
+
+
+def strip_leading_docstring_closer(out: str) -> str:
+    lines = out.strip("\n").splitlines()
+    while lines and lines[0].strip() in {'"""', "'''"}:
+        lines = lines[1:]
+    return "\n".join(lines).strip("\n")
+
+
+def reindent_function_body(out: str) -> str:
+    lines = [("    " + line if line.strip() else line) for line in out.strip("\n").splitlines()]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def remove_extra_prompt_indent(out: str) -> str:
+    lines = out.strip("\n").splitlines()
+    indents = [len(line) - len(line.lstrip(" ")) for line in lines if line.strip()]
+    positive = [indent for indent in indents if indent > 0]
+    if not indents or indents[0] != 0 or not positive:
+        return out
+    shift = min(positive)
+    shifted = []
+    for line in lines:
+        indent = len(line) - len(line.lstrip(" "))
+        shifted.append(line[min(indent, shift):] if indent > 0 else line)
+    return "\n".join(shifted).strip("\n")
+
+
+def shift_left(out: str, spaces: int) -> str:
+    shifted = []
+    for line in out.strip("\n").splitlines():
+        indent = len(line) - len(line.lstrip(" "))
+        shifted.append(line[min(indent, spaces):] if indent else line)
+    return "\n".join(shifted).strip("\n")
+
+
+def append_body_ast_score(prompt: str, candidate: str) -> int | None:
+    try:
+        tree = ast.parse(prompt.rstrip() + "\n" + candidate)
+    except SyntaxError:
+        return None
+    return sum(1 for _ in ast.walk(tree))
+
+
+def normalize_append_body(out: str, prompt: str) -> tuple[str, str]:
+    stripped = strip_leading_docstring_closer(out)
+    if not stripped.strip():
+        return stripped, "empty"
+    indents = [len(line) - len(line.lstrip(" ")) for line in stripped.splitlines() if line.strip()]
+    positive = [indent for indent in indents if indent > 0]
+    shift_values = sorted(set([0] + positive[:1] + ([min(positive)] if positive else [])))
+    bases = [
+        stripped.strip("\n"),
+        textwrap.dedent(stripped).strip("\n"),
+        textwrap.dedent(remove_extra_prompt_indent(stripped)).strip("\n"),
+    ]
+    bases.extend(textwrap.dedent(shift_left(stripped, shift)).strip("\n") for shift in shift_values)
+    candidates = []
+    seen = set()
+    for base in bases:
+        candidate = reindent_function_body(base)
+        if candidate not in seen:
+            candidates.append(candidate)
+            seen.add(candidate)
+    scored = [
+        (score, index, candidate)
+        for index, candidate in enumerate(candidates)
+        if (score := append_body_ast_score(prompt, candidate)) is not None
+    ]
+    if scored:
+        _score, index, candidate = max(scored, key=lambda item: (item[0], -item[1]))
+        return candidate, f"syntax_repair_variant_{index}"
+    return (candidates[0] if candidates else stripped.rstrip() + "\n"), "syntax_unverified"
+
+
+def clean_completion(raw: str, prompt: str, entry_point: str, mode: str) -> tuple[str, str]:
+    out = strip_llama_cli_scaffold(raw)
+    if mode == "raw-full-function":
+        full_defs = list(re.finditer(rf"(?m)^def\s+{re.escape(entry_point)}\s*\(", out))
+        if full_defs:
+            out = out[full_defs[-1].start():]
+            return trim_at_stop_markers(out).rstrip() + "\n", "full_function_extract"
+    if prompt and prompt in out:
+        out = out.split(prompt, 1)[-1]
+    prompt_tail = prompt.strip().splitlines()[-1] if prompt.strip() else ""
+    if prompt_tail and prompt_tail in out:
+        out = out.split(prompt_tail, 1)[-1]
+    if "(truncated)" in out:
+        out = out.split("(truncated)", 1)[-1]
+    out = trim_at_stop_markers(out)
+    full_defs = list(re.finditer(rf"(?m)^def\s+{re.escape(entry_point)}\s*\(", out))
+    if full_defs:
+        return out[full_defs[-1].start():].rstrip() + "\n", "full_function_extract"
+    while True:
+        stripped = out.lstrip("\n")
+        first = stripped.splitlines()[0].strip() if stripped.splitlines() else ""
+        if first.startswith((">>>", ">>")) or first in {"True", "False"} or re.fullmatch(r"[-+]?\d+(?:\.\d+)?", first or ""):
+            out = "\n".join(stripped.splitlines()[1:])
+            continue
+        break
+    if mode == "socra":
+        return normalize_append_body(out, prompt)
+    return out.rstrip() + "\n", "raw_extract"
+
+
+def candidate_source(task: dict[str, Any], completion: str) -> str:
+    entry = task["entry_point"]
+    if re.search(rf"(?m)^def\s+{re.escape(entry)}\s*\(", completion):
+        imports = "\n".join(
+            line for line in task["prompt"].splitlines()
+            if re.match(r"^\s*(?:from\s+\S+\s+import\s+.+|import\s+.+)\s*$", line)
+        )
+        return (imports.rstrip() + "\n\n" if imports.strip() else "") + completion
+    return task["prompt"].rstrip() + "\n" + completion
+
+
+def sandbox_env(tmpdir: Path) -> dict[str, str]:
+    return {
+        "HOME": str(tmpdir),
+        "TMPDIR": str(tmpdir),
+        "PYTHONDONTWRITEBYTECODE": "1",
+        "PATH": os.environ.get("PATH", ""),
+    }
+
+
+def evaluate(task: dict[str, Any], completion: str, tmpdir: Path, timeout: int) -> tuple[bool, str]:
+    source = candidate_source(task, completion)
+    test = "\n".join([source, "", task["test"], "", f"check({task['entry_point']})", ""])
+    path = tmpdir / f"{task['task_id'].replace('/', '_')}.py"
+    path.write_text(test)
+    proc = run(["python3", str(path)], timeout=timeout, cwd=tmpdir, env=sandbox_env(tmpdir))
+    return proc.returncode == 0, (proc.stdout + proc.stderr)[-4000:]
+
+
+def markdown(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    lines = [
+        "# Socra Harness HumanEval Run",
+        "",
+        f"Model: `{report['model_name']}`",
+        f"Mode: `{report['mode']}`",
+        f"Task file: `{report['task_file']}`",
+        f"Task count: `{report['task_count']}`",
+        "",
+        "| Passed | Pass@1 | GPU generations | CPU fallback |",
+        "| ---: | ---: | ---: | ---: |",
+        f"| {summary['passed']}/{summary['total']} | {summary['pass_at_1']:.4f} | {summary['gpu_generations']} | {summary['cpu_fallback_generations']} |",
+        "",
+        "## Failures",
+        "",
+    ]
+    failed = [row["task_id"] for row in report["results"] if not row["passed"]]
+    lines.extend([f"- `{task}`" for task in failed] or ["- none"])
+    return "\n".join(lines) + "\n"
+
+
+def humaneval_main(args: Any) -> int:
+    args.out.mkdir(parents=True, exist_ok=True)
+    args.report.parent.mkdir(parents=True, exist_ok=True)
+    events = EventLog(args.event_log)
+    tasks = read_jsonl(args.tasks)
+    if args.limit:
+        tasks = tasks[: args.limit]
+    rows = []
+    events.emit("eval_start", benchmark="humaneval", model=args.name, mode=args.mode, total=len(tasks))
+    with tempfile.TemporaryDirectory(prefix=f"socra-humaneval-{args.name}-") as td:
+        tmpdir = Path(td)
+        for index, task in enumerate(tasks, start=1):
+            safe_id = task["task_id"].replace("/", "_")
+            print(f"[{args.name}] {index}/{len(tasks)} {task['task_id']}", flush=True)
+            raw_path = args.out / f"{args.name}-{safe_id}.raw.txt"
+            completion_path = args.out / f"{args.name}-{safe_id}.completion.py"
+            started = time.time()
+            try:
+                raw, gen_seconds, generation_mode = generate(args, build_prompt(task, args.mode), raw_path)
+                completion, repair = clean_completion(raw, task["prompt"], task["entry_point"], args.mode)
+                completion_path.write_text(completion)
+                passed, detail = evaluate(task, completion, tmpdir, args.timeout)
+            except Exception as exc:
+                gen_seconds = time.time() - started
+                generation_mode = "error"
+                repair = "error"
+                completion_path.write_text("")
+                passed = False
+                detail = repr(exc)
+            row = {
+                "model": args.name,
+                "task_id": task["task_id"],
+                "entry_point": task["entry_point"],
+                "passed": passed,
+                "generation_mode": generation_mode,
+                "repair": repair,
+                "gen_seconds": round(gen_seconds, 3),
+                "completion_path": str(completion_path),
+                "raw_path": str(raw_path),
+                "detail": detail,
+            }
+            rows.append(row)
+            events.emit("eval_task", index=index, total=len(tasks), task_id=task["task_id"], passed=passed, repair=repair)
+    passed = sum(1 for row in rows if row["passed"])
+    summary = {
+        "passed": passed,
+        "total": len(rows),
+        "pass_at_1": passed / len(rows) if rows else 0,
+        "gpu_generations": sum(1 for row in rows if row["generation_mode"] == "gpu"),
+        "cpu_fallback_generations": sum(1 for row in rows if row["generation_mode"] == "cpu_fallback"),
+    }
+    report = {
+        "benchmark": "HumanEval",
+        "mode": args.mode,
+        "model_name": args.name,
+        "model_path": str(args.model),
+        "task_file": str(args.tasks),
+        "task_count": len(rows),
+        "summary": summary,
+        "results": rows,
+    }
+    (args.out / "results.json").write_text(json.dumps(report, indent=2, sort_keys=True) + "\n")
+    args.report.write_text(markdown(report))
+    events.emit("eval_complete", benchmark="humaneval", model=args.name, mode=args.mode, **summary)
+    print(json.dumps(summary, indent=2, sort_keys=True))
+    print(f"Results: {args.out / 'results.json'}")
+    print(f"Report: {args.report}")
+    return 0