genesis-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: genesis-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Genesis Agent Workbench CLI — make any repo agent-ready and keep AI-generated changes governed.
 Project-URL: Homepage, https://github.com/Inceptium-ai/genesis-framework
 Project-URL: Repository, https://github.com/Inceptium-ai/genesis-framework
@@ -20,7 +20,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.12
-Requires-Dist: genesis-gates>=0.1.0
+Requires-Dist: genesis-gates>=0.2.0
+Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "genesis-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Genesis Agent Workbench CLI — make any repo agent-ready and keep AI-generated changes governed."
 readme = "README.md"
 license = "Apache-2.0"
@@ -30,8 +30,10 @@ dependencies = [
     # Must stay a REAL version requirement: `[tool.uv.sources]` below is a
     # dev-only workspace override and is not written into published metadata,
     # so this is what `pip install genesis-cli` resolves against on PyPI.
-    "genesis-gates>=0.1.0",
+    "genesis-gates>=0.2.0",
     "pyyaml>=6.0",
+    # `genesis runner` talks to a Genesis server over HTTP.
+    "httpx>=0.27",
 ]
 
 [project.urls]

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/src/genesis_cli/adopt.py

@@ -17,6 +17,7 @@ import genesis_gates.providers  # noqa: F401
 from genesis_gates import GateContext, GateRunner, get_gate, load_gate_config
 from genesis_gates.analysis import (
     analyze,
+    declared_env_vars,
     reconcile,
     repo_input,
     score_readiness,
@@ -56,7 +57,13 @@ def run_audit(repo: Path) -> dict:
     repo = repo.resolve()
     gate_results = run_gates(repo).get("gate_results", [])
     completeness = analyze(repo_input(repo))
-    reconciliation = reconcile(repo, stored_deps={})
+    # A brownfield audit has no stored dependency map, so the repo's own
+    # `.env.example`-family files ARE its declared config contract. Passing
+    # them makes env_hygiene measure "are env vars declared?"; with an empty
+    # map, every compose `${VAR}` without a default counted as an undeclared
+    # gap even when the repo documents it properly, which pinned the category
+    # near zero for any repo with an undefaulted compose reference.
+    reconciliation = reconcile(repo, stored_deps=declared_env_vars(repo))
     facts = structure_facts(repo)
     readiness = score_readiness(
         gate_results=gate_results, facts=facts,

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/src/genesis_cli/init.py

@@ -104,6 +104,13 @@ kind: GateConfig
 #   dependency-scan:
 #     provider: trivy
 #     fail_on_severity: critical
+#     # Trees this repo does not author and is not accountable for: vendored
+#     # dependencies, generated output, packaged sample apps that are scanned
+#     # in their own right. Repo-relative, anchored at the root ("vendor" does
+#     # not match "packages/x/vendor"). This is SCOPE, not suppression — a
+#     # skipped directory is invisible to the gate, so justify each entry in a
+#     # comment and keep your own source, infra and CI in scope.
+#     skip_dirs: [vendor, third_party/generated]
 #   unit-tests:
 #     provider: command
 #     command: "npm test"

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/src/genesis_cli/main.py

@@ -9,6 +9,12 @@ Commands:
   genesis init [path]    Scaffold a new/bare repo so agents start agent-ready:
                          AGENTS.md, .gitignore, .env.example, audit workflow,
                          gate config. Idempotent — never overwrites.
+  genesis runner …       Local runner for the Genesis platform: `connect` pairs
+                         this machine with a server (runner token), `start`
+                         executes your builds' coding-agent tasks here through
+                         your own `claude` CLI (your subscription), `status`
+                         shows the connection. The server keeps orchestration,
+                         validation, gates, evidence, and billing.
   genesis --version      Print the installed genesis-cli version.
 """
 
@@ -220,6 +226,11 @@ def main(argv: list[str] | None = None) -> int:
                       help="directory to scaffold (default: .; created if missing)")
     init.set_defaults(func=_cmd_init)
 
+    # Local runner (deferred imports: the subcommands import httpx lazily).
+    from .runner.runner_cmd import add_runner_parser
+
+    add_runner_parser(sub)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

genesis_cli-0.2.0/src/genesis_cli/runner/__init__.py

@@ -0,0 +1,11 @@
+"""`genesis runner` — execute your Genesis coding-agent tasks locally.
+
+Connect this machine to a Genesis server with a runner token and your builds'
+agent tasks run HERE, through your own local `claude` CLI (your subscription)
+— while the server keeps all orchestration, validation, repair policy,
+commits, gates, evidence, and billing.
+
+Public package rule: this code never imports genesis_server or
+genesis_executor; the wire protocol (claim / workspace / events / result)
+is its only contract with the server.
+"""

genesis_cli-0.2.0/src/genesis_cli/runner/claude_driver.py

@@ -0,0 +1,185 @@
+"""Headless `claude` driver — the public runner-side reimplementation of the
+platform's stream-json adapter (same argv, same parsing, no shared code: this
+package never imports the commercial packages).
+
+Runs `claude -p <prompt> --output-format stream-json` as an argv subprocess
+(never a shell) with cwd = the task workspace. The child env is a pass-through
+of the login environment with ANTHROPIC_API_KEY explicitly UNSET so the CLI
+uses the user's subscription auth and never silently bills an API key.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+# stream-json emits one JSON object per line; a single line (a large tool
+# result or a long assistant turn) routinely exceeds asyncio's default 64 KB
+# StreamReader line cap, which would raise LimitOverrunError mid-task. We read
+# raw chunks and split on newlines ourselves (no per-line cap), and raise the
+# subprocess buffer limit so the transport isn't paused every 64 KB.
+_STREAM_LIMIT = 64 * 1024 * 1024  # 64 MB StreamReader buffer
+_READ_CHUNK = 256 * 1024  # 256 KB per read
+
+
+async def _iter_json_lines(stream: asyncio.StreamReader):
+    """Yield complete decoded lines via chunked reads — an oversized line can
+    never raise asyncio.LimitOverrunError."""
+    buf = bytearray()
+    while True:
+        chunk = await stream.read(_READ_CHUNK)
+        if not chunk:
+            break
+        buf.extend(chunk)
+        while True:
+            nl = buf.find(b"\n")
+            if nl == -1:
+                break
+            line = bytes(buf[:nl])
+            del buf[: nl + 1]
+            yield line
+    if buf:
+        yield bytes(buf)
+
+
+def _assistant_text(evt: dict) -> str:
+    msg = evt.get("message") or {}
+    parts = msg.get("content") or []
+    if isinstance(parts, str):
+        return parts
+    return "".join(
+        p.get("text", "")
+        for p in parts
+        if isinstance(p, dict) and p.get("type") == "text"
+    )
+
+
+def check_cli() -> tuple[bool, str]:
+    """Preflight: is a working `claude` CLI on PATH?"""
+    if not shutil.which("claude"):
+        return False, (
+            "The `claude` CLI is not on PATH. Install Claude Code "
+            "(https://claude.com/claude-code) and sign in with your "
+            "subscription, then run `genesis runner start` again."
+        )
+    try:
+        proc = subprocess.run(["claude", "--version"], capture_output=True,
+                              text=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return False, f"`claude --version` failed to run: {exc}"
+    if proc.returncode != 0:
+        return False, (f"`claude --version` exited {proc.returncode}: "
+                       f"{(proc.stderr or proc.stdout)[:200]}")
+    return True, (proc.stdout or "").strip()
+
+
+class ClaudeDriver:
+    """One task = one run(). kill() aborts the live subprocess (server-side
+    cancel or a second Ctrl-C)."""
+
+    def __init__(self, model: str | None = None):
+        self.model = model
+        self._proc: asyncio.subprocess.Process | None = None
+        self.killed = False
+
+    def kill(self) -> None:
+        self.killed = True
+        if self._proc is not None and self._proc.returncode is None:
+            self._proc.kill()
+
+    def _child_env(self) -> dict:
+        env = dict(os.environ)
+        # Force subscription auth: never let an API key take over accidentally.
+        env.pop("ANTHROPIC_API_KEY", None)
+        return env
+
+    async def run(self, prompt: str, *, workdir: Path,
+                  resume_session: str | None = None,
+                  on_text: Callable[[str], None] | None = None) -> dict:
+        """Run one task; returns {status, session_id, usage, error} parsed
+        from the CLI's final result message."""
+        started = time.monotonic()
+        argv = [
+            "claude", "-p", prompt,
+            "--output-format", "stream-json",
+            "--verbose",
+            "--add-dir", str(workdir),
+            "--permission-mode", "acceptEdits",
+        ]
+        if self.model:
+            argv += ["--model", self.model]
+        if resume_session:
+            argv += ["--resume", resume_session]
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *argv,
+                cwd=str(workdir),
+                env=self._child_env(),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                limit=_STREAM_LIMIT,
+            )
+        except FileNotFoundError:
+            return {"status": "failed", "session_id": None,
+                    "usage": {}, "error": "claude CLI not found"}
+        self._proc = proc
+
+        usage: dict = {"input_tokens": 0, "output_tokens": 0, "cost_usd": None,
+                       "estimated": False, "duration_s": None}
+        session_id: str | None = None
+        status = "failed"
+        error: str | None = None
+
+        assert proc.stdout is not None
+        try:
+            async for raw in _iter_json_lines(proc.stdout):
+                line = raw.decode("utf-8", "replace").strip()
+                if not line:
+                    continue
+                try:
+                    evt = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                etype = evt.get("type")
+                if evt.get("session_id"):
+                    session_id = evt["session_id"]
+                if etype == "assistant":
+                    text = _assistant_text(evt)
+                    if text and on_text is not None:
+                        on_text(text)
+                elif etype == "result":
+                    if evt.get("total_cost_usd") is not None:
+                        usage["cost_usd"] = float(evt["total_cost_usd"])
+                    u = evt.get("usage") or {}
+                    usage["input_tokens"] = int(u.get("input_tokens", 0))
+                    usage["output_tokens"] = int(u.get("output_tokens", 0))
+                    status = "completed" if evt.get("subtype") == "success" else "failed"
+                    if evt.get("is_error"):
+                        error = str(evt.get("result", "cli error"))[:500]
+            await proc.wait()
+        except asyncio.CancelledError:
+            proc.kill()
+            raise
+        finally:
+            self._proc = None
+
+        if self.killed:
+            status = "interrupted"
+            error = error or "task aborted on the runner"
+        elif proc.returncode not in (0, None) and status != "completed":
+            status = "failed"
+            if error is None:
+                err = (await proc.stderr.read()).decode("utf-8", "replace") \
+                    if proc.stderr else ""
+                error = err[:500] or f"claude exited {proc.returncode}"
+
+        usage["duration_s"] = time.monotonic() - started
+        return {"status": status, "session_id": session_id,
+                "usage": usage, "error": error}

genesis_cli-0.2.0/src/genesis_cli/runner/client.py

@@ -0,0 +1,102 @@
+"""HTTP client for the Genesis runner gateway.
+
+One rule above all: the token is a credential — it goes into the
+Authorization header and NOWHERE else (never a log line, never an error
+message, never a URL).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+# The server long-polls a claim for ~25s; read must comfortably outlast that.
+_CLAIM_TIMEOUT = httpx.Timeout(10.0, read=60.0)
+_IO_TIMEOUT = httpx.Timeout(10.0, read=300.0)
+
+
+class RunnerAuthError(RuntimeError):
+    """The server rejected the runner token (bad, rotated, or revoked)."""
+
+
+class RunnerClient:
+    def __init__(self, server: str, token: str):
+        self._client = httpx.AsyncClient(
+            base_url=server.rstrip("/"),
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=_IO_TIMEOUT,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    @staticmethod
+    def _check_auth(resp: httpx.Response) -> None:
+        if resp.status_code == 401:
+            raise RunnerAuthError(
+                "The server rejected this runner's token — it may have been "
+                "rotated or revoked. Run `genesis runner connect` again."
+            )
+
+    async def probe(self) -> bool:
+        """Side-effect-free auth check: a nonexistent work item reads 404 with
+        a valid token, 401 with a bad one (and never claims real work)."""
+        resp = await self._client.get("/api/runner/work/probe/workspace")
+        if resp.status_code == 401:
+            return False
+        return resp.status_code == 404
+
+    async def claim(self) -> dict | None:
+        """One long-poll. None = no work this window (poll again)."""
+        resp = await self._client.post("/api/runner/claim", timeout=_CLAIM_TIMEOUT)
+        self._check_auth(resp)
+        if resp.status_code == 204:
+            return None
+        resp.raise_for_status()
+        data = resp.json()
+        return data if isinstance(data, dict) and data.get("item_id") else None
+
+    async def download_workspace(self, item_id: str, dest: Path) -> Path:
+        """Stream the task workspace archive to dest (tar.gz)."""
+        async with self._client.stream(
+            "GET", f"/api/runner/work/{item_id}/workspace", timeout=_IO_TIMEOUT
+        ) as resp:
+            self._check_auth(resp)
+            resp.raise_for_status()
+            with dest.open("wb") as f:
+                async for chunk in resp.aiter_bytes():
+                    f.write(chunk)
+        return dest
+
+    async def post_events(self, item_id: str, events: list[dict]) -> bool:
+        """Forward an event batch; the reply carries the cancel signal."""
+        resp = await self._client.post(
+            f"/api/runner/work/{item_id}/events", json={"events": events}
+        )
+        self._check_auth(resp)
+        resp.raise_for_status()
+        try:
+            return bool(resp.json().get("cancelled"))
+        except ValueError:
+            return False
+
+    async def post_result(self, item_id: str, result: dict,
+                          tar_path: Path | None = None) -> None:
+        """Upload the task outcome (+ the changed-files archive when any)."""
+        import json
+
+        data = {"result": json.dumps(result)}
+        if tar_path is not None:
+            with tar_path.open("rb") as f:
+                resp = await self._client.post(
+                    f"/api/runner/work/{item_id}/result", data=data,
+                    files={"files": ("files.tar.gz", f, "application/gzip")},
+                    timeout=_IO_TIMEOUT,
+                )
+        else:
+            resp = await self._client.post(
+                f"/api/runner/work/{item_id}/result", data=data, timeout=_IO_TIMEOUT
+            )
+        self._check_auth(resp)
+        resp.raise_for_status()

genesis_cli-0.2.0/src/genesis_cli/runner/config.py

@@ -0,0 +1,62 @@
+"""Runner configuration: ~/.genesis/runner.toml, mode 0600.
+
+The file holds the server URL, the runner token (a credential — hence the
+restrictive mode and the minimal writer that never round-trips through a
+general serializer), and this machine's runner name.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+_FIELDS = ("server", "token", "name")
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get("GENESIS_RUNNER_HOME", str(Path.home() / ".genesis")))
+
+
+def config_path() -> Path:
+    return config_dir() / "runner.toml"
+
+
+def work_root() -> Path:
+    """Where claimed task workspaces are materialized (and cleaned up)."""
+    root = config_dir() / "runner-work"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def load_config() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+    return {k: v for k, v in data.items() if k in _FIELDS and isinstance(v, str)}
+
+
+def _toml_str(value: str) -> str:
+    # Minimal TOML basic-string escaping: backslash and double quote.
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def save_config(server: str, token: str, name: str) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = (
+        "# genesis runner credentials — created by `genesis runner connect`\n"
+        f"server = {_toml_str(server)}\n"
+        f"token = {_toml_str(token)}\n"
+        f"name = {_toml_str(name)}\n"
+    )
+    # Create 0600 BEFORE writing the secret (never a world-readable window).
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(body)
+    os.chmod(path, 0o600)
+    return path

