mechbench-runner 0.1.0__tar.gz

mechbench_runner-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: mechbench-runner
+Version: 0.1.0
+Summary: The mechbench runner: claims jobs from mechbench-api, executes protocols against mechbench-compute, and emits results. Also exposes those primitives as MCP tools.
+Author-email: Benji Smith <benji@shaxpir.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mechbench/mechbench-runner
+Project-URL: Website, https://mechbench.ai
+Keywords: interpretability,mechanistic-interpretability,mlx,mcp,runner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2
+Requires-Dist: mechbench-compute>=0.10
+Requires-Dist: mechbench-schema>=0.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=13
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# mechbench-runner
+
+The machine-side process of the [mechbench](https://mechbench.ai) family: it claims queued jobs from `mechbench-api`, executes them against `mechbench-compute`, and posts results back. It also exposes those same primitives as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an LLM agent can call them directly.
+
+**Status:** in use. `login` pairs a machine with an account; the runner then claims and executes jobs, reports progress and preparing steps, holds a live WSS channel for control and telemetry, and installs as a launchd or systemd service so it survives reboots. `doctor` tells you whether a machine will work before it tries. Three MCP tools (`run_protocol`, `get_result`, `list_jobs`) expose the same primitives to an agent.
+
+## What this repo is for
+
+Two adjacent surfaces for different callers:
+
+1. **MCP server.** An LLM agent (Claude, others) connects via MCP stdio and calls mechbench primitives as structured tools. Tool bodies run in-process against `mechbench-compute`.
+2. **Job-runner.** Polls `mechbench-api`'s `/jobs/next` for UI-queued protocols, runs them, posts results back. Same compute path as the MCP `run_protocol` tool; different *trigger*.
+
+Both modes share one binary (`mechbench-runner`) with subcommands; they share the loaded model, API client, and protocol executor. Splitting into separate processes is a later operational decision — see "Open design questions" below.
+
+## Architectural decisions (task 000185)
+
+- **Python.** `mechbench-compute` is Python; delegating to Python via RPC or subprocess-shell from a TS runner adds a layer that pays no dividends in v0. The MCP Python SDK is mature.
+- **One binary, two subcommands.** `mechbench-runner mcp` launches the MCP server over stdio; `mechbench-runner run` starts the job-runner loop. They share `ExperimentRunner` (owns the loaded Gemma model) and `ApiClient`.
+- **Agent authenticates to `mechbench-api` with a dedicated API key**, not a user's personal session. Export `MECHBENCH_API_KEY` (mint one at `/settings/api-keys`, or via `POST /auth/api-keys`). Matches the pattern from the e2e trace.
+- **MCP `run_protocol` runs in-process**, not queued through `mechbench-api`. The MCP caller wants the answer; we are the compute target. Job-queue round-tripping exists for the *UI-triggered* path (job-runner subcommand).
+- **stdio transport only.** SSE / HTTP-SSE transports earn their seat once remote MCP deploy matters (deferred).
+
+## Install
+
+```bash
+uv tool install mechbench-runner     # or: pipx install mechbench-runner
+mechbench-runner login
+```
+
+`login` prints a link, takes the registration token from it, stores a
+durable key at `~/.mechbench/config.toml` (mode 0600), and offers to
+start the runner automatically. Say yes and there is nothing further to
+do: it starts at login, comes back after a crash, and is controlled from
+the website.
+
+`mechbench-runner doctor` answers "will this actually work here" —
+Python, backend, credentials, API, model cache, disk — before you find
+out the slow way.
+
+Running a model needs Apple Silicon (the MLX backend from
+`mechbench-compute`). The rest installs anywhere.
+
+### Running it yourself
+
+```bash
+mechbench-runner run              # foreground, ^C to stop
+mechbench-runner install-agent    # or have the OS keep it running
+mechbench-runner agent-status
+```
+
+The service is supervised by launchd or systemd rather than by anything
+we wrote — see `mechbench_runner/exits.py` for the contract that makes
+that work.
+
+### From a checkout
+
+```bash
+git clone https://github.com/mechbench/mechbench-runner.git
+cd mechbench-runner
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Usage
+
+### MCP server
+
+Launch as a stdio MCP server — connect from Claude Desktop via `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mechbench": {
+      "command": "/abs/path/to/mechbench-runner/.venv/bin/mechbench-runner",
+      "args": ["mcp"],
+      "env": {
+        "MECHBENCH_API_URL": "http://localhost:3000",
+        "MECHBENCH_API_KEY": "mbk_..."
+      }
+    }
+  }
+}
+```
+
+Three tools appear in Claude:
+
+| tool | description |
+|---|---|
+| `run_protocol` | Run a layer-ablation protocol in-process on a prompt; return per-layer damage. |
+| `get_result` | Fetch a cached payload from `mechbench-api` by MechbenchPath. |
+| `list_jobs` | List the caller's queued / running / completed jobs. |
+
+### Job-runner
+
+Polls `mechbench-api` for UI-queued jobs. Same compute path as `run_protocol`; different trigger.
+
+```bash
+export MECHBENCH_API_URL=http://localhost:3000
+export MECHBENCH_API_KEY=mbk_...
+mechbench-runner run
+```
+
+Ctrl-C exits cleanly. API-unreachable is retried with exponential backoff capped at 30 s.
+
+### In-process smoke test
+
+```bash
+mechbench-runner smoke            # quick: list_jobs + get_result
+mechbench-runner smoke --full     # adds run_protocol (42 forwards, ~1-2 min)
+```
+
+## Configuration
+
+All via env vars:
+
+| var | default | purpose |
+|---|---|---|
+| `MECHBENCH_API_URL` | `http://localhost:3000` | mechbench-api base URL. Ignored when credentials are stored, which carry their own. |
+| `MECHBENCH_API_KEY` | *(from `login`)* | Overrides the stored credential entirely, URL included. For CI and containers, which have nowhere to put a config file. |
+| `MECHBENCH_POLL_INTERVAL_SECONDS` | `2.0` | Job-runner poll cadence. |
+| `MECHBENCH_WARM_MODEL_ID` | *(none)* | Optional model to load at startup so the first job skips cold start. There is deliberately no default: a protocol names the model it runs against, and a job that names none is an error. |
+| `MECHBENCH_WATCHDOG_SECONDS` | `900` | How long without progress counts as wedged. `0` disables it. |
+
+## Relationship to other mechbench repos
+
+- **`mechbench-compute`** — imported directly. `Model`, `Ablate`, hook-aware forward.
+- **`mechbench-schema`** — produces `LayerAblationPayload` etc. as typed results.
+- **`mechbench-api`** — the runner's only platform dependency. All workspace state (jobs, cache reads) goes through it.
+- **`mechbench-ui`** — no coupling. UI queues jobs; the job-runner consumes them.
+- **`mechbench-experiments`** — research scripts that use `mechbench-compute` directly, without the job machinery.
+
+## Open design questions (deferred)
+
+- **One binary or two processes?** Current answer: one binary, two subcommands. Revisit if MCP-caller frequency vs. job-runner throughput diverges enough to want independent scaling.
+- **Structured-summary interface.** The family's philosophy doc describes a read-side surface where agents consume JSON summaries of findings / experiments. Currently implicit in `list_jobs` + `get_result`. A richer summary layer (`GET /summary`, `POST /query`) is still on the table but unbuilt.
+- **MCP-surface observability.** Rate limits, per-tool metrics, audit trail for the tool-calling side. Deferred until a second LLM-agent consumer exists.
+
+## License
+
+MIT.

