Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

23.7 KB
Raw Blame
#!/usr/bin/env python3
"""Attested Pilot build reuse and explicit owner/session lifecycle (execution host)."""
import argparse
import contextlib
import hashlib
import importlib.util
import io
import json
import os
from pathlib import Path
import platform
import re
import shutil
import signal
import stat
import subprocess
import sys
import time
import types
import uuid

sys.dont_write_bytecode = True


def module(name):
    spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
    value = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(value)
    return value


local = module("local-rust")
pilot = module("desktop-pilot")
COMMAND = ["cargo", "build", "--locked", "-p", "hiroute-desktop", "-p", "hiroute-daemon",
           "-p", "hiroute-cli", "--features", "hiroute-desktop/desktop-pilot",
           "--bin", "hiroute-desktop", "--bin", "hirouted", "--bin", "hiroute"]
DRIVERS = ("pilot-builds.py", "local-rust.py", "remote-rust.py", "desktop-pilot.py", "pilot-native-app.py", "validation-report.py")
VERDICTS = ("green", "red", "expected_red", "not_executed")
DEFAULT_CPA_MANIFEST = Path("apps/desktop/src-tauri/development-cpa-artifacts.v1.json")


def digest(value):
    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()


def tree_digest(root):
    """Content hash, rejecting links/special files instead of following them."""
    root = Path(root)
    local.identity(root)
    entries = []
    for path in sorted(root.rglob("*")):
        if path.is_symlink() or not (path.is_dir() or path.is_file()):
            raise ValueError("Frontend contains a link or special file")
        if path.is_file():
            entries.append([str(path.relative_to(root)), pilot.file_sha256(path)])
    if not entries or not (root / "index.html").is_file():
        raise ValueError("Frontend output is empty or has no index.html")
    return digest(entries)


def validate_cpa_manifest(contents):
    def reject_constant(value):
        raise ValueError("Non-finite JSON constant: " + value)

    try:
        value = json.loads(contents.decode("utf-8"), parse_constant=reject_constant)
    except (UnicodeDecodeError, ValueError):
        raise ValueError("CPA manifest must be a UTF-8 JSON object") from None
    if not isinstance(value, dict):
        raise ValueError("CPA manifest must be a UTF-8 JSON object")


def read_cpa_manifest(path):
    """Read one stable regular file without following a final-component link."""
    path = Path(path)
    try:
        before = path.lstat()
        if path.is_symlink() or not stat.S_ISREG(before.st_mode):
            raise ValueError("CPA manifest must be a real regular file")
        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
        with os.fdopen(descriptor, "rb") as source:
            opened = os.fstat(source.fileno())
            if not stat.S_ISREG(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino):
                raise ValueError("CPA manifest changed while opening")
            contents = source.read()
            after = os.fstat(source.fileno())
        final = path.lstat()
    except OSError:
        raise ValueError("CPA manifest is missing or unreadable") from None
    identity = lambda item: (item.st_dev, item.st_ino, item.st_mode, item.st_size,
                             item.st_mtime_ns, item.st_ctime_ns)
    if path.is_symlink() or not stat.S_ISREG(final.st_mode) or not (
            identity(before) == identity(opened) == identity(after) == identity(final)):
        raise ValueError("CPA manifest changed while reading")
    validate_cpa_manifest(contents)
    return contents


def candidate_cpa_manifest(repo, sha):
    relative = DEFAULT_CPA_MANIFEST.as_posix()
    try:
        entry = subprocess.check_output(
            ["git", "-C", str(repo), "ls-tree", sha, "--", relative], text=True, timeout=30).strip()
        fields = entry.split(None, 3)
        if len(fields) != 4 or fields[:2] not in (["100644", "blob"], ["100755", "blob"]):
            raise ValueError
        contents = subprocess.check_output(
            ["git", "-C", str(repo), "show", sha + ":" + relative], timeout=30)
    except (OSError, ValueError, subprocess.SubprocessError):
        raise ValueError("Candidate default CPA manifest is missing or not a regular file") from None
    validate_cpa_manifest(contents)
    return contents


def select_cpa_manifest(repo, sha):
    selected = os.environ.get("HIROUTE_CPA_MANIFEST")
    if selected is None:
        return candidate_cpa_manifest(repo, sha)
    try:
        supplied = Path(selected)
        path = supplied if supplied.is_absolute() else repo / DEFAULT_CPA_MANIFEST.parent / supplied
        path = Path(os.path.abspath(path))
    except (OSError, TypeError, ValueError):
        raise ValueError("HIROUTE_CPA_MANIFEST does not identify a valid CPA manifest") from None
    return read_cpa_manifest(path)