genesis_cli-0.2.0/src/genesis_cli/runner/loop.py

@@ -0,0 +1,262 @@
+"""The runner loop: connect, start, status.
+
+start() is the long-lived process: claim → materialize the workspace →
+drive the local `claude` CLI (events batched upstream ~1/s; the batch reply
+carries the server's cancel signal) → diff → upload the result → clean up.
+
+Ctrl-C is graceful: the first stops claiming and lets the current task
+finish; the second aborts the task (the server records it interrupted).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import getpass
+import platform
+import re
+import shutil
+import sys
+
+import httpx
+
+from .claude_driver import ClaudeDriver, check_cli
+from .client import RunnerAuthError, RunnerClient
+from .config import config_path, load_config, save_config, work_root
+from .workspace import build_result_tar, diff, manifest, safe_extract
+
+_EVENT_FLUSH_S = 1.0
+_CLAIM_BACKOFF_S = 5.0
+_SAFE_NAME = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def _say(msg: str) -> None:
+    print(msg, flush=True)
+
+
+# ── connect ───────────────────────────────────────────────────────────────────
+
+def connect(server: str, name: str | None = None) -> int:
+    server = server.strip().rstrip("/")
+    if not server.startswith(("http://", "https://")):
+        print("error: --server must be an http(s) URL", file=sys.stderr)
+        return 2
+    name = (name or platform.node() or "my-machine").strip()[:80]
+    _say(f"Connecting this machine to {server} as runner {name!r}.")
+    _say("In Genesis: Settings → Runners → New runner, then paste the grt_ "
+         "token below (it is shown there exactly once).")
+    try:
+        token = getpass.getpass("Runner token: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print("\naborted", file=sys.stderr)
+        return 2
+    if not token:
+        print("error: no token provided", file=sys.stderr)
+        return 2
+
+    async def _probe() -> bool:
+        client = RunnerClient(server, token)
+        try:
+            return await client.probe()
+        finally:
+            await client.aclose()
+
+    try:
+        ok = asyncio.run(_probe())
+    except httpx.HTTPError as exc:
+        print(f"error: could not reach {server}: {exc}", file=sys.stderr)
+        return 1
+    if not ok:
+        print("error: the server rejected that token — mint a fresh one in "
+              "Settings → Runners and try again.", file=sys.stderr)
+        return 1
+    path = save_config(server, token, name)
+    _say(f"Connected. Credentials saved to {path} (mode 0600).")
+    _say("Start picking up work with: genesis runner start")
+    return 0
+
+
+# ── status ────────────────────────────────────────────────────────────────────
+
+def status() -> int:
+    cfg = load_config()
+    if not cfg.get("server") or not cfg.get("token"):
+        _say("Not connected. Run: genesis runner connect --server <URL>")
+        return 1
+    _say(f"Server : {cfg['server']}")
+    _say(f"Name   : {cfg.get('name', '?')}")
+    _say(f"Config : {config_path()}")
+    ok, detail = check_cli()
+    _say(f"claude : {detail if ok else 'MISSING — ' + detail}")
+
+    async def _probe() -> bool:
+        client = RunnerClient(cfg["server"], cfg["token"])
+        try:
+            return await client.probe()
+        finally:
+            await client.aclose()
+
+    try:
+        auth_ok = asyncio.run(_probe())
+    except httpx.HTTPError as exc:
+        _say(f"Auth   : unreachable ({exc})")
+        return 1
+    _say(f"Auth   : {'ok' if auth_ok else 'REJECTED — reconnect with a fresh token'}")
+    return 0 if (ok and auth_ok) else 1
+
+
+# ── start ─────────────────────────────────────────────────────────────────────
+
+class _Stop:
+    """Two-stage Ctrl-C: 1 = stop claiming, finish the task; 2 = abort it."""
+
+    def __init__(self) -> None:
+        self.stopping = False
+        self.driver: ClaudeDriver | None = None
+
+    def interrupt(self) -> None:
+        if not self.stopping:
+            self.stopping = True
+            _say("\nStopping — finishing the current task (Ctrl-C again to abort it).")
+        elif self.driver is not None:
+            _say("\nAborting the current task.")
+            self.driver.kill()
+
+
+def start() -> int:
+    cfg = load_config()
+    if not cfg.get("server") or not cfg.get("token"):
+        print("error: not connected — run `genesis runner connect --server <URL>` "
+              "first.", file=sys.stderr)
+        return 2
+    ok, detail = check_cli()
+    if not ok:
+        print(f"error: {detail}", file=sys.stderr)
+        return 2
+    _say(f"claude CLI: {detail}")
+    try:
+        return asyncio.run(_start(cfg))
+    except KeyboardInterrupt:
+        return 0
+
+
+async def _start(cfg: dict) -> int:
+    import signal
+
+    client = RunnerClient(cfg["server"], cfg["token"])
+    stop = _Stop()
+    loop = asyncio.get_running_loop()
+    try:
+        loop.add_signal_handler(signal.SIGINT, stop.interrupt)
+    except (NotImplementedError, RuntimeError):
+        pass  # non-Unix: KeyboardInterrupt still lands in start()
+
+    _say(f"Runner {cfg.get('name', '?')!r} polling {cfg['server']} for work. Ctrl-C to stop.")
+    try:
+        while not stop.stopping:
+            try:
+                item = await client.claim()
+            except RunnerAuthError as exc:
+                print(f"error: {exc}", file=sys.stderr)
+                return 1
+            except httpx.HTTPError as exc:
+                _say(f"server unreachable ({exc.__class__.__name__}); retrying in "
+                     f"{_CLAIM_BACKOFF_S:.0f}s…")
+                await asyncio.sleep(_CLAIM_BACKOFF_S)
+                continue
+            if item is None:
+                continue
+            await _run_item(client, item, stop)
+    finally:
+        await client.aclose()
+    _say("Runner stopped.")
+    return 0
+
+
+async def _run_item(client: RunnerClient, item: dict, stop: _Stop) -> None:
+    item_id = str(item.get("item_id"))
+    task = item.get("task") or {}
+    task_id = str(task.get("task_id") or "task")
+    project = _SAFE_NAME.sub("-", str(task.get("project_name") or "project")) or "project"
+    workdir = work_root() / project / item_id
+    workdir.mkdir(parents=True, exist_ok=True)
+    tar_in = workdir.parent / f"{item_id}.in.tar.gz"
+    tar_out = None
+    _say(f"▶ {task_id} (item {item_id[:12]}…) — downloading workspace")
+
+    events: list[dict] = []
+
+    def on_text(text: str) -> None:
+        events.append({"type": "agent_message", "data": {"text": text}})
+
+    driver = ClaudeDriver()
+    stop.driver = driver
+
+    async def flusher() -> None:
+        while True:
+            await asyncio.sleep(_EVENT_FLUSH_S)
+            # An empty batch still flushes: it doubles as the cancel poll.
+            batch, events[:] = list(events), []
+            try:
+                cancelled = await client.post_events(item_id, batch)
+            except (httpx.HTTPError, RunnerAuthError):
+                continue  # transient — the final result upload is what matters
+            if cancelled:
+                _say(f"✖ {task_id} cancelled by the server — stopping claude")
+                driver.kill()
+                return
+
+    try:
+        await client.download_workspace(item_id, tar_in)
+        safe_extract(tar_in, workdir)
+        before = manifest(workdir)
+
+        flush_task = asyncio.create_task(flusher())
+        try:
+            result = await driver.run(
+                str(task.get("prompt") or ""),
+                workdir=workdir,
+                resume_session=task.get("resume_session") or None,
+                on_text=on_text,
+            )
+        finally:
+            flush_task.cancel()
+        # Final event flush (best-effort).
+        if events:
+            try:
+                await client.post_events(item_id, list(events))
+            except (httpx.HTTPError, RunnerAuthError):
+                pass
+            events.clear()
+
+        after = manifest(workdir)
+        changed, deleted = diff(before, after)
+        payload = {
+            "status": result.get("status", "failed"),
+            "session_id": result.get("session_id"),
+            "error": result.get("error"),
+            "usage": result.get("usage") or {},
+            "deleted": deleted,
+        }
+        if changed:
+            tar_out = build_result_tar(workdir, changed)
+        await client.post_result(item_id, payload, tar_out)
+        _say(f"✓ {task_id}: {payload['status']} "
+             f"({len(changed)} changed, {len(deleted)} deleted)")
+    except RunnerAuthError:
+        raise
+    except Exception as exc:  # noqa: BLE001 — report, never crash the loop
+        _say(f"✗ {task_id}: {exc.__class__.__name__}: {exc}")
+        try:
+            await client.post_result(item_id, {
+                "status": "failed", "session_id": None,
+                "error": f"runner error: {exc}"[:500],
+                "usage": {}, "deleted": [],
+            })
+        except (httpx.HTTPError, RunnerAuthError):
+            pass
+    finally:
+        stop.driver = None
+        tar_in.unlink(missing_ok=True)
+        if tar_out is not None:
+            tar_out.unlink(missing_ok=True)
+        shutil.rmtree(workdir, ignore_errors=True)

genesis_cli-0.2.0/src/genesis_cli/runner/runner_cmd.py

@@ -0,0 +1,53 @@
+"""argparse wiring for `genesis runner …` (heavy imports deferred to run time
+so `genesis adopt` never pays for httpx)."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def _cmd_connect(args: argparse.Namespace) -> int:
+    from .loop import connect
+
+    return connect(args.server, args.name)
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    from .loop import start
+
+    return start()
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    from .loop import status
+
+    return status()
+
+
+def add_runner_parser(sub: argparse._SubParsersAction) -> None:
+    runner = sub.add_parser(
+        "runner",
+        help="execute your Genesis builds' coding-agent tasks on THIS machine "
+             "with your local claude CLI (subscription) — the server keeps "
+             "orchestration, validation, gates, and billing",
+    )
+    rsub = runner.add_subparsers(dest="runner_command", required=True)
+
+    connect = rsub.add_parser(
+        "connect", help="pair this machine with a Genesis server "
+                        "(paste a runner token from Settings → Runners)")
+    connect.add_argument("--server", required=True, metavar="URL",
+                         help="the Genesis server origin, e.g. "
+                              "https://genesis.example.com")
+    connect.add_argument("--name", default=None,
+                         help="a name for this machine (default: hostname)")
+    connect.set_defaults(func=_cmd_connect)
+
+    start = rsub.add_parser(
+        "start", help="poll for work and run tasks locally (Ctrl-C to stop; "
+                      "twice to abort the current task)")
+    start.set_defaults(func=_cmd_start)
+
+    status = rsub.add_parser("status", help="show connection, claude CLI and "
+                                            "auth status")
+    status.set_defaults(func=_cmd_status)

