shelldeck 0.0.1__py3-none-any.whl

shelldeck/gitgraph.py

@@ -0,0 +1,150 @@
+"""Git commit graph for a project: log parsing, lane layout, checkout.
+
+The lane-assignment algorithm mirrors what tig/gitk/vscode-git-graph do
+internally: walk commits newest-first, keep a list of "lanes" each
+waiting for a specific next commit hash, and let a commit take over the
+leftmost lane already waiting for it (or open a new one). Merge commits
+add lanes for their extra parents, reusing freed columns to keep the
+graph narrow.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+NO_WINDOW = subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+FORMAT = FIELD_SEP.join(["%H", "%h", "%P", "%an", "%ad", "%s", "%D"]) + RECORD_SEP
+# mirrors PROJECT_COLORS in app.js
+PALETTE = ["#60a5fa", "#f472b6", "#34d399", "#fbbf24", "#a78bfa", "#f87171", "#22d3ee", "#fb923c"]
+
+
+class GitError(Exception):
+    pass
+
+
+def _run(path: str, args: list[str], timeout: int = 15) -> str:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=timeout,
+            check=False,
+            creationflags=NO_WINDOW,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise GitError(str(e)) from e
+    if proc.returncode != 0:
+        raise GitError((proc.stderr or "").strip() or f"git {args[0]} failed")
+    return proc.stdout
+
+
+def parse_log(text: str) -> list[dict]:
+    """Parse `git log --format=FORMAT` output into raw commit dicts."""
+    commits = []
+    for record in text.split(RECORD_SEP):
+        record = record.strip("\n")
+        if not record.strip():
+            continue
+        h, short, parents, author, date, subject, refs = record.split(FIELD_SEP)
+        commits.append({
+            "hash": h,
+            "short": short,
+            "parents": parents.split() if parents else [],
+            "author": author,
+            "date": date,
+            "subject": subject,
+            "refs": [r.strip() for r in refs.split(",") if r.strip()],
+        })
+    return commits
+
+
+def build_graph(commits: list[dict]) -> None:
+    """Assign `column`, `color`, `enter`, `exit`, and `through` to each commit in place.
+
+    Each row is drawn in two halves, matching how vscode-git-graph/gitk render a row:
+    - `enter`: lanes converging into this commit's node from above (`{from_col, color}`,
+      curved unless from_col == column).
+    - `exit`: lanes diverging from this commit's node downward, one per parent
+      (`{to_col, color}`, curved unless to_col == column).
+    - `through`: unrelated lanes that just pass straight through this row (`{col, color}`).
+    """
+    lanes: dict[int, dict] = {}  # column -> {"next": hash, "color": color}
+    next_color = 0
+
+    def new_color() -> str:
+        nonlocal next_color
+        c = PALETTE[next_color % len(PALETTE)]
+        next_color += 1
+        return c
+
+    def free_column() -> int:
+        return next((c for c in range(len(lanes) + 1) if c not in lanes), 0)
+
+    for commit in commits:
+        h = commit["hash"]
+        matches = sorted(col for col, lane in lanes.items() if lane["next"] == h)
+        if matches:
+            col, color = matches[0], lanes[matches[0]]["color"]
+        else:
+            col, color = free_column(), new_color()
+
+        enter, through = [], []
+        for other_col, lane in list(lanes.items()):
+            if other_col in matches:
+                enter.append({"from_col": other_col, "color": lane["color"]})
+                del lanes[other_col]
+            elif other_col != col:
+                through.append({"col": other_col, "color": lane["color"]})
+
+        exit_ = []
+        parents = commit["parents"]
+        if parents:
+            lanes[col] = {"next": parents[0], "color": color}
+            exit_.append({"to_col": col, "color": color})
+            for parent in parents[1:]:
+                free, pcolor = free_column(), new_color()
+                lanes[free] = {"next": parent, "color": pcolor}
+                exit_.append({"to_col": free, "color": pcolor})
+        else:
+            lanes.pop(col, None)
+
+        commit["column"] = col
+        commit["color"] = color
+        commit["enter"] = enter
+        commit["exit"] = exit_
+        commit["through"] = through
+
+
+def get_log(path: str, max_commits: int = 300) -> dict:
+    """Commit graph for the repo at `path`: local branches + HEAD."""
+    try:
+        branch = _run(path, ["rev-parse", "--abbrev-ref", "HEAD"], timeout=5).strip()
+    except GitError:  # unborn HEAD: a fresh `git init` with no commits
+        return {"commits": [], "current_branch": "", "has_more": False}
+    raw = _run(path, ["log", "HEAD", "--branches", "--date-order", f"--format={FORMAT}",
+                      "--date=format:%Y-%m-%dT%H:%M:%S", "-n", str(max_commits + 1)])
+    commits = parse_log(raw)
+    has_more = len(commits) > max_commits
+    commits = commits[:max_commits]
+    build_graph(commits)
+    return {"commits": commits, "current_branch": branch, "has_more": has_more}
+
+
+def checkout(path: str, ref: str) -> tuple[bool, str]:
+    """`git checkout <ref>`. git itself refuses an unsafe checkout on a dirty tree."""
+    if ref.startswith("-"):  # would be parsed as an option (e.g. --force)
+        return False, "invalid ref"
+    try:
+        out = _run(path, ["checkout", ref])
+        return True, out.strip()
+    except GitError as e:
+        return False, str(e)
+
+
+def has_git(path: str) -> bool:
+    return (Path(path) / ".git").exists()

shelldeck/integration/bash.sh

@@ -0,0 +1,27 @@
+# shelldeck shell integration for bash (used as --rcfile).
+# Loads the user's normal startup files, then reports prompt/exit/cwd via OSC sequences.
+if [ -n "$SHELLDECK_LOGIN" ]; then
+  unset SHELLDECK_LOGIN
+  [ -f /etc/profile ] && . /etc/profile
+  for __sd_f in ~/.bash_profile ~/.bash_login ~/.profile; do
+    if [ -f "$__sd_f" ]; then . "$__sd_f"; break; fi
+  done
+  unset __sd_f
+else
+  [ -f ~/.bashrc ] && . ~/.bashrc
+fi
+
+__sd_prompt() {
+  local ec=$? d=$PWD
+  # Git Bash: report /c/x as C:\x so the server can reopen the folder
+  if [ -n "$MSYSTEM" ] && [[ $d =~ ^/([a-zA-Z])(/.*)?$ ]]; then
+    d="${BASH_REMATCH[1]^^}:${BASH_REMATCH[2]:-/}"
+    d=${d//\//\\}
+  fi
+  printf '\033]133;D;%s\007\033]633;P;Cwd=%s\007' "$ec" "$d"
+  return $ec
+}
+if [[ "$PROMPT_COMMAND" != *__sd_prompt* ]]; then
+  PROMPT_COMMAND="__sd_prompt${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+fi
+PS1="\[\033]133;A\007\]$PS1\[\033]133;B\007\]"

shelldeck/integration/shelldeck.fish

@@ -0,0 +1,5 @@
+# shelldeck shell integration for fish: report prompt/exit/cwd via OSC sequences.
+function __sd_prompt --on-event fish_prompt
+    set -l ec $status
+    printf '\e]133;D;%s\a\e]633;P;Cwd=%s\a\e]133;A\a' $ec $PWD
+end

shelldeck/integration/shelldeck.ps1

@@ -0,0 +1,35 @@
+# shelldeck shell integration for pwsh / Windows PowerShell.
+# Wraps the user's prompt (after their profile ran) to report, via OSC sequences:
+#   633;E;<cmd>  last command line      133;D;<code>  command finished
+#   633;P;Cwd=   current directory       133;A / 133;B  prompt start / end
+if ($global:__sdLoaded) { return }
+$global:__sdLoaded = $true
+$global:__sdOrigPrompt = $function:prompt
+$global:__sdLastId = -1
+$global:__sdPrevCode = $global:LASTEXITCODE
+
+function global:prompt {
+    $ok = $?
+    $code = $global:LASTEXITCODE
+    $e = [char]27
+    $b = [char]7
+    $out = ""
+    $h = Get-History -Count 1
+    if ($global:__sdLastId -eq -1) {
+        # first prompt: history holds this integration script (-EncodedCommand), not a user command
+        $global:__sdLastId = if ($h) { $h.Id } else { 0 }
+    } elseif ($h -and $h.Id -ne $global:__sdLastId) {
+        $global:__sdLastId = $h.Id
+        # cmdlet errors leave $LASTEXITCODE stale, so only trust it when the command changed it
+        $ec = if ($ok) { 0 } elseif ($code -and $code -ne $global:__sdPrevCode) { $code } else { 1 }
+        $cmd = $h.CommandLine -replace '[\x00-\x1f]', ' '
+        $out += "$e]633;E;$cmd$b$e]133;D;$ec$b"
+    }
+    $loc = Get-Location
+    if ($loc.Provider.Name -eq 'FileSystem') { $out += "$e]633;P;Cwd=$($loc.ProviderPath)$b" }
+    $out += "$e]133;A$b"
+    $global:__sdPrevCode = $code
+    $p = & $global:__sdOrigPrompt
+    $global:LASTEXITCODE = $code
+    "$out$p$e]133;B$b"
+}

shelldeck/integration/zsh/.zshenv

@@ -0,0 +1,6 @@
+# shelldeck: zsh reads startup files from $ZDOTDIR; restore the user's and chain to theirs.
+__sd_zdotdir="${ZDOTDIR}"
+ZDOTDIR="${SHELLDECK_USER_ZDOTDIR:-$HOME}"
+[ -f "$ZDOTDIR/.zshenv" ] && . "$ZDOTDIR/.zshenv"
+__sd_user_zdotdir="$ZDOTDIR"
+ZDOTDIR="$__sd_zdotdir"

shelldeck/integration/zsh/.zshrc

@@ -0,0 +1,10 @@
+# shelldeck shell integration for zsh: load the user's .zshrc, then report prompt/exit/cwd.
+ZDOTDIR="$__sd_user_zdotdir"
+[ -f "$ZDOTDIR/.zshrc" ] && . "$ZDOTDIR/.zshrc"
+
+__sd_precmd() {
+  local ec=$?
+  printf '\033]133;D;%s\007\033]633;P;Cwd=%s\007\033]133;A\007' "$ec" "$PWD"
+}
+autoload -Uz add-zsh-hook
+add-zsh-hook precmd __sd_precmd

shelldeck/pty.py

@@ -0,0 +1,352 @@
+"""Pseudo-terminals: ConPTY (pywinpty) on Windows, stdlib pty on Linux/macOS."""
+
+import codecs
+import logging
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from collections import deque
+from pathlib import Path
+
+from . import shells
+
+log = logging.getLogger(__name__)
+
+SCROLLBACK_CHARS = 256 * 1024
+
+
+class Scrollback:
+    """Last `limit` chars of output, so a reconnecting client can redraw the screen."""
+
+    def __init__(self, limit: int = SCROLLBACK_CHARS):
+        self.limit = limit
+        self.chunks: deque[str] = deque()
+        self.size = 0
+        self.dirty = False
+        self.total = 0  # chars ever added, to tell how stale a snapshot is
+        self.snapshot: tuple[int, str] | None = None  # (total at snapshot, client-rendered screen)
+
+    def add(self, data: str) -> None:
+        self.dirty = True
+        self.total += len(data)
+        self.chunks.append(data)
+        self.size += len(data)
+        while self.size - len(self.chunks[0]) >= self.limit:
+            self.size -= len(self.chunks.popleft())
+        if (extra := self.size - self.limit) > 0:
+            self.chunks[0] = self.chunks[0][extra:]
+            self.size = self.limit
+
+    def text(self) -> str:
+        return "".join(self.chunks)
+
+    def persisted(self) -> str:
+        """What to save for a restart: the client's rendered snapshot while it is fresh.
+
+        Raw ConPTY output positions the cursor absolutely, so it replays garbled on a new screen.
+        ponytail: staleness = output since the snapshot; a server-side emulator would drop this."""
+        if self.snapshot and self.total - self.snapshot[0] < 4096:
+            return self.snapshot[1]
+        return self.text()
+
+
+# --------------------------------------------------------------- backends
+# Both expose: read() -> str (non-blocking), write(str), resize(rows, cols),
+# isalive() -> bool, kill().
+
+
+class WinProc:
+    def __init__(self, argv: list[str], cwd: str | None, env: dict[str, str], rows: int, cols: int):
+        import ctypes
+
+        from winpty import PTY, Backend
+
+        def short(path: str) -> str:
+            if " " not in path:
+                return path
+            buf = ctypes.create_unicode_buffer(512)
+            n = ctypes.windll.kernel32.GetShortPathNameW(path, buf, 512)
+            return buf.value if n and buf.value else path
+
+        # A detached server (CREATE_NEW_PROCESS_GROUP) ignores Ctrl+C and every shell inherits
+        # that, so ^C would never interrupt a running command. Re-enable it before spawning.
+        ctypes.windll.kernel32.SetConsoleCtrlHandler(None, False)
+        self.pty = PTY(cols, rows, backend=Backend.ConPTY)
+        cmdline = " " + subprocess.list2cmdline(argv[1:]) if len(argv) > 1 else None
+        env_str = "\0".join(f"{k}={v}" for k, v in env.items()) + "\0"
+        self.pty.spawn(short(argv[0]), cwd=cwd, env=env_str, cmdline=cmdline)
+        self.pid = self.pty.pid
+
+    def read(self) -> str:
+        try:
+            return self.pty.read(blocking=False)
+        except Exception:  # noqa: BLE001 - winpty raises bare errors at EOF
+            return ""
+
+    def write(self, data: str) -> None:
+        self.pty.write(data)
+
+    def resize(self, rows: int, cols: int) -> None:
+        self.pty.set_size(cols, rows)
+
+    def isalive(self) -> bool:
+        return self.pty.isalive()
+
+    def kill(self) -> None:
+        pid = self.pty.pid
+        os.kill(pid, signal.SIGINT)
+        time.sleep(0.1)
+        if self.pty.isalive():
+            os.kill(pid, signal.SIGTERM)
+
+
+class PosixProc:
+    def __init__(self, argv: list[str], cwd: str | None, env: dict[str, str], rows: int, cols: int):
+        import pty
+
+        self.master, slave = pty.openpty()
+        self._winsize(slave, rows, cols)
+        env.setdefault("TERM", "xterm-256color")
+        env.setdefault("COLORTERM", "truecolor")
+        self.proc = subprocess.Popen(
+            argv,
+            stdin=slave,
+            stdout=slave,
+            stderr=slave,
+            cwd=cwd,
+            env=env,
+            start_new_session=True,  # own session + controlling tty
+            close_fds=True,
+        )
+        os.close(slave)
+        self.pid = self.proc.pid
+        os.set_blocking(self.master, False)
+        self.decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        self.eof = False
+
+    @staticmethod
+    def _winsize(fd: int, rows: int, cols: int) -> None:
+        import fcntl
+        import struct
+        import termios
+
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+    def read(self) -> str:
+        if self.eof:
+            return ""
+        try:
+            data = os.read(self.master, 65536)
+        except BlockingIOError:
+            return ""
+        except OSError:  # EIO: slave side closed
+            data = b""
+        if not data:
+            self.eof = True
+        return self.decoder.decode(data, final=not data)
+
+    def write(self, data: str) -> None:
+        os.write(self.master, data.encode())
+
+    def resize(self, rows: int, cols: int) -> None:
+        self._winsize(self.master, rows, cols)
+
+    def isalive(self) -> bool:
+        return not self.eof and self.proc.poll() is None
+
+    def kill(self) -> None:
+        try:
+            os.killpg(self.proc.pid, signal.SIGHUP)
+        except OSError:
+            pass
+        try:
+            self.proc.wait(timeout=0.5)
+        except subprocess.TimeoutExpired:
+            os.killpg(self.proc.pid, signal.SIGKILL)
+        os.close(self.master)
+
+
+Proc = WinProc if sys.platform == "win32" else PosixProc
+
+
+# ---------------------------------------------------------------- manager
+
+
+# after replayed scrollback from a previous run: leave alt screen (1047: no cursor restore), reset style, show cursor
+RESTORED = "\x1b[0m\x1b[?1047l\x1b[?25h\r\n\x1b[J\x1b[2m--- restored {when} ---\x1b[0m"
+
+
+def _push_to_scrollback(rows: int) -> str:
+    """Scroll everything on screen into scrollback and home the cursor.
+
+    A new ConPTY paints at absolute rows of a screen it thinks is blank, which would
+    overwrite restored lines still in view."""
+    return "\x1b[999B" + "\r\n" * rows + "\x1b[H"
+
+
+class PtyManager:
+    def __init__(self, store: Path | None = None):
+        self.procs: dict[str, Proc] = {}
+        self.scrollback: dict[str, Scrollback] = {}
+        self.wakes: dict[str, threading.Event] = {}
+        self.store = store  # scrollback files, so a restart/reboot keeps terminal history
+
+    def _file(self, session_id: str) -> Path | None:
+        if not self.store or not session_id.replace("-", "").isalnum():
+            return None
+        return self.store / f"{session_id}.log"
+
+    def _restore(self, session_id: str, rows: int = 24) -> Scrollback:
+        sb = Scrollback()
+        f = self._file(session_id)
+        if f and f.exists():
+            old = f.read_bytes().decode("utf-8", errors="replace")  # bytes: text mode drops the CR in CRLF
+            if old:
+                when = time.strftime("%Y-%m-%d %H:%M", time.localtime(f.stat().st_mtime))
+                sb.add(old + RESTORED.format(when=when) + _push_to_scrollback(rows))
+        return sb
+
+    def save(self) -> None:
+        """Write changed scrollbacks to disk."""
+        if not self.store:
+            return
+        self.store.mkdir(parents=True, exist_ok=True)
+        for sid, sb in list(self.scrollback.items()):
+            if sb.dirty and (f := self._file(sid)):
+                sb.dirty = False
+                f.write_bytes(sb.persisted().encode("utf-8"))
+
+    def snapshot(self, session_id: str, data: str) -> None:
+        """Store the client's serialized screen (xterm serialize addon) for the next restart."""
+        if sb := self.scrollback.get(session_id):
+            sb.snapshot = (sb.total, data[-SCROLLBACK_CHARS:])
+            sb.dirty = True
+
+    def searchable(self, session_id: str) -> str:
+        """Terminal output as saved for restore: from memory while running, else from disk."""
+        if sb := self.scrollback.get(session_id):
+            return sb.persisted()
+        f = self._file(session_id)
+        return f.read_bytes().decode("utf-8", errors="replace") if f and f.exists() else ""
+
+    def forget(self, session_id: str) -> None:
+        if f := self._file(session_id):
+            f.unlink(missing_ok=True)
+
+    def prune(self, keep: set[str]) -> None:
+        """Delete saved scrollback for sessions that no longer exist."""
+        if self.store and self.store.exists():
+            for f in self.store.glob("*.log"):
+                if f.stem not in keep:
+                    f.unlink(missing_ok=True)
+
+    def create(
+        self,
+        session_id: str,
+        cwd: str | None = None,
+        shell: str | None = None,
+        rows: int = 24,
+        cols: int = 120,
+        distro: str | None = None,
+    ) -> Proc:
+        proc = self.get(session_id)
+        if proc:
+            return proc
+        start_dir = cwd if (cwd and Path(cwd).is_dir()) else None
+        argv, extra = shells.with_integration(shells.interactive_argv(shell or "", distro, start_dir))
+        env = os.environ.copy() | extra
+        env["SHELLDECK_SESSION_ID"] = session_id
+        proc = Proc(argv, start_dir, env, rows, cols)
+        self.procs[session_id] = proc
+        self.scrollback[session_id] = self._restore(session_id, rows)
+        log.info("spawned %s for session %s in %s", argv, session_id, start_dir)
+        return proc
+
+    def get(self, session_id: str) -> Proc | None:
+        proc = self.procs.get(session_id)
+        if proc and not proc.isalive():
+            return None
+        return proc
+
+    def history(self, session_id: str) -> str:
+        sb = self.scrollback.get(session_id)
+        return sb.text() if sb else ""
+
+    def stream(self, session_id: str, emit) -> None:
+        """Read the session's output on its own thread, calling emit(str) per chunk and emit(None) at exit.
+
+        The thread polls non-blocking reads: pywinpty's blocking read holds data back and never
+        returns at EOF. After output or a keystroke (write() wakes it) it polls with time.sleep,
+        which is ~1ms on Windows; asyncio sleeps and Event.wait round up to ~16ms there. Once idle
+        it waits on the event instead, so a quiet shell costs almost no CPU."""
+        proc = self.procs.get(session_id)
+        wake = self.wakes.setdefault(session_id, threading.Event())
+
+        def run() -> None:
+            idle = 0
+            while proc is not None:
+                try:
+                    data = proc.read()
+                except OSError:  # POSIX fd closed by kill()
+                    break
+                if data:
+                    idle = 0
+                    emit(data)
+                    continue
+                if not proc.isalive():
+                    break
+                idle += 1
+                if idle <= 50:  # just active or typed into: ~1ms polls for ~75ms
+                    time.sleep(0.001)
+                elif wake.wait(0.02):  # idle: Event.wait is ~16ms-grained on Windows, fine here
+                    wake.clear()
+                    idle = 0
+            emit(None)
+
+        threading.Thread(target=run, name=f"pty-{session_id}", daemon=True).start()
+
+    def record(self, session_id: str, data: str) -> None:
+        if sb := self.scrollback.get(session_id):
+            sb.add(data)
+
+    def write(self, session_id: str, data: str) -> bool:
+        proc = self.get(session_id)
+        if not proc:
+            return False
+        try:
+            proc.write(data)
+            if wake := self.wakes.get(session_id):
+                wake.set()
+            return True
+        except Exception:  # noqa: BLE001
+            log.warning("write failed for session %s", session_id, exc_info=True)
+            return False
+
+    def resize(self, session_id: str, rows: int, cols: int) -> bool:
+        proc = self.get(session_id)
+        if not proc:
+            return False
+        try:
+            proc.resize(rows, cols)
+            return True
+        except Exception:  # noqa: BLE001
+            log.warning("resize failed for session %s", session_id, exc_info=True)
+            return False
+
+    def list_alive(self) -> list[str]:
+        return [sid for sid in list(self.procs) if self.get(sid)]
+
+    def terminate(self, session_id: str) -> None:
+        self.scrollback.pop(session_id, None)
+        if wake := self.wakes.pop(session_id, None):
+            wake.set()
+        proc = self.procs.pop(session_id, None)
+        if not proc:
+            return
+        try:
+            proc.kill()  # also releases the pty fd on POSIX, even if the shell already exited
+        except OSError:
+            log.warning("terminate failed for session %s", session_id, exc_info=True)

