autop-runner 0.1.0__py3-none-any.whl

autop_runner/__init__.py

@@ -0,0 +1,19 @@
+"""Autop runner — the customer-side executor (installs the `autop` command).
+
+It dials out to the control plane, claims leased jobs, and runs every
+LLM-backed Autopilot flow locally with the customer's own clones, worktrees,
+and coding-agent CLI. It never holds a GitHub App key and never reads the
+provider credential the CLI uses.
+
+Modules (see `~/Projects/ATC/specs/001-atc-platform/plan.md`):
+
+- `cli`          — `autop runner enroll | run | status | drain`
+- `config`       — local, non-secret runner config (schema v1)
+- `protocol`     — protocol version range and message constants
+- `client`       — register/claim/heartbeat/events/complete/fail/abandon (phase 2)
+- `executor/`    — extracted from the Autopilot core's `dispatcher.py` (phase 3)
+- `credentials/` — git credential helper + gh wrapper fetching per-job tokens (phase 3)
+- `hooks/`       — Claude Code hooks ported from the core (phase 3)
+"""
+
+__version__ = "0.1.0"

autop_runner/cli.py

@@ -0,0 +1,429 @@
+"""`autop` command line.
+
+The customer-facing entrypoint. Runner operations live under `autop runner`;
+authoring helpers are sibling groups: `autop issue` files
+backlog work as the person's own `gh` login (`issues.py`), `autop skills`
+installs the public Agent Skills (`skills.py`).
+
+* `setup`  — the interactive install: preflight, questions, files, enrollment,
+  start (D67; the one-liner's `install.sh` ends in this command).
+* `status` — local readiness, no network.
+* `enroll`  — exchange the console's one-time token for the runner credential
+  (saved 0600, never printed).
+* `run`     — register and claim/execute until stopped; SIGTERM/SIGINT drain
+  (finish current work, claim nothing new, exit).
+* `drain`   — send that SIGTERM to the running `autop runner run`.
+
+Execution mode (FR-026): `run` requires `AUTOP_EXECUTION`. The container
+image sets `container` (the default install, deploy/Dockerfile). Running the
+agents directly on the host needs the explicit `direct-host` opt-in and prints
+why that is discouraged: the agent CLIs run with permission prompts skipped
+(the core's `--dangerously-skip-permissions`, guarded by hooks and PATH
+shims), and provider terms expect such runs to be confined.
+
+Exit codes: 0 ok, 1 local configuration error, 4 credential rejected (re-enroll),
+5 protocol incompatible (upgrade), 2 usage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import logging
+import os
+import pathlib
+import platform
+import signal
+import sys
+
+from autop_runner import __version__, credstore, issues, skills
+from autop_runner.client import Incompatible, PlaneClient, PlaneError, Unauthorized
+from autop_runner.config import ConfigError, RunnerConfig
+from autop_runner.protocol import PROTOCOL_MAX, PROTOCOL_MIN
+from autop_runner.setup.wizard import Answers, run_setup
+from autop_runner.worker import EXIT_INCOMPATIBLE, EXIT_UNAUTHORIZED, Worker
+
+DEFAULT_CONFIG = pathlib.Path("~/.autop/runner.json").expanduser()
+PID_FILE = pathlib.Path("~/.autop/runner.pid").expanduser()
+ENV_ENROLL_TOKEN = "AUTOP_ENROLL_TOKEN"
+
+# Customer-facing environment (secrets live only here, never in the config file).
+ENV_URL = "AUTOP_URL"
+ENV_RUNNER_ID = "AUTOP_RUNNER_ID"
+ENV_RUNNER_TOKEN = "AUTOP_RUNNER_TOKEN"
+ENV_EXECUTION = "AUTOP_EXECUTION"
+EXECUTION_MODES = ("container", "direct-host")
+
+DIRECT_HOST_WARNING = (
+    "WARNING: direct-host execution. Agent CLIs run on this machine with "
+    "permission prompts skipped, confined only by Autop's hooks and command "
+    "guards, with access to everything your user can read. Provider terms "
+    "expect permission-skipped runs to be sandboxed; the container install "
+    "(deploy/compose.yml) is the supported default."
+)
+UNSET_EXECUTION = (
+    f"run: {ENV_EXECUTION} is not set. Autop runs agents in a container by "
+    "default (see deploy/INSTALL.md in the runner package). To run agents "
+    f"directly on this host anyway, set {ENV_EXECUTION}=direct-host."
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="autop", description="Autop command line.")
+    p.add_argument("--version", action="version", version=f"autop {__version__}")
+    groups = p.add_subparsers(dest="group", required=True)
+
+    runner = groups.add_parser("runner", help="operate this machine's Autop runner")
+    runner.add_argument(
+        "--config",
+        type=pathlib.Path,
+        default=DEFAULT_CONFIG,
+        help=f"runner config file (default {DEFAULT_CONFIG})",
+    )
+    sub = runner.add_subparsers(dest="command", required=True)
+    for name, help_ in (
+        ("status", "print local readiness without contacting Autop"),
+        ("enroll", "exchange a one-time enrollment token for a credential"),
+        ("run", "claim and execute jobs until stopped"),
+        ("drain", "stop claiming, finish current work, exit"),
+    ):
+        sp = sub.add_parser(name, help=help_)
+        # Accept --config after the subcommand too; people type it both ways.
+        sp.add_argument(
+            "--config", type=pathlib.Path, dest="config_after", default=None
+        )
+        sp.add_argument(
+            "--credential-file",
+            type=pathlib.Path,
+            default=credstore.DEFAULT_PATH,
+            help=f"runner credential (default {credstore.DEFAULT_PATH})",
+        )
+        if name == "enroll":
+            sp.add_argument("--url", help=f"Autop API URL (or {ENV_URL})")
+            sp.add_argument(
+                "--token-stdin",
+                action="store_true",
+                help=f"read the enrollment token from stdin (else {ENV_ENROLL_TOKEN} "
+                "or a hidden prompt)",
+            )
+        if name == "run":
+            sp.add_argument(
+                "--once", action="store_true", help="run a single job, then exit"
+            )
+    # `setup` stays out of that loop: it derives the config and credential paths
+    # from the layout it installs (container and direct host differ, D64), so
+    # --config / --credential-file would be two ways to say the same thing.
+    st = sub.add_parser(
+        "setup", help="install and configure this machine's runner interactively"
+    )
+    st.add_argument("--url", help=f"Autop API URL (or {ENV_URL})")
+    st.add_argument(
+        "--execution",
+        choices=EXECUTION_MODES,
+        default="container",
+        help="where agents run (default container)",
+    )
+    st.add_argument(
+        "--repos-dir", type=pathlib.Path, help="directory holding your clones"
+    )
+    st.add_argument("--image", help="runner image to pin (default the published one)")
+    st.add_argument(
+        "--build", action="store_true", help="build the image from this checkout"
+    )
+    st.add_argument(
+        "--upgrade", action="store_true", help="re-pin the image and restart"
+    )
+    st.add_argument(
+        "--yes", action="store_true", help="no questions: flags and environment only"
+    )
+    _issue_parser(groups)
+    _skills_parser(groups)
+    return p
+
+
+def _issue_parser(groups) -> None:
+    issue = groups.add_parser(
+        "issue", help="file backlog work for Autop with your own gh login"
+    )
+    sub = issue.add_subparsers(dest="issue_command", required=True)
+    add = sub.add_parser(
+        "add", help="create an issue, label it, put it on the board as Todo, link it"
+    )
+    add.add_argument("--board", required=True, help="<org>/<number> or the board URL")
+    add.add_argument("--repo", required=True, help="owner/repo to file in")
+    add.add_argument("--title", required=True)
+    add.add_argument(
+        "--body-file", required=True, help="Markdown body ('-' reads stdin)"
+    )
+    add.add_argument("--priority", required=True, choices=issues.PRIORITIES)
+    add.add_argument(
+        "--spec", help="owner/<project>-autopilot@<sha>:specs/…/spec.md#user-story-N"
+    )
+    add.add_argument("--epic", action="store_true", help="label it an epic")
+    add.add_argument(
+        "--human", action="store_true", help="human-task: Autop never picks it"
+    )
+    add.add_argument("--parent", help="epic to attach to as a native sub-issue")
+    add.add_argument(
+        "--blocked-by",
+        action="append",
+        metavar="REF",
+        help="blocking issue (repeatable): native link plus a Blocked-by: line",
+    )
+    link = sub.add_parser("link", help="add sub-issue/blocked-by links to an issue")
+    link.add_argument("issue", help="owner/repo#N or URL")
+    link.add_argument("--parent")
+    link.add_argument("--blocked-by", action="append", metavar="REF")
+    labels = sub.add_parser("labels", help="create or refresh Autop's labels")
+    labels.add_argument("repos", nargs="+", metavar="owner/repo")
+    subs = sub.add_parser("subs", help="list an epic's native sub-issues")
+    subs.add_argument("epic", help="owner/repo#N or URL")
+
+
+def _skills_parser(groups) -> None:
+    sk = groups.add_parser("skills", help="install public Autop Agent Skills")
+    sub = sk.add_subparsers(dest="skills_command", required=True)
+    listing = sub.add_parser("list", help="list installed managed skills")
+    listing.add_argument("--target", choices=("all", *skills.TARGETS), default="all")
+    listing.add_argument(
+        "--dest", type=pathlib.Path, help="list this directory instead"
+    )
+    inst = sub.add_parser(
+        "install", help="copy them into ~/.claude/skills and ~/.agents/skills"
+    )
+    inst.add_argument("--ref", help="pin a tag or commit instead of following main")
+    inst.add_argument("--target", choices=("all", *skills.TARGETS), default="all")
+    inst.add_argument(
+        "--dest", type=pathlib.Path, help="install into this directory instead"
+    )
+
+
+def cmd_status(config_path: pathlib.Path) -> int:
+    print(f"autop {__version__}")
+    print(f"protocol {PROTOCOL_MIN}..{PROTOCOL_MAX}")
+    print(f"os {platform.system().lower()} {platform.machine()}")
+    print(f"{ENV_URL} {'set' if os.environ.get(ENV_URL) else 'unset'}")
+    print(f"execution {execution_mode() or f'unset (set {ENV_EXECUTION})'}")
+    print(
+        f"{ENV_RUNNER_TOKEN} {'set' if os.environ.get(ENV_RUNNER_TOKEN) else 'unset'}"
+    )
+    cred_path = credstore.DEFAULT_PATH
+    print(f"credential {cred_path}: {'present' if cred_path.exists() else 'absent'}")
+    try:
+        cfg = RunnerConfig.load(config_path)
+    except ConfigError as exc:
+        print(f"config {config_path}: {exc}")
+        return 1
+    ready_repos = cfg.ready_repos()
+    ready = {r.full_name for r in ready_repos}
+    print(
+        f"config {config_path}: ok (name={cfg.name}, max_jobs={cfg.max_concurrent_jobs})"
+    )
+    explicit = {r.full_name for r in cfg.repos}
+    for r in cfg.repos:
+        # Same test as registration (`ready_repos`): a checkout, not a directory.
+        if r.full_name in ready:
+            state = "ready"
+        elif r.workspace.is_dir():
+            state = "not a clone (no .git)"
+        else:
+            state = "workspace missing"
+        print(f"  repo {r.full_name}: {state}")
+    for r in ready_repos:
+        if r.full_name not in explicit:
+            print(f"  repo {r.full_name}: ready (discovered)")
+    if cfg.repos_dir is not None:
+        print(f"  repos_dir {cfg.repos_dir}")
+    print(f"  runtimes {', '.join(cfg.runtimes) or '(none)'}")
+    return 0
+
+
+def _client(url: str, token: str) -> PlaneClient:
+    """Seam for tests (they substitute an in-process fake plane)."""
+    return PlaneClient(url, token)
+
+
+def report(cfg: RunnerConfig) -> dict:
+    """What this machine offers: only ready repos, only configured runtimes.
+    The plane intersects it with the tenant's policy (it can only narrow)."""
+    return {
+        "name": cfg.name,
+        "os": platform.system().lower(),
+        "arch": platform.machine(),
+        "labels": list(cfg.labels),
+        "max_concurrent_jobs": cfg.max_concurrent_jobs,
+        "repos_ready": sorted(r.full_name for r in cfg.ready_repos()),
+        "runtimes_ready": list(cfg.runtimes),
+    }
+
+
+def cmd_enroll(args, config_path: pathlib.Path) -> int:
+    url = args.url or os.environ.get(ENV_URL)
+    if not url:
+        print(f"enroll: pass --url or set {ENV_URL}")
+        return 1
+    try:
+        cfg = RunnerConfig.load(config_path)
+    except ConfigError as exc:
+        print(f"config {config_path}: {exc}")
+        return 1
+    if args.token_stdin:
+        token = sys.stdin.readline().strip()
+    else:
+        token = os.environ.get(ENV_ENROLL_TOKEN) or getpass.getpass(
+            "Enrollment token: "
+        )
+    if not token.startswith("autop_enroll_"):
+        print("enroll: that is not an Autop enrollment token (autop_enroll_…)")
+        return 1
+    try:
+        client = _client(url, token)
+        reg = client.register(report(cfg))
+    except ValueError as exc:
+        print(f"enroll: {exc}")
+        return 1
+    except Unauthorized:
+        print(
+            "enroll: the token was rejected (used, expired, or revoked); "
+            "create a new one in the console"
+        )
+        return EXIT_UNAUTHORIZED
+    except Incompatible as exc:
+        print(f"enroll: {exc}")
+        return EXIT_INCOMPATIBLE
+    except PlaneError as exc:
+        print(f"enroll: {exc}")
+        return 1
+    if not reg.get("enrolled"):
+        print("enroll: Autop did not issue a credential")
+        return 1
+    credstore.save(
+        args.credential_file,
+        credstore.Credential(
+            url=client.url, runner_id=reg["runner_id"], token=client.token
+        ),
+    )
+    client.close()
+    caps = reg.get("capabilities") or {}
+    print(
+        f"enrolled runner {reg['runner_id']}; credential saved to "
+        f"{args.credential_file}"
+    )
+    print(f"  repos {', '.join(caps.get('repos') or []) or '(none)'}")
+    print(f"  runtimes {', '.join(caps.get('runtimes') or []) or '(none)'}")
+    ignored = reg.get("ignored") or {}
+    if ignored.get("repos") or ignored.get("runtimes"):
+        print(f"  not permitted by your Autop policy: {ignored}")
+    return 0
+
+
+def execution_mode(env=None) -> str | None:
+    """`container` or `direct-host` when declared, else None (refuse)."""
+    mode = (os.environ if env is None else env).get(ENV_EXECUTION, "").strip()
+    return mode if mode in EXECUTION_MODES else None
+
+
+def cmd_run(args, config_path: pathlib.Path) -> int:
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    mode = execution_mode()
+    if mode is None:
+        print(UNSET_EXECUTION)
+        return 1
+    if mode == "direct-host":
+        print(DIRECT_HOST_WARNING, file=sys.stderr)
+        logging.getLogger("autop.runner").warning("execution mode: direct-host")
+    try:
+        cfg = RunnerConfig.load(config_path)
+        cred = credstore.load(args.credential_file)
+        client = _client(cred.url, cred.token)
+    except (ConfigError, credstore.CredentialError, ValueError) as exc:
+        print(f"run: {exc}")
+        return 1
+    from autop_runner.executor.registry import build_executors
+    from autop_runner.executor.settings import RuntimeSettings
+
+    executors = build_executors(cfg, RuntimeSettings.from_env())
+    worker = Worker(client, report(cfg), executors=executors)
+
+    def drain(signum, _frame):
+        logging.getLogger("autop.runner").info(
+            "signal %s: draining (finishing current work)", signum
+        )
+        worker.stop.set()
+
+    signal.signal(signal.SIGTERM, drain)
+    signal.signal(signal.SIGINT, drain)
+    pid_file = args.credential_file.parent / PID_FILE.name
+    pid_file.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    pid_file.write_text(str(os.getpid()))
+    try:
+        return worker.run(max_jobs=1 if args.once else None)
+    finally:
+        client.close()
+        if pid_file.exists() and pid_file.read_text() == str(os.getpid()):
+            pid_file.unlink()
+
+
+def cmd_drain(args) -> int:
+    pid_file = args.credential_file.parent / PID_FILE.name
+    try:
+        pid = int(pid_file.read_text())
+    except (FileNotFoundError, ValueError):
+        print("drain: no running runner found")
+        return 1
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        print("drain: the recorded runner is not running")
+        pid_file.unlink(missing_ok=True)
+        return 1
+    print(f"drain: asked runner (pid {pid}) to finish current work and exit")
+    return 0
+
+
+def cmd_setup(args) -> int:
+    url = args.url or os.environ.get(ENV_URL)
+    if not url:
+        print(f"setup: pass --url or set {ENV_URL}")
+        return 1
+    return run_setup(
+        Answers(
+            url=url,
+            mode=args.execution,
+            # The token may come from the environment (`install.sh` exports
+            # nothing; an unattended install may). It is never echoed.
+            token=os.environ.get(ENV_ENROLL_TOKEN),
+            repos_dir=args.repos_dir,
+            image=args.image,
+            build=args.build,
+            upgrade=args.upgrade,
+            assume_yes=args.yes,
+        )
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.group == "issue":
+        return issues.main(args)
+    if args.group == "skills":
+        return skills.main(args)
+    if args.group == "runner":
+        if args.command == "setup":
+            return cmd_setup(args)
+        config_path = args.config_after or args.config
+        if args.command == "status":
+            return cmd_status(config_path)
+        if args.command == "enroll":
+            return cmd_enroll(args, config_path)
+        if args.command == "run":
+            return cmd_run(args, config_path)
+        if args.command == "drain":
+            return cmd_drain(args)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

autop_runner/client.py

@@ -0,0 +1,240 @@
+"""Protocol client for `/api/runner/v1` (the plane's side is `atc/api/runner_v1.py`).
+
+Outbound HTTPS only (D2): the runner dials the plane; nothing dials the runner.
+Every failure maps to a typed exception so the worker can decide without
+parsing strings:
+
+* `Unauthorized` — credential unknown/revoked: stop; re-enroll.
+* `Incompatible` — disjoint protocol ranges (426): drain and exit.
+* `StaleLease(reason)` — this attempt no longer owns its job: stop the work,
+  send nothing further for it.
+* `SequenceGap(expected)` — resend events from `expected`.
+* `Refused(reason)` — the plane's 422: a tenancy rule refused the request
+  (for a publishing token: a paused project, unverified org ownership, a
+  repo outside the project, an uncovered repo). `reason` is the plane's
+  tenant-facing sentence, non-secret by construction (`atc.db.Rejected`).
+* `PlaneUnavailable` — network error or 5xx: retry with backoff. Every call is
+  safe to retry: claims carry a request id the plane replays, terminal reports
+  replay to the same answer, events are idempotent by sequence.
+
+The credential is sent only in the Authorization header and never appears in
+an exception message or `repr`.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+import httpx
+
+from autop_runner import __version__
+from autop_runner.protocol import PROTOCOL_MAX, PROTOCOL_MIN
+
+BUILD_TAG = f"autop-runner/{__version__}"
+_LOCAL_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+class PlaneError(RuntimeError):
+    pass
+
+
+class Unauthorized(PlaneError):
+    pass
+
+
+class Incompatible(PlaneError):
+    def __init__(self, plane_min: int, plane_max: int):
+        super().__init__(
+            f"protocol {PROTOCOL_MIN}..{PROTOCOL_MAX} is incompatible with the "
+            f"plane's {plane_min}..{plane_max}; upgrade autop-runner"
+        )
+        self.plane_min, self.plane_max = plane_min, plane_max
+
+
+class StaleLease(PlaneError):
+    def __init__(self, reason: str):
+        super().__init__(f"lease is {reason}")
+        self.reason = reason
+
+
+class SequenceGap(PlaneError):
+    def __init__(self, expected: int):
+        super().__init__(f"plane expects event sequence {expected}")
+        self.expected = expected
+
+
+class PlaneUnavailable(PlaneError):
+    pass
+
+
+class Refused(PlaneError):
+    def __init__(self, reason: str):
+        super().__init__(f"Autop refused: {reason}")
+        self.reason = reason
+
+
+def _refusal_reason(response: httpx.Response) -> str:
+    """The 422 body's `detail` (a `Rejected` message), bounded; never raw
+    bytes the plane did not mean to show."""
+    try:
+        detail = response.json().get("detail")
+    except (ValueError, AttributeError):
+        detail = None
+    return " ".join(str(detail).split())[:200] if isinstance(detail, str) else ""
+
+
+def check_url(url: str) -> str:
+    """HTTPS required (FR-008), except loopback for local development."""
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme == "https" and parsed.hostname:
+        return url.rstrip("/")
+    if parsed.scheme == "http" and parsed.hostname in _LOCAL_HOSTS:
+        return url.rstrip("/")
+    raise ValueError("AUTOP_URL must be https:// (http:// only for localhost)")
+
+
+class PlaneClient:
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 20,
+    ):
+        self.url = check_url(url)
+        self._token = token
+        self._http = httpx.Client(
+            transport=transport,
+            timeout=httpx.Timeout(timeout, read=timeout + 70),  # long-poll headroom
+            headers={"User-Agent": BUILD_TAG},
+            follow_redirects=False,
+        )
+
+    def __repr__(self) -> str:
+        return f"PlaneClient(url={self.url!r})"
+
+    @property
+    def token(self) -> str:
+        return self._token
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        try:
+            r = self._http.post(
+                f"{self.url}/api/runner/v1{path}",
+                json=body,
+                headers={"Authorization": f"Bearer {self._token}"},
+            )
+        except httpx.HTTPError as exc:
+            raise PlaneUnavailable(f"cannot reach Autop: {type(exc).__name__}") from exc
+        if r.status_code == 200:
+            return r.json()
+        if r.status_code == 401:
+            raise Unauthorized("the runner credential was rejected; re-enroll")
+        if r.status_code == 426:
+            data = r.json()
+            raise Incompatible(int(data["plane_min"]), int(data["plane_max"]))
+        if r.status_code == 409:
+            data = r.json()
+            if data.get("detail") == "stale_lease":
+                raise StaleLease(str(data.get("reason")))
+            if data.get("detail") == "sequence_gap":
+                raise SequenceGap(int(data["expected_sequence"]))
+        if r.status_code == 422:
+            reason = _refusal_reason(r)
+            if reason:
+                raise Refused(reason)
+        if r.status_code >= 500 or r.status_code == 429:
+            raise PlaneUnavailable(f"Autop answered {r.status_code} for {path}")
+        raise PlaneError(f"Autop answered {r.status_code} for {path}")
+
+    def _get_json(self, path: str) -> dict[str, Any] | None:
+        """GET for the installer's reads. `None` means the plane does not have
+        the route (a plane older than protocol 2), which is a fallback, not an
+        error."""
+        try:
+            r = self._http.get(
+                f"{self.url}/api/runner/v1{path}",
+                headers={"Authorization": f"Bearer {self._token}"},
+            )
+        except httpx.HTTPError as exc:
+            raise PlaneUnavailable(f"cannot reach Autop: {type(exc).__name__}") from exc
+        if r.status_code == 200:
+            return r.json()
+        if r.status_code == 404:
+            return None
+        if r.status_code == 401:
+            raise Unauthorized("the token was rejected (used, expired or revoked)")
+        if r.status_code >= 500 or r.status_code == 429:
+            raise PlaneUnavailable(f"Autop answered {r.status_code} for {path}")
+        raise PlaneError(f"Autop answered {r.status_code} for {path}")
+
+    # ── calls ────────────────────────────────────────────────────────────────
+
+    def enrollment(self) -> dict[str, Any] | None:
+        """The runner's configured policy behind an enrollment token, without
+        consuming it (D70). `None` when the plane predates protocol 2."""
+        return self._get_json("/enrollment")
+
+    def register(self, report: dict[str, Any]) -> dict[str, Any]:
+        """Register (or refresh). With an enrollment token, the response carries
+        the new credential once; the client switches to it immediately."""
+        body = {
+            "protocol_min": PROTOCOL_MIN,
+            "protocol_max": PROTOCOL_MAX,
+            "build_tag": BUILD_TAG,
+            **report,
+        }
+        data = self._post("/register", body)
+        credential = data.pop("credential", None)
+        if credential:
+            self._token = credential
+            data["enrolled"] = True
+        return data
+
+    def claim(self, *, wait_seconds: int, request_id: str) -> dict[str, Any]:
+        return self._post(
+            "/claim",
+            {
+                "protocol_min": PROTOCOL_MIN,
+                "protocol_max": PROTOCOL_MAX,
+                "wait_seconds": wait_seconds,
+                "request_id": request_id,
+                "build_tag": BUILD_TAG,
+            },
+        )
+
+    def _lease(self, job: dict[str, Any], path: str, **extra: Any) -> dict[str, Any]:
+        body = {"attempt_id": job["attempt_id"], "epoch": job["epoch"], **extra}
+        return self._post(f"/jobs/{job['job_id']}/{path}", body)
+
+    def heartbeat(self, job: dict[str, Any]) -> dict[str, Any]:
+        return self._lease(job, "heartbeat")
+
+    def events(self, job: dict[str, Any], events: list[dict[str, Any]]) -> int:
+        return int(self._lease(job, "events", events=events)["next_sequence"])
+
+    def publishing_token(self, job: dict[str, Any]) -> dict[str, Any]:
+        """A fresh Coder token for the job's repo under the current epoch (D-A)."""
+        return self._lease(job, "token")
+
+    def finish(
+        self,
+        job: dict[str, Any],
+        outcome: str,
+        detail: dict[str, Any],
+        *,
+        retryable: bool = False,
+        effect_free: bool = False,
+    ) -> str:
+        path = {"succeeded": "complete", "failed": "fail", "abandoned": "abandon"}[
+            outcome
+        ]
+        data = self._lease(
+            job, path, outcome=detail, retryable=retryable, effect_free=effect_free
+        )
+        return str(data["job_state"])