genesis_cli-0.2.0/src/genesis_cli/runner/workspace.py

@@ -0,0 +1,90 @@
+"""Local task workspaces: safe extraction, change manifests, result archives.
+
+The server's archive is data from a machine seam — extraction validates every
+member (relative, no '..', regular files only) and uses the tarfile "data"
+filter. The change manifest (sha256 per file) brackets the agent run; the
+diff decides what goes back up. The same exclusion set applies in every
+direction: VCS internals, dependency trees, caches, env files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import tarfile
+import tempfile
+from pathlib import Path, PurePosixPath
+
+_EXCLUDE_DIRS = {".git", "node_modules", ".genesis-work", "__pycache__",
+                 ".venv", "dist", "build"}
+
+
+class ExtractError(ValueError):
+    """An archive member tried to escape or smuggle a non-file."""
+
+
+def _excluded(rel: str) -> bool:
+    parts = PurePosixPath(rel).parts
+    return any(p in _EXCLUDE_DIRS or p.startswith(".env") for p in parts)
+
+
+def safe_extract(tar_path: Path, dest: Path) -> list[str]:
+    """Extract the workspace archive; every member is validated first.
+    Returns the extracted member names."""
+    dest.mkdir(parents=True, exist_ok=True)
+    names: list[str] = []
+    with tarfile.open(tar_path, mode="r:gz") as tar:
+        members = tar.getmembers()
+        for m in members:
+            p = PurePosixPath(m.name)
+            if p.is_absolute() or ".." in p.parts or not p.parts:
+                raise ExtractError(f"unsafe archive member path: {m.name!r}")
+            if not m.isreg():
+                raise ExtractError(f"archive member {m.name!r} is not a regular file")
+        tar.extractall(path=dest, members=members, filter="data")
+        names = [m.name for m in members]
+    return names
+
+
+def manifest(dest: Path) -> dict[str, str]:
+    """sha256 per file under dest, excluded trees skipped — the before/after
+    bracket around a task run."""
+    out: dict[str, str] = {}
+    for path in sorted(dest.rglob("*")):
+        if not path.is_file() or path.is_symlink():
+            continue
+        rel = path.relative_to(dest).as_posix()
+        if _excluded(rel):
+            continue
+        h = hashlib.sha256()
+        try:
+            with path.open("rb") as f:
+                while chunk := f.read(1024 * 1024):
+                    h.update(chunk)
+        except OSError:
+            continue
+        out[rel] = h.hexdigest()
+    return out
+
+
+def diff(before: dict[str, str], after: dict[str, str]) -> tuple[list[str], list[str]]:
+    """(changed, deleted): new or modified paths, and paths that vanished."""
+    changed = [p for p, digest in after.items() if before.get(p) != digest]
+    deleted = [p for p in before if p not in after]
+    return sorted(changed), sorted(deleted)
+
+
+def build_result_tar(dest: Path, changed: list[str]) -> Path:
+    """tar.gz of the changed files (relative to dest) in a temp file the
+    caller uploads then deletes. Excluded paths never ride along."""
+    fd = tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False)
+    tar_path = Path(fd.name)
+    with tarfile.open(fileobj=fd, mode="w:gz") as tar:
+        for rel in changed:
+            if _excluded(rel):
+                continue
+            full = dest / rel
+            if not full.is_file() or full.is_symlink():
+                continue
+            tar.add(str(full), arcname=rel, recursive=False)
+    fd.close()
+    return tar_path

{genesis_cli-0.1.0 → genesis_cli-0.2.0}/tests/test_adopt.py

@@ -50,6 +50,23 @@ def test_run_audit_shapes_and_findings(tmp_path):
     assert abs(sum(c["points"] for c in r["categories"]) - r["score"]) < 0.2
 
 
+def test_documented_env_var_is_not_an_env_hygiene_gap(tmp_path):
+    """env_hygiene must measure declaration, not what this machine holds.
+
+    The seeded repo references ${API_SECRET_KEY} with no default; documenting
+    it in `.env.example` is exactly the fix the report asks for, so the gap has
+    to clear — previously it did not, which pinned the category at 0/10 in any
+    checkout whose compose files reference undefaulted vars.
+    """
+    repo = _seed_repo(tmp_path)
+    (repo / ".env.example").write_text("API_SECRET_KEY=\n")
+    report = run_audit(repo)
+    assert report["env"]["missing_required"] == []
+    env_cat = next(c for c in report["readiness"]["categories"]
+                   if c["key"] == "env_hygiene")
+    assert env_cat["points"] > 0
+
+
 def test_renderers_and_agents_md(tmp_path):
     report = run_audit(_seed_repo(tmp_path))
     term = render_terminal(report)

genesis_cli-0.2.0/tests/test_runner_config.py

@@ -0,0 +1,55 @@
+"""Runner config: round-trip, restrictive mode, resilience to junk."""
+
+from __future__ import annotations
+
+import stat
+
+import pytest
+from genesis_cli.runner.config import (
+    config_path,
+    load_config,
+    save_config,
+    work_root,
+)
+
+
+@pytest.fixture(autouse=True)
+def _home(tmp_path, monkeypatch):
+    monkeypatch.setenv("GENESIS_RUNNER_HOME", str(tmp_path / ".genesis"))
+
+
+def test_round_trip_and_mode():
+    path = save_config("https://genesis.example.com/", "grt_secret-token", "my laptop")
+    assert path == config_path()
+    mode = stat.S_IMODE(path.stat().st_mode)
+    assert mode == 0o600
+
+    cfg = load_config()
+    assert cfg == {"server": "https://genesis.example.com/",
+                   "token": "grt_secret-token", "name": "my laptop"}
+
+
+def test_overwrite_keeps_mode_0600():
+    save_config("https://a", "grt_1", "m")
+    save_config("https://b", "grt_2", "m")
+    assert stat.S_IMODE(config_path().stat().st_mode) == 0o600
+    assert load_config()["token"] == "grt_2"
+
+
+def test_values_with_quotes_and_backslashes_survive():
+    save_config("https://a", 'grt_we"ird\\tok', 'na"me')
+    cfg = load_config()
+    assert cfg["token"] == 'grt_we"ird\\tok' and cfg["name"] == 'na"me'
+
+
+def test_missing_or_bad_file_reads_empty():
+    assert load_config() == {}
+    config_path().parent.mkdir(parents=True, exist_ok=True)
+    config_path().write_text("not = valid = toml [")
+    assert load_config() == {}
+
+
+def test_work_root_is_created_under_runner_home(tmp_path):
+    root = work_root()
+    assert root.is_dir()
+    assert root == tmp_path / ".genesis" / "runner-work"

genesis_cli-0.2.0/tests/test_runner_driver.py

@@ -0,0 +1,135 @@
+"""ClaudeDriver: stream-json parsing against a fake `claude` on PATH —
+final-result extraction, assistant-text callback, oversized lines, env
+hygiene (ANTHROPIC_API_KEY never reaches the child)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import stat
+import textwrap
+from pathlib import Path
+
+import pytest
+from genesis_cli.runner.claude_driver import ClaudeDriver, check_cli
+
+BIG = 300_000  # > asyncio's default 64 KB line cap
+
+
+@pytest.fixture
+def fake_claude(tmp_path: Path, monkeypatch):
+    def install(body: str) -> None:
+        bin_dir = tmp_path / "bin"
+        bin_dir.mkdir(exist_ok=True)
+        script = bin_dir / "claude"
+        script.write_text("#!/usr/bin/env python3\n" + textwrap.dedent(body))
+        script.chmod(script.stat().st_mode | stat.S_IEXEC)
+        monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}")
+
+    return install
+
+
+STREAMING_BODY = f"""
+import json, os, sys
+args = sys.argv[1:]
+if args == ["--version"]:
+    print("1.2.3 (fake)")
+    sys.exit(0)
+# Record what the driver passed and what env the child saw.
+open("argv.json", "w").write(json.dumps(args))
+open("env.json", "w").write(json.dumps(
+    {{"has_api_key": "ANTHROPIC_API_KEY" in os.environ}}))
+print(json.dumps({{"type": "system", "session_id": "sess-fake"}}))
+print(json.dumps({{"type": "assistant", "session_id": "sess-fake",
+                   "message": {{"content": [{{"type": "text", "text": "hello "}},
+                                            {{"type": "text", "text": "world"}}]}}}}))
+# An oversized single line must not kill the stream.
+print(json.dumps({{"type": "tool_result", "data": "x" * {BIG}}}))
+print(json.dumps({{"type": "result", "subtype": "success", "is_error": False,
+                   "session_id": "sess-fake", "total_cost_usd": None,
+                   "usage": {{"input_tokens": 123, "output_tokens": 45}}}}))
+"""
+
+
+async def test_driver_parses_stream_and_scrubs_env(tmp_path, fake_claude, monkeypatch):
+    fake_claude(STREAMING_BODY)
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-should-not-leak")
+    ok, detail = check_cli()
+    assert ok and "1.2.3" in detail
+
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    texts: list[str] = []
+    result = await ClaudeDriver().run(
+        "build it", workdir=ws, resume_session="old-sess",
+        on_text=texts.append)
+
+    assert result["status"] == "completed"
+    assert result["session_id"] == "sess-fake"
+    assert result["usage"]["input_tokens"] == 123
+    assert result["usage"]["output_tokens"] == 45
+    assert result["usage"]["cost_usd"] is None  # subscription: no dollar cost
+    assert result["usage"]["duration_s"] is not None
+    assert result["error"] is None
+    assert texts == ["hello world"]
+
+    argv = json.loads((ws / "argv.json").read_text())
+    assert argv[:2] == ["-p", "build it"]
+    for flag in ("--output-format", "--verbose", "--add-dir",
+                 "--permission-mode", "--resume"):
+        assert flag in argv
+    assert argv[argv.index("--output-format") + 1] == "stream-json"
+    assert argv[argv.index("--permission-mode") + 1] == "acceptEdits"
+    assert argv[argv.index("--resume") + 1] == "old-sess"
+    assert argv[argv.index("--add-dir") + 1] == str(ws)
+    # The subscription rule: the child never sees an API key.
+    assert json.loads((ws / "env.json").read_text()) == {"has_api_key": False}
+
+
+FAILING_BODY = """
+import json, sys
+if sys.argv[1:] == ["--version"]:
+    print("1.2.3 (fake)"); sys.exit(0)
+print(json.dumps({"type": "result", "subtype": "error", "is_error": True,
+                  "session_id": "s2", "result": "budget exhausted",
+                  "usage": {"input_tokens": 1, "output_tokens": 0}}))
+sys.exit(1)
+"""
+
+
+async def test_driver_reports_cli_error(tmp_path, fake_claude):
+    fake_claude(FAILING_BODY)
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    result = await ClaudeDriver().run("x", workdir=ws)
+    assert result["status"] == "failed"
+    assert "budget exhausted" in (result["error"] or "")
+
+
+HANGING_BODY = """
+import sys, time
+if sys.argv[1:] == ["--version"]:
+    print("1.2.3 (fake)"); sys.exit(0)
+sys.stdout.write('{"type": "system", "session_id": "s3"}\\n')
+sys.stdout.flush()
+time.sleep(60)
+"""
+
+
+async def test_kill_marks_interrupted(tmp_path, fake_claude):
+    fake_claude(HANGING_BODY)
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    driver = ClaudeDriver()
+    task = asyncio.create_task(driver.run("x", workdir=ws))
+    await asyncio.sleep(0.5)
+    driver.kill()
+    result = await asyncio.wait_for(task, timeout=10)
+    assert result["status"] == "interrupted"
+
+
+async def test_missing_cli_guidance(monkeypatch, tmp_path):
+    monkeypatch.setenv("PATH", str(tmp_path / "empty-bin"))
+    ok, detail = check_cli()
+    assert ok is False and "PATH" in detail

