wydcode 0.4.3

package/socra_harness/tui/app.py

@@ -0,0 +1,1114 @@
+from __future__ import annotations
+
+import curses
+import datetime as dt
+import json
+import os
+import re
+import shlex
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+from ..events import read_events
+
+
+MAX_AGENT_LOOP_PASSES = 3
+
+
+CHAT_SYSTEM_PROMPT = """You are Socra Harness, a local-first coding partner.
+The user is vibe coding inside the selected project folder.
+
+Rules:
+- Use the project context and scanned candidates when helpful.
+- Keep answers concise and practical.
+- Do not include hidden reasoning.
+- For normal questions, answer normally.
+- When the user asks you to create or modify project files, return ONLY this JSON:
+  {"message":"short summary","files":[{"path":"relative/project/path","content":"complete file content"}]}
+- File paths must be relative to the project root. Never use absolute paths or .. segments.
+- Include complete file contents, not patches, for every file you want Socra to write.
+- If the user asks for a website, include at least index.html and any CSS/JS files it needs.
+- If sandbox network/install access is enabled and you need to download a repo,
+  fetch software, or install dependencies, include commands in the same JSON:
+  {"commands":[{"argv":["git","clone","https://example/repo.git"],"cwd":"."}]}
+- Commands run only inside Socra's disposable sandbox, never directly in the project root.
+"""
+
+
+def now_iso() -> str:
+    return dt.datetime.now(dt.UTC).isoformat()
+
+
+def read_json(path: Path) -> dict[str, Any] | None:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def append_jsonl(path: Path, row: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def read_chat(path: Path, limit: int = 10) -> list[dict[str, Any]]:
+    if limit <= 0:
+        return []
+    if not path.exists():
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(row, dict):
+            continue
+        if row.get("role") in {"user", "assistant", "system"}:
+            rows.append(row)
+    return rows[-limit:]
+
+
+def pct(value: float) -> str:
+    return f"{value * 100:.1f}%"
+
+
+def safe_addstr(stdscr: Any, y: int, x: int, text: str, attr: int = 0) -> None:
+    h, w = stdscr.getmaxyx()
+    if y < 0 or y >= h or x >= w:
+        return
+    text = text.replace("\n", " ")
+    try:
+        stdscr.addstr(y, x, text[: max(0, w - x - 1)], attr)
+    except curses.error:
+        return
+
+
+def draw_bar(stdscr: Any, y: int, x: int, width: int, fraction: float, label: str) -> None:
+    fraction = max(0.0, min(1.0, fraction))
+    fill = int(width * fraction)
+    bar = "[" + "#" * fill + "-" * (width - fill) + "]"
+    safe_addstr(stdscr, y, x, f"{bar} {label}")
+
+
+def latest_eval_progress(events: list[dict[str, Any]]) -> tuple[int, int, int]:
+    total = 0
+    done = 0
+    passed = 0
+    for event in events:
+        if event.get("event") == "eval_start":
+            total = int(event.get("total") or 0)
+            done = 0
+            passed = 0
+        elif event.get("event") == "eval_task":
+            done = max(done, int(event.get("index") or 0))
+            total = max(total, int(event.get("total") or 0))
+            if event.get("passed"):
+                passed += 1
+        elif event.get("event") == "eval_complete":
+            total = int(event.get("total") or total)
+            done = total
+            passed = int(event.get("passed") or passed)
+    return done, total, passed
+
+
+def candidate_summary(candidates: dict[str, Any], limit: int = 6) -> str:
+    rows = []
+    for item in (candidates.get("candidates") or [])[:limit]:
+        rows.append(
+            f"- {item.get('family')}: {item.get('file_count')} files, "
+            f"score {item.get('score_estimate')}, samples {item.get('samples') or []}"
+        )
+    return "\n".join(rows) if rows else "No repeatable candidates found yet."
+
+
+def sandbox_policy(session: dict[str, Any]) -> dict[str, Any]:
+    sandbox = session.get("sandbox") if isinstance(session.get("sandbox"), dict) else {}
+    return {
+        "network": bool(sandbox.get("network")),
+        "installs": bool(sandbox.get("installs")),
+        "root": str(sandbox.get("root") or ""),
+    }
+
+
+def chat_system_prompt(project: Path, candidates: dict[str, Any], session: dict[str, Any]) -> str:
+    policy = sandbox_policy(session)
+    sandbox_text = (
+        f"\nSandbox command access: network={policy['network']} installs={policy['installs']} "
+        f"root={policy['root'] or 'not configured'}.\n"
+    )
+    if not policy["network"]:
+        sandbox_text += "Do not request network/download/install commands; this session has not enabled sandbox network.\n"
+    return (
+        CHAT_SYSTEM_PROMPT
+        + f"\nProject root: {project}\n\nScanned repeatable project patterns:\n"
+        + candidate_summary(candidates)
+        + sandbox_text
+    )
+
+
+def chat_endpoint(server: dict[str, Any]) -> str | None:
+    endpoint = server.get("endpoint")
+    if not endpoint:
+        return None
+    return str(endpoint).rstrip("/") + "/chat/completions"
+
+
+def prompt_wants_files(text: str) -> bool:
+    lowered = text.lower()
+    triggers = [
+        "create",
+        "make",
+        "build",
+        "write",
+        "generate",
+        "add",
+        "app",
+        "website",
+        "page",
+        "file",
+        "component",
+        "script",
+        "download",
+        "install",
+        "clone",
+        "repo",
+        "dependency",
+        "dependencies",
+    ]
+    return any(trigger in lowered for trigger in triggers)
+
+
+def prompt_wants_website(text: str) -> bool:
+    lowered = text.lower()
+    return any(word in lowered for word in ["website", "webpage", "web page", "html", "landing page", "game"])
+
+
+def post_chat(server: dict[str, Any], messages: list[dict[str, str]], json_mode: bool = False) -> str:
+    endpoint = chat_endpoint(server)
+    if not endpoint:
+        raise RuntimeError("Socra endpoint is not running yet.")
+    model = str(server.get("model_alias") or server.get("model") or "local-model")
+    payload = {
+        "model": model,
+        "messages": messages,
+        "temperature": 0.2,
+        "max_tokens": 4096,
+    }
+    if json_mode:
+        payload["response_format"] = {"type": "json_object"}
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(endpoint, data=data, headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=900) as res:
+            body = json.loads(res.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"chat failed: HTTP {exc.code}: {detail[:500]}") from exc
+    choices = body.get("choices") or []
+    if not choices:
+        raise RuntimeError("chat failed: no choices returned")
+    message = choices[0].get("message") or {}
+    content = message.get("content")
+    if isinstance(content, str) and content.strip():
+        return content.strip()
+    raise RuntimeError("chat failed: empty assistant content")
+
+
+def run_command(command: list[str], cwd: Path, timeout: int = 20) -> tuple[bool, str]:
+    try:
+        proc = subprocess.run(command, cwd=cwd, text=True, capture_output=True, timeout=timeout)
+    except FileNotFoundError:
+        return True, f"skipped; command not found: {command[0]}"
+    except subprocess.TimeoutExpired:
+        return False, f"timed out: {' '.join(command)}"
+    output = (proc.stdout + proc.stderr).strip()
+    return proc.returncode == 0, output
+
+
+def command_sandbox_root(project: Path, state_dir: Path, session: dict[str, Any]) -> Path:
+    policy = sandbox_policy(session)
+    configured = str(policy.get("root") or "").strip()
+    if configured:
+        root = Path(configured).expanduser()
+    else:
+        root = state_dir / "run-sandbox" / "command-workspace"
+    root = root.resolve()
+    fallback = (state_dir / "run-sandbox" / "command-workspace").resolve()
+    if fallback != root and fallback not in root.parents:
+        root = fallback
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def safe_sandbox_cwd(root: Path, relative: str) -> Path:
+    raw = Path(relative or ".")
+    if raw.is_absolute() or any(part == ".." for part in raw.parts):
+        raise ValueError(f"unsafe sandbox cwd: {relative}")
+    cwd = (root / raw).resolve()
+    if cwd != root and root not in cwd.parents:
+        raise ValueError(f"sandbox cwd escapes root: {relative}")
+    cwd.mkdir(parents=True, exist_ok=True)
+    return cwd
+
+
+def command_needs_network(argv: list[str]) -> bool:
+    if not argv:
+        return False
+    tool = Path(argv[0]).name
+    if tool in {"curl", "wget"}:
+        return True
+    if tool == "git" and len(argv) > 1 and argv[1] in {"clone", "fetch", "pull", "submodule"}:
+        return True
+    if tool in {"npm", "pnpm", "yarn", "bun", "pip", "pip3"} and any(part in {"install", "add", "create", "dlx"} for part in argv[1:3]):
+        return True
+    if tool in {"npx"}:
+        return True
+    return any(part.startswith(("http://", "https://", "git@")) for part in argv)
+
+
+def command_is_install(argv: list[str]) -> bool:
+    if not argv:
+        return False
+    tool = Path(argv[0]).name
+    if tool in {"npm", "pnpm", "yarn", "bun", "pip", "pip3", "npx"}:
+        return any(part in {"install", "add", "create", "dlx"} for part in argv[1:3]) or tool == "npx"
+    return False
+
+
+def command_has_shell_metacharacters(argv: list[str]) -> bool:
+    forbidden = {";", "&&", "||", "|", ">", ">>", "<", "$(", "`"}
+    return any(any(mark in part for mark in forbidden) for part in argv)
+
+
+def execute_sandbox_commands(
+    project: Path,
+    state_dir: Path,
+    session: dict[str, Any],
+    commands: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[str]]:
+    policy = sandbox_policy(session)
+    root = command_sandbox_root(project, state_dir, session)
+    results: list[dict[str, Any]] = []
+    errors: list[str] = []
+    for index, command in enumerate(commands, start=1):
+        argv = command.get("argv")
+        cwd_raw = command.get("cwd", ".")
+        if not isinstance(argv, list) or not all(isinstance(part, str) for part in argv) or not argv:
+            errors.append(f"command {index}: invalid argv")
+            continue
+        if command_has_shell_metacharacters(argv):
+            errors.append(f"command {index}: shell metacharacters are not allowed")
+            continue
+        if command_needs_network(argv) and not policy["network"]:
+            errors.append(f"command {index}: blocked; sandbox network is not enabled")
+            continue
+        if command_is_install(argv) and not policy["installs"]:
+            errors.append(f"command {index}: blocked; sandbox installs are not enabled")
+            continue
+        try:
+            cwd = safe_sandbox_cwd(root, str(cwd_raw))
+        except ValueError as exc:
+            errors.append(f"command {index}: {exc}")
+            continue
+        record_agent_stage(state_dir, "sandbox", "running", command=argv, cwd=str(cwd))
+        ok, output = run_command(argv, cwd=cwd, timeout=180)
+        result = {"index": index, "argv": argv, "cwd": str(cwd), "ok": ok, "output": output[-4000:]}
+        results.append(result)
+        append_jsonl(state_dir / "sandbox-commands.jsonl", {"timestamp": now_iso(), **result})
+        record_agent_stage(state_dir, "sandbox", "passed" if ok else "failed", command=argv, cwd=str(cwd), output=output[-1000:])
+        if not ok:
+            errors.append(f"command {index} failed: {output[-1000:]}")
+    if results:
+        (state_dir / "last-sandbox-commands.json").write_text(json.dumps({"root": str(root), "results": results}, indent=2) + "\n", encoding="utf-8")
+    return results, errors
+
+
+def strip_json_fence(text: str) -> str:
+    stripped = text.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].startswith("```"):
+            lines = lines[:-1]
+        return "\n".join(lines).strip()
+    return stripped
+
+
+def json_candidates(text: str) -> list[str]:
+    raw = text.strip()
+    candidates = [strip_json_fence(raw)]
+    for match in re.finditer(r"```(?:json)?\s*([\s\S]*?)```", raw, flags=re.IGNORECASE):
+        candidates.append(match.group(1).strip())
+    start = raw.find("{")
+    while start >= 0:
+        depth = 0
+        in_string = False
+        escaped = False
+        for index in range(start, len(raw)):
+            char = raw[index]
+            if escaped:
+                escaped = False
+                continue
+            if char == "\\":
+                escaped = True
+                continue
+            if char == '"':
+                in_string = not in_string
+                continue
+            if in_string:
+                continue
+            if char == "{":
+                depth += 1
+            elif char == "}":
+                depth -= 1
+                if depth == 0:
+                    candidates.append(raw[start : index + 1])
+                    break
+        start = raw.find("{", start + 1)
+    unique: list[str] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        if candidate and candidate not in seen:
+            seen.add(candidate)
+            unique.append(candidate)
+    return unique
+
+
+def loads_model_json(raw: str) -> Any:
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        # Some local models emit JavaScript-style escaped apostrophes inside
+        # JSON strings. JSON does not allow \', but code content often needs
+        # the backslash preserved, so encode it as a JSON backslash instead.
+        repaired = raw.replace("\\'", "\\\\'")
+        if repaired != raw:
+            return json.loads(repaired)
+        raise
+
+
+def parse_file_bundle(text: str) -> dict[str, Any] | None:
+    path_content_objects: list[dict[str, str]] = []
+    for raw in json_candidates(text):
+        try:
+            value = loads_model_json(raw)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict) and isinstance(value.get("files"), list):
+            return value
+        if isinstance(value, dict) and isinstance(value.get("path"), str) and isinstance(value.get("content"), str):
+            path_content_objects.append({"path": value["path"], "content": value["content"]})
+    if path_content_objects:
+        return {"message": "Created files from the model response.", "files": path_content_objects}
+    return None
+
+
+def parse_action_bundle(text: str) -> dict[str, Any] | None:
+    for raw in json_candidates(text):
+        try:
+            value = loads_model_json(raw)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict) and (isinstance(value.get("files"), list) or isinstance(value.get("commands"), list)):
+            return value
+    file_bundle = parse_file_bundle(text)
+    return file_bundle
+
+
+def parse_command_requests(text: str) -> list[dict[str, Any]]:
+    bundle = parse_action_bundle(text)
+    if not bundle:
+        return []
+    commands = bundle.get("commands")
+    if not isinstance(commands, list):
+        return []
+    parsed: list[dict[str, Any]] = []
+    for item in commands:
+        if not isinstance(item, dict):
+            continue
+        argv = item.get("argv")
+        cmd = item.get("cmd")
+        if isinstance(argv, list) and all(isinstance(part, str) for part in argv):
+            parts = argv
+        elif isinstance(cmd, str):
+            try:
+                parts = shlex.split(cmd)
+            except ValueError:
+                continue
+        else:
+            continue
+        if not parts:
+            continue
+        parsed.append({"argv": parts, "cwd": item.get("cwd") if isinstance(item.get("cwd"), str) else "."})
+    return parsed
+
+
+def code_block_candidates(text: str) -> list[tuple[str, str]]:
+    blocks = []
+    for match in re.finditer(r"```(\w+)?\s*([\s\S]*?)```", text):
+        language = (match.group(1) or "").lower()
+        code = match.group(2).strip()
+        if code:
+            blocks.append((language, code))
+    return blocks
+
+
+def synthesize_file_bundle_from_code_blocks(text: str) -> dict[str, Any] | None:
+    files: list[dict[str, str]] = []
+    counters: dict[str, int] = {}
+    extension_by_language = {
+        "html": "html",
+        "css": "css",
+        "javascript": "js",
+        "js": "js",
+        "typescript": "ts",
+        "ts": "ts",
+        "tsx": "tsx",
+        "jsx": "jsx",
+        "python": "py",
+        "py": "py",
+        "swift": "swift",
+        "json": "json",
+        "markdown": "md",
+        "md": "md",
+    }
+    default_name = {
+        "html": "index.html",
+        "css": "styles.css",
+        "javascript": "script.js",
+        "js": "script.js",
+    }
+    for language, code in code_block_candidates(text):
+        if language == "json":
+            continue
+        ext = extension_by_language.get(language)
+        if not ext:
+            if "<html" in code.lower() or "<!doctype html" in code.lower():
+                ext = "html"
+                language = "html"
+            else:
+                continue
+        name = default_name.get(language)
+        if not name:
+            counters[ext] = counters.get(ext, 0) + 1
+            name = f"generated-{counters[ext]}.{ext}"
+        if any(file["path"] == name for file in files):
+            counters[ext] = counters.get(ext, 1) + 1
+            stem, suffix = name.rsplit(".", 1)
+            name = f"{stem}-{counters[ext]}.{suffix}"
+        files.append({"path": name, "content": code})
+    if not files:
+        return None
+    return {"message": "Created files from the model response.", "files": files}
+
+
+def bundle_to_text(bundle: dict[str, Any]) -> str:
+    return json.dumps(bundle, ensure_ascii=False)
+
+
+def repair_file_bundle_with_model(server: dict[str, Any], project: Path, user_text: str, assistant_text: str) -> str | None:
+    repair_system = (
+        "You convert a coding assistant answer into Socra file JSON. "
+        "Return ONLY JSON with this shape: "
+        '{"message":"short summary","files":[{"path":"relative/project/path","content":"complete file content"}]}. '
+        "Use only relative paths. Do not include prose or markdown."
+    )
+    repair_user = (
+        f"Project root: {project}\n"
+        f"Original user request:\n{user_text}\n\n"
+        f"Assistant answer to package:\n{assistant_text}"
+    )
+    try:
+        repaired = post_chat(
+            server,
+            [{"role": "system", "content": repair_system}, {"role": "user", "content": repair_user}],
+            json_mode=True,
+        )
+    except Exception:
+        return None
+    if parse_file_bundle(repaired):
+        return repaired
+    return None
+
+
+def repair_written_files_with_model(
+    server: dict[str, Any],
+    project: Path,
+    user_text: str,
+    written: list[str],
+    validation_errors: list[str],
+) -> str | None:
+    file_sections = []
+    for rel in written:
+        try:
+            content = safe_project_file(project, rel).read_text(encoding="utf-8")
+        except Exception:
+            continue
+        file_sections.append(f"--- {rel} ---\n{content}")
+    repair_system = (
+        "You repair files that were just generated by a coding agent. "
+        "Return ONLY Socra file JSON: "
+        '{"message":"short summary","files":[{"path":"relative/project/path","content":"complete file content"}]}. '
+        "Include complete corrected contents for every changed file. Use relative paths only."
+    )
+    repair_user = (
+        f"Original request:\n{user_text}\n\n"
+        f"Validation errors:\n" + "\n".join(f"- {error}" for error in validation_errors) + "\n\n"
+        f"Current files:\n\n" + "\n\n".join(file_sections)
+    )
+    try:
+        repaired = post_chat(
+            server,
+            [{"role": "system", "content": repair_system}, {"role": "user", "content": repair_user}],
+            json_mode=True,
+        )
+    except Exception:
+        return None
+    if parse_file_bundle(repaired):
+        return repaired
+    return None
+
+
+def safe_project_file(project: Path, relative: str) -> Path:
+    raw = Path(relative)
+    if raw.is_absolute() or any(part == ".." for part in raw.parts):
+        raise ValueError(f"unsafe path: {relative}")
+    target = (project / raw).resolve()
+    project_root = project.resolve()
+    if target != project_root and project_root not in target.parents:
+        raise ValueError(f"path escapes project: {relative}")
+    return target
+
+
+def read_file_if_exists(project: Path, relative: str) -> str:
+    path = safe_project_file(project, relative)
+    if not path.exists() or not path.is_file():
+        return ""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def file_mentions(project: Path, html: str, relative: str) -> bool:
+    return relative in html or f"./{relative}" in html
+
+
+def self_contain_static_site(project: Path, written: list[str], state_dir: Path) -> list[str]:
+    lower_written = {path.lower() for path in written}
+    html_files = [path for path in written if path.lower().endswith((".html", ".htm"))]
+    if "index.html" not in lower_written or not html_files:
+        return written
+    index = safe_project_file(project, "index.html")
+    html = index.read_text(encoding="utf-8", errors="replace")
+    changed = False
+    css = read_file_if_exists(project, "styles.css")
+    if css and file_mentions(project, html, "styles.css") and "<style>" not in html.lower():
+        html = re.sub(r'\s*<link[^>]+href=["\'](?:\./)?styles\.css["\'][^>]*>\s*', "\n", html, flags=re.IGNORECASE)
+        html = html.replace("</head>", f"  <style>\n{css}\n  </style>\n</head>")
+        changed = True
+    js = read_file_if_exists(project, "script.js")
+    if js and file_mentions(project, html, "script.js") and "<script>" not in html.lower():
+        html = re.sub(r'\s*<script[^>]+src=["\'](?:\./)?script\.js["\'][^>]*>\s*</script>\s*', "\n", html, flags=re.IGNORECASE)
+        html = html.replace("</body>", f"  <script>\n{js}\n  </script>\n</body>")
+        changed = True
+    if changed:
+        index.write_text(html, encoding="utf-8")
+        if "index.html" not in written:
+            written.append("index.html")
+        record = {"timestamp": now_iso(), "project": str(project.resolve()), "action": "self_contained_static_site", "files": ["index.html"]}
+        append_jsonl(state_dir / "validation-repairs.jsonl", record)
+    return written
+
+
+def validate_written_files(project: Path, written: list[str], state_dir: Path) -> tuple[bool, list[str]]:
+    errors: list[str] = []
+    checks: list[dict[str, Any]] = []
+    for rel in written:
+        path = safe_project_file(project, rel)
+        suffix = path.suffix.lower()
+        ok = True
+        output = ""
+        if suffix == ".js":
+            ok, output = run_command(["node", "--check", str(path)], cwd=project)
+        elif suffix == ".json":
+            try:
+                json.loads(path.read_text(encoding="utf-8"))
+                output = "json ok"
+            except Exception as exc:
+                ok = False
+                output = str(exc)
+        elif suffix == ".py":
+            ok, output = run_command([sys.executable, "-m", "py_compile", str(path)], cwd=project)
+        elif suffix == ".swift":
+            ok, output = run_command(["swiftc", "-parse", str(path)], cwd=project)
+        checks.append({"file": rel, "ok": ok, "output": output[-2000:]})
+        if not ok:
+            errors.append(f"{rel}: {output[-1000:]}")
+    if any(path.lower().endswith((".html", ".htm")) for path in written):
+        for rel in [path for path in written if path.lower().endswith((".html", ".htm"))]:
+            html = safe_project_file(project, rel).read_text(encoding="utf-8", errors="replace")
+            if "<style>" not in html.lower() and ".css" not in html.lower():
+                errors.append(f"{rel}: no visible CSS detected")
+            if "<script" not in html.lower() and ".js" not in html.lower():
+                errors.append(f"{rel}: no script detected")
+    state_dir.mkdir(parents=True, exist_ok=True)
+    record = {"timestamp": now_iso(), "checks": checks, "errors": errors}
+    (state_dir / "last-validation.json").write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    append_jsonl(state_dir / "validation.jsonl", record)
+    return not errors, errors
+
+
+def reviewer_agent_check(project: Path, state_dir: Path, user_text: str, written: list[str]) -> tuple[list[str], list[str]]:
+    record_agent_stage(state_dir, "reviewer", "running", files=written)
+    current = self_contain_static_site(project, list(written), state_dir) if prompt_wants_website(user_text) else list(written)
+    ok, errors = validate_written_files(project, current, state_dir)
+    record_agent_stage(state_dir, "reviewer", "passed" if ok else "failed", files=current, errors=errors)
+    return current, errors
+
+
+def runner_agent_check(project: Path, state_dir: Path, user_text: str, written: list[str]) -> list[str]:
+    record_agent_stage(state_dir, "runner", "running", files=written)
+    errors: list[str] = []
+    if prompt_wants_website(user_text):
+        ok, output = run_static_preview_smoke(project, state_dir, written)
+        if not ok:
+            errors.append(output)
+    record_agent_stage(state_dir, "runner", "passed" if not errors else "failed", files=written, errors=errors)
+    return errors
+
+
+def validate_and_repair_output(
+    server: dict[str, Any],
+    project: Path,
+    state_dir: Path,
+    user_text: str,
+    written: list[str],
+) -> tuple[list[str], list[str]]:
+    original = list(written)
+    current = list(written)
+    all_errors: list[str] = []
+    for attempt in range(1, MAX_AGENT_LOOP_PASSES + 1):
+        write_status(state_dir, f"Reviewer pass {attempt}/{MAX_AGENT_LOOP_PASSES}...", stage="reviewer", attempt=attempt)
+        current, review_errors = reviewer_agent_check(project, state_dir, user_text, current)
+        write_status(state_dir, f"Runner pass {attempt}/{MAX_AGENT_LOOP_PASSES}...", stage="runner", attempt=attempt)
+        run_errors = runner_agent_check(project, state_dir, user_text, current)
+        all_errors = [*review_errors, *run_errors]
+        if not all_errors:
+            record_agent_stage(state_dir, "agent_loop", "passed", attempt=attempt, files=current)
+            return current, []
+        if attempt >= MAX_AGENT_LOOP_PASSES:
+            break
+        write_status(state_dir, f"Creator repair pass {attempt + 1}/{MAX_AGENT_LOOP_PASSES}...", stage="creator_repair", attempt=attempt + 1)
+        record_agent_stage(state_dir, "creator", "repairing", attempt=attempt + 1, notes=all_errors)
+        repaired = repair_written_files_with_model(server, project, user_text, current, all_errors)
+        if not repaired:
+            record_agent_stage(state_dir, "creator", "failed", attempt=attempt + 1, notes=["model did not return repair bundle"])
+            break
+        _message, repaired_written = apply_file_bundle(project, repaired, state_dir)
+        current = sorted(set([*current, *repaired_written]))
+        record_agent_stage(state_dir, "creator", "repaired", attempt=attempt + 1, files=repaired_written)
+    record_agent_stage(state_dir, "agent_loop", "failed", files=current, errors=all_errors)
+    return original, all_errors
+
+
+def write_status(state_dir: Path, message: str, **extra: Any) -> None:
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {"timestamp": now_iso(), "message": message, **extra}
+    (state_dir / "working-status.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def record_agent_stage(state_dir: Path, stage: str, status: str, **extra: Any) -> None:
+    row = {"timestamp": now_iso(), "stage": stage, "status": status, **extra}
+    append_jsonl(state_dir / "agent-loop.jsonl", row)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    (state_dir / "last-agent-stage.json").write_text(json.dumps(row, indent=2) + "\n", encoding="utf-8")
+
+
+def free_loopback_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def stop_previous_preview(state_dir: Path) -> None:
+    state = read_json(state_dir / "preview-state.json") or {}
+    pid = state.get("pid")
+    if not isinstance(pid, int):
+        return
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return
+    try:
+        os.kill(pid, 15)
+    except OSError:
+        return
+
+
+def copy_written_files_to_sandbox(project: Path, sandbox: Path, written: list[str]) -> None:
+    if sandbox.exists():
+        shutil.rmtree(sandbox)
+    sandbox.mkdir(parents=True, exist_ok=True)
+    for rel in written:
+        source = safe_project_file(project, rel)
+        if not source.exists() or not source.is_file():
+            continue
+        target = safe_project_file(sandbox, rel)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
+
+
+def prepare_static_preview_sandbox(project: Path, state_dir: Path, written: list[str]) -> tuple[Path, str] | None:
+    route = preview_path_for(written)
+    if not route:
+        return None
+    sandbox = state_dir / "run-sandbox" / "static-preview"
+    copy_written_files_to_sandbox(project.resolve(), sandbox, written)
+    return sandbox, route
+
+
+def run_static_preview_smoke(project: Path, state_dir: Path, written: list[str]) -> tuple[bool, str]:
+    prepared = prepare_static_preview_sandbox(project, state_dir, written)
+    if not prepared:
+        return True, "no static preview target"
+    sandbox, route = prepared
+    file_url = preview_file_url(sandbox, route)
+    parsed = urllib.parse.urlparse(file_url)
+    file_path = Path(urllib.request.url2pathname(parsed.path))
+    if not file_path.exists():
+        return False, f"preview entry file missing: {file_path}"
+    html = file_path.read_text(encoding="utf-8", errors="replace")
+    if not html.strip():
+        return False, f"preview entry file is empty: {file_path}"
+    return True, f"preview smoke ok: {file_url}"
+
+
+def preview_path_for(written: list[str]) -> str | None:
+    html = [path for path in written if path.lower().endswith((".html", ".htm"))]
+    if not html:
+        return None
+    if "index.html" in {Path(path).name.lower() for path in html}:
+        for path in html:
+            if Path(path).name.lower() == "index.html":
+                parent = str(Path(path).parent)
+                return "/" if parent == "." else "/" + parent.replace(os.sep, "/") + "/"
+    return "/" + html[0].replace(os.sep, "/")
+
+
+def preview_file_url(sandbox: Path, route: str) -> str:
+    if route.endswith("/"):
+        file_path = sandbox / route.lstrip("/") / "index.html"
+    else:
+        file_path = sandbox / route.lstrip("/")
+    return file_path.resolve().as_uri()
+
+
+def preview_server_ready(url: str, timeout_seconds: float = 2.0) -> bool:
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=0.5) as res:
+                return 200 <= res.status < 500
+        except Exception:
+            time.sleep(0.1)
+    return False
+
+
+def launch_static_preview(project: Path, state_dir: Path, written: list[str]) -> str | None:
+    prepared = prepare_static_preview_sandbox(project, state_dir, written)
+    if not prepared:
+        return None
+    sandbox, route = prepared
+    project_root = project.resolve()
+    write_status(state_dir, "Preparing local preview sandbox...")
+    stop_previous_preview(state_dir)
+    port = free_loopback_port()
+    out_log = state_dir / "preview-server.out.log"
+    err_log = state_dir / "preview-server.err.log"
+    with out_log.open("a", encoding="utf-8") as out, err_log.open("a", encoding="utf-8") as err:
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "http.server", str(port), "--bind", "127.0.0.1", "--directory", str(sandbox)],
+            stdout=out,
+            stderr=err,
+        )
+    http_url = f"http://127.0.0.1:{port}{route}"
+    if preview_server_ready(http_url):
+        url = http_url
+        mode = "http_server"
+        pid: int | None = proc.pid
+    else:
+        proc.terminate()
+        url = preview_file_url(sandbox, route)
+        mode = "file_url_fallback"
+        pid = None
+    record = {
+        "timestamp": now_iso(),
+        "pid": pid,
+        "url": url,
+        "mode": mode,
+        "sandbox": str(sandbox),
+        "project": str(project_root),
+        "files": written,
+    }
+    (state_dir / "preview-state.json").write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    if os.environ.get("SOCRA_NO_BROWSER") != "1":
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    return url
+
+
+def apply_file_bundle(project: Path, text: str, state_dir: Path) -> tuple[str | None, list[str]]:
+    bundle = parse_file_bundle(text)
+    if not bundle:
+        return None, []
+    project_root = project.resolve()
+    written: list[str] = []
+    for item in bundle.get("files") or []:
+        if not isinstance(item, dict):
+            continue
+        rel = item.get("path")
+        content = item.get("content")
+        if not isinstance(rel, str) or not isinstance(content, str):
+            continue
+        target = safe_project_file(project_root, rel)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        written.append(str(target.relative_to(project_root)))
+    record = {"timestamp": now_iso(), "project": str(project_root), "message": bundle.get("message"), "files": written}
+    state_dir.mkdir(parents=True, exist_ok=True)
+    (state_dir / "last-file-write.json").write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    append_jsonl(state_dir / "file-writes.jsonl", record)
+    return str(bundle.get("message") or "").strip() or None, written
+
+
+def prompt_line(stdscr: Any, prompt: str) -> str:
+    h, w = stdscr.getmaxyx()
+    y = h - 2
+    stdscr.nodelay(False)
+    curses.echo()
+    safe_addstr(stdscr, y, 0, " " * max(0, w - 1))
+    safe_addstr(stdscr, y, 0, prompt)
+    stdscr.move(y, min(len(prompt), max(0, w - 2)))
+    try:
+        raw = stdscr.getstr(y, min(len(prompt), max(0, w - 2)), max(1, w - len(prompt) - 2))
+    finally:
+        curses.noecho()
+        stdscr.nodelay(True)
+    return raw.decode("utf-8", errors="replace").strip()
+
+
+def project_from_state(state_dir: Path, session: dict[str, Any]) -> Path:
+    project = session.get("project")
+    if isinstance(project, str) and project:
+        return Path(project).expanduser().resolve()
+    if state_dir.name == ".socra":
+        return state_dir.parent.resolve()
+    return Path.cwd().resolve()
+
+
+def run_chat_turn(stdscr: Any, state_dir: Path, user_text: str) -> None:
+    server = read_json(state_dir / "server-state.json") or {}
+    session = read_json(state_dir / "session.json") or {}
+    candidates = read_json(state_dir / "candidates.json") or {}
+    project = project_from_state(state_dir, session)
+    chat_path = state_dir / "chat.jsonl"
+    append_jsonl(chat_path, {"timestamp": now_iso(), "role": "user", "content": user_text})
+
+    history = read_chat(chat_path, limit=8)
+    messages = [{"role": "system", "content": chat_system_prompt(project, candidates, session)}]
+    for row in history:
+        if row.get("role") in {"user", "assistant"} and isinstance(row.get("content"), str):
+            messages.append({"role": row["role"], "content": row["content"]})
+
+    h, _w = stdscr.getmaxyx()
+    write_status(state_dir, "Model is working...", stage="model_call")
+    safe_addstr(stdscr, h - 1, 0, "Model is working locally...")
+    stdscr.refresh()
+    try:
+        wants_files = prompt_wants_files(user_text)
+        assistant_text = post_chat(server, messages, json_mode=wants_files)
+        write_status(state_dir, "Parsing response...", stage="parse_response")
+        command_results: list[dict[str, Any]] = []
+        command_errors: list[str] = []
+        commands = parse_command_requests(assistant_text)
+        bundle_message, written = apply_file_bundle(project, assistant_text, state_dir)
+        if commands:
+            write_status(state_dir, "Running requested sandbox commands...", stage="sandbox_commands")
+            command_results, command_errors = execute_sandbox_commands(project, state_dir, session, commands)
+        if wants_files and not written:
+            write_status(state_dir, "Repackaging model output into files...", stage="json_repair")
+            repaired = repair_file_bundle_with_model(server, project, user_text, assistant_text)
+            if repaired:
+                bundle_message, written = apply_file_bundle(project, repaired, state_dir)
+                assistant_text = repaired
+                repaired_commands = parse_command_requests(repaired)
+                if repaired_commands:
+                    write_status(state_dir, "Running requested sandbox commands...", stage="sandbox_commands")
+                    extra_results, extra_errors = execute_sandbox_commands(project, state_dir, session, repaired_commands)
+                    command_results.extend(extra_results)
+                    command_errors.extend(extra_errors)
+        if wants_files and not written:
+            synthesized = synthesize_file_bundle_from_code_blocks(assistant_text)
+            if synthesized:
+                bundle_message, written = apply_file_bundle(project, bundle_to_text(synthesized), state_dir)
+        display_text = bundle_message or assistant_text
+        if written:
+            record_agent_stage(state_dir, "creator", "created", files=written)
+            write_status(state_dir, "Validating generated files...", stage="validate")
+            written, validation_errors = validate_and_repair_output(server, project, state_dir, user_text, written)
+            write_status(state_dir, "Launching local preview sandbox...", stage="preview")
+            preview_url = launch_static_preview(project, state_dir, written)
+            if validation_errors:
+                display_text = f"{display_text}\nValidation warnings: {'; '.join(validation_errors[:2])}"
+            if preview_url:
+                display_text = f"{display_text}\nWrote: {', '.join(written)}\nPreview: {preview_url}"
+            else:
+                display_text = f"{display_text}\nWrote: {', '.join(written)}"
+        if command_results:
+            passed = sum(1 for result in command_results if result.get("ok"))
+            display_text = f"{display_text}\nSandbox commands: {passed}/{len(command_results)} passed."
+        if command_errors:
+            display_text = f"{display_text}\nSandbox warnings: {'; '.join(command_errors[:2])}"
+        if wants_files and not written and not command_results:
+            display_text = (
+                "No files were written because the model did not return the required Socra file JSON. "
+                "Try again with: create the files and return ONLY the JSON file bundle."
+            )
+        append_jsonl(chat_path, {"timestamp": now_iso(), "role": "assistant", "content": display_text, "files": written, "commands": command_results})
+        write_status(state_dir, "Ready.", stage="idle")
+    except Exception as exc:
+        append_jsonl(chat_path, {"timestamp": now_iso(), "role": "system", "content": f"Chat error: {exc}"})
+        write_status(state_dir, f"Chat error: {exc}", stage="error")
+
+
+def draw_chat(stdscr: Any, y: int, state_dir: Path, max_rows: int) -> int:
+    safe_addstr(stdscr, y, 0, "Vibe Chat", curses.A_BOLD)
+    y += 1
+    chat = read_chat(state_dir / "chat.jsonl", limit=6)
+    if not chat:
+        safe_addstr(stdscr, y, 2, "Press Enter or c to chat with the loaded local model.")
+        return y + 1
+    rows_used = 0
+    for row in chat[-6:]:
+        if rows_used >= max_rows:
+            break
+        role = row.get("role", "?")
+        content = str(row.get("content") or "").replace("\n", " ")
+        safe_addstr(stdscr, y, 2, f"{role}: {content}")
+        y += 1
+        rows_used += 1
+    return y
+
+
+def tui_loop(stdscr: Any, state_dir: Path, refresh: float) -> None:
+    curses.curs_set(0)
+    stdscr.nodelay(True)
+    event_path = state_dir / "events.jsonl"
+    while True:
+        stdscr.erase()
+        h, w = stdscr.getmaxyx()
+        events = read_events(event_path, limit=400)
+        server = read_json(state_dir / "server-state.json") or {}
+        status = read_json(state_dir / "working-status.json") or {}
+        agent_stage = read_json(state_dir / "last-agent-stage.json") or {}
+        preview = read_json(state_dir / "preview-state.json") or {}
+        candidates = read_json(state_dir / "candidates.json") or {}
+        results = read_json(state_dir / "humaneval" / "results.json") or read_json(state_dir / "results.json") or {}
+        done, total, passed = latest_eval_progress(events)
+
+        safe_addstr(stdscr, 0, 0, "Socra Harness Terminal Dashboard", curses.A_BOLD)
+        safe_addstr(stdscr, 1, 0, "Enter/c chat + create files | q quit | live from .socra state")
+
+        y = 3
+        safe_addstr(stdscr, y, 0, "Runtime", curses.A_BOLD)
+        y += 1
+        model_label = server.get("model_alias") or server.get("model", "not running")
+        safe_addstr(stdscr, y, 2, f"Model: {model_label}")
+        y += 1
+        endpoint = server.get("endpoint") or (f"http://{server.get('host', '127.0.0.1')}:{server.get('port', '11439')}/v1" if server else "not running")
+        safe_addstr(stdscr, y, 2, f"Endpoint: {endpoint}")
+        y += 1
+        safe_addstr(stdscr, y, 2, f"Backend: {server.get('backend_endpoint', 'unknown')}")
+        y += 1
+        safe_addstr(
+            stdscr,
+            y,
+            2,
+            f"Harness: {server.get('harness', 'unknown')} | local-first: {server.get('local_first', 'unknown')} | hosted fallback: {server.get('hosted_fallback', 'unknown')}",
+        )
+        y += 2
+        if status.get("message"):
+            safe_addstr(stdscr, y, 2, f"Status: {status.get('message')}")
+            y += 1
+        if agent_stage.get("stage"):
+            safe_addstr(stdscr, y, 2, f"Agent: {agent_stage.get('stage')} / {agent_stage.get('status')}")
+            y += 1
+        if preview.get("url"):
+            safe_addstr(stdscr, y, 2, f"Preview: {preview.get('url')}")
+            y += 1
+        y += 1
+
+        safe_addstr(stdscr, y, 0, "HumanEval", curses.A_BOLD)
+        y += 1
+        fraction = (done / total) if total else 0
+        draw_bar(stdscr, y, 2, min(42, max(10, w - 30)), fraction, f"{done}/{total} tasks, {passed} passed")
+        y += 1
+        if results.get("summary"):
+            summary = results["summary"]
+            safe_addstr(stdscr, y, 2, f"Latest: {summary.get('passed')}/{summary.get('total')} pass@1={pct(summary.get('pass_at_1', 0))}")
+            y += 2
+        else:
+            y += 1
+
+        safe_addstr(stdscr, y, 0, "Repo Scan", curses.A_BOLD)
+        y += 1
+        safe_addstr(stdscr, y, 2, f"Source files: {candidates.get('source_files', 0)} | candidates: {candidates.get('candidate_count', 0)}")
+        y += 1
+        for item in (candidates.get("candidates") or [])[: min(4, max(0, h - y - 12))]:
+            safe_addstr(stdscr, y, 2, f"{item['family']}: {item['file_count']} files, score {item['score_estimate']}")
+            y += 1
+        y += 1
+
+        chat_rows = max(3, min(8, h - y - 8))
+        y = draw_chat(stdscr, y, state_dir, chat_rows)
+        y += 1
+
+        safe_addstr(stdscr, y, 0, "Recent Events", curses.A_BOLD)
+        y += 1
+        for event in events[-min(5, max(0, h - y - 3)):]:
+            label = event.get("event", "event")
+            detail = event.get("task_id") or event.get("folder") or event.get("model") or ""
+            safe_addstr(stdscr, y, 2, f"{label}: {detail}")
+            y += 1
+
+        safe_addstr(stdscr, h - 1, 0, "Enter/c: chat  |  q: quit")
+        stdscr.refresh()
+        key = stdscr.getch()
+        if key in {ord("q"), ord("Q")}:
+            return
+        if key in {10, 13, ord("c"), ord("C")}:
+            user_text = prompt_line(stdscr, "You: ")
+            if user_text:
+                run_chat_turn(stdscr, state_dir, user_text)
+            continue
+        time.sleep(refresh)
+
+
+def tui_main(args: Any) -> int:
+    args.state_dir.mkdir(parents=True, exist_ok=True)
+    curses.wrapper(tui_loop, args.state_dir, args.refresh)
+    return 0