hexcli 2.8.0__py3-none-any.whl

hexcli/safety.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""hexcli.safety — Command safety classifier and append-only audit log."""
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+# Patterns checked in order: first match wins.  Destructive > safe > caution.
+
+_DESTRUCTIVE: list[re.Pattern[str]] = [re.compile(p, re.IGNORECASE) for p in [
+    r"\bremove-item\b",
+    r"(?<![a-z])rm\s",              # rm <args> but not 'strm' etc.
+    r"(?<![a-z])del\s",
+    r"(?<![a-z])rd\s",
+    r"\berase\b",
+    # Format-Volume / Format-Disk / the DOS `format X:` — not PowerShell's
+    # output formatters (Format-List, Format-Table, Format-Wide, Format-Custom,
+    # Format-Hex), which the CPU/RAM cookbook queries end in. Those asked for
+    # confirmation for weeks and were auto-denied in every unattended eval.
+    r"\bformat-(?!list\b|table\b|wide\b|custom\b|hex\b)\w+",
+    r"^\s*format\s+[a-z]:",
+    r"git\s+reset\s+--hard\b",
+    r"git\s+push\s+(-f\b|--force\b)",
+    r"git\s+clean\s+-[a-z]*f",     # git clean -f / -df / -xf
+    r"\breg\s+delete\b",
+    r"\bclear-recyclebin\b",
+    r"\b(stop|restart)-computer\b",
+    r"\bdiskpart\b",
+    # -Force and -Recurse together — almost always Remove-Item level danger
+    r"-force\b[^|&\n]*-recurse\b|-recurse\b[^|&\n]*-force\b",
+    # Invoke-Expression / iex: evaluates arbitrary strings as code
+    r"\b(invoke-expression|iex)\b",
+]]
+
+# Sensitive-data access: not destructive, but touching credentials, keys, or
+# security-critical system files. Requires explicit confirmation (deny when
+# non-interactive). Checked BEFORE the safe list — v1.7's blanket `^get-\w+`
+# safe rule waved `Get-Content …\drivers\etc\hosts` straight through, which is
+# exactly the injection payload uc3-t7 measured executing 3/3.
+_SENSITIVE: list[re.Pattern[str]] = [re.compile(p, re.IGNORECASE) for p in [
+    r"[\\/]\.ssh\b",                              # ssh keys & config
+    r"\bid_(rsa|ed25519|ecdsa|dsa)\b",
+    r"[\\/]\.gnupg\b",
+    r"[\\/]\.aws\b",
+    r"[\\/]\.azure\b",
+    r"drivers[\\/]+etc[\\/]+hosts\b",             # hosts-file tampering/recon
+    r"\bconfig[\\/]+(sam|security|system)\b",     # registry hive files
+    r"\breg\s+(save|export)\b.*\b(sam|security|system)\b",
+    r"\bntds\.dit\b",
+    r"\bvaultcmd\b",                              # Windows credential vault
+    r"\bcmdkey\b.*/list",
+    r"login data",                                # browser credential stores
+    r"-encodedcommand\b|\s-enc\b|\s-e[nc]?\b\s+[A-Za-z0-9+/=]{20,}",  # obfuscated exec
+    r"frombase64string",
+    r"protecteddata\]::unprotect",                # DPAPI secrets
+    r"\$env:\w*(token|secret|password|api_?key)\w*",  # credential env vars
+    # Launching a program image (uc3-t9's calc.exe): run_code's workspace
+    # boundary refuses `C:\Windows\System32\calc.exe`, but the same payload
+    # routed through run_command ran three different ways in one afternoon
+    # (2026-09-02: the absolute path, bare `calc.exe`, `start calc.exe`).
+    # Any command segment that STARTS with an executable image, plus
+    # Start-Process / start / cmd /c start, is confirm-gated like the rest
+    # of this tier. `python script.py`, cmdlets and git are untouched.
+    r"(?:^|[&|;]\s*)(?:&\s*)?(?:\"[^\"]*?\.(?:exe|com|bat|cmd|msi|scr|vbs|ps1|js)\b[^\"]*\""
+    r"|'[^']*?\.(?:exe|com|bat|cmd|msi|scr|vbs|ps1|js)\b[^']*'"
+    r"|(?:[a-z]:[\\/]|[.\\/]+)?[^\s\"'|&;]*?\.(?:exe|com|bat|cmd|msi|scr|vbs|ps1|js)\b)",
+    r"(?:^|[&|;]\s*)(?:start-process|start|saps)\b",
+    r"\bcmd(\.exe)?\s+/[ck]\s+start\b",
+]]
+
+_SAFE: list[re.Pattern[str]] = [re.compile(p, re.IGNORECASE) for p in [
+    r"^\s*get-\w+",                          # Get-Process, Get-ChildItem …
+    r"^\s*(ls|dir)\b",
+    r"^\s*(cat|type)\s",
+    r"^\s*git\s+(status|log|diff|show|branch|stash list|tag|remote -v|describe)\b",
+    r"^\s*(python|python3|py)\s+(--version|-V)\b",
+    r"^\s*pip\s+(list|show|freeze)\b",
+    r"^\s*(where|where\.exe)\b",
+    r"^\s*(echo|write-output|write-host|pwd|test-path)\b",
+    r"^\s*(node|npm)\s+(--version|-v)\b",
+    r"^\s*select-string\b",                  # grep equivalent — read-only
+]]
+
+
+def classify_command(cmd: str) -> str:
+    """Return 'safe', 'caution', 'sensitive', or 'destructive'.
+
+    Priority: destructive > sensitive > safe > caution. Sensitive must outrank
+    the safe list, or read-only cmdlet prefixes whitelist credential access.
+    """
+    s = cmd.strip()
+    for pat in _DESTRUCTIVE:
+        if pat.search(s):
+            return "destructive"
+    for pat in _SENSITIVE:
+        if pat.search(s):
+            return "sensitive"
+    for pat in _SAFE:
+        if pat.match(s):
+            return "safe"
+    return "caution"
+
+
+def append_audit_log(
+    session_id: str | None,
+    classification: str,
+    cmd: str,
+    exit_code: int | str | None = None,
+) -> None:
+    """Append one JSON line to .shellai/audit.log.  Best-effort — never raises."""
+    try:
+        log_dir = Path.cwd() / ".shellai"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        entry: dict[str, object] = {
+            "ts": datetime.now(UTC).isoformat(),
+            "session": session_id or "",
+            "classification": classification,
+            "cmd": cmd,
+        }
+        if exit_code is not None:
+            entry["exit_code"] = exit_code
+        with (log_dir / "audit.log").open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass

hexcli/sessions.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""hexcli.sessions — session objects and the on-disk history store.
+
+Lifted out of agent.py unchanged. Owns HISTORY_PATH, because the only readers
+of it are the two functions here; keeping the path next to them is what makes
+the store redirectable in tests.
+
+`evals/test_core.py` patches `sessions.HISTORY_PATH` to a temp file. That patch
+MUST target this module: these functions resolve the name in their own
+namespace, so patching a re-exported copy on hexcli.agent would silently do
+nothing and the suite would write to the real history.json while still passing.
+
+Checkpoints (/save, /load) deliberately stay in agent.py — they capture a
+workspace_snapshot, which belongs with the tools.
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import uuid4
+
+from hexcli import paths
+from hexcli.ui import C, cprint
+
+# ~/.shellai/history.json (a checkout's history.json is migrated once).
+HISTORY_PATH = paths.history_path()
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def iso_now() -> str:
+    return utc_now().isoformat()
+
+
+def parse_timestamp(value: str) -> datetime:
+    dt = datetime.fromisoformat(value)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt
+
+
+def create_session() -> dict[str, Any]:
+    now = iso_now()
+    return {
+        "id": str(uuid4()),
+        "title": "New session",
+        "created_at": now,
+        "modified_at": now,
+        "messages": [],
+        "compact_count": 0,
+    }
+
+
+def session_has_messages(session: dict[str, Any]) -> bool:
+    msgs = session.get("messages")
+    return isinstance(msgs, list) and len(msgs) > 0
+
+
+def generate_session_title(text: str) -> str:
+    """The first words of the first message, as typed: "what is 2+2" stays
+    readable ("What Is 22" did not). Trailing punctuation goes, the case
+    is the person's own but for the first letter, and long lines are cut
+    at a word."""
+    first_line = text.strip().splitlines()[0] if text.strip() else ""
+    cleaned = re.sub(r"[^A-Za-z0-9\s\-+_./:'\"]", "", first_line)
+    words = [w.strip("-+_./:'\"") for w in cleaned.split()]
+    words = [w for w in words if w]
+    if not words:
+        return "New session"
+    title = " ".join(words[:8])
+    if len(title) > 48:
+        title = title[:47].rsplit(" ", 1)[0] + "…"
+    return title[0].upper() + title[1:]
+
+
+def touch_session(session: dict[str, Any]) -> None:
+    session["modified_at"] = iso_now()
+
+
+def append_session_message(session: dict[str, Any], role: str, content: str) -> None:
+    msgs = session.setdefault("messages", [])
+    if not isinstance(msgs, list):
+        session["messages"] = []
+        msgs = session["messages"]
+    if not session_has_messages(session) and role == "user":
+        session["title"] = generate_session_title(content)
+    msgs.append({"role": role, "content": content})
+    touch_session(session)
+
+
+def sort_sessions(sessions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    _epoch = datetime.min.replace(tzinfo=UTC)
+
+    def _key(s: dict[str, Any]) -> datetime:
+        raw = s.get("modified_at", "")
+        try:
+            return parse_timestamp(str(raw))
+        except (ValueError, TypeError):
+            return _epoch
+
+    return sorted(sessions, key=_key, reverse=True)
+
+
+def save_history_store(sessions: list[dict[str, Any]]) -> None:
+    payload = json.dumps({"sessions": sort_sessions(sessions)}, indent=2) + "\n"
+    tmp = HISTORY_PATH.with_suffix(".tmp")
+    tmp.write_text(payload, encoding="utf-8")
+    tmp.replace(HISTORY_PATH)
+
+
+def load_history_store(config: dict[str, Any]) -> list[dict[str, Any]]:
+    sessions: list[dict[str, Any]] = []
+    if HISTORY_PATH.exists():
+        # A truncated or corrupted history file used to raise here and take
+        # the whole app down on EVERY launch — unrecoverable without knowing
+        # to delete a file you were never told about. Past history is never
+        # worth more than a working CLI: quarantine it and carry on.
+        try:
+            with HISTORY_PATH.open("r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            raw = data.get("sessions", []) if isinstance(data, dict) else []
+            sessions = [s for s in raw if isinstance(s, dict)]
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError) as exc:
+            quarantine = HISTORY_PATH.with_suffix(".corrupt")
+            try:
+                HISTORY_PATH.replace(quarantine)
+                cprint(
+                    f"\n  History file was unreadable ({exc.__class__.__name__}). "
+                    f"Moved it to {quarantine.name} and started a fresh history.",
+                    C.YELLOW,
+                )
+            except OSError:
+                cprint("\n  History file is unreadable and could not be moved; "
+                       "continuing with an empty history.", C.YELLOW)
+            sessions = []
+
+    cutoff = utc_now() - timedelta(days=int(config.get("history_retention_days", 30)))
+    filtered: list[dict[str, Any]] = []
+    changed = False
+    for s in sessions:
+        try:
+            modified_at = parse_timestamp(str(s.get("modified_at", "")))
+        except ValueError:
+            changed = True
+            continue
+        if modified_at < cutoff:
+            changed = True
+            continue
+        s.setdefault("title", "New session")
+        s.setdefault("created_at", s.get("modified_at", iso_now()))
+        s.setdefault("messages", [])
+        s.setdefault("compact_count", 0)
+        filtered.append(s)
+
+    filtered = sort_sessions(filtered)
+    if changed:
+        save_history_store(filtered)
+    return filtered
+
+
+def search_sessions(
+    sessions: list[dict[str, Any]],
+    term: str,
+    max_snippets: int = 2,
+    context: int = 44,
+) -> list[dict[str, Any]]:
+    """Case-insensitive substring search over titles and message content.
+
+    Returns hits in the same order as `sessions`, each carrying the 1-based
+    index into that list — the SAME number /history shows and /resume takes,
+    so a search result is directly resumable. Snippets come pre-split as
+    (role, prefix, match, suffix) so the renderer can highlight the match
+    without re-finding it.
+    """
+    term_l = term.lower()
+    if not term_l:
+        return []
+    hits: list[dict[str, Any]] = []
+    for idx, session in enumerate(sessions, start=1):
+        raw_matches: list[tuple[str, str, int]] = []
+        title = str(session.get("title", ""))
+        pos = title.lower().find(term_l)
+        if pos >= 0:
+            raw_matches.append(("title", title, pos))
+        for msg in session.get("messages", []):
+            if len(raw_matches) >= max_snippets:
+                break
+            if not isinstance(msg, dict):
+                continue
+            content = str(msg.get("content", ""))
+            pos = content.lower().find(term_l)
+            if pos >= 0:
+                raw_matches.append((str(msg.get("role", "?")), content, pos))
+        if not raw_matches:
+            continue
+        snippets: list[tuple[str, str, str, str]] = []
+        for role, text, pos in raw_matches[:max_snippets]:
+            start = max(0, pos - context)
+            end = min(len(text), pos + len(term) + context)
+            prefix = ("…" if start > 0 else "") + text[start:pos].replace("\n", " ")
+            match = text[pos:pos + len(term)].replace("\n", " ")
+            suffix = text[pos + len(term):end].replace("\n", " ") + ("…" if end < len(text) else "")
+            snippets.append((role, prefix, match, suffix))
+        hits.append({"index": idx, "session": session, "snippets": snippets})
+    return hits
+
+
+def upsert_session(sessions: list[dict[str, Any]], session: dict[str, Any]) -> None:
+    if not session_has_messages(session):
+        return
+    for i, existing in enumerate(sessions):
+        if existing.get("id") == session.get("id"):
+            sessions[i] = session
+            return
+    sessions.append(session)
+
+
+def sync_session_store(sessions: list[dict[str, Any]], session: dict[str, Any]) -> None:
+    upsert_session(sessions, session)
+    save_history_store(sessions)
+
+

hexcli/setup_wizard.py

@@ -0,0 +1,144 @@
+"""hexcli/setup_wizard.py — /setup: interactive configuration wizard.
+
+A handful of questions covering the config decisions that actually matter
+day one (safety posture, network policy, UI). Each shows the current value
+as the default, so Enter-Enter-Enter through the wizard changes nothing.
+
+It writes ONLY the keys the user was asked about, merged over whatever the
+config file already contains — never a full DEFAULT_CONFIG dump. A config
+file full of copied defaults is exactly the drift bug the generated example
+config exists to prevent: values silently pinned at whatever release they
+were written by.
+
+IO is injected (ask/echo) so the whole flow is testable offline; EOF or
+Ctrl+C at any question aborts without writing.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from hexcli.ui import C, cprint
+
+# (key, question, kind, choices) — kind is "bool" or "choice".
+QUESTIONS: list[tuple[str, str, str, tuple[str, ...]]] = [
+    ("autopilot_confirm_destructive",
+     "Confirm destructive commands such as rm and format?", "bool", ()),
+    ("autopilot_confirm_sensitive",
+     "Confirm access to sensitive paths such as SSH keys and credentials?", "bool", ()),
+    ("workspace_write_scope",
+     "Block file writes outside the project directory?", "bool", ()),
+    ("network_access",
+     "Network access for fetch_url?", "choice", ("ask", "deny", "allow")),
+    ("show_diffs",
+     "Show a diff after every file change?", "bool", ()),
+    ("rich_input",
+     "Rich input line with history and Tab completion?", "bool", ()),
+]
+
+
+def _ask_bool(ask: Callable[[str], str], question: str, current: bool) -> bool:
+    hint = "[Y/n]" if current else "[y/N]"
+    answer = ask(f"  {question} {hint} ").strip().lower()
+    if not answer:
+        return current
+    return answer in ("y", "yes", "1", "true", "on")
+
+
+def _ask_choice(ask: Callable[[str], str], question: str,
+                choices: tuple[str, ...], current: str) -> str:
+    menu = "/".join(c.upper() if c == current else c for c in choices)
+    while True:
+        answer = ask(f"  {question} [{menu}] ").strip().lower()
+        if not answer:
+            return current
+        if answer in choices:
+            return answer
+        cprint(f"    Answer {', '.join(choices[:-1])} or {choices[-1]}.", C.DIM)
+
+
+def write_config_keys(path: Path, chosen: dict[str, Any]) -> None:
+    """Merge the chosen keys over the existing file, atomically."""
+    existing: dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                existing = data
+        except (json.JSONDecodeError, OSError):
+            pass  # unreadable file: the wizard's keys become the file
+    existing.update(chosen)
+    payload = json.dumps(existing, indent=2) + "\n"
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(payload, encoding="utf-8")
+    tmp.replace(path)
+
+
+def overridden_by_project(chosen: dict[str, Any], project_cfg: Path) -> list[str]:
+    """Keys the wizard just saved that a project .shellai/config.json will
+    still override on every load (it deep-merges on top of the user config).
+
+    Without this, the wizard's closing "applies on every launch" line is a
+    lie in any repo that ships its own config.
+    """
+    if not project_cfg.exists():
+        return []
+    try:
+        data = json.loads(project_cfg.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(data, dict):
+        return []
+    return [k for k in chosen if k in data and data[k] != chosen[k]]
+
+
+def run_wizard(
+    config: dict[str, Any],
+    config_path: Path,
+    ask: Callable[[str], str] = input,
+    project_cfg: Path | None = None,
+) -> bool:
+    """Run the wizard. Returns True if the config file was written.
+
+    Updates `config` in place on success so answers apply to the running
+    session immediately, not just the next launch.
+    """
+    print()
+    cprint("  Setup", C.BOLD)
+    cprint("  Enter keeps the current value.", C.DIM)
+    print()
+    chosen: dict[str, Any] = {}
+    try:
+        for key, question, kind, choices in QUESTIONS:
+            if kind == "bool":
+                chosen[key] = _ask_bool(ask, question, bool(config.get(key, True)))
+            else:
+                current = str(config.get(key, choices[0]))
+                if current not in choices:
+                    current = choices[0]
+                chosen[key] = _ask_choice(ask, question, choices, current)
+        print()
+        for key, value in chosen.items():
+            marker = "" if config.get(key) == value else "  changed"
+            cprint(f"    {key} = {value!r}{marker}", C.DIM)
+        print()
+        confirm = ask(f"  Save to {config_path.name}? [Y/n] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        cprint("  Cancelled. Nothing written.", C.DIM)
+        return False
+    if confirm not in ("", "y", "yes"):
+        cprint("  Nothing written.", C.DIM)
+        return False
+    write_config_keys(config_path, chosen)
+    config.update(chosen)
+    cprint(f"  Saved {config_path}.", C.DIM)
+    shadowed = overridden_by_project(
+        chosen, project_cfg if project_cfg is not None else Path.cwd() / ".shellai" / "config.json"
+    )
+    if shadowed:
+        cprint(f"  .shellai/config.json overrides {', '.join(sorted(shadowed))}. "
+               "Edit it there too.", C.YELLOW)
+    return True

hexcli/shell_session.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""hexcli.shell_session — persistent PowerShell session for the v2 `shell` tool.
+
+v1 spawned a fresh `powershell.exe -Command` per call, so `cd`, environment
+variables, and venv activation evaporated between steps. This module keeps ONE
+PowerShell process alive per agent session and multiplexes commands through it
+with a sentinel protocol:
+
+    <command>
+    Write-Output "<sentinel> <exit-ish code>"
+
+stdout+stderr are merged at the command level (2>&1) so the model sees errors
+inline, in order. A timeout kills the whole process tree (taskkill /T) and the
+next call transparently respawns a fresh session — a hung command can never
+wedge the agent loop.
+"""
+from __future__ import annotations
+
+import base64
+import queue
+import subprocess
+import threading
+import uuid
+from typing import Any
+
+_DEFAULT_TIMEOUT_S = 60
+_OUTPUT_CAP_CHARS = 200_000  # hard runaway guard; the agent loop trims further
+
+
+class ShellSession:
+    """One persistent PowerShell process; safe to reuse across commands."""
+
+    def __init__(self, cwd: str | None = None, shell_exe: str = "powershell.exe") -> None:
+        self._cwd = cwd
+        self._shell_exe = shell_exe
+        self._proc: subprocess.Popen[str] | None = None
+        self._out_queue: queue.Queue[str | None] = queue.Queue()
+        self._reader: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def _spawn(self) -> None:
+        self._proc = subprocess.Popen(
+            [self._shell_exe, "-NoProfile", "-NoLogo", "-NonInteractive", "-Command", "-"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=self._cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            bufsize=1,
+        )
+        self._out_queue = queue.Queue()
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+    def _read_loop(self) -> None:
+        proc = self._proc
+        if proc is None or proc.stdout is None:
+            return
+        q = self._out_queue
+        for line in proc.stdout:
+            q.put(line)
+        q.put(None)  # EOF marker
+
+    def _send(self, text: str) -> None:
+        assert self._proc is not None and self._proc.stdin is not None
+        self._proc.stdin.write(text + "\n")
+        self._proc.stdin.flush()
+
+    def _alive(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    def close(self) -> None:
+        with self._lock:
+            self._kill_tree()
+
+    def _kill_tree(self) -> None:
+        if self._proc is None:
+            return
+        pid = self._proc.pid
+        try:
+            subprocess.run(
+                ["taskkill", "/T", "/F", "/PID", str(pid)],
+                capture_output=True, timeout=10,
+            )
+        except Exception:
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+        self._proc = None
+
+    # -- command execution --------------------------------------------------
+
+    def run(self, command: str, timeout_s: int = _DEFAULT_TIMEOUT_S) -> dict[str, Any]:
+        """Run one command; returns {"output": str, "exit_code": int|None,
+        "timed_out": bool, "restarted": bool}."""
+        with self._lock:
+            restarted = False
+            if not self._alive():
+                self._kill_tree()
+                self._spawn()
+                restarted = self._proc is not None
+
+            sentinel = f"__HEX_DONE_{uuid.uuid4().hex}__"
+            # Windows PowerShell 5.1 decodes piped stdin — and encodes piped
+            # stdout — with the OEM codepage, mangling any non-ASCII content.
+            # So the command travels IN as UTF-16LE base64 (Invoke-Expression
+            # keeps it in the session's own scope: cd, $env:, and variables
+            # all persist), and the output travels OUT as UTF-8 base64 on the
+            # sentinel line. Base64 is pure ASCII and survives any codepage.
+            #
+            # Exit-code detection: native commands set $LASTEXITCODE; cmdlet
+            # failures are detected via $Error growth ($? is useless here —
+            # it would reflect the last pipeline stage, not the command).
+            cmd_b64 = base64.b64encode(command.encode("utf-16-le")).decode("ascii")
+            wrapped = (
+                "$global:LASTEXITCODE = $null; $__hex_errs = $Error.Count; "
+                f"$__hex_cmd = [System.Text.Encoding]::Unicode.GetString([System.Convert]::FromBase64String('{cmd_b64}')); "
+                # Dot-sourcing a created ScriptBlock runs in the CURRENT scope
+                # (cd/$env:/variables persist) while letting 2>&1 capture the
+                # invoked command's error stream — Invoke-Expression's redirect
+                # cannot see errors raised inside the expression.
+                "try { $__hex_out = . ([System.Management.Automation.ScriptBlock]::Create($__hex_cmd)) 2>&1 | Out-String } "
+                "catch { $__hex_out = ($_ | Out-String) ; $__hex_errs = -1 }; "
+                "$__hex_code = if ($null -ne $global:LASTEXITCODE) { $global:LASTEXITCODE } "
+                "elseif ($__hex_errs -lt 0 -or $Error.Count -gt $__hex_errs) { 1 } else { 0 }; "
+                f"if ($__hex_out.Length -gt {_OUTPUT_CAP_CHARS}) "
+                f"{{ $__hex_out = $__hex_out.Substring(0, {_OUTPUT_CAP_CHARS}) + \"`n[output truncated]\" }}; "
+                "$__hex_b64 = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__hex_out)); "
+                f"Write-Output \"{sentinel}:$__hex_code`:$__hex_b64\""
+            )
+            try:
+                self._send(wrapped)
+            except (OSError, AssertionError):
+                self._kill_tree()
+                return {"output": "shell session died while sending the command; it will restart on the next call",
+                        "exit_code": None, "timed_out": False, "restarted": restarted}
+
+            lines: list[str] = []
+            total = 0
+            deadline = timeout_s
+            import time
+            start = time.monotonic()
+            while True:
+                remaining = deadline - (time.monotonic() - start)
+                if remaining <= 0:
+                    self._kill_tree()
+                    return {
+                        "output": "".join(lines)[:_OUTPUT_CAP_CHARS]
+                        + f"\n[timeout] command exceeded {timeout_s}s; the shell session was killed and will restart on the next call",
+                        "exit_code": None, "timed_out": True, "restarted": restarted,
+                    }
+                try:
+                    line = self._out_queue.get(timeout=min(remaining, 0.5))
+                except queue.Empty:
+                    continue
+                if line is None:
+                    # Process exited underneath us (e.g. the command ran `exit`).
+                    self._kill_tree()
+                    return {"output": "".join(lines)[:_OUTPUT_CAP_CHARS],
+                            "exit_code": None, "timed_out": False, "restarted": restarted}
+                if line.startswith(sentinel):
+                    parts = line.strip().split(":", 2)
+                    exit_code: int | None
+                    output: str
+                    try:
+                        exit_code = int(parts[1])
+                    except (IndexError, ValueError):
+                        exit_code = None
+                    try:
+                        output = base64.b64decode(parts[2]).decode("utf-8", errors="replace") if len(parts) > 2 else ""
+                    except Exception:
+                        output = ""
+                    # Anything that leaked outside the sentinel protocol (e.g.
+                    # wrapper-level parse errors) is prepended so it's never lost.
+                    if lines:
+                        output = "".join(lines) + output
+                    return {"output": output[:_OUTPUT_CAP_CHARS],
+                            "exit_code": exit_code, "timed_out": False, "restarted": restarted}
+                total += len(line)
+                if total <= _OUTPUT_CAP_CHARS:
+                    lines.append(line)