genesis_cli-0.2.0/tests/test_runner_workspace.py

@@ -0,0 +1,103 @@
+"""Runner workspace handling: safe extraction, manifest diffs, result tars."""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+
+import pytest
+from genesis_cli.runner.workspace import (
+    ExtractError,
+    build_result_tar,
+    diff,
+    manifest,
+    safe_extract,
+)
+
+
+def _make_tar(tmp_path: Path, entries: dict[str, bytes], *, symlink: str | None = None) -> Path:
+    path = tmp_path / "in.tar.gz"
+    with tarfile.open(path, mode="w:gz") as tar:
+        for name, data in entries.items():
+            info = tarfile.TarInfo(name)
+            info.size = len(data)
+            tar.addfile(info, io.BytesIO(data))
+        if symlink:
+            info = tarfile.TarInfo(symlink)
+            info.type = tarfile.SYMTYPE
+            info.linkname = "/etc/passwd"
+            tar.addfile(info)
+    return path
+
+
+def test_safe_extract_happy_path(tmp_path):
+    tar = _make_tar(tmp_path, {"index.html": b"<h1>x</h1>", "src/app.js": b"1"})
+    dest = tmp_path / "ws"
+    names = safe_extract(tar, dest)
+    assert set(names) == {"index.html", "src/app.js"}
+    assert (dest / "src" / "app.js").read_bytes() == b"1"
+
+
+@pytest.mark.parametrize("name", ["../escape.txt", "/abs.txt", "a/../../up.txt"])
+def test_safe_extract_rejects_traversal(tmp_path, name):
+    tar = _make_tar(tmp_path, {name: b"evil", "ok.txt": b"fine"})
+    dest = tmp_path / "ws"
+    with pytest.raises(ExtractError):
+        safe_extract(tar, dest)
+    # Fail closed: nothing extracted from a bad archive.
+    assert not (dest / "ok.txt").exists()
+
+
+def test_safe_extract_rejects_symlinks(tmp_path):
+    tar = _make_tar(tmp_path, {"ok.txt": b"fine"}, symlink="sneaky")
+    with pytest.raises(ExtractError):
+        safe_extract(tar, tmp_path / "ws")
+
+
+def test_manifest_diff_detects_changes_and_deletions(tmp_path):
+    ws = tmp_path / "ws"
+    (ws / "sub").mkdir(parents=True)
+    (ws / "keep.txt").write_text("same")
+    (ws / "edit.txt").write_text("v1")
+    (ws / "sub" / "gone.txt").write_text("bye")
+    before = manifest(ws)
+
+    (ws / "edit.txt").write_text("v2")
+    (ws / "new.txt").write_text("hello")
+    (ws / "sub" / "gone.txt").unlink()
+    after = manifest(ws)
+
+    changed, deleted = diff(before, after)
+    assert changed == ["edit.txt", "new.txt"]
+    assert deleted == ["sub/gone.txt"]
+
+
+def test_manifest_skips_excluded_trees(tmp_path):
+    ws = tmp_path / "ws"
+    for d in (".git", "node_modules", ".genesis-work", "__pycache__", ".venv",
+              "dist", "build"):
+        (ws / d).mkdir(parents=True)
+        (ws / d / "f.txt").write_text("x")
+    (ws / ".env").write_text("SECRET=1")
+    (ws / ".env.local").write_text("SECRET=2")
+    (ws / "app.py").write_text("print(1)")
+    m = manifest(ws)
+    assert set(m) == {"app.py"}
+
+
+def test_result_tar_excludes_protected_paths(tmp_path):
+    ws = tmp_path / "ws"
+    ws.mkdir()
+    (ws / "good.txt").write_text("ok")
+    (ws / ".env").write_text("SECRET=1")
+    (ws / "node_modules").mkdir()
+    (ws / "node_modules" / "x.js").write_text("x")
+    # Even if the changed list names protected paths, they never ride along.
+    tar_path = build_result_tar(ws, ["good.txt", ".env", "node_modules/x.js",
+                                     "missing.txt"])
+    try:
+        with tarfile.open(tar_path, mode="r:gz") as tar:
+            assert [m.name for m in tar.getmembers()] == ["good.txt"]
+    finally:
+        tar_path.unlink()