def build_recipe(repo, sha, jobs, cpa_manifest=None):
    # These are the only inherited knobs supported by this fixed build profile.
    # Values may contain private paths/flags; persist their digest, not plaintext.
    knobs = {k: v for k, v in os.environ.items() if
             k.startswith(("CARGO_", "RUST", "VITE_", "npm_config_", "NPM_CONFIG_", "CC_", "CXX_",
                           "CMAKE_", "PKG_CONFIG_", "OPENSSL_"))
             or k in ("PATH", "SDKROOT", "MACOSX_DEPLOYMENT_TARGET", "CC", "CXX", "CFLAGS",
                      "CXXFLAGS", "CPPFLAGS", "LDFLAGS", "ARCHFLAGS", "NODE_ENV", "NODE_OPTIONS")}
    for forbidden in ("CARGO_TARGET_DIR", "CARGO_BUILD_TARGET_DIR", "TAURI_CONFIG"):
        if forbidden in os.environ:
            raise ValueError("Remove " + forbidden + " before acquiring a reusable Pilot build")
    toolchain = local.git(repo, "show", sha + ":rust-toolchain.toml")
    if (repo / "rust-toolchain.toml").read_text().strip() != toolchain:
        raise ValueError("Execution checkout toolchain differs from candidate; select a matching checkout")
    versions = {}
    for command in (["cargo", "--version"], ["rustc", "-vV"], ["node", "--version"], ["npm", "--version"],
                    ["cc", "--version"], ["cmake", "--version"], ["sccache", "--version"]):
        versions[command[0]] = subprocess.check_output(command, cwd=repo, text=True, timeout=30).strip()
    if sys.platform == "darwin":
        versions["sdk"] = subprocess.check_output(["xcrun", "--show-sdk-version"], text=True, timeout=30).strip()
        versions["sdk_path"] = subprocess.check_output(["xcrun", "--show-sdk-path"], text=True, timeout=30).strip()
    if cpa_manifest is None:
        cpa_manifest = select_cpa_manifest(repo, sha)
    return dict(sha=sha, origin=local.git(repo, "remote", "get-url", "origin"), command=COMMAND,
                profile="debug", jobs=jobs, toolchain=toolchain, tools=versions,
                platform=[sys.platform, platform.machine(), platform.release()], environment=digest(knobs),
                cpa_manifest={"sha256": hashlib.sha256(cpa_manifest).hexdigest()},
                drivers={name: pilot.file_sha256(Path(__file__).with_name(name)) for name in DRIVERS})


def run_step(argv, checkout, env, log, timeout, descriptors):
    with log.open("a") as output:
        process = local.remote.start_locked_command(argv, checkout, env, output, descriptors)
        try:
            code = process.wait(timeout=timeout)
        finally:
            if process.poll() is None:
                os.killpg(process.pid, signal.SIGKILL)
                process.wait()
        if code:
            raise RuntimeError("Frontend step failed (%s); inspect %s" % (code, log))


