"""PATH shim for VCS-call attribution in real-agent runs.

Real agent CLIs do not always expose per-tool-call timestamps in their

streams. The shim makes VCS timing observable regardless of adapter: wrapper

executables named after the VCS binaries (git/oak) are written into a

directory that the harness prepends to the agent subprocess PATH. Each

wrapper runs the real binary with inherited stdio (agent behavior unchanged),

then appends one JSON line to a sidecar JSONL with keys directly consumable

by oakbench.thrash: command, start_ms, end_ms, elapsed_ms, returncode.

Shim overhead is measured per run via measure_shim_overhead and recorded as a

field. It is never subtracted from measurements (ADR-0002: record the

instrument's cost, do not fabricate corrected numbers).

"""

from __future__ import annotations

import json

import statistics

import subprocess

import sys

import time

from pathlib import Path

# The wrapper intentionally uses subprocess.run rather than os.exec*: exec

# replaces the wrapper process, so there would be nobody left to record

# end_ns/returncode. stdio is inherited (no capture) and the child shares the

# wrapper's process-group defaults, so interactive prompts and Ctrl-C reach

# the real binary unchanged; a KeyboardInterrupt in the wrapper itself exits

# 130 like a shell would.

_WRAPPER_TEMPLATE = '''#!{python}

"""Auto-generated VCS shim wrapper. Records call timing, then runs the real binary."""

import fcntl

import json

import os

import subprocess

import sys

import time

REAL = {real}

SIDECAR = {sidecar}

TOOL = {tool}

def write_all(fd, data):

    written_total = 0

    while written_total < len(data):

        written = os.write(fd, data[written_total:])

        if written == 0:

            raise OSError("os.write returned 0 bytes")

        written_total += written

def main() -> int:

    argv = sys.argv[1:]

    start_ns = time.time_ns()

    try:

        rc = subprocess.run([REAL, *argv]).returncode

    except KeyboardInterrupt:

        rc = 130

    except FileNotFoundError:

        rc = 127

    end_ns = time.time_ns()

    row = {{

        "command": " ".join([TOOL, *argv]) if argv else TOOL,

        "argv": argv,

        "start_ms": start_ns / 1e6,

        "end_ms": end_ns / 1e6,

        "elapsed_ms": (end_ns - start_ns) / 1e6,

        "returncode": rc,

        "shim": True,

    }}

    data = (json.dumps(row, sort_keys=True) + "\\n").encode("utf-8")

    try:

        fd = os.open(SIDECAR, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)

        try:

            fcntl.flock(fd, fcntl.LOCK_EX)

            # With O_APPEND plus the exclusive lock, parallel shim calls

            # cannot interleave rows even if the OS accepts only part of the

            # buffer per syscall.

            write_all(fd, data)

        finally:

            try:

                fcntl.flock(fd, fcntl.LOCK_UN)

            finally:

                os.close(fd)

    except OSError:

        # Recording must never change agent-visible behavior; a lost row is

        # an unmeasured call, not a failed agent command.

        pass

    return rc

if __name__ == "__main__":

    raise SystemExit(main())

'''

def create_shim_dir(target_dir: Path, *, real_binaries: dict[str, str], sidecar_path: Path) -> Path:

    """Write executable wrapper scripts into target_dir and return it.

    One wrapper per entry in real_binaries (e.g. {"git": "/usr/bin/git",

    "oak": "/path/to/oak"}); names without a real binary get no wrapper, so

    PATH lookups for them behave exactly as without the shim. The real-binary

    absolute path and the sidecar path are baked into the wrapper at creation

    time, so the wrapper never re-resolves PATH (no recursion risk).

    """

    target_dir = Path(target_dir)

    target_dir.mkdir(parents=True, exist_ok=True)

    sidecar = Path(sidecar_path).expanduser()

    sidecar.parent.mkdir(parents=True, exist_ok=True)

    sidecar.touch(exist_ok=True)

    for tool, real in real_binaries.items():

        if not real:

            continue

        real_path = Path(real).expanduser()

        script = _WRAPPER_TEMPLATE.format(

            python=sys.executable,

            real=json.dumps(str(real_path)),

            sidecar=json.dumps(str(sidecar)),

            tool=json.dumps(str(tool)),

        )

        wrapper = target_dir / str(tool)

        wrapper.write_text(script)

        wrapper.chmod(0o755)

    return target_dir

def measure_shim_overhead(shim_dir: Path, sidecar: Path, real_git: str, n: int = 5) -> float | None:

    """Median extra ms of `shim git --version` over direct `git --version`.

    Calibration rows for the shimmed runs land in `sidecar` (the path baked

    into the wrappers); callers that reuse the sidecar for agent attribution

    should measure overhead first and reset the file. The result is recorded

    alongside measurements, never subtracted from them, and is clamped at 0

    (timer noise can make the shim appear faster; negative overhead is

    fabrication). Returns None when overhead could not be measured.

    """

    shim_git = Path(shim_dir) / "git"

    if not real_git or not shim_git.exists():

        return None

    def median_ms(command: list[str]) -> float | None:

        samples: list[float] = []

        for _ in range(max(1, n)):

            start = time.perf_counter()

            try:

                subprocess.run(

                    command,

                    stdout=subprocess.DEVNULL,

                    stderr=subprocess.DEVNULL,

                    stdin=subprocess.DEVNULL,

                    check=False,

                    timeout=30.0,

                )

            except (OSError, subprocess.SubprocessError):

                return None

            samples.append((time.perf_counter() - start) * 1000.0)

        return statistics.median(samples)

    direct = median_ms([str(real_git), "--version"])

    shimmed = median_ms([str(shim_git), "--version"])

    if direct is None or shimmed is None:

        return None

    return round(max(0.0, shimmed - direct), 3)

def read_sidecar_rows(sidecar: Path) -> list[dict]:

    """Parse sidecar JSONL rows, skipping blank or malformed lines."""

    try:

        text = Path(sidecar).read_text(encoding="utf-8")

    except (FileNotFoundError, OSError):

        return []

    rows: list[dict] = []

    for line in text.splitlines():

        stripped = line.strip()

        if not stripped:

            continue

        try:

            row = json.loads(stripped)

        except json.JSONDecodeError:

            continue

        if isinstance(row, dict):

            rows.append(row)

    return rows