pilot-workers 0.2.0__py3-none-any.whl

pilot_workers/runners/opencode_runner.py

@@ -0,0 +1,377 @@
+"""OpenCode runner adapter — concrete Runner for the opencode-ai CLI.
+
+This module is the new home for the OpenCode-specific glue that used to live
+inline in ``cli/run.py`` / ``runtime.py`` / ``cli/dispatch.py`` /
+``fmt_events.py``. Behaviour is preserved verbatim from those sources.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from pilot_workers import policy
+from pilot_workers.providers import (
+    Provider,
+    pilot_home,
+    profile_paths,
+    profile_root,
+)
+from pilot_workers.runners.base import (
+    Runner,
+    TokenUsage,
+    ToolCall,
+    UnifiedEvent,
+)
+
+
+# Pinned engine version. Single source of truth — install_runtime.sh and
+# everything else reads it from here.
+PINNED_OPENCODE_VERSION = "1.18.4"
+
+# Substring in a tool error message that signals a permission-rule denial.
+# Mirrors the check formerly inlined in ``cli/dispatch.py`` (parse_jsonl,
+# tool_use branch).
+_PERMISSION_DENIED_MARK = "rule which prevents"
+
+# Tools whose output is a file dump or a plain confirmation — the input path
+# already says everything; echoing the output only adds noise. Mirrors
+# ``fmt_events.SILENT_OUTPUT_TOOLS`` (deleted from there).
+SILENT_OUTPUT_TOOLS = {"read", "edit", "write", "list", "todowrite"}
+
+# Renderer input/output limits (mirror fmt_events defaults verbatim).
+_INPUT_LIMIT = 200
+
+
+class OpenCodeRunner(Runner):
+    """Adapter for the opencode-ai CLI (pinned to ``PINNED_OPENCODE_VERSION``)."""
+
+    name = "opencode"
+
+    # ------------------------------------------------------------------
+    # config / command / env
+    # ------------------------------------------------------------------
+
+    def build_config(
+        self, provider: Any, mode: str, permission_profile: str | None = None,
+    ) -> dict:
+        # Thin pass-through to policy.build_config — single source of truth.
+        return policy.build_config(
+            provider, mode, permission_profile=permission_profile,
+        )
+
+    def build_command(
+        self, binary: Path, provider: Any, mode: str,
+        workdir: Path, run_id: str, session: str | None,
+    ) -> list[str]:
+        # Mirrors cli/run.py:118-128 exactly.
+        command = [
+            str(binary), "--pure", "run",
+            "--model", provider.model,
+            "--agent", policy.MODE_TO_AGENT[mode],
+            "--format", "json",
+            "--thinking",
+            "--title", f"pilot-worker-{mode}-{run_id}",
+            "--dir", str(workdir),
+        ]
+        if session:
+            command.extend(["--session", session])
+        return command
+
+    def runner_environment(self, provider: Any, config: dict) -> dict[str, str]:
+        # Mirrors the OpenCode-only slice of the former runtime.build_environment
+        # (runtime.py:47-56). Neutral keys (SAFE_ENV_KEYS, XDG_*, NO_COLOR,
+        # CI) are added by the runtime layer, not here.
+        paths = profile_paths(provider)
+        return {
+            "OPENCODE_CONFIG_DIR": str(paths["config"] / "opencode"),
+            "OPENCODE_CONFIG_CONTENT": json.dumps(config, separators=(",", ":")),
+            "OPENCODE_DISABLE_AUTOUPDATE": "1",
+            "OPENCODE_AUTO_SHARE": "false",
+            "OPENCODE_DISABLE_DEFAULT_PLUGINS": "1",
+            "OPENCODE_DISABLE_LSP_DOWNLOAD": "1",
+            "OPENCODE_DISABLE_MODELS_FETCH": "1",
+            "OPENCODE_DISABLE_CLAUDE_CODE": "1",
+            "OPENCODE_DISABLE_CLAUDE_CODE_PROMPT": "1",
+            "OPENCODE_DISABLE_CLAUDE_CODE_SKILLS": "1",
+        }
+
+    def format_task_input(self, task: str, mode: str) -> str:
+        # Mirrors cli/run.py:117.
+        return f'<worker-task mode="{mode}">\n{task}\n</worker-task>'
+
+    # ------------------------------------------------------------------
+    # event translation
+    # ------------------------------------------------------------------
+
+    def parse_events(self, raw: dict) -> list[UnifiedEvent]:
+        """Translate one raw OpenCode event into 0..n UnifiedEvents.
+
+        Behaviour mirrors the union of the former inline translators:
+          - cli/dispatch.parse_jsonl (step/text/tool/error branches)
+          - fmt_events tool input/output brief extraction
+          - runtime.run_process recursive session-id scan
+        """
+        events: list[UnifiedEvent] = []
+
+        # Top-level timestamp → ts (epoch ms). bool excluded.
+        ts_value = raw.get("timestamp")
+        ts: int | None = None
+        if isinstance(ts_value, (int, float)) and not isinstance(ts_value, bool):
+            ts = int(ts_value)
+
+        # Recursive session-id scan: emit one session event if any found.
+        # runtime.run_process keeps the LAST id (ids[-1]); do the same here.
+        ids = _session_ids(raw)
+        if ids:
+            events.append(UnifiedEvent(kind="session", ts=ts, session_id=ids[-1]))
+
+        event_type = raw.get("type")
+
+        if event_type == "step_finish":
+            events.append(UnifiedEvent(
+                kind="step",
+                ts=ts,
+                tokens=_extract_tokens(raw.get("part")),
+            ))
+        elif event_type == "text":
+            events.append(UnifiedEvent(
+                kind="text",
+                ts=ts,
+                text=_part_text(raw.get("part")),
+            ))
+        elif event_type == "reasoning":
+            events.append(UnifiedEvent(
+                kind="reasoning",
+                ts=ts,
+                text=_part_text(raw.get("part")),
+            ))
+        elif event_type == "tool_use":
+            events.append(UnifiedEvent(
+                kind="tool",
+                ts=ts,
+                tool=_extract_tool_call(raw.get("part") or {}),
+            ))
+        elif event_type == "error":
+            events.append(UnifiedEvent(kind="error", ts=ts))
+        # Anything else → emit nothing (the session event above, if any,
+        # already covers the session-id extraction side-effect).
+
+        return events
+
+    # ------------------------------------------------------------------
+    # binary / credentials
+    # ------------------------------------------------------------------
+
+    def binary_path(self) -> Path | None:
+        # Best-effort location used for dry-run display; not verified.
+        return (
+            pilot_home()
+            / "worker-runtime"
+            / "opencode"
+            / PINNED_OPENCODE_VERSION
+            / "node_modules"
+            / ".bin"
+            / "opencode"
+        )
+
+    def resolve_binary(self) -> Path:
+        # Absorbs runners/opencode.py:verify_binary behaviour, but builds the
+        # path locally so this module is the single source of truth for the
+        # runner's binary location.
+        binary = self.binary_path()
+        assert binary is not None
+        if not binary.is_file() or not os.access(binary, os.X_OK):
+            raise RuntimeError(
+                f"pinned OpenCode {PINNED_OPENCODE_VERSION} is missing; "
+                "run: bash scripts/install_runtime.sh"
+            )
+        version = subprocess.run(
+            [str(binary), "--version"], text=True, capture_output=True, check=False,
+        )
+        if (
+            version.returncode != 0
+            or version.stdout.strip() != PINNED_OPENCODE_VERSION
+        ):
+            actual = (version.stdout or version.stderr).strip()
+            raise RuntimeError(
+                f"expected OpenCode {PINNED_OPENCODE_VERSION}, "
+                f"got {actual or 'unknown'}"
+            )
+        return binary
+
+    def credential_path(self, provider: Any) -> Path:
+        return profile_root(provider) / "data" / "opencode" / "auth.json"
+
+    def credential_payload(self, provider: Any, key: str) -> dict:
+        return {provider.provider_id: {"type": "api", "key": key}}
+
+    def parse_credential(self, provider: Any, payload: dict) -> str:
+        # Mirrors the validation in the former runtime.credential_key
+        # (runtime.py:73-79).
+        entry = payload.get(provider.provider_id)
+        if not isinstance(entry, dict) or entry.get("type") != "api":
+            raise RuntimeError(
+                f"credential file lacks API auth for {provider.provider_id}"
+            )
+        key = entry.get("key")
+        if not isinstance(key, str) or not key.strip():
+            raise RuntimeError(
+                f"credential is empty for {provider.provider_id}"
+            )
+        return key
+
+
+# ----------------------------------------------------------------------
+# parse_events helpers (mirror cli/dispatch.py:_safe_int semantics exactly)
+# ----------------------------------------------------------------------
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, (int, float)):
+        return int(value)
+    return default
+
+
+def _safe_int_cache(cache: Any, field: str) -> int:
+    if isinstance(cache, dict):
+        return _safe_int(cache.get(field))
+    return 0
+
+
+def _extract_tokens(part: Any) -> TokenUsage:
+    if not isinstance(part, dict):
+        return TokenUsage()
+    tk = part.get("tokens")
+    if not isinstance(tk, dict):
+        return TokenUsage()
+    return TokenUsage(
+        input=_safe_int(tk.get("input")),
+        output=_safe_int(tk.get("output")),
+        reasoning=_safe_int(tk.get("reasoning")),
+        cache_read=_safe_int_cache(tk.get("cache"), "read"),
+        cache_write=_safe_int_cache(tk.get("cache"), "write"),
+    )
+
+
+def _part_text(part: Any) -> str | None:
+    if not isinstance(part, dict):
+        return None
+    text = part.get("text")
+    return text if isinstance(text, str) else None
+
+
+def _extract_tool_call(part: Any) -> ToolCall:
+    if not isinstance(part, dict):
+        part = {}
+    state = part.get("state") or {}
+    if not isinstance(state, dict):
+        state = {}
+    tool_name = part.get("tool", "?")
+    if not isinstance(tool_name, str):
+        tool_name = "?" if tool_name is None else str(tool_name)
+
+    status_value = state.get("status")
+    status = status_value if isinstance(status_value, str) else (
+        "" if status_value is None else str(status_value)
+    )
+
+    input_brief = _tool_input_brief(tool_name, state.get("input") or {})
+    output_brief = _first_line(state.get("output") or "", _INPUT_LIMIT)
+
+    error = None
+    if status == "error":
+        error_value = state.get("error")
+        if isinstance(error_value, str):
+            error = _first_line(error_value, _INPUT_LIMIT)
+        elif error_value is not None:
+            error = _first_line(str(error_value), _INPUT_LIMIT)
+
+    is_permission_denied = (
+        isinstance(error, str) and _PERMISSION_DENIED_MARK in error
+    )
+    silent_output = tool_name in SILENT_OUTPUT_TOOLS
+
+    return ToolCall(
+        name=tool_name,
+        status=status,
+        input_brief=input_brief,
+        output_brief=output_brief,
+        error=error,
+        is_permission_denied=is_permission_denied,
+        silent_output=silent_output,
+    )
+
+
+# ----------------------------------------------------------------------
+# Migrated from fmt_events.py — private, behaviour preserved verbatim.
+# ----------------------------------------------------------------------
+
+
+def _trim(value: Any, limit: int) -> str:
+    text = str(value).strip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"
+
+
+def _short_path(value: str) -> str:
+    """~ for home, and keep only the last 3 segments of long paths."""
+    home = str(Path.home())
+    if value.startswith(home):
+        value = "~" + value[len(home):]
+    if len(value) > 64 and "/" in value:
+        parts = value.split("/")
+        if len(parts) > 4:
+            value = "…/" + "/".join(parts[-3:])
+    return value
+
+
+def _first_line(value: str, limit: int) -> str:
+    """First informative line, never a raw newline. Skips XML-ish wrappers."""
+    for line in str(value).splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("<") and line.endswith(">"):
+            continue  # <path>…</path> / <type>file</type> / <content> wrappers
+        if line.startswith("/") and " " not in line:
+            line = _short_path(line)
+        return _trim(line, limit)
+    return ""
+
+
+def _tool_input_brief(tool: str, tool_input: dict[str, Any]) -> str:
+    for key in ("command", "filePath", "pattern", "path", "query", "url"):
+        value = tool_input.get(key)
+        if value:
+            text = str(value)
+            if key in ("filePath", "path"):
+                text = _short_path(text)
+            return _trim(text.replace("\n", " "), _INPUT_LIMIT)
+    return _trim(json.dumps(tool_input, ensure_ascii=False), _INPUT_LIMIT) if tool_input else ""
+
+
+# ----------------------------------------------------------------------
+# Migrated from runtime.session_ids — recursive session-id scan, used by
+# parse_events. The neutral runtime no longer knows this shape.
+# ----------------------------------------------------------------------
+
+
+def _session_ids(value: Any) -> list[str]:
+    found: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in {"sessionID", "sessionId", "session_id"} and isinstance(item, str):
+                found.append(item)
+            else:
+                found.extend(_session_ids(item))
+    elif isinstance(value, list):
+        for item in value:
+            found.extend(_session_ids(item))
+    return found

pilot_workers/runtime.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Isolated execution runtime: environment, credentials, worktrees, process I/O."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import threading
+import time
+from typing import Any, TextIO
+
+from pilot_workers.providers import Provider, profile_paths
+from pilot_workers.runners.base import Runner, UnifiedEvent
+
+SAFE_ENV_KEYS = (
+    "HOME", "USER", "LOGNAME", "SHELL", "PATH", "TMPDIR",
+    "LANG", "LC_ALL",
+    "JAVA_HOME", "ANDROID_HOME", "ANDROID_SDK_ROOT",
+    "FLUTTER_ROOT", "GOPATH", "GOROOT",
+    "CARGO_HOME", "RUSTUP_HOME",
+    "NVM_DIR", "PYENV_ROOT", "RBENV_ROOT",
+    "BUN_INSTALL", "PNPM_HOME",
+)
+
+# Env keys a runner must never override: neutral SAFE_ENV_KEYS already owned
+# by this layer, the XDG_*_HOME dirs (also owned here), plus the NO_COLOR / CI
+# flags the runtime sets to keep worker output deterministic.
+_PROTECTED_KEYS = frozenset(SAFE_ENV_KEYS) | frozenset(
+    k for k in ("NO_COLOR", "CI")
+) | frozenset(
+    f"XDG_{d}_HOME" for d in ("CONFIG", "DATA", "STATE", "CACHE")
+)
+
+HEARTBEAT_SECONDS = 60
+TERMINATE_GRACE_SECONDS = 10
+
+
+def ensure_private_directory(path: Path) -> None:
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.chmod(0o700)
+
+
+def build_environment(provider: Provider, runner_env: dict[str, str]) -> dict[str, str]:
+    """Compose the child process environment.
+
+    Neutral concerns (SAFE_ENV_KEYS whitelist + XDG dirs) are owned here; the
+    runner-specific variables come from ``runner.runner_environment`` via the
+    ``runner_env`` argument and are merged unchanged.
+    """
+    paths = profile_paths(provider)
+    for name in ("root", "config", "data", "state", "cache"):
+        ensure_private_directory(paths[name])
+    env = {key: os.environ[key] for key in SAFE_ENV_KEYS if os.environ.get(key)}
+    env.update({
+        "XDG_CONFIG_HOME": str(paths["config"]),
+        "XDG_DATA_HOME": str(paths["data"]),
+        "XDG_STATE_HOME": str(paths["state"]),
+        "XDG_CACHE_HOME": str(paths["cache"]),
+        "NO_COLOR": "1",
+        "CI": "1",
+    })
+    # Drop any runner-supplied entry that would shadow a neutral key — those
+    # are owned by this layer and must remain deterministic.
+    filtered = {k: v for k, v in runner_env.items() if k not in _PROTECTED_KEYS}
+    env.update(filtered)
+    return env
+
+
+def credential_key(provider: Provider, runner: Runner) -> str:
+    path = runner.credential_path(provider)
+    if not path.is_file():
+        raise RuntimeError(f"credential missing for {provider.key}; run: pilot-workers configure {provider.key}")
+    if path.stat().st_mode & 0o077:
+        raise RuntimeError(f"credential file is not private (expected mode 0600): {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"cannot read credential from {path}: {exc}") from exc
+    return runner.parse_credential(provider, payload)
+
+
+def credential_metadata(provider: Provider, runner: Runner) -> dict[str, Any]:
+    path = runner.credential_path(provider)
+    configured = False
+    secure_mode = False
+    if path.is_file():
+        secure_mode = (path.stat().st_mode & 0o077) == 0
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            configured = _looks_configured(provider, runner, payload)
+        except (OSError, json.JSONDecodeError):
+            configured = False
+    return {"configured": configured, "secure_mode": secure_mode, "path": str(path)}
+
+
+def _looks_configured(provider: Provider, runner: Runner, payload: Any) -> bool:
+    """Best-effort 'has a usable API key' check; never raises."""
+    try:
+        key = runner.parse_credential(provider, payload)
+    except (RuntimeError, TypeError, AttributeError):
+        return False
+    return bool(key.strip())
+
+
+def create_detached_worktree(workdir: Path, worktree_parent: Path) -> Path:
+    root_result = subprocess.run(
+        ["git", "-C", str(workdir), "rev-parse", "--show-toplevel"],
+        text=True, capture_output=True, check=False,
+    )
+    if root_result.returncode != 0:
+        raise RuntimeError(f"--worktree requires a Git repository: {root_result.stderr.strip()}")
+    repository_root = Path(root_result.stdout.strip()).resolve()
+    status = subprocess.run(
+        ["git", "-C", str(repository_root), "status", "--porcelain"],
+        text=True, capture_output=True, check=False,
+    )
+    if status.returncode != 0:
+        raise RuntimeError(f"cannot inspect Git status: {status.stderr.strip()}")
+    if status.stdout.strip():
+        raise RuntimeError("--worktree requires a clean repository (commit or stash first)")
+    ensure_private_directory(worktree_parent)
+    from datetime import datetime, timezone
+    import secrets as secrets_module
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    target = worktree_parent / f"{repository_root.name}-{stamp}-{secrets_module.token_hex(3)}"
+    add_result = subprocess.run(
+        ["git", "-C", str(repository_root), "worktree", "add", "--detach", str(target), "HEAD"],
+        text=True, capture_output=True, check=False,
+    )
+    if add_result.returncode != 0:
+        raise RuntimeError(f"cannot create detached worktree: {add_result.stderr.strip()}")
+    try:
+        relative = workdir.resolve().relative_to(repository_root)
+    except ValueError as exc:
+        raise RuntimeError(f"workdir {workdir} is not inside repository {repository_root}") from exc
+    return target / relative
+
+
+def open_private_text(path: Path) -> TextIO:
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    return os.fdopen(descriptor, "w", encoding="utf-8")
+
+
+@dataclass
+class RunResult:
+    exit_code: int
+    session_id: str | None
+    timed_out: bool = False
+    idle_timed_out: bool = False
+    interrupted: bool = False
+
+
+class _SafeRenderer:
+    def __init__(self, writer: Any) -> None:
+        self._writer = writer
+        self._broken = False
+
+    def _guard(self, action) -> None:
+        if self._broken or self._writer is None:
+            return
+        try:
+            action()
+        except Exception as exc:
+            self._broken = True
+            print(f"note: live log rendering disabled ({exc})", file=sys.stderr)
+
+    def event(self, event: dict[str, Any]) -> None:
+        self._guard(lambda: self._writer.write_event(event))
+
+    def raw_line(self, line: str, runner: Runner | None) -> None:
+        def action() -> None:
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                return
+            if not isinstance(event, dict):
+                return
+            if runner is None:
+                # Without a runner we can only render self-owned events.
+                self._writer.write_event(event)
+                return
+            for ev in runner.parse_events(event):
+                self._writer.write_unified(ev)
+            # Self-owned events (worker_runner.*) live outside parse_events;
+            # also render them in case the line is one.
+            self._writer.write_event(event)
+        self._guard(action)
+
+    def finalize(self) -> None:
+        self._guard(lambda: self._writer.finalize())
+
+
+def run_process(
+    command: list[str], env: dict[str, str], task: str,
+    log_path: Path, stderr_path: Path, secret: str,
+    renderer: Any = None, timeout_s: int = 0, idle_timeout_s: int = 0,
+    runner: Runner | None = None,
+) -> RunResult:
+    safe_renderer = _SafeRenderer(renderer)
+    result = RunResult(exit_code=1, session_id=None)
+    last_activity = time.monotonic()
+    started_at = last_activity
+    lock = threading.Lock()
+
+    def redact(value: str) -> str:
+        return value.replace(secret, "[REDACTED]") if secret else value
+
+    with open_private_text(log_path) as stdout_log, open_private_text(stderr_path) as stderr_log:
+        process = subprocess.Popen(
+            command, env=env, stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1,
+        )
+
+        def feed_stdin() -> None:
+            try:
+                assert process.stdin is not None
+                process.stdin.write(task)
+                process.stdin.close()
+            except (BrokenPipeError, OSError):
+                pass
+
+        def touch() -> None:
+            nonlocal last_activity
+            with lock:
+                last_activity = time.monotonic()
+
+        def consume_stdout() -> None:
+            assert process.stdout is not None
+            for raw_line in process.stdout:
+                touch()
+                line = redact(raw_line)
+                stdout_log.write(line); stdout_log.flush()
+                sys.stdout.write(line); sys.stdout.flush()
+                safe_renderer.raw_line(line, runner)
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(event, dict) or runner is None:
+                    continue
+                try:
+                    for ev in runner.parse_events(event):
+                        if ev.kind == "session" and ev.session_id:
+                            result.session_id = ev.session_id
+                except Exception:
+                    pass
+
+        def consume_stderr() -> None:
+            assert process.stderr is not None
+            for raw_line in process.stderr:
+                touch()
+                line = redact(raw_line)
+                stderr_log.write(line); stderr_log.flush()
+                sys.stderr.write(line); sys.stderr.flush()
+
+        threads = [
+            threading.Thread(target=feed_stdin, daemon=True),
+            threading.Thread(target=consume_stdout, daemon=True),
+            threading.Thread(target=consume_stderr, daemon=True),
+        ]
+        for thread in threads:
+            thread.start()
+
+        def stop_child() -> None:
+            process.terminate()
+            try:
+                process.wait(timeout=TERMINATE_GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                process.kill(); process.wait()
+
+        def emit_runner_event(event: dict[str, Any]) -> None:
+            payload = json.dumps(event)
+            stderr_log.write(payload + "\n"); stderr_log.flush()
+            sys.stderr.write(payload + "\n"); sys.stderr.flush()
+            safe_renderer.event(event)
+
+        next_heartbeat_silence = HEARTBEAT_SECONDS
+        try:
+            while True:
+                try:
+                    result.exit_code = process.wait(timeout=1)
+                    break
+                except subprocess.TimeoutExpired:
+                    pass
+                now = time.monotonic()
+                with lock:
+                    silent = now - last_activity
+                elapsed = now - started_at
+                if timeout_s and elapsed >= timeout_s:
+                    result.timed_out = True; stop_child()
+                    result.exit_code = process.returncode or 124; break
+                if idle_timeout_s and silent >= idle_timeout_s:
+                    result.idle_timed_out = True; stop_child()
+                    result.exit_code = process.returncode or 124; break
+                if silent >= next_heartbeat_silence:
+                    emit_runner_event({"type": "worker_runner.heartbeat",
+                                       "elapsed_s": int(elapsed), "silent_s": int(silent)})
+                    next_heartbeat_silence = silent + HEARTBEAT_SECONDS
+                else:
+                    next_heartbeat_silence = max(next_heartbeat_silence, HEARTBEAT_SECONDS)
+        except KeyboardInterrupt:
+            result.interrupted = True; stop_child()
+            result.exit_code = process.returncode or 130
+        finally:
+            for thread in threads:
+                thread.join(timeout=5)
+
+    if (result.timed_out or result.idle_timed_out or result.interrupted) and result.exit_code == 0:
+        result.exit_code = 124
+    return result