regent-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{regent_cli-0.6.0 → regent_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regent-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project.
 Author-email: Flavio Alvim <flavioalvim@gmail.com>
 License: MIT

{regent_cli-0.6.0 → regent_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "regent-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project."
 readme = "README.md"
 requires-python = ">=3.10"

{regent_cli-0.6.0 → regent_cli-0.7.0}/src/regent/__init__.py

@@ -1,3 +1,3 @@
 """regent — autonomous conduction and mediated adversarial deliberation between AI agents."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{regent_cli-0.6.0 → regent_cli-0.7.0}/src/regent/activity_cli.py

@@ -28,6 +28,9 @@ _EXIT_BY_CODE = {
     "TURN_VIOLATION": 3, "TURN_TAMPERED": 3, "TURN_FAILED": 3, "NOT_ACTIVE": 2,
     "STEP_MISMATCH": 2, "ARTIFACT_OUTSIDE_REGENT": 2, "STEP_ALREADY_DONE": 2,
     "WORKTREE_DIRTY": 3,
+    "LOOP_HALTED": 3, "LOOP_ABORTED": 3, "LOOP_MAX_TURNS": 3, "LOOP_STOPPED": 2,
+    "LOOP_BUSY": 3, "PLAN_NOT_EXECUTABLE": 2, "LOOP_CONFLICT": 3, "LOOP_DIRTY": 3,
+    "LOOP_MISCONFIGURED": 2, "ABORT_PENDING": 3,
 }
 
 
@@ -105,6 +108,22 @@ def build_parser(sub) -> None:
     p.add_argument("--timeout", type=float, default=600.0)
     p.add_argument("--expect-verdict", default=None, dest="expect_verdict")
 
+    p_loop = sub.add_parser("loop", help="chain supervised turns over a plan")
+    p_loop.add_argument("--project", default=None)
+    loop_sub = p_loop.add_subparsers(dest="loop_command", required=True)
+    p = loop_sub.add_parser("run")
+    p.add_argument("--plan", required=True)
+    p.add_argument("--prompt-template", required=True, dest="prompt_template")
+    p.add_argument("--envelope", action="append", required=True)
+    p.add_argument("--gate-envelope", action="append", default=[], dest="gate_envelope")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--artifact-dir", required=True, dest="artifact_dir")
+    p.add_argument("--max-turns", type=int, default=20, dest="max_turns")
+    p.add_argument("--timeout", type=float, default=900.0)
+    p.add_argument("--claude-bin", default="claude", dest="claude_bin")
+    p = loop_sub.add_parser("abort")
+    p.add_argument("--reason", required=True)
+
     p_turn = sub.add_parser("turn", help="supervised confined production turn")
     p_turn.add_argument("--project", default=None)
     turn_sub = p_turn.add_subparsers(dest="turn_command", required=True)
@@ -179,6 +198,41 @@ def run(args, out=None) -> int:
                               "verdict": result["verdict"],
                               "artifact": result["artifact"]}, out)
             return _emit(result, 0, out)
+        if args.command == "loop":
+            if args.loop_command == "abort":
+                from .conduction.abort import AbortPending, write_abort_request
+                control = service.store.load()
+                activity = control.get("activity")
+                if activity is None:
+                    return _fail("NO_ACTIVITY", {"state": "idle"}, out)
+                token = (activity.get("turn") or {}).get("token")
+                try:
+                    req = write_abort_request(
+                        service.state_dir, activity_id=activity["id"],
+                        activity_epoch=activity["epoch"], turn_token=token,
+                        reason=args.reason)
+                except AbortPending:
+                    return _fail("ABORT_PENDING", {"reason": "an abort is already "
+                                                   "pending"}, out)
+                return _emit({"ok": True, "abort_id": req["id"]}, 0, out)
+            from .conduction.loop import LoopError, run_loop
+            try:
+                result = run_loop(
+                    root, plan_id=args.plan, prompt_template=Path(args.prompt_template),
+                    envelope=args.envelope, gate_envelope=args.gate_envelope,
+                    declared_in=Path(args.declared_in),
+                    artifact_dir=Path(args.artifact_dir), max_turns=args.max_turns,
+                    timeout=args.timeout, claude_bin=args.claude_bin)
+            except LoopError as exc:
+                return _fail(exc.code, exc.detail, out)
+            if not result["ok"]:
+                cond = result["stop_condition"]
+                code = {"HALTED": "LOOP_HALTED", "ABORTED": "LOOP_ABORTED",
+                        "MAX_TURNS": "LOOP_MAX_TURNS", "STOPPED": "LOOP_STOPPED",
+                        }.get(cond, cond if cond in _EXIT_BY_CODE else "LOOP_HALTED")
+                return _fail(code, {"stop_condition": cond, "turns": result["turns"],
+                                    "count": result["count"]}, out)
+            return _emit(result, 0, out)
         if args.command == "turn":
             from .conduction.turn import TurnError, run_turn
             from .conduction.gate import ProvenanceError

regent_cli-0.7.0/src/regent/conduction/abort.py

@@ -0,0 +1,130 @@
+"""Durable abort-request signalling (PLAN-005 STEP-01).
+
+A `regent loop abort` writes an abort-request into the DISPOSABLE XDG state
+(outside the repo), bound to {activity_id, activity_epoch, turn_token} plus the
+in-flight turn nonce. The in-flight turn's keep-alive reads it (~1s), validates
+the binding, and — only if a matching turn is in flight — signals cancellation.
+Honored exactly once (rename to `.claimed`); a request whose binding no longer
+matches is discarded with an audit record. Creation is O_EXCL: one pending
+abort at a time.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import Path
+
+from ..protocol.audit import AuditLog, utcnow
+
+
+class AbortPending(Exception):
+    """An abort-request is already pending (O_EXCL)."""
+
+
+def request_path(state_dir: Path) -> Path:
+    return Path(state_dir) / "abort.request"
+
+
+def write_abort_request(state_dir: Path, *, activity_id: str, activity_epoch: int,
+                        turn_token: str | None, reason: str) -> dict:
+    state_dir = Path(state_dir)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {"id": uuid.uuid4().hex, "activity_id": activity_id,
+               "activity_epoch": activity_epoch, "turn_token": turn_token,
+               "turn_nonce": _turn_in_flight(state_dir),  # bind to the CURRENT turn
+               "reason": reason, "requested_at": utcnow()}
+    path = request_path(state_dir)
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        raise AbortPending(str(path)) from None
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle)
+    return payload
+
+
+def write_turn_nonce(state_dir: Path, nonce: str) -> None:
+    """Marks a turn in flight (atomic tmp+replace)."""
+    target = Path(state_dir) / "turn.nonce"
+    tmp = target.with_name(".turn.nonce.tmp")
+    tmp.write_text(nonce, encoding="utf-8")
+    os.replace(tmp, target)
+
+
+def clear_turn_nonce(state_dir: Path) -> None:
+    try:
+        (Path(state_dir) / "turn.nonce").unlink()
+    except OSError:
+        pass
+
+
+def _turn_in_flight(state_dir: Path) -> str | None:
+    try:
+        return (Path(state_dir) / "turn.nonce").read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+
+
+def claim_matching_abort(state_dir: Path, audit: AuditLog, *, activity_id: str,
+                         activity_epoch: int, turn_token: str | None) -> dict | None:
+    """Returns and CLAIMS (rename → .claimed) a valid abort-request bound to the
+    current activity while a turn is in flight; discards a stale one (audited);
+    returns None if there is none/not honorable."""
+    path = request_path(state_dir)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    in_flight = _turn_in_flight(state_dir)
+    bound = (payload.get("activity_id") == activity_id
+             and payload.get("activity_epoch") == activity_epoch
+             and payload.get("turn_token") == turn_token
+             and payload.get("turn_nonce") is not None
+             and payload.get("turn_nonce") == in_flight)  # SAME turn, not just any
+    if not bound:
+        _discard(path, audit, payload, "binding mismatch or wrong/absent turn nonce")
+        return None
+    claimed = path.with_name(f"abort.claimed-{payload['id']}")  # unique, never clobbered
+    try:
+        os.replace(path, claimed)  # single claim
+    except OSError:
+        return None
+    return payload
+
+
+def pending_claimed(state_dir: Path) -> list[Path]:
+    """Unfinished aborts (claimed but not yet reconciled) — for recovery."""
+    return sorted(Path(state_dir).glob("abort.claimed-*"))
+
+
+def clear_claimed(state_dir: Path, *, activity_id: str | None = None,
+                  activity_epoch: int | None = None,
+                  turn_token: str | None = None) -> None:
+    """Removes claimed markers. If a binding is given, ONLY markers matching it
+    (never unrelated aborts)."""
+    import json as _json
+    for p in pending_claimed(state_dir):
+        if activity_id is not None:
+            try:
+                m = _json.loads(p.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            if not (m.get("activity_id") == activity_id
+                    and m.get("activity_epoch") == activity_epoch
+                    and m.get("turn_token") == turn_token):
+                continue  # a different abort — leave it
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
+def _discard(path: Path, audit: AuditLog, payload: dict, reason: str) -> None:
+    audit.append({"event": "abort_request_discarded", "request_id": payload.get("id"),
+                  "reason": reason})
+    try:
+        path.unlink()
+    except OSError:
+        pass

{regent_cli-0.6.0 → regent_cli-0.7.0}/src/regent/conduction/gate.py

@@ -22,7 +22,7 @@ class ProvenanceError(Exception):
 
 
 def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
-             linkage: str, timeout: float = 1800.0, runner=None) -> dict:
+             linkage: str, timeout: float = 1800.0, runner=None, cancel=None) -> dict:
     root = Path(root)
     if not command.strip():
         raise ProvenanceError("empty gate command is never declared")