shelldeck/runner.py

@@ -0,0 +1,75 @@
+import subprocess
+import time
+from pathlib import Path
+
+from . import db, shells
+
+
+def run_command(
+    project_id: str,
+    command: str,
+    shell: str | None = None,
+    timeout: int = 60,
+) -> dict:
+    started = time.perf_counter()
+    project = db.get_project(project_id)
+    if not project:
+        return {
+            "status": "failed",
+            "exit_code": None,
+            "output": "",
+            "error": "project not found",
+            "duration_ms": 0,
+        }
+
+    cwd = project.get("path")
+    if not cwd or not Path(cwd).exists():
+        return {
+            "status": "failed",
+            "exit_code": None,
+            "output": "",
+            "error": "project directory does not exist",
+            "duration_ms": 0,
+        }
+
+    shell = shell or db.get_setting("default_shell", shells.default_kind())
+    args = shells.command_argv(shell, command, db.get_setting("wsl_distro"), cwd)
+
+    try:
+        proc = subprocess.run(
+            args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+        output = (proc.stdout or "") + (proc.stderr or "")
+        exit_code = proc.returncode
+        status = "success" if exit_code == 0 else "failed"
+        error = None if status == "success" else f"exit code {exit_code}"
+    except subprocess.TimeoutExpired as exc:
+        # TimeoutExpired carries bytes even with text=True
+        output = "".join(
+            x.decode(errors="replace") if isinstance(x, bytes) else x
+            for x in (exc.stdout or "", exc.stderr or "")
+        )
+        exit_code = None
+        status = "failed"
+        error = f"timeout after {timeout}s"
+    except OSError as exc:
+        output = ""
+        exit_code = None
+        status = "failed"
+        error = str(exc)
+
+    duration_ms = int((time.perf_counter() - started) * 1000)
+
+    return {
+        "status": status,
+        "exit_code": exit_code,
+        "output": output,
+        "error": error,
+        "duration_ms": duration_ms,
+    }