class Builds:
    def __init__(self, store=None):
        self.store = store or local.Store()
        pilot.LOCAL_RUST_ROOT = self.store.root
        self.root = self.store.root / "pilot-builds"
        self.root.mkdir(exist_ok=True, mode=0o700)
        local.identity(self.root)
        for name in ("keys", "leases"):
            (self.root / name).mkdir(exist_ok=True, mode=0o700)
            local.identity(self.root / name)

    @contextlib.contextmanager
    def locked(self, key):
        if not re.fullmatch(r"[a-f0-9]{64}", key):
            raise ValueError("Invalid build key")
        with (self.root / "keys" / (key + ".lock")).open("a") as handle:
            local.remote.fcntl.flock(handle, local.remote.fcntl.LOCK_EX | local.remote.fcntl.LOCK_NB)
            yield

    def index(self, key):
        return self.root / "keys" / (key + ".json")

    def locate(self, lease):
        if not re.fullmatch(r"[a-f0-9]{32}", lease):
            raise ValueError("Invalid lease ID")
        link = json.loads((self.root / "leases" / (lease + ".json")).read_text())
        row = self.store.load(link["run"])
        if row["pilot_reuse"]["key"] != link["key"] or lease not in row["pilot_leases"]:
            raise ValueError("Lease/build identity mismatch")
        return row

    def prepare(self, timeout, manifest):
        def frontend(checkout, env, row, descriptors):
            run = self.store.record_path(row["id"]).parent
            # Cargo consumes these verified bytes even if the borrowed source changes
            # while npm/Cargo run. Only the build-owned snapshot survives ingestion.
            snapshot = run / "cpa-manifest.json"
            with snapshot.open("xb") as output:
                os.chmod(snapshot, 0o600)
                output.write(manifest)
            env["HIROUTE_CPA_MANIFEST"] = str(snapshot)
            log = run / "frontend.log"
            env["PYTHONDONTWRITEBYTECODE"] = "1"
            for argv in (["npm", "--prefix", "apps/desktop", "ci"],
                         ["npm", "--prefix", "apps/desktop", "run", "build"]):
                run_step(argv, checkout, env, log, timeout, descriptors)
            dist = checkout / "apps/desktop/dist"
            row["pilot_frontend"] = {"sha256": tree_digest(dist)}
            saved = run / "frontend-dist"
            shutil.copytree(dist, saved)
            row["pilot_frontend"]["path"] = str(saved)
            env["TAURI_CONFIG"] = subprocess.check_output(
                [sys.executable, str(checkout / "scripts/desktop-pilot.py"), "config",
                 "--frontend-dist", str(dist)], cwd=checkout, env=env, text=True, timeout=30).strip()
            row["pilot_frontend"]["tauri_config_sha256"] = hashlib.sha256(env["TAURI_CONFIG"].encode()).hexdigest()
            row["pilot_frontend"]["generated"] = {
                str(path.relative_to(checkout)): local.identity(path)
                for path in (checkout / "apps/desktop/node_modules", dist) if path.exists()}
        return frontend

    def discard_generated(self, row):
        checkout = Path(row["checkout"])
        if local.identity(checkout) != row["identity"] or local.git(checkout, "status", "--porcelain", "--untracked-files=no"):
            raise ValueError("Build checkout changed; generated files retained")
        generated = dict(row["pilot_frontend"]["generated"])
        native = checkout / "apps/desktop/src-tauri/gen"
        if native.exists():
            generated[str(native.relative_to(checkout))] = local.identity(native)
        for relative, expected in generated.items():
            if relative not in ("apps/desktop/node_modules", "apps/desktop/dist", "apps/desktop/src-tauri/gen"):
                raise ValueError("Unexpected generated directory")
            path = checkout / relative
            if local.identity(path) != expected or local.git(checkout, "ls-files", relative):
                raise ValueError("Generated directory identity changed or contains tracked files")
            shutil.rmtree(path)  # Owned generated root; rmtree does not follow contained npm links.
        row["pilot_frontend"]["generated_removed"] = True

    def verify(self, row, recipe):
        if row["pilot_reuse"]["recipe"] != recipe or row["command"] != COMMAND:
            raise ValueError("Build inputs differ")
        snapshot = self.store.record_path(row["id"]).parent / "cpa-manifest.json"
        if hashlib.sha256(read_cpa_manifest(snapshot)).hexdigest() != recipe["cpa_manifest"]["sha256"]:
            raise ValueError("Compiled CPA manifest snapshot changed")
        self.store.verify(row)
        build = pilot.verify_managed_pilot_build(row["id"], str(Path(row["checkout"]) / "target/debug/hiroute-desktop"), row["sha"])
        if build["artifacts"] != row["pilot_reuse"]["artifacts"]:
            raise ValueError("Reusable executable identity/content changed")
        frontend = row["pilot_frontend"]
        expected = self.store.record_path(row["id"]).parent / "frontend-dist"
        if Path(frontend["path"]) != expected or tree_digest(expected) != frontend["sha256"]:
            raise ValueError("Reusable frontend content changed")
        return build

    def acquire(self, args):
        cases = sorted(set(args.case))
        if not cases or len(cases) != len(args.case) or not args.owner.strip() or any(not c.strip() or "=" in c for c in cases):
            raise ValueError("Declare a nonempty owner and distinct required cases")
        if args.jobs < 1 or args.timeout <= 0:
            raise ValueError("jobs/timeout must be positive")
        repo = Path(args.repo).resolve(strict=True)
        local.remote.validate(args.ref, args.sha, COMMAND)
        os.environ["PATH"] = local.toolchain_environment()
        ref = "refs/hiroute-pilot/" + uuid.uuid4().hex
        try:
            local.git(repo, "fetch", "--no-tags", "origin", args.ref + ":" + ref)
            local.git(repo, "merge-base", "--is-ancestor", args.sha, ref)
        finally:
            local.git(repo, "update-ref", "-d", ref)
        manifest = select_cpa_manifest(repo, args.sha)
        recipe = build_recipe(repo, args.sha, args.jobs, manifest)
        key = digest(recipe)
        with self.locked(key):
            index = self.index(key)
            row = self.store.load(json.loads(index.read_text())["run"]) if index.exists() else None
            reused = bool(row and not row.get("removed"))
            if reused:
                if not row.get("pilot_reuse"):
                    raise ValueError("Previous build failed/interrupted; inspect retained run " + row["id"])
                with self.store.locked(row["checkout"]):
                    self.verify(row, recipe)
            else:
                run_args = types.SimpleNamespace(repo=str(repo), ref=args.ref, sha=args.sha, source="origin",
                                                jobs=args.jobs, command=COMMAND, keep=True, cargo_only=False, timeout=args.timeout)
                row = local.run(self.store, run_args, prepare=self.prepare(args.timeout, manifest),
                                on_record=lambda record: local.remote.save(index, {"run": record["id"], "key": key}))
                if row.get("process_exit") != 0 or row.get("error") or row.get("scenario") != "unassessed":
                    raise ValueError("Pilot build failed/unknown; retained run " + row["id"])
                with self.store.locked(row["checkout"]):
                    self.discard_generated(row)
                    self.store.save(row)
                    build = pilot.verify_managed_pilot_build(row["id"], str(Path(row["checkout"]) / "target/debug/hiroute-desktop"), args.sha)
                    row["pilot_reuse"] = {"key": key, "recipe": recipe, "artifacts": build["artifacts"]}
                    row["pilot_leases"] = {}
                    row["pilot_cleanup_ready"] = False
                    self.store.save(row)
                    self.verify(row, recipe)
            with self.store.locked(row["checkout"]):
                # An open lease is durable ownership, not inferred from a process scan.
                for lease, owner in row["pilot_leases"].items():
                    if owner["owner"] == args.owner and owner["state"] == "open":
                        if owner["cases"] != cases:
                            raise ValueError("Owner already acquired this build with different cases")
                        break
                else:
                    lease = uuid.uuid4().hex
                    row["pilot_leases"][lease] = dict(owner=args.owner, cases=cases, sessions={}, state="open")
                row.update(keep=True, evidence_saved=False, pilot_cleanup_ready=False)
                self.store.save(row)
                local.remote.save(self.root / "leases" / (lease + ".json"), {"run": row["id"], "key": key})
            return dict(lease=lease, build_run=row["id"], reused=reused, source_sha=row["sha"],
                        checkout=row["checkout"], cases=cases, scenario="unassessed")

    def start(self, args):
        if getattr(args, "native_app", False) and sys.platform != "darwin":
            raise ValueError("--native-app requires macOS LaunchServices")
        row = self.locate(args.lease)
        with self.locked(row["pilot_reuse"]["key"]), self.store.locked(row["checkout"]):
            row = self.store.load(row["id"])
            owner = row["pilot_leases"][args.lease]
            if owner["state"] != "open" or args.case not in owner["cases"]:
                raise ValueError("Closed lease or undeclared case")
            build = self.verify(row, row["pilot_reuse"]["recipe"])
            if getattr(args, "native_app", False):
                pilot.native_app_module().staged_cpa(build)
            if args.case in owner["sessions"]:
                raise ValueError("Case already started; inspect its recorded session instead of duplicating it")
            root = Path("/tmp").resolve() / ("hrp-" + uuid.uuid4().hex[:12])
            entry = {"session": str(root / "session.json"), "state": "starting"}
            owner["sessions"][args.case] = entry
            self.store.save(row)  # Crash during launch leaves durable unknown ownership.
            launch = pilot.build_parser().parse_args([
                "start", "--app", str(Path(row["checkout"]) / "target/debug/hiroute-desktop"),
                "--build-run", row["id"], "--source-sha", row["sha"], "--root", str(root),
                "--timeout", str(args.timeout),
                *(["--native-app"] if getattr(args, "native_app", False) else []),
                *(["--data-root", args.data_root] if args.data_root else []),
                *(["--process-home", args.process_home] if args.process_home else [])])
            launch.managed_lease = args.lease
            output = io.StringIO()
            with contextlib.redirect_stdout(output):
                pilot.start(launch)
            entry["state"] = "ready"
            self.store.save(row)
            return json.loads(output.getvalue())

    def finish(self, args):
        values = {}
        for assessment in args.case:
            case, separator, verdict = assessment.partition("=")
            if not separator or case in values or verdict not in VERDICTS:
                raise ValueError("Expected distinct CASE=green/red/expected_red/not_executed assessments")
            values[case] = verdict
        if not args.evidence_saved:
            raise ValueError("Confirm unique debug evidence saved before releasing ownership")
        row = self.locate(args.lease)
        with self.locked(row["pilot_reuse"]["key"]):
            with self.store.locked(row["checkout"]):
                row = self.store.load(row["id"])
                owner = row["pilot_leases"][args.lease]
                if set(values) != set(owner["cases"]):
                    raise ValueError("Assess every declared case exactly once")
                if owner["state"] == "closed":
                    if values != owner["verdicts"]:
                        raise ValueError("Finished evidence cannot be rewritten")
                else:
                    for case, verdict in values.items():
                        entry = owner["sessions"].get(case)
                        if verdict == "green" and (not entry or entry["state"] != "ready"):
                            raise ValueError("Unstarted/unknown case cannot be green")
                        if entry:
                            _, session = pilot.read_session(entry["session"])
                            if session["build_run"] != row["id"] or session["source_sha"] != row["sha"]:
                                raise ValueError("Session belongs to another build")
                            pilot.stop_session(Path(entry["session"]), session, revoke=True)
                            diagnostics = pilot.diagnostics_index(Path(session["data_root"]))
                            if verdict == "green":
                                for role in ("desktop", "daemon"):
                                    applied = diagnostics["roles"][role].get("evidence", {}).get("level_applied")
                                    if not applied or applied.get("level") != "debug":
                                        raise ValueError("Green case needs both roles' actual Debug evidence")
                            entry["diagnostics"] = diagnostics
                    owner.update(state="closed", verdicts=values, evidence_saved=True, finished_at=time.time())
                    self.store.save(row)
                active = [lease for lease, value in row["pilot_leases"].items() if value["state"] != "closed"]
                if active:
                    return dict(build_run=row["id"], lease=args.lease, cleanup="retained", active_leases=active)
                outcomes = [v for value in row["pilot_leases"].values() for v in value["verdicts"].values()]
                scenario = ("red" if "red" in outcomes else "unassessed" if "not_executed" in outcomes
                            else "expected_red" if "expected_red" in outcomes else "green")
                row.update(scenario=scenario, evidence_saved=True, keep=False, pilot_cleanup_ready=True)
                self.store.save(row)
            if row.get("removed"):
                return dict(build_run=row["id"], lease=args.lease, cleanup="removed", scenario=row["scenario"])
            candidate = self.store.preview_one(row)
            if candidate["state"] != "candidate":
                return dict(build_run=row["id"], lease=args.lease, cleanup="retained", reason=candidate.get("reason"))
            result = self.store.apply(row["id"], candidate["token"])
            return dict(build_run=row["id"], lease=args.lease, cleanup=result["state"], scenario=row["scenario"])