@@ -41,7 +41,7 @@ def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
     # ONE cleanup guard around execution + both publishes (see consult.py).
     try:
         result = runner.run(["bash", "-c", command], cwd=str(root),
-                            timeout=timeout)
+                            timeout=timeout, cancel=cancel)
         raw = result.output_bytes
         output_bytes = len(raw)
         truncated = output_bytes > TAIL_LIMIT

regent_cli-0.7.0/src/regent/conduction/loop.py

@@ -0,0 +1,265 @@
+"""`regent loop run` — chains supervised turns over an approved build plan
+(PLAN-005 STEP-02). Deterministic driver: recompute the current step from disk,
+run one confined turn, map the outcome to a terminal condition. No own state
+(disk is the truth); no auto-retry; a mid-agent turn is never resumed.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from ..activity import ActivityService
+from ..protocol.control import _FlockMutex, MutationMutexBusy
+from .evidence import EvidenceSet, EvidenceConflict as _EvidenceConflict, header
+from .turn import TurnError, run_turn, _git, _slug
+
+# Outcome → loop stop condition (the complete map, PLAN-005 v3 §6).
+_HALT_OUTCOMES = {"GATE_RED", "TURN_VIOLATION", "TURN_TAMPERED", "FAILURE", "TIMEOUT"}
+
+
+class LoopError(Exception):
+    def __init__(self, code: str, detail: dict) -> None:
+        super().__init__(code)
+        self.code, self.detail = code, detail
+
+
+def _committed_steps(root: Path, plan_id: str) -> set[str]:
+    """Steps proven done: a commit reachable from HEAD whose message has the
+    exact `Regent-Step: PLAN-NNN/STEP-NN` trailer AND that touched
+    build/STEP-NN.md AND the file exists in HEAD."""
+    done = set()
+    build_rel = f".regent/plans/{plan_id}/build"
+    out = _git(root, "log", "--format=%H", f"--grep=^Regent-Step: {re.escape(plan_id)}/",
+               "-E")
+    for sha in out.split():
+        msg = _git(root, "log", "-1", "--format=%B", sha)
+        for m in re.finditer(rf"^Regent-Step: {re.escape(plan_id)}/(STEP-\d+)$",
+                             msg, re.M):
+            step = m.group(1)
+            step_path = f"{build_rel}/{step}.md"
+            touched = _git(root, "show", "--name-only", "--format=", sha)
+            if step_path in touched.split() and _file_in_head(root, step_path):
+                done.add(step)
+    return done
+
+
+def _file_in_head(root: Path, rel: str) -> bool:
+    r = subprocess.run(["git", "-C", str(root), "cat-file", "-e", f"HEAD:{rel}"],
+                       capture_output=True)
+    return r.returncode == 0
+
+
+def _declared_steps(plan_text: str) -> list[str]:
+    return sorted(set(re.findall(r"STEP-\d+", plan_text)),
+                  key=lambda s: int(s.split("-")[1]))
+
+
+def _step_gate(plan_text: str, step_name: str) -> str | None:
+    # Boundary = next step HEADING line, so a gate command containing a step
+    # name (e.g. a path) is not truncated (matches turn._step_gate).
+    m = re.search(rf"{re.escape(step_name)}\b(.*?)(?=\n#+[^\n]*STEP-\d+|\Z)",
+                  plan_text, re.S)
+    if not m:
+        return None
+    g = re.search(r"\*\*Gate:\*\*\s*`([^`]+)`", m.group(1))
+    return g.group(1) if g else None
+
+
+def _attempt_number(artifact_dir: Path, step_name: str) -> int:
+    """K = max existing tryN for this step + 1 (not a count)."""
+    existing = [int(m.group(1)) for p in artifact_dir.glob(f"TURN-*{step_name}*try*.md")
+                for m in [re.search(r"try(\d+)", p.name)] if m]
+    return (max(existing) + 1) if existing else 1
+
+
+def _approval_status(root: Path, plan_id: str) -> str | None:
+    path = root / ".regent" / "plans" / plan_id / "APPROVAL.md"
+    try:
+        m = re.search(r"^status:\s*(\S+)", path.read_text(encoding="utf-8"), re.M)
+        return m.group(1) if m else None
+    except OSError:
+        return None
+
+
+def run_loop(root: Path, *, plan_id: str, prompt_template: Path, envelope: list[str],
+             gate_envelope: list[str] | None, declared_in: Path, artifact_dir: Path,
+             max_turns: int = 20, timeout: float = 900.0, claude_bin: str = "claude",
+             runner=None, service: ActivityService | None = None) -> dict:
+    root = Path(root).resolve()
+    service = service or ActivityService(root)
+    artifact_dir = (root / artifact_dir).resolve() if not Path(artifact_dir).is_absolute() \
+        else Path(artifact_dir).resolve()
+    if max_turns < 1:
+        raise LoopError("USAGE", {"reason": "--max-turns must be >= 1"})
+    template = Path(prompt_template).read_text(encoding="utf-8")
+
+    loop_lock = _FlockMutex(service.state_dir / "loop.lock", timeout=0.5)
+    try:
+        loop_lock.__enter__()
+    except MutationMutexBusy:
+        raise LoopError("LOOP_BUSY", {"reason": "another loop run holds the loop lock"})
+    turns: list[dict] = []
+    condition = "COMPLETE"
+    try:
+      try:
+        while True:
+            control = service.store.load()
+            activity = control.get("activity")
+            if activity is None or activity["state"] != "ACTIVE" \
+                    or activity["type"] != "build" or activity["id"] != plan_id:
+                condition = "PLAN_NOT_EXECUTABLE"
+                break
+            if _approval_status(root, plan_id) != "APPROVED":
+                condition = "PLAN_NOT_EXECUTABLE"
+                break
+            plan_text = Path(declared_in).read_text(encoding="utf-8", errors="replace")
+            declared = _declared_steps(plan_text)
+            done = _committed_steps(root, plan_id)
+            remaining = [s for s in declared if s not in done]
+            if not remaining:
+                condition = "COMPLETE"
+                break
+            if len(turns) >= max_turns:
+                condition = "MAX_TURNS"
+                break
+            step = remaining[0]
+            gate = _step_gate(plan_text, step)
+            attempt = _attempt_number(artifact_dir, step)
+            prompt = template.replace("{step}", step).replace("{gate}", gate or "") \
+                .replace("{plan}", plan_id)
+            # write the prompt OUTSIDE the repo (state dir) — never dirty the
+            # worktree that run_turn requires clean.
+            prompt_file = service.state_dir / f"prompt-{step}-try{attempt}.txt"
+            prompt_file.write_text(prompt, encoding="utf-8")
+            try:
+                result = run_turn(
+                    root, prompt_file=prompt_file, envelope=envelope,
+                    gate_command=gate, declared_in=declared_in, step=f"{plan_id}/{step}",
+                    artifact_dir=artifact_dir, linkage=f"{plan_id}/{step}/try{attempt}",
+                    gate_envelope=gate_envelope, timeout=timeout, claude_bin=claude_bin,
+                    runner=runner, service=service, attempt=attempt)
+            except TurnError as exc:
+                condition = _EXC_TO_CONDITION.get(exc.code, "LOOP_CONFLICT")
+                turns.append({"step": step, "attempt": attempt, "outcome": exc.code,
+                              "commit": None})
+                break
+            except _EvidenceConflict:
+                condition = "LOOP_CONFLICT"
+                turns.append({"step": step, "attempt": attempt,
+                              "outcome": "EVIDENCE_CONFLICT", "commit": None})
+                break
+            except OSError as exc:
+                # spawn / IO failure of the turn itself → treat as a failed turn
+                condition = "HALTED"
+                turns.append({"step": step, "attempt": attempt,
+                              "outcome": "FAILURE",
+                              "detail": f"{type(exc).__name__}: {exc}", "commit": None})
+                break
+            except subprocess.CalledProcessError as exc:
+                condition = "LOOP_CONFLICT"
+                turns.append({"step": step, "attempt": attempt,
+                              "outcome": f"GIT_ERROR:{exc.returncode}", "commit": None})
+                break
+            finally:
+                try:
+                    prompt_file.unlink()
+                except OSError:
+                    pass
+            turns.append({"step": step, "attempt": attempt,
+                          "outcome": result["outcome"], "commit": result.get("commit")})
+            outcome = result["outcome"]
+            if outcome == "TURN_OK":
+                continue  # advance; recompute from disk
+            if outcome == "STOPPED":
+                condition = "STOPPED"
+                break
+            if outcome == "ABORTED":
+                condition = "ABORTED"
+                break
+            if outcome in _HALT_OUTCOMES:
+                condition = "HALTED"
+                break
+            condition = "LOOP_CONFLICT"
+            break
+      except subprocess.CalledProcessError:
+        condition = "LOOP_CONFLICT"
+      try:
+        summary_conflict = _write_loop_evidence(root, artifact_dir, service,
+                                                condition, turns)
+        if summary_conflict:
+            condition = "LOOP_CONFLICT"  # summary could not commit (any prior cond)
+      except subprocess.CalledProcessError:
+        condition = "LOOP_CONFLICT"  # any git error in the summary is a conflict
+    finally:
+        loop_lock.__exit__(None, None, None)
+
+    ok = condition == "COMPLETE"
+    return {"ok": ok, "stop_condition": condition, "turns": turns, "count": len(turns)}
+
+
+_EXC_TO_CONDITION = {
+    "NOT_ACTIVE": "PLAN_NOT_EXECUTABLE", "CONFLICT": "LOOP_CONFLICT",
+    "WORKTREE_DIRTY": "LOOP_DIRTY", "PROVENANCE": "LOOP_MISCONFIGURED",
+    "STEP_MISMATCH": "LOOP_MISCONFIGURED", "ARTIFACT_OUTSIDE_REGENT": "LOOP_MISCONFIGURED",
+    "STEP_ALREADY_DONE": "LOOP_MISCONFIGURED", "STOPPED": "STOPPED",
+}
+
+
+def _write_loop_evidence(root: Path, artifact_dir: Path, service: ActivityService,
+                         condition: str, turns: list[dict]) -> None:
+    slug = _slug(f"{condition}-{len(turns)}")
+    artifact = artifact_dir / f"LOOP-{slug}.md"
+    evidence = EvidenceSet(artifact, {})
+    try:
+        evidence.precheck()
+    except _EvidenceConflict:  # never block on evidence naming
+        artifact = artifact_dir / f"LOOP-{slug}-{len(list(artifact_dir.glob('LOOP-*')))}.md"
+        evidence = EvidenceSet(artifact, {})
+    body = "\n".join(
+        f"- {t['step']} try{t['attempt']} → {t['outcome']}"
+        + (f" ({t['commit'][:8]})" if t.get("commit") else "") for t in turns)
+    evidence.write_main(header(condition, None, "loop", turns=len(turns)),
+                        body or "(no turns)")
+    # Summary commit through a PRIVATE index + HEAD CAS (never the shared index;
+    # no accidentally-staged files). Fenced when a token exists (ACTIVE); a plain
+    # CAS commit when SUSPENDED (no token) — both under the loop lock still held.
+    import os as _os
+    import tempfile as _tf
+    from ..protocol.control import assert_turn_token, NotLockOwner
+    control = service.store.load()
+    activity = control.get("activity")
+    token = (activity.get("turn") or {}).get("token") if activity else None
+    rel = str(artifact.relative_to(root))
+    base_sha = _git(root, "rev-parse", "HEAD").strip()
+    index = Path(_tf.mktemp(prefix="regent-loop-index-"))
+    env = dict(_os.environ, GIT_INDEX_FILE=str(index))
+    try:
+        _git(root, "read-tree", "HEAD", env=env)
+        _git(root, "add", "--", rel, env=env)
+        base_tree = _git(root, "rev-parse", "HEAD^{tree}").strip()
+        tree = _git(root, "write-tree", env=env).strip()
+        if tree == base_tree:
+            return False
+        msg = (f"loop(PLAN-005): {condition} summary ({len(turns)} turns)\n\n"
+               f"Regent-Loop: {condition}")
+        commit = _git(root, "commit-tree", tree, "-p", base_sha, "-m", msg,
+                      env=env).strip()
+        # Fencing + CAS in the SMALLEST window right before advancing HEAD.
+        if token is not None:
+            try:
+                assert_turn_token(service.store.load(), token)
+            except NotLockOwner:
+                return True  # taken over — summary NOT committed (conflict)
+        if _git(root, "rev-parse", "HEAD").strip() != base_sha:
+            return True  # HEAD moved (raced with resume) — conflict
+        _git(root, "update-ref", "-m", "regent loop summary", "HEAD", commit, base_sha,
+             env=env)
+        _git(root, "reset", "--mixed", "HEAD")
+        return False
+    finally:
+        try:
+            index.unlink()
+        except OSError:
+            pass

regent_cli-0.7.0/src/regent/conduction/process.py

@@ -0,0 +1,70 @@
+"""Injectable process runner for the conduction commands (PLAN-003).
+
+The real runner launches the child in a NEW SESSION (its own process group);
+on timeout the WHOLE group is SIGKILLed before the TIMEOUT outcome is
+reported — no child (not even ones spawned by bash) survives the result.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass
+class RunResult:
+    exit_code: int | None
+    output_bytes: bytes
+    timed_out: bool
+    aborted: bool = False
+
+    @property
+    def output(self) -> str:
+        return self.output_bytes.decode("utf-8", errors="replace")
+
+
+class SubprocessRunner:
+    def run(self, argv: list[str], *, cwd: str, timeout: float,
+            env: dict | None = None, cancel=None) -> RunResult:
+        """Cancellable + deadlock-free: a reader THREAD drains stdout while the
+        main loop polls `cancel` (checked BEFORE timeout — deterministic
+        precedence) and the deadline. On either, the whole group is SIGKILLed
+        and the group reaped. `aborted` (cancel) is distinct from `timed_out`."""
+        import threading
+        import time as _time
+        proc = subprocess.Popen(argv, cwd=cwd, stdin=subprocess.DEVNULL,
+                                stdout=subprocess.PIPE,
+                                stderr=subprocess.STDOUT, env=env,
+                                start_new_session=True)
+        chunks: list[bytes] = []
+        reader = threading.Thread(target=lambda: chunks.append(proc.stdout.read()),
+                                  daemon=True)
+        reader.start()
+        deadline = _time.monotonic() + timeout
+        aborted = timed_out = False
+        while True:
+            if cancel is not None and cancel.is_set():  # cancel BEFORE timeout
+                aborted = True
+                break
+            if _time.monotonic() >= deadline:
+                timed_out = True
+                break
+            if proc.poll() is not None:
+                break
+            _time.sleep(0.1)
+        if aborted or timed_out:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+        proc.wait()  # reap the group leader
+        reader.join(timeout=5)
+        try:
+            proc.stdout.close()
+        except OSError:
+            pass
+        output = chunks[0] if chunks else b""
+        exit_code = None if (aborted or timed_out) else proc.returncode
+        return RunResult(exit_code, output or b"", timed_out, aborted)