agentpool-cli 0.1.6__tar.gz → 0.1.7__tar.gz

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.1.7 - 2026-06-01
+
+- Centralize non-interactive subprocess execution behind terminal-safe helpers.
+  Git, tmux client operations, provider detection, Cursor status checks, Codex
+  app-server probes, and external usage helpers now detach from the host TTY by
+  default.
+- Add a subprocess-safety regression test so new product code cannot introduce
+  raw `subprocess.run`/`Popen` calls outside the shared utility.
+
 ## 0.1.6 - 2026-06-01
 
 - Run external usage helper commands in isolated, non-interactive subprocess

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.6
+Version: 0.1.7
 Summary: Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom.
 Author: AgentPool contributors
 License-Expression: MIT

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.6"
+version = "0.1.7"
 description = "Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom."
 readme = "README.md"
 requires-python = ">=3.11"

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sidduHERE/agentpool",
   "title": "AgentPool",
   "description": "See each coding-agent subscription's live limits and offload work to one with headroom.",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "repository": {
     "url": "https://github.com/sidduHERE/agentpool",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "agentpool-cli",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "transport": {
         "type": "stdio"
       },

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/src/agentpool/__init__.py

@@ -1,3 +1,3 @@
 """AgentPool local agent control plane."""
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/src/agentpool/git_worktree.py

@@ -1,6 +1,4 @@
 from __future__ import annotations
-
-import subprocess
 from pathlib import Path
 
 from agentpool.models import ToolError
@@ -41,12 +39,9 @@ def create_worktree(repo_path: Path, provider_id: str, session_id: str) -> Path:
     parent.mkdir(parents=True, exist_ok=True)
     worktree_path = parent / session_id
     branch = agentpool_branch(provider_id, session_id)
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "worktree", "add", "-b", branch, str(worktree_path)],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         raise ToolError(
@@ -66,12 +61,9 @@ def delete_agentpool_branch(repo_path: Path, provider_id: str, session_id: str)
     if not is_git_repo(repo_path):
         return {"deleted": False, "reason": "not_git_repo"}
     branch = agentpool_branch(provider_id, session_id)
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "branch", "-D", branch],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         return {"deleted": False, "branch": branch, "stderr": proc.stderr.strip()}
@@ -81,12 +73,9 @@ def delete_agentpool_branch(repo_path: Path, provider_id: str, session_id: str)
 def list_agentpool_worktrees(repo_path: Path) -> list[dict[str, str | bool]]:
     if not is_git_repo(repo_path):
         return []