mechbench_runner-0.1.0/README.md

@@ -0,0 +1,142 @@
+# mechbench-runner
+
+The machine-side process of the [mechbench](https://mechbench.ai) family: it claims queued jobs from `mechbench-api`, executes them against `mechbench-compute`, and posts results back. It also exposes those same primitives as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an LLM agent can call them directly.
+
+**Status:** in use. `login` pairs a machine with an account; the runner then claims and executes jobs, reports progress and preparing steps, holds a live WSS channel for control and telemetry, and installs as a launchd or systemd service so it survives reboots. `doctor` tells you whether a machine will work before it tries. Three MCP tools (`run_protocol`, `get_result`, `list_jobs`) expose the same primitives to an agent.
+
+## What this repo is for
+
+Two adjacent surfaces for different callers:
+
+1. **MCP server.** An LLM agent (Claude, others) connects via MCP stdio and calls mechbench primitives as structured tools. Tool bodies run in-process against `mechbench-compute`.
+2. **Job-runner.** Polls `mechbench-api`'s `/jobs/next` for UI-queued protocols, runs them, posts results back. Same compute path as the MCP `run_protocol` tool; different *trigger*.
+
+Both modes share one binary (`mechbench-runner`) with subcommands; they share the loaded model, API client, and protocol executor. Splitting into separate processes is a later operational decision — see "Open design questions" below.
+
+## Architectural decisions (task 000185)
+
+- **Python.** `mechbench-compute` is Python; delegating to Python via RPC or subprocess-shell from a TS runner adds a layer that pays no dividends in v0. The MCP Python SDK is mature.
+- **One binary, two subcommands.** `mechbench-runner mcp` launches the MCP server over stdio; `mechbench-runner run` starts the job-runner loop. They share `ExperimentRunner` (owns the loaded Gemma model) and `ApiClient`.
+- **Agent authenticates to `mechbench-api` with a dedicated API key**, not a user's personal session. Export `MECHBENCH_API_KEY` (mint one at `/settings/api-keys`, or via `POST /auth/api-keys`). Matches the pattern from the e2e trace.
+- **MCP `run_protocol` runs in-process**, not queued through `mechbench-api`. The MCP caller wants the answer; we are the compute target. Job-queue round-tripping exists for the *UI-triggered* path (job-runner subcommand).
+- **stdio transport only.** SSE / HTTP-SSE transports earn their seat once remote MCP deploy matters (deferred).
+
+## Install
+
+```bash
+uv tool install mechbench-runner     # or: pipx install mechbench-runner
+mechbench-runner login
+```
+
+`login` prints a link, takes the registration token from it, stores a
+durable key at `~/.mechbench/config.toml` (mode 0600), and offers to
+start the runner automatically. Say yes and there is nothing further to
+do: it starts at login, comes back after a crash, and is controlled from
+the website.
+
+`mechbench-runner doctor` answers "will this actually work here" —
+Python, backend, credentials, API, model cache, disk — before you find
+out the slow way.
+
+Running a model needs Apple Silicon (the MLX backend from
+`mechbench-compute`). The rest installs anywhere.
+
+### Running it yourself
+
+```bash
+mechbench-runner run              # foreground, ^C to stop
+mechbench-runner install-agent    # or have the OS keep it running
+mechbench-runner agent-status
+```
+
+The service is supervised by launchd or systemd rather than by anything
+we wrote — see `mechbench_runner/exits.py` for the contract that makes
+that work.
+
+### From a checkout
+
+```bash
+git clone https://github.com/mechbench/mechbench-runner.git
+cd mechbench-runner
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Usage
+
+### MCP server
+
+Launch as a stdio MCP server — connect from Claude Desktop via `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mechbench": {
+      "command": "/abs/path/to/mechbench-runner/.venv/bin/mechbench-runner",
+      "args": ["mcp"],
+      "env": {
+        "MECHBENCH_API_URL": "http://localhost:3000",
+        "MECHBENCH_API_KEY": "mbk_..."
+      }
+    }
+  }
+}
+```
+
+Three tools appear in Claude:
+
+| tool | description |
+|---|---|
+| `run_protocol` | Run a layer-ablation protocol in-process on a prompt; return per-layer damage. |
+| `get_result` | Fetch a cached payload from `mechbench-api` by MechbenchPath. |
+| `list_jobs` | List the caller's queued / running / completed jobs. |
+
+### Job-runner
+
+Polls `mechbench-api` for UI-queued jobs. Same compute path as `run_protocol`; different trigger.
+
+```bash
+export MECHBENCH_API_URL=http://localhost:3000
+export MECHBENCH_API_KEY=mbk_...
+mechbench-runner run
+```
+
+Ctrl-C exits cleanly. API-unreachable is retried with exponential backoff capped at 30 s.
+
+### In-process smoke test
+
+```bash
+mechbench-runner smoke            # quick: list_jobs + get_result
+mechbench-runner smoke --full     # adds run_protocol (42 forwards, ~1-2 min)
+```
+
+## Configuration
+
+All via env vars:
+
+| var | default | purpose |
+|---|---|---|
+| `MECHBENCH_API_URL` | `http://localhost:3000` | mechbench-api base URL. Ignored when credentials are stored, which carry their own. |
+| `MECHBENCH_API_KEY` | *(from `login`)* | Overrides the stored credential entirely, URL included. For CI and containers, which have nowhere to put a config file. |
+| `MECHBENCH_POLL_INTERVAL_SECONDS` | `2.0` | Job-runner poll cadence. |
+| `MECHBENCH_WARM_MODEL_ID` | *(none)* | Optional model to load at startup so the first job skips cold start. There is deliberately no default: a protocol names the model it runs against, and a job that names none is an error. |
+| `MECHBENCH_WATCHDOG_SECONDS` | `900` | How long without progress counts as wedged. `0` disables it. |
+
+## Relationship to other mechbench repos
+
+- **`mechbench-compute`** — imported directly. `Model`, `Ablate`, hook-aware forward.
+- **`mechbench-schema`** — produces `LayerAblationPayload` etc. as typed results.
+- **`mechbench-api`** — the runner's only platform dependency. All workspace state (jobs, cache reads) goes through it.
+- **`mechbench-ui`** — no coupling. UI queues jobs; the job-runner consumes them.
+- **`mechbench-experiments`** — research scripts that use `mechbench-compute` directly, without the job machinery.
+
+## Open design questions (deferred)
+
+- **One binary or two processes?** Current answer: one binary, two subcommands. Revisit if MCP-caller frequency vs. job-runner throughput diverges enough to want independent scaling.
+- **Structured-summary interface.** The family's philosophy doc describes a read-side surface where agents consume JSON summaries of findings / experiments. Currently implicit in `list_jobs` + `get_result`. A richer summary layer (`GET /summary`, `POST /query`) is still on the table but unbuilt.
+- **MCP-surface observability.** Rate limits, per-tool metrics, audit trail for the tool-calling side. Deferred until a second LLM-agent consumer exists.
+
+## License
+
+MIT.

