Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

60.5 KB
Raw Blame
"""Environments: a project's files and its installed dependencies, built once and read by every
session that names it.

The contract a session sees (UHP 2026-09-28, Environments chapter):

    /env/<slug>                 the environment, READ-ONLY, shared by every session that uses it
    <cwd>                       the session's own workspace: writable, private, where artifacts land
    PROJECT_ROOT=/env/<slug>    plus the environment's venv and node_modules on PATH/PYTHONPATH/NODE_PATH

Why a layer beside the workspace and not a copy into it: the workspace is checkpointed after every
turn and restored before the next one, and dependency directories are excluded from that tarball
because they are large and reinstallable (CHECKPOINT_EXCLUDE). An environment is the opposite
kind of thing: installed once, never checkpointed, never reinstalled, read by many sessions at
once. Putting it beside the workspace keeps both facts true at zero copy per session.

Layout on disk (ENV_ROOT, on the data volume):

    <ENV_ROOT>/<id>/source/           the editable project: what the console's file tree shows
    <ENV_ROOT>/<id>/versions/<n>/     one build: the source copied, then .venv and node_modules
                                      installed into it, then made read-only (root-owned, a+rX)
    <ENV_ROOT>/<id>/versions/<n>/.hr-build.json   the build's record: status, log, packages, size
    <ENV_ROOT>/<id>/active            symlink -> versions/<n>: the version sessions see
    <ENV_MOUNT>/<slug>                symlink -> <ENV_ROOT>/<id>/active: the path the agent is told

A build is a snapshot: editing the source after it changes nothing a session sees until the next
build. Rolling back is pointing `active` at an older version. Behind the write-wall
(HR_SESSION_UIDS) a session runs as its own uid and the layer is root's, so a write into it fails
with EACCES; that is the enforcement, not an instruction.
"""
from __future__ import annotations

import asyncio
import grp
import hashlib
import json
import mimetypes
import platform
import pwd
import ipaddress
import re
import os
import pathlib
import shutil
import stat
import subprocess
import tarfile
import tempfile
import threading
import time
import urllib.error
import urllib.parse
import urllib.request
import zipfile

from fastapi import APIRouter, HTTPException, Request, Response
from fastapi.responses import JSONResponse

ENV_ROOT = os.environ.get("HR_ENV_ROOT") or os.path.join(
    os.path.dirname(os.environ.get("HARNESS_WORKSPACE", "/data/workspaces").rstrip("/")) or "/data", "environments")
ENV_MOUNT = os.environ.get("HR_ENV_MOUNT", "/env")
BUILD_TIMEOUT = int(os.environ.get("HR_ENV_BUILD_TIMEOUT", "1800"))     # the whole build, seconds
LOG_MAX = 200_000                                                        # characters of build log kept
TREE_MAX = 20_000                                                        # entries a tree listing returns
# Dependency and cache directories never copied from the source into a build: the build installs
# its own, from the manifests, in the image's own toolchain (a venv copied from a laptop is the
# thing SPI-001 says not to trust).
NOT_COPIED = {".venv", "venv", "node_modules", "__pycache__", ".pnpm-store", ".cache", ".hr-build.json"}
_ID_SAFE = set("abcdefghijklmnopqrstuvwxyz0123456789_-")
# One declared package. A version may carry apt's epoch — digits and a colon before the upstream
# version, as in `ffmpeg=7:4.4.2-0ubuntu0.22.04.1`: the form apt itself prints as the candidate and
# the one check_package tells an owner to declare. The colon is admitted only in that position
# (`[0-9]{1,4}:`), so nothing else a colon introduces — npm's `pkg@npm:other`, a `pkg@https:` direct
# reference — becomes a spec for pip or npm, which share this pattern and have no epoch.
_SPEC_RE = re.compile(r"^@?[A-Za-z0-9][A-Za-z0-9._/+-]{0,99}(?:(?:==|>=|<=|~=|!=|@|=)(?:[0-9]{1,4}:)?[A-Za-z0-9._*+^~<>-]{0,60})?$")
_ARCH_DIRS = {"amd64": "x86_64-linux-gnu", "arm64": "aarch64-linux-gnu"}

# ── who may read an environment ─────────────────────────────────────────────────────────────────
# One group per environment, and the environment directory's group IS the record (as a session's
# uid is its workspace's owner: nothing to keep in sync, and it survives a restart because it lives
# on the volume). The runner alone reads the source (0700). A built version is the group's to read
# (0750 / 0640), and an agent process joins that group only for a turn whose harness names the
# environment, so a session reads the one environment it was given and no other. The store root
# and the mount directory are traversable, not listable: a session cannot enumerate the rest.
# Package installs run the packages' own code, so they run as the environment's build identity
# (uid = gid = the environment's number), never as root. Ownership needs root: a runner that is not
# root (a dev box, the per-session sandbox, the tests) applies the modes and nothing else.
GID_BASE = int(os.environ.get("HR_ENV_GID_BASE", "60000") or 60000)
GID_SPAN = 40000
_gid_lock = threading.Lock()

router = APIRouter()
_builds_lock = threading.Lock()
_builds: dict[str, threading.Thread] = {}   # "<id>:<n>" -> the thread building it
_source_locks: dict[str, threading.Lock] = {}
_source_locks_guard = threading.Lock()


def _source_lock(env_id: str) -> threading.Lock:
    """Orders every change to an environment's source against the snapshot a build takes of it, so
    a version is one whole state of the source and never a mix of two. The runner serves
    environments from this one process, which is why a threading.Lock per environment id is enough;
    a runner that served them from several processes would need the same ordering across them."""
    with _source_locks_guard:
        return _source_locks.setdefault(str(env_id), threading.Lock())


# ── paths ───────────────────────────────────────────────────────────────────────────────────────
def _check_id(env_id: str) -> str:
    s = str(env_id or "").strip()
    if not s or len(s) > 80 or any(c not in _ID_SAFE for c in s.lower()):
        raise HTTPException(400, "environment id must be a short [a-z0-9_-] token")
    return s


def slug_ok(slug: str) -> bool:
    s = str(slug or "")
    return bool(s) and len(s) <= 64 and s[0].isalnum() and all(c.isalnum() or c in "-_." for c in s) and ".." not in s


def env_dir(env_id: str) -> pathlib.Path:
    return pathlib.Path(ENV_ROOT) / _check_id(env_id)


def source_dir(env_id: str) -> pathlib.Path:
    return env_dir(env_id) / "source"


def version_dir(env_id: str, n: int) -> pathlib.Path:
    return env_dir(env_id) / "versions" / str(int(n))


def active_link(env_id: str) -> pathlib.Path:
    return env_dir(env_id) / "active"


def mount_path(slug: str) -> str:
    return os.path.join(ENV_MOUNT, slug)


def _root() -> bool:
    return os.geteuid() == 0


def _in_range(gid: int) -> int | None:
    return gid if GID_BASE <= gid < GID_BASE + GID_SPAN else None


def env_gid(env_id: str) -> int | None:
    """The group that reads this environment's builds, from its directory; None when the
    directory is not there or predates groups (secure_store gives it one)."""
    try:
        return _in_range(os.stat(env_dir(env_id)).st_gid)
    except OSError:
        return None