def main():
    os.umask(0o077)
    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest="action", required=True)
    acquire = sub.add_parser("acquire")
    acquire.add_argument("--repo", default=".")
    acquire.add_argument("--ref", required=True)
    acquire.add_argument("--sha", required=True)
    acquire.add_argument("--owner", required=True)
    acquire.add_argument("--case", action="append", required=True)
    acquire.add_argument("--jobs", type=int, default=2)
    acquire.add_argument("--timeout", type=int, default=3600)
    start = sub.add_parser("start")
    start.add_argument("--lease", required=True)
    start.add_argument("--case", required=True)
    start.add_argument("--data-root")
    start.add_argument("--process-home")
    start.add_argument("--native-app", action="store_true")
    start.add_argument("--timeout", type=float, default=240)
    finish = sub.add_parser("finish")
    finish.add_argument("--lease", required=True)
    finish.add_argument("--case", action="append", required=True)
    finish.add_argument("--evidence-saved", action="store_true", required=True)
    sub.add_parser("status").add_argument("--lease", required=True)
    args = parser.parse_args()
    builds = Builds()
    result = builds.locate(args.lease) if args.action == "status" else getattr(builds, args.action)(args)
    print(json.dumps(result, indent=2))
    if args.action == "finish" and result["cleanup"] == "retained" and not result.get("active_leases"):
        return 1
    return 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except (ValueError, KeyError, OSError, RuntimeError, subprocess.SubprocessError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(2)