mechbench_runner-0.1.0/mechbench_runner/__init__.py

@@ -0,0 +1,3 @@
+"""mechbench-runner — MCP server + job-runner for the mechbench platform."""
+
+__version__ = "0.1.0"

mechbench_runner-0.1.0/mechbench_runner/_smoke.py

@@ -0,0 +1,73 @@
+"""In-process smoke test for the three MCP tools (task 000185 acceptance).
+
+Exercises the server's tool functions directly — no stdio
+subprocess, no MCP client — so CI / local dev can verify the
+surface without spawning a Claude session. Assumes mechbench-api is
+running on MECHBENCH_API_URL with a seeded `benji` user; a fresh
+API key must be available via MECHBENCH_API_KEY.
+
+The layer-ablation run is gated behind --full because loading Gemma
+4 and running 42 forward passes takes 1-2 minutes; the default run
+asserts only the get_result / list_jobs tools, which are
+fast and enough to verify the wiring.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .api_client import ApiClient
+from .config import Config
+from .mcp_server import build_server
+
+
+def main(full: bool = False) -> int:
+    config = Config.from_env()
+    if not config.api_key:
+        print(
+            "error: MECHBENCH_API_KEY is required for smoke test.",
+            file=sys.stderr,
+        )
+        return 2
+
+    server = build_server(config)
+    # FastMCP stores tools on the internal manager; pull the bound
+    # functions directly so the smoke test doesn't need an MCP client.
+    tools = {t.name: t.fn for t in server._tool_manager.list_tools()}  # noqa: SLF001
+
+    # --- list_jobs: sanity check that the runner can reach the API.
+    jobs = tools["list_jobs"]()
+    print(f"✓ list_jobs returned {len(jobs)} job(s)")
+
+    # --- get_result: exercise against the most recent done job, if any.
+    done = [j for j in jobs if j["status"] == "done" and j.get("resultPath")]
+    if done:
+        path = done[0]["resultPath"]
+        payload = tools["get_result"](path=path)
+        print(f"✓ get_result({path}) → kind/protocol={payload.get('protocol')}")
+    else:
+        # Queue one via the API so get_result has something to target.
+        with ApiClient(config) as api:
+            res = api._client.get("/auth/me")  # noqa: SLF001 — direct probe
+            res.raise_for_status()
+        print("✓ get_result skipped (no completed jobs); api /auth/me reachable")
+
+    if full:
+        payload = tools["run_protocol"](
+            prompt="Complete this sentence with one word: The Eiffel Tower is in"
+        )
+        print(
+            f"✓ run_protocol → protocol={payload['protocol']} "
+            f"n_layers={payload['n_layers']} "
+            f"baseline={payload['prompts'][0]['baseline_logprob']}"
+        )
+    else:
+        print("(skipping run_protocol; pass --full to include it)")
+
+    print("\nall smoke checks passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(full="--full" in sys.argv))

mechbench_runner-0.1.0/mechbench_runner/agent.py

@@ -0,0 +1,276 @@
+"""Installing the runner as a service the operating system supervises.
+
+This writes a launchd agent on macOS or a systemd **user** unit on
+Linux, and then gets out of the way. It deliberately does not supervise
+anything itself: both platforms already do that, and a second supervisor
+underneath the first gives two processes with different ideas about what
+"dead" means (task 000293).
+
+What we are responsible for is telling the platform the right policy,
+and the whole policy is the exit-code contract in `exits.py`:
+
+* `KeepAlive{SuccessfulExit: false}` / `Restart=on-failure` — come back
+  from a crash, stay stopped after a deliberate exit.
+* `ThrottleInterval` / `RestartSec` — do not spin.
+
+The command is `sys.executable -m mechbench_runner.cli run` rather than
+whatever `mechbench-runner` resolves to on `PATH`. A service has no
+shell profile, so `PATH` is not ours to rely on — and pinning the
+interpreter pins the environment the runner was installed into, which
+is the one holding its dependencies.
+
+No credential is written into the unit. It comes from
+`~/.mechbench/config.toml`, and a key in a plist is a key in a backup.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import mechbench_dir
+
+LABEL = "ai.mechbench.runner"
+UNIT_NAME = "mechbench-runner.service"
+
+#: Seconds launchd waits between restarts, and systemd's RestartSec.
+THROTTLE_SECONDS = 10
+
+#: Long enough for a job in flight to finish on SIGTERM before the
+#: supervisor escalates. A layer-ablation sweep is a couple of minutes.
+STOP_TIMEOUT_SECONDS = 300
+
+
+class UnsupportedPlatformError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentStatus:
+    installed: bool
+    loaded: bool
+    running: bool
+    path: Path
+    detail: str
+
+
+def is_macos() -> bool:
+    return sys.platform == "darwin"
+
+
+def is_linux() -> bool:
+    return sys.platform.startswith("linux")
+
+
+def unit_path() -> Path:
+    if is_macos():
+        return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+    if is_linux():
+        return Path.home() / ".config" / "systemd" / "user" / UNIT_NAME
+    raise UnsupportedPlatformError(
+        f"there is no service manager we know how to use on {sys.platform}. "
+        f"Run `mechbench-runner run` under whatever supervises processes "
+        f"here, or use `mechbench-runner supervise` if there is nothing."
+    )
+
+
+def program_arguments() -> list[str]:
+    return [sys.executable, "-m", "mechbench_runner.cli", "run"]
+
+
+def boot_log() -> Path:
+    """Where the platform's own stdout goes.
+
+    Small by construction: the runner replaces stdout with its rotating
+    log as soon as it starts, so only failures *before* that reach here —
+    which is exactly what you want to read when it will not start.
+    """
+    d = mechbench_dir() / "logs"
+    d.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return d / "agent-boot.log"
+
+
+# --- writing the unit --------------------------------------------------------
+
+
+def launchd_plist() -> dict[str, object]:
+    return {
+        "Label": LABEL,
+        "ProgramArguments": program_arguments(),
+        "RunAtLoad": True,
+        # The exit contract, expressed the only way launchd understands:
+        # restart unless the process said it meant to stop.
+        "KeepAlive": {"SuccessfulExit": False},
+        "ThrottleInterval": THROTTLE_SECONDS,
+        "ExitTimeOut": STOP_TIMEOUT_SECONDS,
+        # Background: lower priority than anything the user is looking at.
+        "ProcessType": "Background",
+        "StandardOutPath": str(boot_log()),
+        "StandardErrorPath": str(boot_log()),
+        "WorkingDirectory": str(Path.home()),
+    }
+
+
+def systemd_unit() -> str:
+    args = " ".join(program_arguments())
+    return f"""[Unit]
+Description=mechbench runner
+Documentation=https://mechbench.ai
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart={args}
+# The exit contract (mechbench_runner/exits.py): 0 is deliberate and
+# must stay stopped, anything else is a fault worth restarting.
+Restart=on-failure
+RestartSec={THROTTLE_SECONDS}
+TimeoutStopSec={STOP_TIMEOUT_SECONDS}
+# Give up loudly rather than spinning.
+StartLimitBurst=5
+StartLimitIntervalSec=600
+
+[Install]
+WantedBy=default.target
+"""
+
+
+# --- operations --------------------------------------------------------------
+
+
+def install() -> AgentStatus:
+    path = unit_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if is_macos():
+        path.write_bytes(plistlib.dumps(launchd_plist()))
+        # bootout first so install is idempotent: reinstalling over a
+        # loaded agent otherwise keeps the old command running.
+        _run(["launchctl", "bootout", _domain(), str(path)], check=False)
+        result = _run(["launchctl", "bootstrap", _domain(), str(path)], check=False)
+        if result.returncode != 0:
+            # Older macOS, or a domain that refuses bootstrap.
+            result = _run(["launchctl", "load", "-w", str(path)], check=False)
+        if result.returncode != 0:
+            return AgentStatus(True, False, False, path,
+                               f"written, but could not be loaded: {_msg(result)}")
+    else:
+        path.write_text(systemd_unit())
+        _run(["systemctl", "--user", "daemon-reload"], check=False)
+        result = _run(["systemctl", "--user", "enable", "--now", UNIT_NAME],
+                      check=False)
+        if result.returncode != 0:
+            return AgentStatus(True, False, False, path,
+                               f"written, but could not be enabled: {_msg(result)}")
+
+    return status()
+
+
+def uninstall() -> AgentStatus:
+    path = unit_path()
+    if is_macos():
+        _run(["launchctl", "bootout", _domain(), str(path)], check=False)
+        _run(["launchctl", "unload", "-w", str(path)], check=False)
+    else:
+        _run(["systemctl", "--user", "disable", "--now", UNIT_NAME], check=False)
+    existed = path.exists()
+    path.unlink(missing_ok=True)
+    if is_linux():
+        _run(["systemctl", "--user", "daemon-reload"], check=False)
+    return AgentStatus(
+        installed=False,
+        loaded=False,
+        running=False,
+        path=path,
+        detail="removed" if existed else "there was nothing installed",
+    )
+
+
+def status() -> AgentStatus:
+    path = unit_path()
+    if not path.exists():
+        return AgentStatus(False, False, False, path, "not installed")
+
+    if is_macos():
+        printed = _run(["launchctl", "print", f"{_domain()}/{LABEL}"], check=False)
+        loaded = printed.returncode == 0
+        running = loaded and "state = running" in printed.stdout
+        pid = _extract(printed.stdout, "pid = ")
+        detail = (
+            f"running (pid {pid})" if running
+            else "loaded, not currently running" if loaded
+            else "installed but not loaded"
+        )
+        return AgentStatus(True, loaded, running, path, detail)
+
+    enabled = _run(["systemctl", "--user", "is-enabled", UNIT_NAME], check=False)
+    active = _run(["systemctl", "--user", "is-active", UNIT_NAME], check=False)
+    loaded = enabled.returncode == 0
+    running = active.stdout.strip() == "active"
+    return AgentStatus(
+        True, loaded, running, path,
+        f"{active.stdout.strip() or 'unknown'}, {enabled.stdout.strip() or 'disabled'}",
+    )
+
+
+def kickstart() -> bool:
+    """Start it now, or restart it if it is already up.
+
+    Needed after `login`: a runner that exited because it was signed out
+    exited *deliberately*, so the supervisor is correctly leaving it
+    alone and nothing else will bring it back.
+    """
+    if not unit_path().exists():
+        return False
+    if is_macos():
+        r = _run(["launchctl", "kickstart", "-k", f"{_domain()}/{LABEL}"], check=False)
+        return r.returncode == 0
+    r = _run(["systemctl", "--user", "restart", UNIT_NAME], check=False)
+    return r.returncode == 0
+
+
+def linger_hint() -> str | None:
+    """On Linux a user service stops at logout unless lingering is on —
+    which is the difference between a headless box that works and one
+    that works until you close the SSH session."""
+    if not is_linux():
+        return None
+    user = os.environ.get("USER") or os.environ.get("LOGNAME") or ""
+    check = _run(["loginctl", "show-user", user, "--property=Linger"], check=False)
+    if "Linger=yes" in check.stdout:
+        return None
+    return (
+        f"This service stops when you log out. To keep it running on a "
+        f"headless machine:\n    sudo loginctl enable-linger {user}"
+    )
+
+
+# --- plumbing ----------------------------------------------------------------
+
+
+def _domain() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def _run(cmd: list[str], *, check: bool) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(  # noqa: S603
+            cmd, capture_output=True, text=True, check=check, timeout=30
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return subprocess.CompletedProcess(cmd, 127, "", str(exc))
+
+
+def _msg(result: subprocess.CompletedProcess[str]) -> str:
+    return (result.stderr or result.stdout or "no output").strip().splitlines()[0]
+
+
+def _extract(text: str, marker: str) -> str:
+    for line in text.splitlines():
+        if marker in line:
+            return line.split(marker, 1)[1].strip().rstrip(";")
+    return "?"