def reader_gid(mount: str | None) -> int | None:
    """The group a turn's process joins for the environment at `mount` (the link the agent is
    told), read from the active version the link points at; None when there is none."""
    if not mount:
        return None
    try:
        return _in_range(os.stat(mount).st_gid)
    except OSError:
        return None


def _account(n: int) -> None:
    """A group and passwd entry for an environment's number, so a tool that looks itself up (npm
    does) finds one. Best effort: nothing here needs the entry to exist."""
    try:
        grp.getgrgid(n)
    except KeyError:
        subprocess.run(["groupadd", "-g", str(n), f"henv{n}"], capture_output=True)
    try:
        pwd.getpwuid(n)
    except KeyError:
        subprocess.run(["useradd", "-M", "-u", str(n), "-g", str(n), "-s", "/usr/sbin/nologin", "-d", "/nonexistent", f"henv{n}"],
                       capture_output=True)


def _claim(env_id: str) -> pathlib.Path:
    """The environment's directory with a group of its own: made on first use, its group derived
    from the id and bumped past any sibling that already holds it, traversable by that group only."""
    d = env_dir(env_id)
    if env_gid(env_id) is not None:
        return d
    d.mkdir(parents=True, exist_ok=True)
    if not _root():
        return d
    with _gid_lock:
        taken = set()
        for sib in pathlib.Path(ENV_ROOT).iterdir():
            try:
                taken.add(os.stat(sib).st_gid)
            except OSError:
                pass
        gid = GID_BASE + int(hashlib.sha256(env_id.encode()).hexdigest()[:8], 16) % GID_SPAN
        while gid in taken:
            gid = GID_BASE + (gid - GID_BASE + 1) % GID_SPAN
        os.chown(d, 0, gid)
        os.chmod(d, 0o750)
        _account(gid)
    return d


def _source(env_id: str) -> pathlib.Path:
    """The source directory, the runner's alone."""
    _claim(env_id)
    src = source_dir(env_id)
    src.mkdir(exist_ok=True)
    os.chmod(src, 0o700)
    return src


def _build_as(env_id: str) -> dict:
    """Popen/run arguments that make a build step run as the environment's own identity; empty
    off root, so every step reads the same with or without it."""
    gid = env_gid(env_id)
    return {"user": gid, "group": gid, "extra_groups": []} if gid is not None and _root() else {}


def _own(path: pathlib.Path, uid: int, gid: int) -> None:
    """chown -R, a link as itself rather than what it points at."""
    try:
        os.lchown(path, uid, gid)
    except OSError:
        pass
    for dirpath, dirnames, filenames in os.walk(path):
        for name in dirnames + filenames:
            try:
                os.lchown(os.path.join(dirpath, name), uid, gid)
            except OSError:
                pass


def secure_store() -> int:
    """Every environment made before groups existed (its directory has no group of its own) gets
    one, its source the runner's alone, its versions the group's: the migration a restart on a box
    with older environments runs once. Returns how many it changed."""
    if not _root():
        return 0
    root = pathlib.Path(ENV_ROOT)
    root.mkdir(parents=True, exist_ok=True)
    os.chmod(root, 0o751)
    n = 0
    for d in root.iterdir():
        try:
            if not d.is_dir() or env_gid(d.name) is not None:
                continue
            _claim(d.name)
            gid = env_gid(d.name)
            if gid is None:
                continue
            if source_dir(d.name).is_dir():
                os.chmod(source_dir(d.name), 0o700)
            vers = d / "versions"
            if vers.is_dir():
                os.chown(vers, 0, gid)
                os.chmod(vers, 0o750)
                for v in vers.iterdir():
                    _read_only(v, gid)
            n += 1
        except Exception:  # noqa: BLE001 — one odd directory must not stop the rest
            continue
    return n


def _safe_rel(root: pathlib.Path, rel: str) -> pathlib.Path:
    """A path under root, or 400. Symlinks inside the source are followed for the containment check
    so a link that points out of the tree cannot be read or written through."""
    raw = str(rel or "").replace("\\", "/")
    if raw.startswith("/") or (len(raw) > 1 and raw[1] == ":"):
        raise HTTPException(400, "path must be relative to the environment, not absolute")
    rel = raw.strip("/")
    if not rel or any(part in ("", ".", "..") for part in rel.split("/")):
        raise HTTPException(400, "path must be relative, without . or .. segments")
    base = root.resolve()
    p = (base / rel).resolve()
    try:
        p.relative_to(base)
    except ValueError:
        raise HTTPException(400, "path escapes the environment")
    return p


# ── the source: files a person edits ─────────────────────────────────────────────────────────────
def tree(env_id: str) -> list[dict]:
    """Every entry under the source, deepest last within a directory, as the console's tree wants
    it: path, dir flag, bytes, mtime. Symlinks are listed as what they are and never followed."""
    src = source_dir(env_id)
    out: list[dict] = []
    if not src.is_dir():
        return out
    for dirpath, dirnames, filenames in os.walk(src):
        dirnames.sort()
        rel_dir = os.path.relpath(dirpath, src)
        for d in dirnames:
            out.append({"path": os.path.normpath(os.path.join(rel_dir, d)), "dir": True, "bytes": 0, "mtime": 0})
        for f in sorted(filenames):
            full = os.path.join(dirpath, f)
            try:
                st = os.lstat(full)
            except OSError:
                continue
            out.append({"path": os.path.normpath(os.path.join(rel_dir, f)), "dir": False,
                        "bytes": int(st.st_size), "mtime": int(st.st_mtime),
                        **({"link": True} if stat.S_ISLNK(st.st_mode) else {})})
        if len(out) >= TREE_MAX:
            break
    return out[:TREE_MAX]


def source_stat(env_id: str) -> dict:
    n = b = 0
    for e in tree(env_id):
        if not e["dir"]:
            n += 1
            b += e["bytes"]
    return {"count": n, "bytes": b}


def read_file(env_id: str, rel: str) -> tuple[bytes, str]:
    p = _safe_rel(source_dir(env_id), rel)
    if not p.is_file():
        raise HTTPException(404, "no such file in the environment")
    return p.read_bytes(), (mimetypes.guess_type(p.name)[0] or "application/octet-stream")


def write_file(env_id: str, rel: str, data: bytes) -> dict:
    src = _source(env_id)
    p = _safe_rel(src, rel)
    if p.is_dir():
        raise HTTPException(409, "a directory is at that path")
    with _source_lock(env_id):
        p.parent.mkdir(parents=True, exist_ok=True)
        tmp = p.with_name(p.name + ".hr-tmp")
        tmp.write_bytes(data)
        os.replace(tmp, p)
    return {"path": rel.strip("/"), "bytes": len(data)}


def make_dir(env_id: str, rel: str) -> dict:
    src = _source(env_id)
    p = _safe_rel(src, rel)
    with _source_lock(env_id):
        p.mkdir(parents=True, exist_ok=True)
    return {"path": rel.strip("/"), "dir": True}


def delete_path(env_id: str, rel: str) -> dict:
    p = _safe_rel(source_dir(env_id), rel)
    with _source_lock(env_id):
        if p.is_dir() and not p.is_symlink():
            shutil.rmtree(p)
        elif p.exists() or p.is_symlink():
            p.unlink()
        else:
            raise HTTPException(404, "nothing at that path")
    return {"path": rel.strip("/"), "deleted": True}