-    proc = subprocess.run(
+    proc = run_capture(
         ["git", "worktree", "list", "--porcelain"],
-        cwd=str(repo_path),
-        text=True,
-        capture_output=True,
-        check=False,
+        cwd=repo_path,
     )
     if proc.returncode != 0:
         return []
@@ -128,7 +117,7 @@ def cleanup_worktree(repo_path: Path, worktree_path: Path, force: bool = False)
     if force:
         args.append("--force")
     args.append(str(worktree_path))
-    proc = subprocess.run(args, cwd=str(repo_path), text=True, capture_output=True, check=False)
+    proc = run_capture(args, cwd=repo_path)
     if proc.returncode != 0:
         raise ToolError(
             "WORKTREE_CLEANUP_FAILED",

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/src/agentpool/runtimes/tmux.py

@@ -3,10 +3,10 @@ from __future__ import annotations
 import os
 import signal
 import shutil
-import subprocess
 from pathlib import Path
 
 from agentpool.models import RuntimeKind, TmuxSessionRef, ToolError
+from agentpool.utils import run_capture
 
 
 class TmuxRuntime:
@@ -28,29 +28,22 @@ class TmuxRuntime:
         merged_env = os.environ.copy()
         if env:
             merged_env.update(env)
-        try:
-            subprocess.run(
-                [tmux, "new-session", "-d", "-s", session_name, "-c", str(cwd), *command],
-                env=merged_env,
-                text=True,
-                capture_output=True,
-                check=True,
-            )
-        except subprocess.CalledProcessError as exc:
+        proc = run_capture(
+            [tmux, "new-session", "-d", "-s", session_name, "-c", str(cwd), *command],
+            env=merged_env,
+        )
+        if proc.returncode != 0:
             raise ToolError(
                 "SPAWN_FAILED",
                 f"Failed to create tmux session {session_name}.",
-                {"stderr": exc.stderr, "stdout": exc.stdout, "command": command},
-            ) from exc
+                {"stderr": proc.stderr, "stdout": proc.stdout, "command": command},
+            )
         return TmuxSessionRef(session_name=session_name)
 
     def capture(self, ref: TmuxSessionRef, lines: int = 300) -> str:
         tmux = self.require_tmux()
-        proc = subprocess.run(
+        proc = run_capture(
             [tmux, "capture-pane", "-p", "-J", "-t", ref.target, "-S", f"-{lines}"],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             raise ToolError(
@@ -66,18 +59,27 @@ class TmuxRuntime:
             return
         tmux = self.require_tmux()
         buffer_name = f"agentpool-{ref.session_name}"
-        subprocess.run([tmux, "load-buffer", "-b", buffer_name, "-"], input=text, text=True, check=True)
-        subprocess.run([tmux, "paste-buffer", "-b", buffer_name, "-t", ref.target], check=True)
+        load = run_capture([tmux, "load-buffer", "-b", buffer_name, "-"], input_text=text)
+        if load.returncode != 0:
+            raise ToolError(
+                "TMUX_SEND_FAILED",
+                f"Could not load tmux paste buffer for {ref.target}.",
+                {"stderr": load.stderr},
+            )
+        paste = run_capture([tmux, "paste-buffer", "-b", buffer_name, "-t", ref.target])
+        if paste.returncode != 0:
+            raise ToolError(
+                "TMUX_SEND_FAILED",
+                f"Could not paste tmux buffer to {ref.target}.",
+                {"stderr": paste.stderr},
+            )
         if submit and not text.endswith("\n"):
             self.send_keys(ref, ["Enter"])
 
     def send_keys(self, ref: TmuxSessionRef, keys: list[str]) -> None:
         tmux = self.require_tmux()
-        proc = subprocess.run(
+        proc = run_capture(
             [tmux, "send-keys", "-t", ref.target, *keys],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             raise ToolError(
@@ -95,7 +97,7 @@ class TmuxRuntime:
     def terminate(self, ref: TmuxSessionRef) -> None:
         tmux = self.require_tmux()
         pgid = self._pane_process_group(ref)
-        subprocess.run([tmux, "kill-session", "-t", ref.session_name], check=False)
+        run_capture([tmux, "kill-session", "-t", ref.session_name])
         if pgid is not None:
             try:
                 os.killpg(pgid, signal.SIGTERM)
@@ -107,22 +109,16 @@ class TmuxRuntime:
     def exists(self, ref: TmuxSessionRef) -> bool:
         if not self.tmux_binary:
             return False
-        proc = subprocess.run(
+        proc = run_capture(
             [self.tmux_binary, "has-session", "-t", ref.session_name],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         return proc.returncode == 0
 
     def _pane_process_group(self, ref: TmuxSessionRef) -> int | None:
         if not self.tmux_binary:
             return None
-        proc = subprocess.run(
+        proc = run_capture(
             [self.tmux_binary, "display-message", "-p", "-t", ref.target, "#{pane_pid}"],
-            text=True,
-            capture_output=True,
-            check=False,
         )
         if proc.returncode != 0:
             return None

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/src/agentpool/usage/_common.py

@@ -17,6 +17,7 @@ import certifi
 
 from agentpool.models import CapacitySnapshot, Confidence, TmuxSessionRef, UsageStatus, UsageWindow, UsageWindowKind
 from agentpool.runtimes.tmux import TmuxRuntime
+from agentpool.utils import run_capture, terminate_process_group
 
 
 class ProbeError(Exception):
@@ -65,34 +66,12 @@ def _urlopen(
     return urllib.request.urlopen(request, timeout=timeout, context=context)
 
 
-def _probe_env() -> dict[str, str]:
-    env = os.environ.copy()
-    env.update(
-        {
-            "TERM": "dumb",
-            "NO_COLOR": "1",
-            "CLICOLOR": "0",
-            "FORCE_COLOR": "0",
-        }
-    )
-    return env
-
-
 def _run_probe_command(
     command: list[str],
     *,
     timeout: float,
 ) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        command,
-        stdin=subprocess.DEVNULL,
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-        check=False,
-        start_new_session=True,
-        env=_probe_env(),
-    )
+    return run_capture(command, timeout=timeout, terminal_dumb=True)
 
 
 def _request_json(request: urllib.request.Request) -> dict[str, Any]:
@@ -248,12 +227,7 @@ def _clean_optional_string(value: object) -> str | None:
 
 
 def _terminate_process(proc: subprocess.Popen[str]) -> None:
-    if proc.poll() is None:
-        proc.terminate()
-        try:
-            proc.wait(timeout=1)
-        except subprocess.TimeoutExpired:
-            proc.kill()
+    terminate_process_group(proc)
 
 
 def _safe_read_pipe(pipe: Any) -> str:

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/src/agentpool/usage/codex.py

@@ -20,6 +20,7 @@ from agentpool.usage._common import (
     unavailable,
     unknown,
 )
+from agentpool.utils import popen_text
 
 
 def codex_cli_usage_snapshot(provider_id: str, binary: str | None = None) -> CapacitySnapshot:
@@ -79,12 +80,9 @@ def parse_codex_rate_limits(provider_id: str, payload: dict[str, Any]) -> Capaci
 
 
 def _codex_rpc_rate_limits(executable: str) -> dict[str, Any]:
-    proc = subprocess.Popen(
+    proc = popen_text(
         [executable, "-s", "read-only", "-a", "untrusted", "app-server"],
-        stdin=subprocess.PIPE,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
+        terminal_dumb=True,
     )
     try:
         _json_rpc_request(proc, 1, "initialize", {"clientInfo": {"name": "agentpool", "version": "0.1.0"}}, 8.0)

agentpool_cli-0.1.7/src/agentpool/utils.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import signal
+import subprocess
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def new_session_id() -> str:
+    return f"ap_{uuid.uuid4().hex[:12]}"
+
+
+def repo_hash(path: Path) -> str:
+    return hashlib.sha256(str(path.resolve()).encode("utf-8")).hexdigest()[:16]
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True, default=str) + "\n")
+
+
+def append_jsonl(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(data, sort_keys=True, default=str) + "\n")
+
+
+def subprocess_env(
+    env: dict[str, str] | None = None,
+    *,
+    terminal_dumb: bool = False,
+) -> dict[str, str]:
+    merged = os.environ.copy()
+    if env:
+        merged.update(env)
+    if terminal_dumb:
+        merged.update(
+            {
+                "TERM": "dumb",
+                "NO_COLOR": "1",
+                "CLICOLOR": "0",
+                "FORCE_COLOR": "0",
+            }
+        )
+    return merged
+
+
+def run_capture(
+    args: list[str],
+    cwd: Path | None = None,
+    timeout: float = 10,
+    *,
+    env: dict[str, str] | None = None,
+    input_text: str | None = None,
+    terminal_dumb: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    stdin = subprocess.PIPE if input_text is not None else subprocess.DEVNULL
+    proc = subprocess.Popen(
+        args,
+        cwd=str(cwd) if cwd else None,
+        stdin=stdin,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        start_new_session=True,
+        env=subprocess_env(env, terminal_dumb=terminal_dumb),
+    )
+    try:
+        stdout, stderr = proc.communicate(input_text, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        terminate_process_group(proc)
+        stdout = exc.stdout or ""
+        stderr = exc.stderr or "timed out"
+        if isinstance(stdout, bytes):
+            stdout = stdout.decode("utf-8", errors="replace")
+        if isinstance(stderr, bytes):
+            stderr = stderr.decode("utf-8", errors="replace")
+        return subprocess.CompletedProcess(args, 124, stdout, stderr)
+    return subprocess.CompletedProcess(args, proc.returncode, stdout, stderr)
+
+
+def popen_text(
+    args: list[str],
+    *,
+    env: dict[str, str] | None = None,
+    terminal_dumb: bool = False,
+) -> subprocess.Popen[str]:
+    return subprocess.Popen(
+        args,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        start_new_session=True,
+        env=subprocess_env(env, terminal_dumb=terminal_dumb),
+    )
+
+
+def terminate_process_group(proc: subprocess.Popen[str], timeout: float = 1) -> None:
+    if proc.poll() is not None:
+        return
+    try:
+        os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+    except OSError:
+        try:
+            proc.terminate()
+        except OSError:
+            return
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except OSError:
+            try:
+                proc.kill()
+            except OSError:
+                return
+
+
+def expand_user_path(value: str) -> Path:
+    return Path(os.path.expandvars(value)).expanduser()

agentpool_cli-0.1.7/tests/unit/test_subprocess_safety.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from agentpool import utils
+
+
+def test_run_capture_detaches_from_host_terminal(monkeypatch) -> None:
+    seen: dict[str, object] = {}
+
+    class FakeProcess:
+        pid = 12345
+        returncode = 0
+
+        def communicate(self, input: str | None = None, timeout: float | None = None) -> tuple[str, str]:
+            seen["communicate_input"] = input
+            seen["communicate_timeout"] = timeout
+            return "out", ""
+
+    def fake_popen(command: list[str], **kwargs: object) -> FakeProcess:
+        seen["command"] = command
+        seen.update(kwargs)
+        return FakeProcess()
+
+    monkeypatch.setattr(utils.subprocess, "Popen", fake_popen)
+
+    result = utils.run_capture(["helper", "usage"], cwd=Path("/tmp"), timeout=3, terminal_dumb=True)
+
+    assert result.stdout == "out"
+    assert seen["command"] == ["helper", "usage"]
+    assert seen["cwd"] == "/tmp"
+    assert seen["stdin"] is subprocess.DEVNULL
+    assert seen["stdout"] is subprocess.PIPE
+    assert seen["stderr"] is subprocess.PIPE
+    assert seen["text"] is True
+    assert seen["start_new_session"] is True
+    assert seen["communicate_timeout"] == 3
+    env = seen["env"]
+    assert isinstance(env, dict)
+    assert env["TERM"] == "dumb"
+    assert env["NO_COLOR"] == "1"
+    assert env["CLICOLOR"] == "0"
+    assert env["FORCE_COLOR"] == "0"
+
+
+def test_run_capture_uses_pipe_only_for_explicit_input(monkeypatch) -> None:
+    seen: dict[str, object] = {}
+
+    class FakeProcess:
+        pid = 12345
+        returncode = 0
+
+        def communicate(self, input: str | None = None, timeout: float | None = None) -> tuple[str, str]:
+            seen["communicate_input"] = input
+            return "", ""
+
+    def fake_popen(command: list[str], **kwargs: object) -> FakeProcess:
+        seen.update(kwargs)
+        return FakeProcess()
+
+    monkeypatch.setattr(utils.subprocess, "Popen", fake_popen)
+
+    utils.run_capture(["tmux", "load-buffer"], input_text="hello")
+
+    assert seen["stdin"] is subprocess.PIPE
+    assert seen["communicate_input"] == "hello"
+    assert seen["start_new_session"] is True
+
+
+def test_run_capture_timeout_terminates_process_group(monkeypatch) -> None:
+    seen: dict[str, object] = {}
+
+    class FakeProcess:
+        pid = 12345
+        returncode = None
+
+        def communicate(self, input: str | None = None, timeout: float | None = None) -> tuple[str, str]:
+            raise subprocess.TimeoutExpired(["slow"], timeout or 0, output="partial")
+
+        def poll(self) -> None:
+            return None
+
+        def terminate(self) -> None:
+            seen["terminated"] = True
+
+        def wait(self, timeout: float | None = None) -> None:
+            seen["wait_timeout"] = timeout
+            self.returncode = -15
+
+    def fake_popen(command: list[str], **kwargs: object) -> FakeProcess:
+        return FakeProcess()
+
+    monkeypatch.setattr(utils.subprocess, "Popen", fake_popen)
+    monkeypatch.setattr(utils.os, "getpgid", lambda pid: pid)
+    monkeypatch.setattr(utils.os, "killpg", lambda pgid, sig: seen.update({"pgid": pgid, "signal": sig}))
+
+    result = utils.run_capture(["slow"], timeout=0.01)
+
+    assert result.returncode == 124
+    assert result.stdout == "partial"
+    assert seen["pgid"] == 12345
+    assert seen["wait_timeout"] == 1
+
+
+def test_popen_text_detaches_from_host_terminal(monkeypatch) -> None:
+    seen: dict[str, object] = {}
+
+    class FakeProcess:
+        pass
+
+    def fake_popen(command: list[str], **kwargs: object) -> FakeProcess:
+        seen["command"] = command
+        seen.update(kwargs)
+        return FakeProcess()
+
+    monkeypatch.setattr(utils.subprocess, "Popen", fake_popen)
+
+    proc = utils.popen_text(["codex", "app-server"], terminal_dumb=True)
+
+    assert isinstance(proc, FakeProcess)
+    assert seen["stdin"] is subprocess.PIPE
+    assert seen["stdout"] is subprocess.PIPE
+    assert seen["stderr"] is subprocess.PIPE
+    assert seen["text"] is True
+    assert seen["start_new_session"] is True
+    env = seen["env"]
+    assert isinstance(env, dict)
+    assert env["TERM"] == "dumb"
+
+
+def test_product_code_uses_subprocess_only_through_utils() -> None:
+    root = Path(__file__).resolve().parents[2] / "src" / "agentpool"
+    offenders: list[str] = []
+    for path in root.rglob("*.py"):
+        if path.name == "utils.py":
+            continue
+        text = path.read_text(encoding="utf-8")
+        for needle in ("subprocess.run(", "subprocess.Popen(", "subprocess.check_output(", "subprocess.check_call("):
+            if needle in text:
+                offenders.append(f"{path.relative_to(root)} uses {needle}")
+
+    assert offenders == []

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/tests/unit/test_usage_probes.py

@@ -311,27 +311,19 @@ def test_usage_http_requests_use_certifi_context(monkeypatch: pytest.MonkeyPatch
 def test_usage_probe_subprocesses_are_tty_isolated(monkeypatch: pytest.MonkeyPatch) -> None:
     seen: dict[str, object] = {}
 
-    def fake_run(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+    def fake_run_capture(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        seen["command"] = command
         seen.update(kwargs)
         return subprocess.CompletedProcess(command, 0, "{}", "")
 
-    monkeypatch.setattr(usage_common.subprocess, "run", fake_run)
+    monkeypatch.setattr(usage_common, "run_capture", fake_run_capture)
 
     result = usage_common._run_probe_command(["codexbar", "usage"], timeout=7)
 
     assert result.returncode == 0
-    assert seen["stdin"] is subprocess.DEVNULL
-    assert seen["capture_output"] is True
-    assert seen["text"] is True
+    assert seen["command"] == ["codexbar", "usage"]
     assert seen["timeout"] == 7
-    assert seen["check"] is False
-    assert seen["start_new_session"] is True
-    env = seen["env"]
-    assert isinstance(env, dict)
-    assert env["TERM"] == "dumb"
-    assert env["NO_COLOR"] == "1"
-    assert env["CLICOLOR"] == "0"
-    assert env["FORCE_COLOR"] == "0"
+    assert seen["terminal_dumb"] is True
 
 
 def test_devin_plan_status_request_contains_auth_and_top_up_flag() -> None:

{agentpool_cli-0.1.6 → agentpool_cli-0.1.7}/uv.lock

@@ -3,7 +3,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentpool-cli"
-version = "0.1.6"
+version = "0.1.7"
 source = { editable = "." }
 dependencies = [
     { name = "certifi" },

agentpool_cli-0.1.6/src/agentpool/utils.py

@@ -1,59 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import subprocess
-import uuid
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-
-def utc_now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def new_session_id() -> str:
-    return f"ap_{uuid.uuid4().hex[:12]}"
-
-
-def repo_hash(path: Path) -> str:
-    return hashlib.sha256(str(path.resolve()).encode("utf-8")).hexdigest()[:16]
-
-
-def sha256_file(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as fh:
-        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def write_json(path: Path, data: Any) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2, sort_keys=True, default=str) + "\n")
-
-
-def append_jsonl(path: Path, data: Any) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("a", encoding="utf-8") as fh:
-        fh.write(json.dumps(data, sort_keys=True, default=str) + "\n")
-
-
-def run_capture(args: list[str], cwd: Path | None = None, timeout: float = 10) -> subprocess.CompletedProcess[str]:
-    try:
-        return subprocess.run(
-            args,
-            cwd=str(cwd) if cwd else None,
-            text=True,
-            capture_output=True,
-            timeout=timeout,
-            check=False,
-        )
-    except subprocess.TimeoutExpired as exc:
-        return subprocess.CompletedProcess(args, 124, exc.stdout or "", exc.stderr or "timed out")
-
-
-def expand_user_path(value: str) -> Path:
-    return Path(os.path.expandvars(value)).expanduser()