def _members_zip(zf: zipfile.ZipFile) -> list[tuple[str, bool, int]]:
    return [(i.filename, i.is_dir(), i.file_size) for i in zf.infolist()]


def _strip_common_root(names: list[str]) -> str:
    """GitHub's archives and most folder zips wrap everything in one directory; the project is
    what is inside it. The common first segment, when EVERY entry has the same one and nothing sits
    beside it, is stripped."""
    firsts = {n.split("/", 1)[0] for n in names if n.strip("/")}
    if len(firsts) == 1:
        root = next(iter(firsts))
        if not any(n.startswith(root + "/") and n[len(root) + 1:].strip("/") for n in names):
            return ""
        if all(n == root or n == root + "/" or n.startswith(root + "/") for n in names if n.strip("/")):
            return root + "/"
    return ""


def _member_ok(name: str) -> str | None:
    """The relative path a member may land at, or None for one that must not land at all."""
    n = name.replace("\\", "/")
    if n.startswith("/") or any(part in ("..", "") for part in n.strip("/").split("/") if n.strip("/")):
        return None
    return n.strip("/")


def import_archive(env_id: str, data_path: str, *, replace: bool = False) -> dict:
    """Extract a zip or tar archive into the source. Only regular files and directories land:
    symlinks, hard links, devices and any member that names a path outside the source are
    dropped and counted, never written. A single wrapping directory is stripped.

    The lock is held from the replace through the last member, so a build snapshotting while this
    runs waits instead of copying a tree half-refilled. The wait is bounded by the archive."""
    with _source_lock(env_id):
        return _import_archive(env_id, data_path, replace=replace)


def _import_archive(env_id: str, data_path: str, *, replace: bool = False) -> dict:
    src = source_dir(env_id)
    if replace and src.exists():
        shutil.rmtree(src)
    src = _source(env_id)
    written = skipped = 0
    if zipfile.is_zipfile(data_path):
        with zipfile.ZipFile(data_path) as zf:
            names = [i.filename for i in zf.infolist()]
            root = _strip_common_root(names)
            for info in zf.infolist():
                rel = _member_ok(info.filename)
                if rel is None or (root and not (rel + "/").startswith(root)):
                    skipped += 1
                    continue
                rel = rel[len(root):] if root else rel
                if not rel:
                    continue
                mode = (info.external_attr >> 16) & 0xFFFF
                if stat.S_ISLNK(mode):
                    skipped += 1
                    continue
                dest = _safe_rel(src, rel)
                if info.is_dir():
                    dest.mkdir(parents=True, exist_ok=True)
                    continue
                dest.parent.mkdir(parents=True, exist_ok=True)
                with zf.open(info) as fin, open(dest, "wb") as fout:
                    shutil.copyfileobj(fin, fout)
                if mode & 0o111:
                    os.chmod(dest, 0o755)
                written += 1
    elif tarfile.is_tarfile(data_path):
        with tarfile.open(data_path) as tf:
            members = tf.getmembers()
            root = _strip_common_root([m.name for m in members])
            for m in members:
                rel = _member_ok(m.name)
                if rel is None or (root and not (rel + "/").startswith(root)):
                    skipped += 1
                    continue
                rel = rel[len(root):] if root else rel
                if not rel:
                    continue
                if not (m.isreg() or m.isdir()):
                    skipped += 1
                    continue
                dest = _safe_rel(src, rel)
                if m.isdir():
                    dest.mkdir(parents=True, exist_ok=True)
                    continue
                dest.parent.mkdir(parents=True, exist_ok=True)
                fin = tf.extractfile(m)
                if fin is None:
                    skipped += 1
                    continue
                with fin, open(dest, "wb") as fout:
                    shutil.copyfileobj(fin, fout)
                if m.mode & 0o111:
                    os.chmod(dest, 0o755)
                written += 1
    else:
        raise HTTPException(400, "the upload is neither a zip nor a tar archive")
    return {"written": written, "skipped": skipped, **source_stat(env_id)}


def _copy_without_links(src_root: str, dst: pathlib.Path) -> tuple[int, int]:
    """Copy a tree's regular files and directories into dst; a link, a device or a fifo is counted
    and left behind, never followed. Returns (written, skipped)."""
    written = skipped = 0
    for dirpath, dirnames, filenames in os.walk(src_root):   # os.walk does not descend a linked directory
        keep = []
        for d in dirnames:
            if os.path.islink(os.path.join(dirpath, d)):
                skipped += 1
            else:
                keep.append(d)
        dirnames[:] = keep
        rel = os.path.relpath(dirpath, src_root)
        out = dst if rel == "." else dst / rel
        out.mkdir(parents=True, exist_ok=True)
        for f in filenames:
            p = os.path.join(dirpath, f)
            st = os.lstat(p)
            if not stat.S_ISREG(st.st_mode):
                skipped += 1
                continue
            target = out / f
            if target.is_symlink():
                target.unlink()
            shutil.copyfile(p, target, follow_symlinks=False)
            if st.st_mode & 0o111:
                os.chmod(target, 0o755)
            written += 1
    return written, skipped


def _git_pin_args(url: str, pin: str) -> list[str]:
    """`git -c` settings that make the clone connect to the address the gateway classified.

    `pin` is "<host>:<port>:<address>" from the gateway, on a deployment shared by several
    organizations; empty otherwise. Without it git resolved the name again when it connected, so a
    name that answered a public address to the gateway's check and an internal one a moment later
    reached the internal one. Over http(s), curl is told the address for that host and port, and
    redirects are not followed (one to another host would be resolved afresh); over ssh, ssh
    connects to the address and still checks the host key under the name."""
    if not pin:
        return []
    host, _, rest = pin.partition(":")
    port, _, addr = rest.partition(":")
    try:
        ip = ipaddress.ip_address(addr)
    except ValueError:
        raise HTTPException(400, "git pin is not host:port:address")
    if not (host and port.isdigit()):
        raise HTTPException(400, "git pin is not host:port:address")
    if url.startswith(("https://", "http://")):
        shown = f"[{ip}]" if ip.version == 6 else str(ip)
        return ["-c", f"http.curloptResolve={host}:{port}:{shown}", "-c", "http.followRedirects=false"]
    if not re.fullmatch(r"[A-Za-z0-9.-]+", host):
        raise HTTPException(400, "git pin names an invalid host")
    return ["-c", f"core.sshCommand=ssh -o HostName={ip} -o HostKeyAlias={host}"]


def import_git(env_id: str, url: str, ref: str = "", *, replace: bool = False, pin: str = "") -> dict:
    """Clone a repository's tree (shallow, one ref) into the source, without its .git. As with an
    archive, only regular files and directories land: a link the repository commits is dropped and
    counted, never followed. The copy runs as root, and following a committed link (say, to
    /proc/self/environ) wrote what it pointed at into the source, where the files route reads it
    back (reported privately, GHSA-mw9j-m5jf-5r56). The clone runs with the environment a build's
    commands get, without the runner's own secrets."""
    if not str(url).startswith(("https://", "http://", "git@", "ssh://")):
        raise HTTPException(400, "git url must be https://, http://, ssh:// or git@")
    with tempfile.TemporaryDirectory(prefix="hr-env-git-") as tmp:
        cmd = (["git"] + _git_pin_args(url, pin) + ["clone", "--depth", "1", "--quiet"]
               + (["--branch", ref] if ref else []) + [url, tmp + "/repo"])
        try:
            subprocess.run(cmd, check=True, capture_output=True, text=True, timeout=600,
                           env={**_tool_env(), "GIT_TERMINAL_PROMPT": "0"})
        except subprocess.CalledProcessError as e:
            raise HTTPException(400, f"git clone failed: {(e.stderr or '')[-400:].strip()}")
        except subprocess.TimeoutExpired:
            raise HTTPException(504, "git clone did not finish in 10 minutes")
        shutil.rmtree(tmp + "/repo/.git", ignore_errors=True)
        # The clone ran outside the lock, into its own temporary directory, so a slow network never
        # holds up a build. Only swapping the source in needs ordering against a snapshot.
        with _source_lock(env_id):
            src = source_dir(env_id)
            if replace and src.exists():
                shutil.rmtree(src)
            written, skipped = _copy_without_links(tmp + "/repo", _source(env_id))
    return {"imported": "git", "url": url, "ref": ref, "written": written, "skipped": skipped, **source_stat(env_id)}


# ── runtimes ────────────────────────────────────────────────────────────────────────────────────
def runtimes() -> dict:
    """What a build can be made with, on this box: the Python minors present as python3.N binaries,
    the Node major, the OS release for apt. Only what is here; nothing offered that is not."""
    env = _tool_env()
    pythons = []
    for minor in range(8, 20):
        if shutil.which(f"python3.{minor}", path=env.get("PATH")):
            pythons.append(f"3.{minor}")
    node = ""
    try:
        node = subprocess.run(["node", "--version"], capture_output=True, text=True, timeout=10, env=env).stdout.strip().lstrip("v").split(".")[0]
    except (OSError, subprocess.TimeoutExpired):
        pass
    os_name = os_ver = ""
    try:
        for line in open("/etc/os-release"):
            k, _, v = line.strip().partition("=")
            if k == "ID":
                os_name = v.strip('"')
            elif k == "VERSION_ID":
                os_ver = v.strip('"')
    except OSError:
        pass
    return {"python": pythons, "node": [node] if node else [], "os": {"name": os_name, "version": os_ver},
            "apt": bool(shutil.which("apt-get") and shutil.which("dpkg"))}


REGISTRY_TIMEOUT = 8
_apt_lists_at = 0.0


_RANGE_OPS = (">=", "<=", "~=", "!=", ">", "<")
_NPM_RANGE = re.compile(r"[\^~<>*|\s]|(?:^|\.)[xX](?:\.|$)")


def spec_parts(spec: str, manager: str) -> tuple[str, str]:
    """A spec's name and exact pin: npm's name@version, pip's name==version, apt's name=version.
    A range (>=, ~=, ...) is a name with no pin; pip resolves it at build time, and apt cannot
    (apt_range)."""
    s = spec.strip()
    if manager == "npm":
        i = s.rfind("@")
        if i <= 0:
            return s, ""
        # npm's ranges (^4.17.0, ~4.17, >=1, 1.x, *) are not one version either: the registry's
        # `versions` names exact ones, so a range read as a pin was "not published".
        v = s[i + 1:]
        return s[:i], ("" if _NPM_RANGE.search(v) else v)
    # Ranges before the pin operators: `>=`, `<=`, `~=` and `!=` each end in `=`, so looking for a
    # pin first read `jq>=1.6` as the name `jq>` with the pin `1.6` — neither what the owner
    # declared nor something apt-get, pip or a registry will answer for.
    for sep in _RANGE_OPS:
        if sep in s:
            return s.split(sep, 1)[0].strip(), ""
    for sep in ("==", "="):
        if sep in s:
            n, v = s.split(sep, 1)
            n, v = n.strip(), v.strip()
            # PEP 440's prefix match (`numpy==1.4.*`) is every release whose version begins `1.4.`,
            # not one version, just as npm's `4.x` is not: PyPI's `releases` names exact ones, so a
            # range read as a pin was "not published". pip resolves it at build time. apt keeps its
            # pin verbatim: it has no wildcard, so `=1.4.*` really is not in the sources.
            if manager == "pip" and v.endswith(".*"):
                return n, ""
            return n, v
    return s, ""


def apt_range(spec: str) -> bool:
    """Whether an apt declaration is a range. apt installs one exact version (name=version) or the
    newest its sources offer (name) and has no syntax for a range, so `jq>=9` would be installed as
    whatever jq is newest, and the layer would differ from its declaration with nothing saying so
    (the failure #427 is about). A range is refused instead: when the console checks it, and by the
    build before apt runs."""
    return any(op in spec for op in _RANGE_OPS)


def _http_json(url: str) -> tuple[int, dict]:
    req = urllib.request.Request(url, headers={"User-Agent": "harnessrouter-environments/1", "Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=REGISTRY_TIMEOUT) as r:
            return r.status, json.loads(r.read().decode("utf-8", "replace") or "{}")
    except urllib.error.HTTPError as e:
        return e.code, {}


def _apt_lists() -> None:
    """apt's package lists, refreshed at most every six hours: what a build's apt would see."""
    global _apt_lists_at
    if time.time() - _apt_lists_at < 6 * 3600:
        return
    subprocess.run(["apt-get", "update", "-qq"], capture_output=True, timeout=180, env=_tool_env())
    _apt_lists_at = time.time()


def check_package(manager: str, spec: str) -> dict:
    """What the manager's registry says about a declared package before any build: whether the
    name exists, its latest version, and whether an exact pin is published. pip asks PyPI, npm the
    npm registry, apt this box's own package lists (the ones a build would download from). A typo
    is refused at the moment it is typed instead of failing a build minutes later. `exists` is
    None when the registry could not be asked; the build is then the check."""
    manager = (manager or "").strip().lower()
    if manager not in ("pip", "npm", "apt"):
        raise HTTPException(400, "manager must be pip, npm or apt")
    spec = (spec or "").strip()
    if not _SPEC_RE.match(spec):
        raise HTTPException(400, "that is not a package spec")
    name, pin = spec_parts(spec, manager)
    out = {"manager": manager, "name": name, "spec": spec, "exists": None, "latest": "", "version": "", "error": ""}
    dist_tags: dict = {}   # npm only: PyPI and apt have no dist-tag concept
    try:
        if manager == "pip":
            st, j = _http_json(f"https://pypi.org/pypi/{urllib.parse.quote(name)}/json")
            if st == 404:
                out.update(exists=False, error=f"{name} is not on PyPI")
                return out
            if st != 200:
                raise RuntimeError(f"PyPI answered {st}")
            info = j.get("info") or {}
            out.update(exists=True, latest=str(info.get("version") or ""), name=str(info.get("name") or name))
            versions = set((j.get("releases") or {}).keys())
        elif manager == "npm":
            st, j = _http_json("https://registry.npmjs.org/" + urllib.parse.quote(name, safe="@").replace("/", "%2F"))
            if st == 404:
                out.update(exists=False, error=f"{name} is not on the npm registry")
                return out
            if st != 200:
                raise RuntimeError(f"the npm registry answered {st}")
            dist_tags = j.get("dist-tags") or {}
            out.update(exists=True, latest=str(dist_tags.get("latest") or ""))
            versions = set((j.get("versions") or {}).keys())
        else:
            _apt_lists()
            env = _tool_env()
            r = subprocess.run(["apt-cache", "policy", name], capture_output=True, text=True, timeout=60, env=env)
            cand = next((ln.split(":", 1)[1].strip() for ln in r.stdout.splitlines() if ln.strip().startswith("Candidate:")), "")
            if not cand or cand == "(none)":
                out.update(exists=False, error=f"{name} is not in this server's apt sources")
                return out
            out.update(exists=True, latest=cand)
            m = subprocess.run(["apt-cache", "madison", name], capture_output=True, text=True, timeout=60, env=env)
            versions = {ln.split("|")[1].strip() for ln in m.stdout.splitlines() if ln.count("|") >= 2}
        if pin:
            # A dist-tag is a name for a version, not a version: resolve it before checking
            # the published versions, so `lodash@latest` stops reading as "not published".
            # An unknown tag keeps the error below; only an exact version is looked up.
            if pin in dist_tags:
                out["version"] = str(dist_tags[pin])
            elif pin in versions:
                out["version"] = pin
            else:
                out["error"] = f"{name} {pin} is not published; the latest is {out['latest']}"
        elif manager == "apt" and apt_range(spec):
            out["error"] = (f"apt installs one exact version or the newest, and cannot hold to {spec}. "
                            f"Declare {name}, or {name}={out['latest']} to pin the newest.")
    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as e:
        out.update(exists=None, error=f"the registry could not be asked: {str(e)[:120]}")
    return out


def clean_specs(specs) -> list[str]:
    """Declared packages as short spec strings, each checked against one shape."""
    out: list[str] = []
    for x in (specs or []):
        t = str(x or "").strip()
        if t and _SPEC_RE.match(t) and t not in out and len(out) < 200:
            out.append(t)
    return out


# ── builds ──────────────────────────────────────────────────────────────────────────────────────
def build_record(env_id: str, n: int) -> dict | None:
    p = version_dir(env_id, n) / ".hr-build.json"
    try:
        return json.loads(p.read_text())
    except (OSError, ValueError):
        return None


def _build_running(env_id: str, n: int) -> bool:
    with _builds_lock:
        t = _builds.get(f"{env_id}:{int(n)}")
    return bool(t and t.is_alive())


def _as_read(env_id: str, n: int, rec: dict) -> dict:
    """A record that says building with no build thread behind it is a build that stopped. The
    record is the build's only report, and the thread that writes it is gone: its last write failed
    (a full disk; _build swallows that one) or the runner restarted under it. Read as it lies, it
    said building to every read for good, and the gateway, which takes the environment's status
    from versions(), showed it building for good too. Both reads answer it as failed."""
    if rec.get("status") != "building" or _build_running(env_id, n):
        return rec
    try:
        stopped = int(os.path.getmtime(version_dir(env_id, n) / ".hr-build.json"))
    except OSError:
        stopped = int(time.time())
    return {**rec, "status": "failed", "stage": "", "finished_at": stopped,
            "error": "the build stopped before it recorded its end"}


def versions(env_id: str) -> list[dict]:
    root = env_dir(env_id) / "versions"
    out = []
    if root.is_dir():
        for e in sorted(root.iterdir(), key=lambda x: int(x.name) if x.name.isdigit() else 0):
            if e.name.isdigit():
                rec = _as_read(env_id, int(e.name), build_record(env_id, int(e.name)) or {"version": int(e.name), "status": "unknown"})
                out.append({k: rec.get(k) for k in ("version", "status", "started_at", "finished_at", "error", "files", "bytes")
                            } | {"packages": len(rec.get("packages") or [])})
    return out


def active_version(env_id: str) -> int | None:
    try:
        target = os.readlink(active_link(env_id))
    except OSError:
        return None
    name = os.path.basename(target.rstrip("/"))
    return int(name) if name.isdigit() else None


def _tool_env() -> dict:
    """The environment the build's commands run in: the runner's own (the image's toolchain, the
    same python3 and node an agent gets), minus anything secret-shaped, with caches kept out of
    the layer."""
    from server import _child_env   # the same scrub agents get; imported late to avoid a cycle
    env = _child_env()
    env["PIP_NO_CACHE_DIR"] = "1"
    env["PIP_DISABLE_PIP_VERSION_CHECK"] = "1"
    env["npm_config_fund"] = env["npm_config_audit"] = "false"
    env["npm_config_update_notifier"] = "false"
    return env


def _run(log: list[str], cmd: list[str], cwd: str, env: dict, deadline: float, run_as: dict | None = None,
         flush=None) -> None:
    """One build command. `flush` writes the record after the command line and again after its
    output, so a build's log is readable while the build runs, not only when it ends."""
    left = max(1, int(deadline - time.time()))
    log.append(f"$ {' '.join(cmd)}")
    if flush:
        flush()
    try:
        r = subprocess.run(cmd, cwd=cwd, env=env, capture_output=True, text=True, timeout=left, **(run_as or {}))
    except subprocess.TimeoutExpired:
        raise RuntimeError(f"{cmd[0]} did not finish within the build's {BUILD_TIMEOUT}s")
    if r.stdout.strip():
        log.append(r.stdout.rstrip()[-20000:])
    if r.stderr.strip():
        log.append(r.stderr.rstrip()[-20000:])
    if flush:
        flush()
    if r.returncode != 0:
        raise RuntimeError(f"{cmd[0]} exited {r.returncode}")


def _packages(dst: pathlib.Path, env: dict, run_as: dict | None = None) -> list[dict]:
    out: list[dict] = []
    run_as = run_as or {}
    pip = dst / ".venv" / "bin" / "pip"
    if pip.is_file():
        try:
            r = subprocess.run([str(pip), "list", "--format=json"], capture_output=True, text=True, timeout=120, env=env, **run_as)
            for row in json.loads(r.stdout or "[]"):
                out.append({"manager": "pip", "name": str(row.get("name")), "version": str(row.get("version"))})
        except (OSError, ValueError, subprocess.TimeoutExpired):
            pass
    if (dst / "node_modules").is_dir():
        try:
            r = subprocess.run(["npm", "ls", "--json", "--depth=0"], cwd=str(dst), capture_output=True, text=True,
                               timeout=120, env=env, **run_as)
            deps = (json.loads(r.stdout or "{}") or {}).get("dependencies") or {}
            for name, info in sorted(deps.items()):
                out.append({"manager": "npm", "name": name, "version": str((info or {}).get("version") or "")})
        except (OSError, ValueError, subprocess.TimeoutExpired):
            pass
    return out


def _apt_into_layer(log: list[str], dst: pathlib.Path, names: list[str], env: dict, scratch: str, deadline: float, flush=None) -> None:
    """System packages, unpacked into the layer rather than installed into the box: apt resolves
    and downloads each named package with the dependencies the image lacks, and dpkg unpacks every
    archive under <version>/apt, which a turn puts on PATH and LD_LIBRARY_PATH. The image's own
    packages stay the image's; nothing here changes the container."""
    ranged = [s for s in names if apt_range(s)]
    if ranged:
        raise RuntimeError(f"apt installs one exact version or the newest, and cannot hold to {', '.join(ranged)}: "
                           f"declare the name alone, or name=version")
    cache = pathlib.Path(scratch) / "apt-archives"
    cache.mkdir(parents=True, exist_ok=True)
    _run(log, ["apt-get", "update", "-qq"], str(dst), env, deadline, flush=flush)
    _run(log, ["apt-get", "install", "-y", "--download-only", "--reinstall", "--allow-downgrades",
               "-o", f"Dir::Cache::archives={cache}",
               # A pin older than a version the image already has is planned by apt as a downgrade,
               # and `-y` alone stops on "Packages were downgraded and -y was used without
               # --allow-downgrades". Nothing here touches the image: the archives go to the layer's
               # own cache and dpkg unpacks them into the layer, so the flag only lets the planner
               # fetch the version the declaration names.
               # apt-get does not parse pip's `==`, so each spec goes through spec_parts: an
               # exact pin reaches apt as name=version (a range was refused above).
               "-o", "Debug::NoLocking=1",
               *[f"{n}={v}" if v else n for n, v in (spec_parts(s, "apt") for s in names)]],
         str(dst), env, deadline, flush=flush)
    debs = sorted(cache.glob("*.deb"))
    if not debs:
        raise RuntimeError("apt downloaded nothing for " + ", ".join(names))
    out = dst / "apt"
    out.mkdir(exist_ok=True)
    for deb in debs:
        _run(log, ["dpkg", "-x", str(deb), str(out)], str(dst), env, deadline, flush=flush)
    (out / ".packages").write_text("\n".join(d.name for d in debs) + "\n")
    log.append(f"apt: unpacked {len(debs)} archive(s) into apt/")


def _apt_packages(dst: pathlib.Path) -> list[dict]:
    """The archives a build unpacked, as manager/name/version, from their file names."""
    out = []
    try:
        for name in (dst / "apt" / ".packages").read_text().split():
            parts = name[:-4].split("_") if name.endswith(".deb") else []
            if len(parts) >= 2:
                out.append({"manager": "apt", "name": parts[0], "version": parts[1].replace("%3a", ":")})
    except OSError:
        pass
    return out


def _read_only(dst: pathlib.Path, gid: int | None = None) -> None:
    """Root's, the environment's group's to read, writable by nobody: directories 750, files 640
    keeping their execute bit (750). Nobody outside the group sees a byte of it."""
    own = gid is not None and _root()

    def one(p: str, is_dir: bool) -> None:
        try:
            st = os.lstat(p)
            if own:
                os.lchown(p, 0, gid)
            if not stat.S_ISLNK(st.st_mode):
                os.chmod(p, 0o750 if is_dir or st.st_mode & 0o111 else 0o640)
        except OSError:
            pass

    one(str(dst), True)
    for dirpath, dirnames, filenames in os.walk(dst):
        for d in dirnames:
            one(os.path.join(dirpath, d), True)
        for f in filenames:
            one(os.path.join(dirpath, f), False)


def _size(dst: pathlib.Path) -> tuple[int, int]:
    n = b = 0
    for dirpath, _, filenames in os.walk(dst):
        for f in filenames:
            try:
                st = os.lstat(os.path.join(dirpath, f))
            except OSError:
                continue
            if stat.S_ISREG(st.st_mode):
                n += 1
                b += st.st_size
    return n, b


def _write_record(dst: pathlib.Path, rec: dict) -> None:
    dst.mkdir(parents=True, exist_ok=True)
    rec = dict(rec)
    if isinstance(rec.get("log"), list):
        text = "\n".join(rec["log"])
        rec["log"] = text[-LOG_MAX:] if len(text) > LOG_MAX else text
    tmp = dst / ".hr-build.json.tmp"
    tmp.write_text(json.dumps(rec, indent=1))
    os.replace(tmp, dst / ".hr-build.json")


def _build(env_id: str, n: int, slug: str, activate: bool, spec: dict | None = None) -> None:
    spec = spec or {}
    pip_specs, npm_specs, apt_specs = clean_specs(spec.get("pip")), clean_specs(spec.get("npm")), clean_specs(spec.get("apt"))
    want_py = str(spec.get("python") or "")   # the node major is the box's one; recorded, not chosen
    src, dst = source_dir(env_id), version_dir(env_id, n)
    started = int(time.time())
    log: list[str] = []
    rec = {"version": n, "status": "building", "started_at": started, "finished_at": None, "error": "",
           "packages": [], "files": 0, "bytes": 0, "log": log, "runtime": {}, "stage": "starting",
           "declared": {"pip": pip_specs, "npm": npm_specs, "apt": apt_specs}}

    def flush() -> None:
        """The record on disk IS what the owner sees while the build runs: written as each step ends."""
        try:
            _write_record(dst, rec)
        except OSError:
            pass

    def stage(name: str) -> None:
        rec["stage"] = name
        flush()

    try:
        _claim(env_id)
        gid = env_gid(env_id)
        if dst.exists():
            shutil.rmtree(dst)
        _write_record(dst, rec)
        if gid is not None:
            os.chown(dst.parent, 0, gid)
            os.chmod(dst.parent, 0o750)
        deadline = time.time() + BUILD_TIMEOUT
        env = _tool_env()
        stage("copying files")
        # The count and the copy are one reading of the tree: a source write waits here, so a version
        # holds one whole state of the source and the log counts what this build actually copied.
        with _source_lock(env_id):
            log.append(f"copying the project ({source_stat(env_id)['count']} files)")
            shutil.copytree(src, dst, symlinks=False, dirs_exist_ok=True,
                            ignore=lambda d, names: [x for x in names if x in NOT_COPIED])
        as_build = _build_as(env_id)
        with tempfile.TemporaryDirectory(prefix="hr-env-build-") as scratch:
            env["HOME"] = env["TMPDIR"] = scratch
            env["npm_config_cache"] = os.path.join(scratch, "npm-cache")
            if as_build:
                # pip, npm and setup.sh run the project's and its packages' own code: as the
                # environment's identity, which owns this layer and the scratch and nothing else.
                _own(dst, gid, gid)
                os.chown(scratch, gid, gid)
            if pip_specs or (dst / "requirements.txt").is_file() or (dst / "pyproject.toml").is_file():
                stage("python packages")
                # The interpreter the owner chose, when the box has it; the image's python3 otherwise.
                python = (shutil.which(f"python{want_py}", path=env.get("PATH")) if want_py else None) \
                    or shutil.which("python3", path=env.get("PATH")) or "python3"
                _run(log, [python, "-m", "venv", ".venv"], str(dst), env, deadline, as_build, flush)
                pip = str(dst / ".venv" / "bin" / "pip")
                if (dst / "requirements.txt").is_file():
                    _run(log, [pip, "install", "-r", "requirements.txt"], str(dst), env, deadline, as_build, flush)
                if (dst / "pyproject.toml").is_file():
                    _run(log, [pip, "install", "."], str(dst), env, deadline, as_build, flush)
                if pip_specs:
                    _run(log, [pip, "install", *pip_specs], str(dst), env, deadline, as_build, flush)
                try:
                    rec["runtime"]["python"] = subprocess.run([str(dst / ".venv" / "bin" / "python"), "-c", "import platform; print(platform.python_version())"],
                                                              capture_output=True, text=True, timeout=30, env=env, **as_build).stdout.strip()
                except (OSError, subprocess.TimeoutExpired):
                    pass
            if npm_specs or (dst / "package.json").is_file():
                stage("node packages")
                npm = shutil.which("npm", path=env.get("PATH")) or "npm"
                if (dst / "package.json").is_file():
                    _run(log, [npm, "ci" if (dst / "package-lock.json").is_file() else "install", "--no-audit", "--no-fund"],
                         str(dst), env, deadline, as_build, flush)
                if npm_specs:
                    if not (dst / "package.json").is_file():
                        (dst / "package.json").write_text(json.dumps({"name": slug or "environment", "version": "0.0.0", "private": True}, indent=2) + "\n")
                        if as_build:
                            os.chown(dst / "package.json", gid, gid)
                    _run(log, [npm, "install", "--no-audit", "--no-fund", "--save", *npm_specs], str(dst), env, deadline, as_build, flush)
                try:
                    rec["runtime"]["node"] = subprocess.run(["node", "--version"], capture_output=True, text=True, timeout=10, env=env).stdout.strip().lstrip("v")
                except (OSError, subprocess.TimeoutExpired):
                    pass
            if apt_specs:   # apt-get and dpkg -x run none of the packages' code; apt's lists need root
                stage("system packages")
                _apt_into_layer(log, dst, apt_specs, env, scratch, deadline, flush)
            if (dst / "setup.sh").is_file():
                stage("setup.sh")
                _run(log, ["bash", "setup.sh"], str(dst), {**env, "ENV_ROOT": str(dst)}, deadline, as_build, flush)
            stage("finishing")
            rec["packages"] = _packages(dst, env, as_build)
            if (dst / "apt").is_dir():
                rec["packages"] += _apt_packages(dst)
        _read_only(dst, gid)
        rec["files"], rec["bytes"] = _size(dst)
        rec["status"], rec["finished_at"], rec["stage"] = "ready", int(time.time()), ""
        log.append(f"ready: {rec['files']} files, {len(rec['packages'])} packages, {int(time.time()) - started}s")
        if activate:
            # The record is the build's last word, so what the build promised is in place before it
            # says ready. It used to be written first: a reader that waited for "ready" and started
            # a turn at once found no active version in between (issue #401; a CI run met it on a
            # slow disk, 2026-10-05). If the last steps fail, the active version is what it was.
            was = active_version(env_id)
            try:
                _point_active(env_id, n)
                ensure_mount(env_id, slug)
                _write_record(dst, rec)
            except Exception:
                _point_active(env_id, was)
                raise
        else:
            _write_record(dst, rec)
    except Exception as e:  # noqa: BLE001 — the record IS the report; nothing else sees this thread
        rec["status"], rec["finished_at"], rec["error"], rec["stage"] = "failed", int(time.time()), str(e)[:500], ""
        log.append(f"failed: {e}")
        try:
            _write_record(dst, rec)
        except OSError:
            pass
    finally:
        with _builds_lock:
            _builds.pop(f"{env_id}:{n}", None)


def start_build(env_id: str, n: int, slug: str, activate: bool = True, spec: dict | None = None) -> dict:
    if not source_dir(env_id).is_dir():
        raise HTTPException(409, "the environment has no files yet")
    key = f"{env_id}:{n}"
    with _builds_lock:
        if key in _builds and _builds[key].is_alive():
            raise HTTPException(409, "that version is already building")
        for k, t in _builds.items():
            if k.startswith(env_id + ":") and t.is_alive():
                raise HTTPException(409, "another version of this environment is building")
        t = threading.Thread(target=_build, args=(env_id, n, slug, activate, spec), daemon=True, name=f"env-build-{key}")
        _builds[key] = t
        t.start()
    return {"version": n, "status": "building"}


def _point_active(env_id: str, n: int | None) -> None:
    """Make version n the environment's active one; None leaves it with none."""
    link = active_link(env_id)
    if n is None:
        link.unlink(missing_ok=True)
        return
    tmp = link.with_name("active.tmp")
    if tmp.is_symlink() or tmp.exists():
        tmp.unlink()
    os.symlink(os.path.join("versions", str(n)), tmp)
    os.replace(tmp, link)                      # atomic: a session mid-turn sees the old or the new, never neither


def activate_version(env_id: str, n: int, slug: str) -> dict:
    dst = version_dir(env_id, n)
    rec = build_record(env_id, n)
    if not dst.is_dir() or not rec or rec.get("status") != "ready":
        raise HTTPException(409, f"version {n} is not a finished build")
    _point_active(env_id, n)
    ensure_mount(env_id, slug)
    return {"version": n, "status": "ready", "path": mount_path(slug)}


def ensure_mount(env_id: str, slug: str) -> str:
    """The path sessions are told, as a link to the environment's active version. Created on the
    container's rootfs, so it is remade after a restart; idempotent."""
    if not slug_ok(slug):
        raise HTTPException(400, "environment slug is not a path segment")
    if active_version(env_id) is None:
        raise HTTPException(409, "the environment has no built version")
    os.makedirs(ENV_MOUNT, mode=0o751, exist_ok=True)
    try:
        os.chmod(ENV_MOUNT, 0o751)
    except OSError:
        pass
    target = str(active_link(env_id))
    link = mount_path(slug)
    try:
        if os.readlink(link) == target:
            return link
    except OSError:
        pass
    tmp = link + ".tmp"
    if os.path.lexists(tmp):
        os.unlink(tmp)
    os.symlink(target, tmp)
    os.replace(tmp, link)
    return link


def drop_mount(slug: str, env_id: str = "") -> None:
    """Take the path down. Given the environment, only while the path is still that environment's:
    a deleted environment's name is free at once, and another environment may hold it by the time
    this one is removed for good."""
    base = os.path.realpath(ENV_MOUNT)
    link = os.path.normpath(os.path.join(base, str(slug or "")))
    if not slug_ok(slug) or not link.startswith(base + os.sep):
        raise HTTPException(400, "environment slug is not a path segment")
    if not os.path.islink(link):
        return
    if env_id and os.readlink(link) != str(active_link(env_id)):
        return
    os.unlink(link)


def delete_environment(env_id: str, slug: str = "") -> dict:
    if slug:
        drop_mount(slug, env_id)
    d = env_dir(env_id)
    if d.exists():
        shutil.rmtree(d, ignore_errors=True)
    return {"id": env_id, "deleted": True}


# ── the turn ────────────────────────────────────────────────────────────────────────────────────
def resolve(spec: dict | None) -> dict | None:
    """What a turn's environment is on this box: the link at the path the agent is told (made if
    the container restarted), the version behind it, the entry the owner declared. None when the
    turn has no environment; 409 when the environment has nothing built."""
    if not spec:
        return None
    env_id, slug = _check_id(spec.get("id")), str(spec.get("slug") or "")
    link = ensure_mount(env_id, slug)
    if not pathlib.Path(link).resolve().is_dir():
        raise HTTPException(409, "the environment's active version is missing on disk")
    return {"id": env_id, "slug": slug, "path": link, "version": active_version(env_id),
            "entry": str(spec.get("entry") or "")}


def apply_env(env: dict, applied: dict | None) -> None:
    """The variables that make the layer's interpreter and packages the ones an agent runs:
    PROJECT_ROOT, the venv first on PATH (so `python3` is the venv's), the project on PYTHONPATH
    (so `from scripts.lib import x` works from anywhere), node_modules on NODE_PATH."""
    if not applied:
        return
    link = applied["path"]
    real = pathlib.Path(link).resolve()
    env["PROJECT_ROOT"] = link
    env["HR_ENVIRONMENT"] = link
    env["PYTHONPATH"] = link + (":" + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
    path_add = []
    if (real / ".venv" / "bin").is_dir():
        path_add.append(os.path.join(link, ".venv", "bin"))
        env["VIRTUAL_ENV"] = os.path.join(link, ".venv")
    if (real / "node_modules" / ".bin").is_dir():
        path_add.append(os.path.join(link, "node_modules", ".bin"))
    if (real / "node_modules").is_dir():
        env["NODE_PATH"] = os.path.join(link, "node_modules") + (":" + env["NODE_PATH"] if env.get("NODE_PATH") else "")
    if (real / "apt").is_dir():
        apt = os.path.join(link, "apt")
        path_add += [os.path.join(apt, "usr", "bin"), os.path.join(apt, "usr", "local", "bin"), os.path.join(apt, "bin")]
        arch = _ARCH_DIRS.get({"x86_64": "amd64", "aarch64": "arm64"}.get(platform.machine(), ""), "")
        libs = [os.path.join(apt, "usr", "lib"), os.path.join(apt, "lib")] + ([os.path.join(apt, "usr", "lib", arch), os.path.join(apt, "lib", arch)] if arch else [])
        env["LD_LIBRARY_PATH"] = ":".join(libs + ([env["LD_LIBRARY_PATH"]] if env.get("LD_LIBRARY_PATH") else []))
    if path_add:
        env["PATH"] = ":".join(path_add + [env.get("PATH", "")])


def apply_to_turn(env: dict, spec: dict | None) -> dict | None:
    """resolve + apply_env in one call, for a caller that has no doc to write first."""
    applied = resolve(spec)
    apply_env(env, applied)
    return applied


def doc_section(applied: dict | None) -> list[str]:
    """The lines the agent's instruction file carries for its environment: where the project is,
    that it is read-only and shared, where to write, and how it is run when the owner said."""
    if not applied:
        return []
    path = applied["path"]
    lines = ["## Project environment", "",
             f"The project `{applied['slug']}` is at `{path}` (also `$PROJECT_ROOT`). It is READ-ONLY and shared "
             "with other sessions: its files are complete and its dependencies are already installed "
             "(its Python virtualenv and node_modules are on your PATH; `python3` and `node` from your "
             "shell use them), so do not install packages or copy the project to start. Do not try to "
             "write under it: write every output, log and scratch file to your working directory, and "
             "copy a project file there first if you need to change it. Run the project's scripts by "
             f"their absolute path (for example `python3 {path}/<script>.py`) with your working directory "
             "as the current directory, so relative outputs land where the user sees them."]
    if applied.get("entry"):
        lines += ["", f"How the project is run: `{applied['entry']}`"]
    lines.append("")
    return lines


# ── routes (internal: the gateway drives these; the write-wall middleware in server.py guards them) ──
@router.get("/environments/{env_id}/tree")
def r_tree(env_id: str) -> dict:
    return {"entries": tree(env_id), **source_stat(env_id)}


@router.get("/environments/{env_id}/source")
def r_read(env_id: str, path: str) -> Response:
    data, ctype = read_file(env_id, path)
    return Response(content=data, media_type=ctype)


@router.put("/environments/{env_id}/source")
async def r_write(env_id: str, path: str, request: Request) -> dict:
    data = await request.body()
    # Off the event loop, as the import is: a write waits for the source lock while a build
    # snapshots the source, and the runner answers every turn from this one loop.
    return await asyncio.to_thread(write_file, env_id, path, data)


@router.post("/environments/{env_id}/mkdir")
def r_mkdir(env_id: str, path: str) -> dict:
    return make_dir(env_id, path)


@router.delete("/environments/{env_id}/source")
def r_delete(env_id: str, path: str) -> dict:
    return delete_path(env_id, path)


@router.post("/environments/{env_id}/import")
async def r_import(env_id: str, request: Request, replace: int = 0, git_url: str = "", git_ref: str = "") -> dict:
    # The clone, the extraction and the wait for the source lock all run in a worker thread. Called
    # here directly they ran on the event loop the runner answers every turn from, so a git import
    # froze the whole runner for as long as the clone took (its /healthz answered in 4.3 s during
    # a 4.6 s import of django; a clone may take up to ten minutes).
    if git_url:
        # git_pin: host:port:address the gateway classified, on a shared deployment (_git_pin_args)
        return await asyncio.to_thread(import_git, env_id, git_url, git_ref, replace=bool(replace),
                                       pin=str(request.query_params.get("git_pin") or ""))
    fd, spool = tempfile.mkstemp(prefix="hr-env-import-")
    try:
        with os.fdopen(fd, "wb") as out:
            async for chunk in request.stream():
                if chunk:
                    out.write(chunk)
        return await asyncio.to_thread(import_archive, env_id, spool, replace=bool(replace))
    finally:
        try:
            os.unlink(spool)
        except OSError:
            pass


@router.get("/environments/runtimes")
def r_runtimes() -> dict:
    return runtimes()


@router.get("/environments/packages/check")
def r_check_package(manager: str, spec: str) -> dict:
    return check_package(manager, spec)


@router.post("/environments/{env_id}/build")
async def r_build(env_id: str, version: int, slug: str, request: Request, activate: int = 1) -> dict:
    if not slug_ok(slug):
        raise HTTPException(400, "environment slug is not a path segment")
    raw = await request.body()
    try:
        spec = json.loads(raw) if raw else {}
    except ValueError:
        raise HTTPException(400, "the build body is not JSON")
    return start_build(env_id, int(version), slug, bool(activate), spec if isinstance(spec, dict) else {})


@router.get("/environments/{env_id}/build")
def r_build_status(env_id: str, version: int) -> dict:
    rec = build_record(env_id, int(version))
    if not rec:
        raise HTTPException(404, "no such build")
    return _as_read(env_id, int(version), rec)


@router.get("/environments/{env_id}/versions")
def r_versions(env_id: str) -> dict:
    return {"versions": versions(env_id), "active": active_version(env_id)}


@router.post("/environments/{env_id}/activate")
def r_activate(env_id: str, version: int, slug: str) -> dict:
    return activate_version(env_id, int(version), slug)


@router.delete("/environments/{env_id}")
def r_delete_env(env_id: str, slug: str = "") -> dict:
    return delete_environment(env_id, slug)


@router.delete("/environments/{env_id}/mount")
def r_unmount_env(env_id: str, slug: str) -> dict:
    """A deleted environment, kept for 30 days: its files stay, its path goes."""
    drop_mount(slug, env_id)
    return {"id": env_id, "mounted": False}


@router.get("/environments/{env_id}")
def r_get(env_id: str) -> JSONResponse:
    return JSONResponse({"id": env_id, "source": source_stat(env_id), "versions": versions(env_id),
                         "active": active_version(env_id), "root": ENV_ROOT})