Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust
74.1 KB
Raw Blame
"""Async-by-default shell execution: bash() spawns immediately and returns a live handle."""

from __future__ import annotations

import asyncio
import atexit
import functools
import json
import os
import secrets
import selectors
import shutil
import signal
import socket
import struct
import subprocess
import sys
import threading
import time
import uuid
from collections import deque
from collections.abc import Awaitable, Callable, Generator
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, NoReturn, cast

from . import _winjob

_IS_POSIX = os.name == "posix"

if _IS_POSIX:
    import fcntl
    import termios

_HEAD_CAP = 512 * 1024
_TAIL_CAP = 3 * 512 * 1024
_READ_CHUNK = 65536
# Fixed child-side fd for the status channel; POSIX shells (notably dash) only
# guarantee single-digit fds in redirection syntax.
_STATUS_FD = 9
_OUTPUT_FD = 8
_COMPLETION_PREFIX = b"\x1eprime-agent-complete:"
_COMPLETION_SUFFIX = b"\x1f"
# Cancelled one-shot awaits: TERM grace before the group KILL, then the bounded
# wait for a confirmed group exit before CancelledError propagates.
_CANCEL_TERM_GRACE = 0.5
_CANCEL_KILL_WAIT = 2.0
_COMPLETION_NOTICE_COMMAND_CAP = 1000
# Display MIME the host aggregates into a per-cell summary of the bash()
# commands the cell ran (first capped command, count, line total).
_BASH_COMMAND_MIME = "application/vnd.prime-agent.bash-command+json"
_ASYNCIO_WRAPPER_CALLBACKS = {
    ("asyncio.tasks", "gather.<locals>._done_callback"),
    ("asyncio.tasks", "shield.<locals>._inner_done_callback"),
    ("asyncio.tasks", "_wait.<locals>._on_completion"),
    ("asyncio.tasks", "as_completed.<locals>._on_completion"),
    ("asyncio.tasks", "_release_waiter"),
}

# Bounded awaits: in sessions whose host registers the bash.completed handler,
# an await still running after _YIELD_AFTER_SECONDS degrades to returning the
# live handle instead of blocking (the [bash-done] notice collects it). The
# kernel bootstrap flips the flag from the host-handler registry — one source
# of truth; the window stays here, never on the Rust side.
_completion_notices_wired = False
_YIELD_AFTER_SECONDS = 1.0


def _set_completion_notices_wired(wired: bool) -> None:
    """Record whether the host wires bash completion notices.

    Called by the kernel bootstrap only when the `bash.completed` host handler
    is registered. Sessions without the notice keep unbounded awaits: nothing
    would wake a cell that ended its turn on a degraded command.
    """
    global _completion_notices_wired
    _completion_notices_wired = wired


# One stderr hint per degrade, budgeted per kernel (nano-rlm's
# MAX_LONG_RUN_NOTES shape): the first few degrades teach the contract, later
# ones stay quiet.
_MAX_DEGRADE_HINTS = 3
_degrade_hints_written = 0


def _note_degrade(handle: "BashHandle", bound: float) -> None:
    """Write the degrade hint to the awaiting cell's stderr, within budget."""
    global _degrade_hints_written
    if _degrade_hints_written >= _MAX_DEGRADE_HINTS:
        return
    _degrade_hints_written += 1
    sys.stderr.write(
        f"bash: still running after {bound:g}s (pid {handle._pid}); "
        "returned a snapshot: r.running is True, r.output is the output so "
        "far, r.handle is the live handle. End the turn — a [bash-done] "
        "notification arrives when it finishes.\n"
    )


async def _bounded_wait(
    wait: Awaitable[BashResult], bound: float | None
) -> BashResult | None:
    """Await a command wait, abandoning it after `bound` seconds.

    Returns None only on the degrade: the wait task keeps running (cancelling
    an owned wait would kill the command — the degrade must not), and its
    late result is consumed silently by the done callback.
    """
    if bound is None:
        return await wait
    wait_task = asyncio.ensure_future(wait)
    try:
        done, _pending = await asyncio.wait({wait_task}, timeout=bound)
    except asyncio.CancelledError:
        # An interrupt inside the window: the wait must observe the cancel
        # (an owned await runs its kill dance in _wait_owned) before the
        # CancelledError propagates.
        wait_task.cancel()
        while not wait_task.done():
            try:
                await asyncio.shield(wait_task)
            except asyncio.CancelledError:
                continue
        raise
    if wait_task in done:
        return wait_task.result()
    wait_task.add_done_callback(_consume_notice_task)
    return None


_live_handles: set["BashHandle"] = set()
# Kernel-owned opaque IDs: retained results are bounded, never resolved by PID.
_activity_handles: dict[str, "BashHandle"] = {}
_activity_order: deque[str] = deque()
_ACTIVITY_HISTORY_CAP = 64
_live_lock = threading.Lock()
_hook_installed = False
_hook_lock = threading.Lock()

# bash(persistent=True): every session's persistent shells live in one home
# under the agent dir (the cross-language contract pa-daemon reads): per shell
# a <id>.json record assigned to its session (RLM_SESSION_ID, the durable
# session id the host exports), plus <id>.out and <id>.rc.
_PERSISTENT_DIR = "persistent-shells"
_PERSISTENT_POLL = 1.0
# Gate on stdin, then run the command in its own shell so exit/exec/set -e
# cannot skip the atomic status write.
_PERSISTENT_WRAPPER = (
    "read -r _prime_agent_gate || exit 127\n"
    "exec 0</dev/null\n"
    '"$1" -c "$2"\n'
    "__prime_status=$?\n"
    "printf '%s\\n' \"$__prime_status\" > \"$3.tmp\" && mv -f \"$3.tmp\" \"$3\"\n"
)


def _current_cell_completion_context() -> tuple[asyncio.Event, asyncio.Task[Any] | None] | None:
    """Get the creating REPL cell's lifecycle without coupling standalone use to repl."""
    try:
        from . import repl

        if repl.is_active():
            return repl.current_cell_completion_context()
    except (ImportError, RuntimeError):
        pass
    return None


def _consume_notice_task(task: asyncio.Task[None]) -> None:
    """Retrieve detached notifier failures so they never become loop warnings."""
    if not task.cancelled():
        task.exception()


def _capped(command: str) -> str:
    if len(command) > _COMPLETION_NOTICE_COMMAND_CAP:
        return command[:_COMPLETION_NOTICE_COMMAND_CAP] + "\n... [command truncated]"
    return command


def _completion_reaches(
    start: asyncio.Future[Any], targets: tuple[asyncio.Future[Any], ...]
) -> bool:
    """Follow asyncio's wrapper and TaskGroup ownership callbacks."""
    pending = [start]
    seen_futures: set[int] = set()
    seen_values: set[int] = set()

    def collect(value: Any, depth: int = 0) -> None:
        if isinstance(value, asyncio.Future):
            pending.append(value)
            return
        identity = id(value)
        if depth >= 4 or identity in seen_values:
            return
        seen_values.add(identity)

        nested: list[Any] = []
        if isinstance(value, asyncio.Queue):
            pending.extend(value._getters)
        elif isinstance(value, functools.partial):
            nested.extend((value.func, value.args, value.keywords))
        elif isinstance(value, dict):
            nested.extend(value.keys())
            nested.extend(value.values())
        elif isinstance(value, (tuple, list, set, frozenset)):
            nested.extend(value)
        else:
            closure = getattr(value, "__closure__", None) or ()
            for cell in closure:
                try:
                    nested.append(cell.cell_contents)
                except ValueError:
                    pass
            bound_self = getattr(value, "__self__", None)
            if bound_self is not None:
                nested.append(bound_self)
        for item in nested:
            collect(item, depth + 1)

    while pending:
        future = pending.pop()
        if any(future is target for target in targets):
            return True
        if id(future) in seen_futures:
            continue
        seen_futures.add(id(future))
        for entry in getattr(future, "_callbacks", None) or ():
            callback = entry[0] if isinstance(entry, tuple) else entry
            base = callback.func if isinstance(callback, functools.partial) else callback
            identity = (getattr(base, "__module__", None), getattr(base, "__qualname__", None))
            if identity in _ASYNCIO_WRAPPER_CALLBACKS:
                collect(callback)
            elif identity == ("asyncio.tasks", "_AsCompletedIterator._handle_completion"):
                collect(base.__self__._done)
            elif identity == (None, "Task.task_wakeup"):
                task = getattr(callback, "__self__", None)
                if isinstance(task, asyncio.Task):
                    pending.append(task)
            elif identity == ("asyncio.taskgroups", "TaskGroup._on_task_done"):
                parent = getattr(getattr(callback, "__self__", None), "_parent_task", None)
                if isinstance(parent, asyncio.Future):
                    pending.append(parent)
    return False


def _creating_cell_waits_for(
    owner: asyncio.Task[Any] | None, awaiter: asyncio.Task[Any] | None
) -> bool:
    """Return whether the cell owner directly or transitively waits for awaiter."""
    if owner is None or awaiter is None:
        return False
    if owner is awaiter:
        return True
    waiter = getattr(owner, "_fut_waiter", None)
    targets: tuple[asyncio.Future[Any], ...] = (owner,)
    if isinstance(waiter, asyncio.Future):
        targets += (waiter,)
    return _completion_reaches(awaiter, targets)


def _live_cell_owner() -> asyncio.Task[Any] | None:
    """Body task of the cell executing right now, ignoring detached context copies."""
    try:
        from . import repl

        if repl.is_active():
            return repl.active_cell_task()
    except (ImportError, RuntimeError):
        pass
    return None


@dataclass(frozen=True)
class BashResult:
    exit_code: int
    output: str
    duration: float

    @property
    def running(self) -> bool:
        # The discriminator the prompt teaches: a finished result is never
        # running (BashSnapshot.running is True). A property, not a field, so
        # repr, equality, and positional construction stay unchanged.
        return False


@dataclass(frozen=True)
class BashSnapshot:
    """A degraded await's still-running snapshot (`BashHandle.__await__`).

    `r.output`/`r.exit_code` read like a BashResult's — output so far and
    None while running — and `r.running` is True; `r.handle` is the live
    handle: collect the final result on the [bash-done] notification or with
    `await r.handle`. The snapshot itself is not awaitable (that was #3076's
    rejected wrapper shape).
    """

    output: str
    exit_code: None
    running: bool
    duration: float
    handle: "BashHandle"

    def __repr__(self) -> str:
        return (
            f"<BashSnapshot running pid={self.handle._pid} "
            f"after {self.duration:g}s: collect on the [bash-done] "
            "notification or await .handle>"
        )


class _BoundedBuffer:
    """First _HEAD_CAP bytes plus a rolling _TAIL_CAP-byte tail; the middle is dropped."""

    def __init__(self) -> None:
        self._head = bytearray()
        self._tail: deque[bytes] = deque()
        self._tail_size = 0
        self._dropped = 0
        self._lock = threading.Lock()

    def write(self, chunk: bytes) -> None:
        with self._lock:
            if len(self._head) < _HEAD_CAP:
                take = _HEAD_CAP - len(self._head)
                self._head.extend(chunk[:take])
                chunk = chunk[take:]
            if not chunk:
                return
            self._tail.append(chunk)
            self._tail_size += len(chunk)
            # Trim the oldest chunk instead of dropping it whole so exactly _TAIL_CAP bytes stay.
            while self._tail_size > _TAIL_CAP:
                excess = self._tail_size - _TAIL_CAP
                oldest = self._tail[0]
                if len(oldest) <= excess:
                    self._tail.popleft()
                    self._tail_size -= len(oldest)
                    self._dropped += len(oldest)
                else:
                    self._tail[0] = oldest[excess:]
                    self._tail_size -= excess
                    self._dropped += excess

    def size(self) -> int:
        with self._lock:
            return len(self._head) + self._tail_size

    def text(self) -> str:
        with self._lock:
            head = bytes(self._head)
            tail = b"".join(self._tail)
            dropped = self._dropped
        if not dropped:
            return (head + tail).decode("utf-8", errors="replace")
        marker = f"\n... [{dropped} bytes dropped] ...\n"
        return head.decode("utf-8", errors="replace") + marker + tail.decode("utf-8", errors="replace")


class BashHandle:
    """Live handle to a shell command; await it for the BashResult.

    A handle awaited before any other API use (the `await bash(cmd)` one-shot
    form, including `h = bash(cmd)` awaited immediately) owns the command:
    cancelling that await kills the process group. Touching .pid/.running/
    .output()/.tail()/.poll()/.kill() first marks the handle as a background
    handle; later awaits only wait and cancelling them leaves it running.
    """

    def __init__(self, command: str) -> None:
        self.command = command
        self._activity_id = secrets.token_hex(16)
        completion_context = _current_cell_completion_context()
        self._creating_cell_finished = completion_context[0] if completion_context else None
        self._creating_cell_task = completion_context[1] if completion_context else None
        self._awaited_by_creating_cell = False
        self._buffer = _BoundedBuffer()
        self._done = threading.Event()
        self._eof = threading.Event()
        self._completion_terminal = threading.Event()
        self._completion_output: str | None = None
        self._completion_lock = threading.Lock()
        self._completion_pending = b""
        self._status: int | None = None
        self._status_known = threading.Event()
        self._reaped = False
        self._result: BashResult | None = None
        self._callbacks: list[Callable[[], None]] = []
        self._reap_callback: Callable[[], None] | None = None
        self._result_consumed = False
        self._consumed_notice: Callable[[], None] | None = None
        self._callback_lock = threading.Lock()
        # Serializes kill/reap so a pid fallback can never outlive the process handle.
        self._kill_lock = threading.Lock()
        self._started = time.monotonic()
        self._started_at = datetime.now(timezone.utc).isoformat()
        # POSIX: own process group so kill() signals the whole pipeline; Windows
        # contains the tree in a kill-on-close job object.
        self._status_read = -1
        self._wake_read = -1
        self._wake_write = -1
        # True only while the pump moves a chunk from the pipe into the buffer.
        self._pump_transfer = False
        self._job: int | None = None
        self._completion_marker: bytes | None = None
        status_write = -1
        if _IS_POSIX:
            # Full-duplex status channel: the child end rides in as stdin (fd 0)
            # and the script remaps it to _STATUS_FD before swapping in /dev/null
            # (dash rejects multi-digit fds in redirections at parse time). The
            # parent end doubles as the gate: the child blocks on it until the
            # pid is journaled, so a kernel kill in that window cannot leak an
            # unjournaled command (parent death closes the socket -> child exits).
            parent_sock, child_sock = socket.socketpair()
            self._status_read = parent_sock.detach()
            status_write = child_sock.detach()
            try:
                self._wake_read, self._wake_write = os.pipe()
            except BaseException:
                os.close(self._status_read)
                os.close(status_write)
                raise
            completion_token = secrets.token_hex(32)
            # Halves stop passive echoes; a deliberate forgery freezes only this call while later bytes stay live.
            token_midpoint = len(completion_token) // 2
            self._completion_marker = (
                _COMPLETION_PREFIX + completion_token.encode("ascii") + _COMPLETION_SUFFIX
            )
            script = _status_script(
                _with_prefix(command),
                completion_token[:token_midpoint],
                completion_token[token_midpoint:],
            )
        else:
            # Windows lacks a foreground-status channel, so its exit drain stays best-effort.
            script = _with_prefix(command)
            self._job = _winjob.create_job()
            if self._job is None:
                # Nothing spawned yet, so nothing can leak: refuse to start.
                raise RuntimeError("bash(): Windows job containment could not be established")
        try:
            self._proc: subprocess.Popen[bytes] | _winjob.JobProcess
            if _IS_POSIX:
                self._proc = subprocess.Popen(
                    [_shell(), "-c", script],
                    cwd=os.getcwd(),
                    env=_child_env(),
                    stdout=subprocess.PIPE,
                    stderr=subprocess.STDOUT,
                    start_new_session=True,
                    stdin=status_write,
                )
            else:
                self._proc = _winjob.spawn_in_job(
                    self._job, [_shell(), "-c", script], cwd=os.getcwd(), env=_child_env()
                )
        except BaseException:
            for fd in (self._status_read, self._wake_read, self._wake_write):
                if fd >= 0:
                    os.close(fd)
            if self._job is not None:
                job, self._job = self._job, None
                _winjob.close(job)
            raise
        finally:
            if status_write >= 0:
                os.close(status_write)
        self._pid: int = self._proc.pid
        self._released = False
        with _live_lock:
            _live_handles.add(self)
            _activity_handles[self._activity_id] = self
        enrolled = _record_journal(self._pid, active=True)
        if not enrolled:
            # Fail closed: a configured journal that cannot enroll the pid must
            # not let the command run (the host reaper would never see it).
            self._abort_spawn()
            raise RuntimeError(
                "bash(): orphan-journal enrollment failed (journal configured but the "
                "pid could not be recorded); the spawned process was killed"
            )
        if _IS_POSIX:
            # Journal first, then open the gate: the child does not run the user
            # command until this byte arrives. A failed write means the child
            # already died; the status/EOF paths report that normally.
            try:
                os.write(self._status_read, b"\n")
            except OSError:
                pass
        else:
            # The child is already job-contained and journaled; resume is the
            # last step. A failed resume would strand a permanently suspended
            # child: fail closed via the assigned job.
            if not cast("_winjob.JobProcess", self._proc).resume():
                self._abort_spawn()
                raise RuntimeError("bash(): Windows job containment could not be established")
        threading.Thread(target=self._pump, daemon=True).start()
        threading.Thread(target=self._report, daemon=True).start()
        threading.Thread(target=self._watch, daemon=True).start()
        self._schedule_background_completion_notice()

    @property
    def pid(self) -> int:
        self._released = True
        return self._pid

    @property
    def running(self) -> bool:
        # Group liveness, matching kill()'s guard and the journal; poll()/await
        # keep foreground result semantics after `cmd &` returns early.
        self._released = True
        return not self._reaped

    def output(self) -> str:
        self._released = True
        self._note_result_consumed()
        return self._buffer.text()

    def tail(self, n: int = 50) -> str:
        self._released = True
        self._note_result_consumed()
        return "\n".join(self._buffer.text().splitlines()[-n:])

    def poll(self) -> BashResult | None:
        self._released = True
        self._note_result_consumed()
        return self._result if self._done.is_set() else None

    def kill(self, sig: int = signal.SIGTERM, grace: float = 5.0) -> None:
        # Guard on group death, not _done: kill() must still reach a lingering
        # background group after the foreground result was already delivered.
        self._released = True
        if self._reaped:
            return
        if not _IS_POSIX:
            with self._kill_lock:
                if self._reaped:  # re-check: _watch may have reaped while we waited
                    return
                if self._job is not None and _winjob.terminate(self._job):
                    return
                # TerminateJobObject failed or reap raced: taskkill fallback.
                if not _taskkill_tree(self._pid):
                    try:
                        self._proc.kill()
                    except OSError:
                        pass
            return
        _signal_group(self._pid, sig)
        if sig == signal.SIGTERM:
            timer = threading.Timer(grace, self._force_kill)
            timer.daemon = True
            timer.start()

    def _force_kill(self) -> None:
        if not self._reaped:
            _signal_group(self._pid, signal.SIGKILL)

    def _pump(self) -> None:
        stdout = self._proc.stdout
        assert stdout is not None
        if not _IS_POSIX:
            try:
                while chunk := stdout.read1(_READ_CHUNK):
                    self._buffer.write(chunk)
            except (OSError, ValueError):
                pass
            stdout.close()
            self._eof.set()
            return
        fd = stdout.fileno()
        try:
            with selectors.DefaultSelector() as sel:
                sel.register(fd, selectors.EVENT_READ)
                while True:
                    sel.select()
                    self._pump_transfer = True
                    try:
                        chunk = os.read(fd, _READ_CHUNK)
                        if not chunk:
                            break
                        self._consume_output(chunk)
                    finally:
                        self._pump_transfer = False
        except (OSError, ValueError):
            pass
        self._abandon_completion()
        try:
            stdout.close()
        except OSError:
            pass
        self._eof.set()

    def _consume_output(self, chunk: bytes) -> None:
        marker = self._completion_marker
        assert marker is not None
        with self._completion_lock:
            if self._completion_terminal.is_set():
                self._buffer.write(chunk)
                return
            data = self._completion_pending + chunk
            marker_at = data.find(marker)
            if marker_at >= 0:
                self._buffer.write(data[:marker_at])
                self._completion_pending = b""
                self._completion_output = self._buffer.text()
                self._completion_terminal.set()
                self._buffer.write(data[marker_at + len(marker) :])
                return
            retained = 0
            for size in range(min(len(data), len(marker) - 1), 0, -1):
                if data.endswith(marker[:size]):
                    retained = size
                    break
            self._buffer.write(data[:-retained] if retained else data)
            self._completion_pending = data[-retained:] if retained else b""

    def _abandon_completion(self) -> None:
        with self._completion_lock:
            if self._completion_terminal.is_set():
                return
            self._buffer.write(self._completion_pending)
            self._completion_pending = b""
            self._completion_terminal.set()

    def _wait_for_completion(self) -> str | None:
        self._completion_terminal.wait()
        return self._completion_output

    def _report(self) -> None:
        # Finalize at foreground completion (status channel), not EOF, so
        # `cmd &` does not hang the await; the shell then `wait`s for its
        # background jobs, keeping the journaled group identity alive.
        status: int | None = None
        try:
            status = self._read_status()
            # Reserve the delivered status before draining so a shell death during
            # the drain window cannot override it with wait()'s signal exit code.
            with self._callback_lock:
                self._status = status
        finally:
            # _watch blocks on this event without a timeout, so every exit path
            # (parsed status, EOF, garbage, exception) must set it.
            self._status_known.set()
        if status is not None:
            output = self._wait_for_completion()
            if output is None:
                self._drain_grace()
            self._finalize(status, output)

    def _watch(self) -> None:
        # Observe shell death independently of the status socket: an early
        # `exit`/`exec`/`set -e`/fatal signal skips `printf`, and background
        # children can hold the socket open past the shell's lifetime.
        exit_code = self._proc.wait()
        if self._wake_write >= 0:
            # Unblock _read_status: background children can hold the status socket
            # open past the shell's lifetime via bash's saved-fd duplicate.
            try:
                os.write(self._wake_write, b"x")
            except OSError:
                pass
            os.close(self._wake_write)
        # _report always sets _status_known (try/finally), so wait indefinitely:
        # a slow reporter can never lose a delivered status to wait()'s code.
        self._status_known.wait()
        with self._callback_lock:
            delivered = self._status
        if delivered is None and not self._done.is_set():
            self._abandon_completion()
            self._drain_grace()
            self._finalize(exit_code)
        with self._kill_lock:
            delivered = self._reap_group()
            self._reaped = True
            if not _IS_POSIX:
                # Reaped: pid fallbacks are gone, so the handle may finally close.
                cast("_winjob.JobProcess", self._proc).close()
        with self._callback_lock:
            callback, self._reap_callback = self._reap_callback, None
        if callback is not None:
            callback()
        if delivered:
            _record_journal(self._pid, active=False)
        with _live_lock:
            _live_handles.discard(self)
            _activity_order.append(self._activity_id)
            while len(_activity_order) > _ACTIVITY_HISTORY_CAP:
                _activity_handles.pop(_activity_order.popleft(), None)

    def _reap_group(self) -> bool:
        # Group liveness, not leader death, gates the inactive record: members
        # that outlive the leader would leak behind a stale journal anchor.
        if not _IS_POSIX:
            # Terminate then close the last handle: kill-on-close reaps
            # stragglers. An unproven terminate falls back to taskkill; if
            # that also fails the record stays active for the host reaper.
            delivered = False
            if self._job is not None:
                delivered = _winjob.terminate(self._job)
                job, self._job = self._job, None
                _winjob.close(job)
            return delivered or _taskkill_tree(self._pid)
        try:
            os.killpg(self._pid, 0)
        except ProcessLookupError:
            return True  # group already gone
        except PermissionError:
            pass
        return _signal_group(self._pid, signal.SIGKILL)

    def _read_status(self) -> int | None:
        if self._status_read < 0:
            return None
        try:
            # DefaultSelector (kqueue/epoll) instead of select(): select() rejects
            # fds >= FD_SETSIZE (1024) even when the process fd limit is higher.
            with selectors.DefaultSelector() as sel:
                sel.register(self._status_read, selectors.EVENT_READ)
                sel.register(self._wake_read, selectors.EVENT_READ)
                line = b""
                while b"\n" not in line:
                    ready = {key.fd for key, _ in sel.select()}
                    # Prefer status bytes: any status write happens before shell exit,
                    # so it is already readable whenever the wake fd fires.
                    if self._status_read not in ready:
                        break  # shell died without writing a status
                    chunk = os.read(self._status_read, 64)
                    if not chunk:
                        break  # EOF without a full status line
                    line += chunk
            return int(line)
        except (OSError, ValueError):
            return None
        finally:
            os.close(self._status_read)
            os.close(self._wake_read)

    def _drain_grace(self) -> None:
        # Best-effort fallback when process exit/EOF arrives without a sentinel.
        deadline = time.monotonic() + 0.5
        size = self._buffer.size()
        while time.monotonic() < deadline:
            if self._eof.wait(0.05):
                return
            # A chunk between pipe read and buffer commit (transfer flag) is
            # invisible to both FIONREAD and the buffer size; wait it out.
            if self._pipe_pending() or self._pump_transfer:
                size = self._buffer.size()
                continue
            current = self._buffer.size()
            if current == size:
                return
            size = current

    def _pipe_pending(self) -> bool:
        # POSIX only: FIONREAD on the capture pipe; Windows keeps the
        # quiescence heuristic (best-effort parity).
        if not _IS_POSIX or self._eof.is_set():
            return False
        stdout = self._proc.stdout
        if stdout is None:
            return False
        try:
            pending = struct.unpack("i", fcntl.ioctl(stdout.fileno(), termios.FIONREAD, struct.pack("i", 0)))[0]
        except (OSError, ValueError):
            return False
        return pending > 0

    def _finalize(self, exit_code: int, output: str | None = None) -> None:
        with self._callback_lock:
            if self._done.is_set():
                return
            self._result = BashResult(
                exit_code=exit_code,
                output=self._buffer.text() if output is None else output,
                duration=time.monotonic() - self._started,
            )
            self._done.set()
            callbacks = self._callbacks
            self._callbacks = []
        for callback in callbacks:
            callback()

    def _add_done_callback(self, callback: Callable[[], None]) -> None:
        with self._callback_lock:
            if not self._done.is_set():
                self._callbacks.append(callback)
                return
        callback()

    def _note_result_consumed(self, awaiter: asyncio.Task[Any] | None = None) -> None:
        """Record a result read that reaches the model: only reads during a live
        cell count (a detached reader between turns must keep the notice — it is
        the idle session's only wake-up), and an awaiting reader must be one the
        live cell waits for."""
        if not self._done.is_set():
            return
        owner = _live_cell_owner()
        if owner is None:
            return
        if awaiter is not None and not _creating_cell_waits_for(owner, awaiter):
            return
        with self._callback_lock:
            if self._result_consumed:
                return
            self._result_consumed = True
            notice, self._consumed_notice = self._consumed_notice, None
        if notice is not None:
            notice()

    def _schedule_background_completion_notice(self) -> None:
        cell_finished = self._creating_cell_finished
        if cell_finished is None:
            return
        try:
            loop = asyncio.get_running_loop()
        except RuntimeError:
            return
        from . import repl

        activity = {"id": self._activity_id, "pid": self._pid, "active": True}
        # Publish synchronously before bash() returns and the creating cell can end.
        repl.emit({"application/vnd.prime-agent.bash-activity+json": activity})
        notice = self._notify_background_completion(cell_finished, activity)
        try:
            task = loop.create_task(notice)
        except BaseException:
            self.kill(signal.SIGKILL if _IS_POSIX else signal.SIGTERM)
            notice.close()
            repl.emit({"application/vnd.prime-agent.bash-activity+json": {**activity, "active": False}})
            raise
        task.add_done_callback(_consume_notice_task)

    async def _notify_background_completion(
        self, cell_finished: asyncio.Event, activity: dict[str, Any]
    ) -> None:
        from . import repl

        try:
            result = await self._wait()
            await self._wait_reaped()
            # The cell may do other work before awaiting this handle. Do not classify
            # it as detached until that whole cell has crossed its completion barrier.
            await cell_finished.wait()
            if self._awaited_by_creating_cell or self._result_consumed or not repl.is_active():
                return
            command = _capped(self.command)
            reply = await repl.host_request(
                {
                    "type": "bash.completed",
                    "pid": self._pid,
                    "command": command,
                    "exitCode": result.exit_code,
                }
            )
            if isinstance(reply, dict) and reply.get("status") == "ok":
                # Notice accepted by the host; later reads must ask it to withdraw.
                self._arm_consumed_notice(command)
            else:
                sys.stderr.write(
                    f"Background bash completion follow-up for pid {self._pid} was not accepted. "
                    "Inspect the saved handle with poll(), output(), or tail().\n"
                )
        except (OSError, RuntimeError):
            # Standalone runtimes have no host handler, and teardown can close
            # the bridge while a process is finishing. Shell results stay usable.
            return
        finally:
            # Reap and deliver (or report rejection) before releasing kernel residency.
            repl.emit({"application/vnd.prime-agent.bash-activity+json": {**activity, "active": False}})

    def _arm_consumed_notice(self, command: str) -> None:
        # Armed only post-acceptance: the withdrawal can never overtake its notice.
        dispatch = functools.partial(self._notify_result_consumed, command)

        with self._callback_lock:
            if not self._result_consumed:
                self._consumed_notice = dispatch
                return
        dispatch()

    def _notify_result_consumed(self, command: str) -> None:
        """Ship the withdrawal inside the read, ahead of the cell's done event.

        The host delivers a queued notice at the reading cell's turn boundary,
        which begins when that cell's done event is processed: a withdrawal
        frame that leaves the kernel after done arrives too late, and the stale
        notice wakes the model anyway. Reads happen inside a live cell, so
        writing the frame right here puts it ahead of done on the wire, where
        the host must withdraw before it can dispatch. The reply never matters
        (unknown reply ids are dropped), so the request is fire-and-forget:
        no future to await, no event-loop hop that could run after the cell.
        """
        from . import repl

        if not repl.is_active():
            return
        repl._send(
            {
                "event": "host_request",
                "id": uuid.uuid4().hex,
                "data": {"type": "bash.consumed", "pid": self._pid, "command": command},
            }
        )

    async def _wait_reaped(self) -> None:
        loop = asyncio.get_running_loop()
        future: asyncio.Future[None] = loop.create_future()

        def wake() -> None:
            try:
                loop.call_soon_threadsafe(lambda: future.done() or future.set_result(None))
            except RuntimeError:
                pass

        with self._callback_lock:
            if self._reaped:
                return
            self._reap_callback = wake
        try:
            await future
        finally:
            with self._callback_lock:
                if self._reap_callback is wake:
                    self._reap_callback = None

    async def _wait(self) -> BashResult:
        # Asyncio-native wakeup: no executor thread is parked for the command's
        # duration, so many concurrent awaits cannot exhaust the default pool.
        loop = asyncio.get_running_loop()
        fut: asyncio.Future[None] = loop.create_future()

        def _wake() -> None:
            try:
                loop.call_soon_threadsafe(lambda: fut.done() or fut.set_result(None))
            except RuntimeError:
                pass  # awaiting loop already closed

        self._add_done_callback(_wake)
        await fut
        assert self._result is not None
        return self._result

    async def _wait_owned(self) -> BashResult:
        # One-shot `await bash(cmd)` owns the process: a cancelled await (e.g.
        # a kernel interrupt) must not leave the command running. TERM, bounded
        # grace, group KILL, then a bounded confirmed-exit wait before the
        # CancelledError propagates, so no side effect can land after it.
        try:
            return await self._wait()
        except asyncio.CancelledError:
            # Signal synchronously first: even if the cleanup awaits below are
            # re-cancelled, TERM is already delivered and the escalation timer
            # armed. The confirm wait runs as a shielded task so repeated
            # cancels of this task cannot skip it (they re-raise into awaits
            # inside this except block); the loop re-awaits until it finishes
            # (the confirm coroutine itself is bounded).
            self.kill(grace=_CANCEL_TERM_GRACE)
            confirm = asyncio.ensure_future(self._confirm_group_exit())
            while not confirm.done():
                try:
                    await asyncio.shield(confirm)
                except asyncio.CancelledError:
                    continue
            raise

    async def _confirm_group_exit(self) -> None:
        if not await self._await_group_death(_CANCEL_TERM_GRACE):
            if _IS_POSIX:
                _signal_group(self._pid, signal.SIGKILL)
            else:
                # kill() holds the escalation lock; to_thread keeps the loop free.
                await asyncio.to_thread(self.kill)
            await self._await_group_death(_CANCEL_KILL_WAIT)

    def _group_alive(self) -> bool:
        if not _IS_POSIX:
            job = self._job  # snapshot: _watch may clear it concurrently
            if job is not None:
                # Job accounting sees detached descendants a dead leader hides.
                empty = _winjob.is_empty(job)
                if empty is not None:
                    return not empty
            return self._proc.poll() is None
        try:
            os.killpg(self._pid, 0)
        except ProcessLookupError:
            return False
        except PermissionError:
            pass
        return True

    async def _await_group_death(self, timeout: float) -> bool:
        deadline = time.monotonic() + timeout
        while self._group_alive():
            if time.monotonic() >= deadline:
                return False
            await asyncio.sleep(0.02)
        return True

    def _abort_spawn(self) -> None:
        # Enrollment or containment failed before the gate opened (POSIX) or
        # while the child is still suspended, before resume (Windows): kill
        # the child and unwind the handle before threads start.
        if _IS_POSIX:
            for fd in (self._status_read, self._wake_read, self._wake_write):
                if fd >= 0:
                    try:
                        os.close(fd)
                    except OSError:
                        pass
            self._status_read = self._wake_read = self._wake_write = -1
            delivered = _signal_group(self._pid, signal.SIGKILL)
        else:
            with self._kill_lock:
                delivered = False
                if self._job is not None:
                    delivered = _winjob.terminate(self._job)
                    job, self._job = self._job, None
                    _winjob.close(job)
                if not delivered:
                    # Pre-resume abort: the never-run leader has no descendants, so a
                    # delivered kill retires the journal record.
                    try:
                        self._proc.kill()
                        delivered = True
                    except OSError:
                        pass
        if self._proc.stdout is not None:
            self._proc.stdout.close()
        # The blocking wait stays outside the lock: hProcess is still open, so a
        # concurrent raw-pid fallback stays pinned to the right process.
        try:
            self._proc.wait(timeout=5)
        except (OSError, subprocess.SubprocessError):
            pass
        with self._kill_lock:
            self._reaped = True
            if not _IS_POSIX:
                # Reaped commits before close: later lock holders skip raw-pid fallbacks.
                cast("_winjob.JobProcess", self._proc).close()
        with _live_lock:
            _live_handles.discard(self)
            _activity_handles.pop(self._activity_id, None)
        if delivered:
            _record_journal(self._pid, active=False)

    def __await__(self) -> Generator[Any, None, BashResult | BashSnapshot]:
        # A handle awaited before any other API use is a one-shot command tied
        # to the await (kill-on-cancel); touching the handle API first marks it
        # as a deliberate background handle whose awaits only wait. Both paths
        # wait at most the yield window, then degrade to this live handle.
        try:
            current_task = asyncio.current_task()
        except RuntimeError:
            current_task = None
        creating_cell_waited = _creating_cell_waits_for(self._creating_cell_task, current_task)
        bound = _YIELD_AFTER_SECONDS if _completion_notices_wired else None
        owned = not self._released
        wait = self._wait_owned() if owned else self._wait()
        self._released = True
        completed = False
        degraded = False
        try:
            result = yield from _bounded_wait(wait, bound).__await__()
            if result is None:
                degraded = True
            else:
                completed = True
        finally:
            # A degraded await never completed: the [bash-done] notice must
            # still fire, so it counts as neither awaited nor consumed.
            if (
                not degraded
                and (completed or owned)
                and (
                    creating_cell_waited
                    or _creating_cell_waits_for(self._creating_cell_task, current_task)
                )
            ):
                self._awaited_by_creating_cell = True
            if completed:
                self._note_result_consumed(current_task)
        if degraded:
            _note_degrade(self, cast("float", bound))
            return self._degrade_snapshot()
        return cast("BashResult", result)

    def _degrade_snapshot(self) -> BashSnapshot:
        """Read the internal buffer directly: the public readers count as a
        result read, which would withdraw the [bash-done] notice the degrade
        must keep alive."""
        return BashSnapshot(
            output=self._buffer.text(),
            exit_code=None,
            running=True,
            duration=time.monotonic() - self._started,
            handle=self,
        )

    def __reduce__(self) -> NoReturn:
        # Reviving a handle would resurrect a stale pid and raw fd numbers: dill
        # restores the pickled pipe by reopening its fd number in the new kernel
        # (and closing it), so a snapshot must never persist a live handle.
        raise TypeError("cannot pickle 'BashHandle' object: live process handle")

    def __repr__(self) -> str:
        state = f"exit_code={self._result.exit_code}" if self._result else "running"
        return f"<BashHandle pid={self._pid} {state} command={self.command!r}>"


class _OutputFile:
    """Bounded view of a persistent shell's output file: first _HEAD_CAP plus last _TAIL_CAP bytes.

    keep() holds the final text in memory, so the file can be removed.
    """

    def __init__(self, path: str) -> None:
        self._path = path
        self._kept: str | None = None

    def keep(self) -> None:
        self._kept = self.text()

    def text(self) -> str:
        if self._kept is not None:
            return self._kept
        try:
            f = open(self._path, "rb")
        except FileNotFoundError:
            return ""
        with f:
            size = os.fstat(f.fileno()).st_size
            if size <= _HEAD_CAP + _TAIL_CAP:
                return f.read(size).decode("utf-8", errors="replace")
            head = f.read(_HEAD_CAP)
            f.seek(size - _TAIL_CAP)
            tail = f.read(_TAIL_CAP)
        marker = f"\n... [{size - _HEAD_CAP - _TAIL_CAP} bytes dropped] ...\n"
        return head.decode("utf-8", errors="replace") + marker + tail.decode("utf-8", errors="replace")


class PersistentBashHandle(BashHandle):
    """bash(..., persistent=True); see bash() for its lifecycle.

    Its record (assigned to the session), output, and exit status are files in
    the agent dir's persistent-shells home instead of an orphan journal entry.
    Awaits never own it: cancelling an await leaves it running. Finished
    output is kept in memory. Files remain recoverable on read errors or when
    a leaderless group cannot be verified because no watcher saw its leader
    exit; such a group is never signalled using only its old numeric
    process-group id.
    """

    def __init__(
        self,
        command: str,
        shell_id: str,
        pid: int,
        start_id: str,
        started_at: str,
        home: str,
        proc: subprocess.Popen[bytes] | None,
        running: bool = True,
    ) -> None:
        self.command = command
        self._activity_id = shell_id
        completion_context = _current_cell_completion_context()
        self._creating_cell_finished = completion_context[0] if completion_context else None
        self._creating_cell_task = completion_context[1] if completion_context else None
        self._awaited_by_creating_cell = False
        self._home = home
        self._buffer = _OutputFile(_persistent_file(home, shell_id, "out"))  # type: ignore[assignment]
        self._rc_path = _persistent_file(home, shell_id, "rc")
        self._done = threading.Event()
        self._result: BashResult | None = None
        self._completion_error: OSError | ValueError | None = None
        self._callbacks: list[Callable[[], None]] = []
        self._reap_callback: Callable[[], None] | None = None
        self._result_consumed = False
        self._consumed_notice: Callable[[], None] | None = None
        self._callback_lock = threading.Lock()
        self._reaped = False
        self._kill_lock = threading.Lock()
        self._started_at = started_at
        self._started = time.monotonic() - max(
            0.0, (datetime.now(timezone.utc) - datetime.fromisoformat(started_at)).total_seconds()
        )
        self._pid = pid
        self._start_id = start_id
        self._proc = proc  # type: ignore[assignment]
        self._released = True
        with _live_lock:
            _activity_handles[shell_id] = self
        threading.Thread(target=self._watch, args=(running,), daemon=True).start()
        self._schedule_background_completion_notice()

    def kill(self, sig: int = signal.SIGTERM, grace: float = 5.0) -> None:
        # Even a fresh Popen may have been reaped by the watcher before it
        # commits _reaped. Every persistent signal must check its identity.
        with self._kill_lock:
            if self._reaped or _shell_identity(self._pid, self._start_id) is not True:
                return
            super().kill(sig, grace)

    def _force_kill(self) -> None:
        with self._kill_lock:
            if not self._reaped:
                _reap_persistent_group(self._pid, self._start_id)

    def _watch(self, running: bool) -> None:
        # running=False: the shell finished while no kernel ran; its pid may
        # since name another process, so it is never polled or signalled.
        exit_code = -1
        if self._proc is not None:
            exit_code = self._proc.wait()
        elif running:
            # Not our child, so nothing to wait() on: poll the rc file and the
            # pid identity (completion lags by up to _PERSISTENT_POLL seconds).
            while not os.path.exists(self._rc_path) and _shell_identity(self._pid, self._start_id) is not False:
                time.sleep(_PERSISTENT_POLL)
        try:
            with open(self._rc_path) as f:
                exit_code = int(f.read())
        except FileNotFoundError:
            pass  # killed before the wrapper recorded a status
        except (OSError, ValueError) as error:
            self._completion_error = error
        # A dead leader's group can still contain the shell's children. A live
        # recycled pid instead names a stranger's group and must not be signalled.
        with self._kill_lock:
            reaped = _reap_persistent_group(
                self._pid, self._start_id, leader_exit_witnessed=self._proc is not None or running
            )
            self._reaped = True
        try:
            cast("_OutputFile", self._buffer).keep()
        except OSError as error:
            self._completion_error = error
        if self._completion_error is None and reaped:
            _remove_shell_files(self._home, self._activity_id)
        # Failed I/O must settle waiters too, without losing the recoverable files.
        self._finalize(exit_code, "" if self._completion_error is not None else None)
        with self._callback_lock:
            callback, self._reap_callback = self._reap_callback, None
        if callback is not None:
            callback()
        with _live_lock:
            _activity_order.append(self._activity_id)
            while len(_activity_order) > _ACTIVITY_HISTORY_CAP:
                _activity_handles.pop(_activity_order.popleft(), None)

    async def _wait(self) -> BashResult:
        result = await super()._wait()
        if self._completion_error is not None:
            raise self._completion_error
        return result

    def poll(self) -> BashResult | None:
        result = super().poll()
        if result is not None and self._completion_error is not None:
            raise self._completion_error
        return result

    def _schedule_background_completion_notice(self) -> None:
        # No bash-activity residency hold: the shell survives kernel release.
        try:
            loop = asyncio.get_running_loop()
        except RuntimeError:
            return
        loop.create_task(self._notify_completion()).add_done_callback(_consume_notice_task)

    async def _notify_completion(self) -> None:
        from . import repl

        try:
            result = await self._wait()
            if self._creating_cell_finished is not None:
                await self._creating_cell_finished.wait()
            if self._awaited_by_creating_cell or self._result_consumed or not repl.is_active():
                return
            command = _capped(self.command)
            reply = await repl.host_request(
                {"type": "bash.completed", "pid": self._pid, "command": command, "exitCode": result.exit_code}
            )
            if isinstance(reply, dict) and reply.get("status") == "ok":
                self._arm_consumed_notice(command)
        except (OSError, RuntimeError):
            return

    def __repr__(self) -> str:
        state = f"exit_code={self._result.exit_code}" if self._result else "running"
        return f"<BashHandle persistent pid={self._pid} {state} command={self.command!r}>"


def bash(command: str, persistent: bool = False) -> BashHandle:
    """Start a shell command immediately; await the handle for the result.

    `await bash(cmd)` is a one-shot: cancelling the await (e.g. an interrupt)
    kills the command's process group. In sessions whose host wires completion
    notices (the kernel bootstrap turns the bound on), an await that is still
    running after 1 second instead DEGRADES: it returns a BashSnapshot
    (r.running True, r.output the output so far, r.handle the live handle)
    while the command keeps running, and its [bash-done] notification arrives
    on completion. In sessions without completion notices every await stays
    unbounded. `h = bash(cmd)` used as a background handle (any
    .pid/.running/.output()/.tail()/.poll()/.kill() access before the first
    await) survives cancellation; awaiting it only waits. Leak
    containment is per-platform: process groups plus the orphan journal on
    POSIX; a kill-on-close job object on Windows entered while the child is
    still suspended, so no descendant can escape it and kill()/crash cleanup
    are unconditional -- bash() raises if containment cannot be established.
    Output written after the completion fence (e.g. by an EXIT trap or a
    background job) is not in BashResult.output but stays visible via
    handle.output()/tail().

    persistent=True (POSIX, saved sessions only; use only when really
    required, e.g. a server or long job that must outlive a restart): the
    shell survives kernel, worker, and daemon restarts and its session's
    delete or archive (a deleted session's shells keep running as orphans);
    only its own exit or an explicit kill() ends it. Its output and exit
    status live in files under the agent dir, and awaits never own it: a
    bounded await degrades as for any handle and the shell runs on. After a
    restart, get the handles back with `from rlm import persistent_shells;
    persistent_shells()`; a shell that finished while no
    kernel ran is listed once, finished. Completion of a re-attached shell is
    polled, so its result and completion notice lag by up to a second; its
    exit_code is -1 when it was killed before recording a status.
    """
    if not isinstance(command, str) or not command:
        raise TypeError("command must be a non-empty str")
    if persistent:
        handle: BashHandle = _spawn_persistent(command)
    else:
        _install_shutdown_hook()
        handle = BashHandle(command)
    from . import repl

    repl.emit(
        {
            _BASH_COMMAND_MIME: {
                "command": _capped(command),
                "lines": sum(1 for line in command.splitlines() if line.strip()),
            }
        }
    )
    return handle


def _shell() -> str:
    # Read per call so env changes made in the REPL apply to later commands.
    override = os.environ.get("PRIME_AGENT_BASH_SHELL")
    if override:
        if not os.path.isabs(override):
            raise ValueError("PRIME_AGENT_BASH_SHELL must be an absolute path")
        return override
    if not _IS_POSIX:
        # Never consult PATH on Windows: a repo-controlled PATH could supply
        # the shell. The host injects PRIME_AGENT_BASH_SHELL when one exists.
        raise RuntimeError(
            "bash() needs PRIME_AGENT_BASH_SHELL set to the absolute path of a "
            "POSIX shell on Windows (e.g. install Git Bash in its default "
            "location so the host injects it)"
        )
    # PATH fallback only serves bare/standalone POSIX runtime use: the host
    # always injects PRIME_AGENT_BASH_SHELL (an absolute path) when a shell exists.
    shell = shutil.which("bash")
    return shell or "/bin/sh"


def _with_prefix(command: str) -> str:
    prefix = os.environ.get("PRIME_AGENT_BASH_COMMAND_PREFIX")
    return f"{prefix}\n{command}" if prefix else command


def _fence_printf() -> str:
    # `\command -p printf` defeats alias expansion but not a user-defined shell
    # function named `command`, which would swallow both fence frames and leave
    # the await hanging until the shell dies (wedged behind background jobs). A
    # slash-qualified command name bypasses function and alias lookup for
    # ordinary command names, so resolve printf on the system default utility PATH.
    path = shutil.which("printf", path=os.confstr("CS_PATH") or os.defpath)
    if path and "'" not in path:
        return f"'{path}'"
    return "\\command -p printf"


def _status_script(command: str, completion_a: str, completion_b: str) -> str:
    # Closed control fds preserve background behavior; supported shells atomically write the frame.
    emit = _fence_printf()
    return (
        f"exec {_STATUS_FD}>&0 {_OUTPUT_FD}>&1 0</dev/null\n"
        f"read -r _prime_agent_gate <&{_STATUS_FD} || exit 127\n"
        "{\n"
        f"{command}\n"
        f"}} {_OUTPUT_FD}>&- {_STATUS_FD}>&-\n"
        "__prime_status=$?\n"
        "\\set +x\n"
        f"{emit} '\\036prime-agent-complete:%s%s\\037' "
        f"'{completion_a}' '{completion_b}' >&{_OUTPUT_FD} || exit \"$__prime_status\"\n"
        f"{emit} '%s\\n' \"$__prime_status\" >&{_STATUS_FD}\n"
        f"exec {_OUTPUT_FD}>&- {_STATUS_FD}>&-\n"
        "wait\n"
        'exit "$__prime_status"\n'
    )


def _child_env() -> dict[str, str]:
    """Environment for kernel-spawned shell commands.

    Same non-interactive guard as the coding-agent shell tool
    (packages/coding-agent/src/utils/shell.ts): agent shell commands have no
    usable stdin, so interactive prompts (git commit without -m opening
    $EDITOR, credential asks, pagers) can only hang. Fail fast or no-op
    instead. Deliberately overrides inherited terminal settings; a
    per-command inline assignment (`GIT_EDITOR=vim git commit`) still wins
    because it replaces the exported value for that command.
    """
    return {
        **os.environ,
        "NO_COLOR": "1",
        "TERM": "dumb",
        "CLICOLOR": "0",
        "FORCE_COLOR": "0",
        "GIT_EDITOR": "true",
        "GIT_SEQUENCE_EDITOR": "true",
        "GIT_TERMINAL_PROMPTS": "0",
        "GIT_ASKPASS": "true",
        "SSH_ASKPASS_REQUIRE": "never",
        "EDITOR": "true",
        "VISUAL": "true",
        "PAGER": "cat",
        "GIT_PAGER": "cat",
        "DEBIAN_FRONTEND": "noninteractive",
    }


def _signal_group(pid: int, sig: int) -> bool:
    """True when the signal was delivered or the group is already gone."""
    try:
        os.killpg(pid, sig)
    except ProcessLookupError:
        return True  # already dead: safe to mark the journal record inactive
    except OSError:
        return False  # not delivered: the record must stay active for the host reaper
    return True


def _system32(*parts: str) -> str:
    # Absolute paths for Windows helper binaries: PATH (and CWD on Windows
    # CPython) lookup could resolve a planted taskkill.exe/powershell.exe.
    root = os.environ.get("SystemRoot", r"C:\Windows")
    return os.path.join(root, "System32", *parts)


def _helper_env() -> dict[str, str]:
    return {**os.environ, "NoDefaultCurrentDirectoryInExePath": "1"}


def _persistent_home() -> str:
    return os.path.join(os.environ["PRIME_AGENT_CODING_AGENT_DIR"], _PERSISTENT_DIR)


def _persistent_file(home: str, shell_id: str, kind: str) -> str:
    return os.path.join(home, f"{shell_id}.{kind}")


def _remove_shell_files(home: str, shell_id: str) -> None:
    # The record goes last: until then, the next boot still finds and removes the rest.
    for kind in ("rc", "out", "json"):
        try:
            os.remove(_persistent_file(home, shell_id, kind))
        except OSError:
            pass


def _session_records(home: str, session_id: str) -> list[dict[str, Any]]:
    """The records assigned to session_id, oldest first."""
    try:
        names = os.listdir(home)
    except FileNotFoundError:
        return []
    records = []
    for name in names:
        if not name.endswith(".json"):
            continue
        try:
            with open(os.path.join(home, name)) as f:
                record = json.load(f)
        except FileNotFoundError:
            continue  # its kernel removed the finished shell meanwhile
        if record["sessionId"] == session_id:
            records.append(record)
    return sorted(records, key=lambda record: record["startedAt"])


def _pid_alive(pid: int) -> bool:
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        pass
    # kill(0) also accepts zombies. Match the host's liveness policy so a
    # reattached shell can finish without waiting for another process to reap it.
    try:
        if sys.platform.startswith("linux"):
            with open(f"/proc/{pid}/stat") as stat_file:
                stat = stat_file.read()
            return stat[stat.rindex(")") + 2:].split()[0] != "Z"
        if sys.platform == "darwin":
            state = subprocess.run(
                ["/bin/ps", "-p", str(pid), "-o", "stat="],
                capture_output=True, text=True, timeout=5,
                env={**os.environ, "LC_ALL": "C", "LANG": "C"},
            )
            return state.returncode != 0 or not state.stdout.lstrip().startswith("Z")
    except (OSError, ValueError, IndexError, subprocess.SubprocessError):
        pass  # unknown state stays alive; never claim a recycled group
    return True


def _shell_identity(pid: int, start_id: str) -> bool | None:
    """True while pid still names the recorded shell, False once it is provably
    gone (dead, or recycled under a new start identity), None when unprovable."""
    if not _pid_alive(pid):
        return False
    current = _process_start_id(pid)
    return None if current is None else current == start_id


def _spawn_persistent(command: str) -> PersistentBashHandle:
    if not _IS_POSIX:
        raise RuntimeError("bash(persistent=True) is only supported on POSIX")
    session_id = os.environ.get("RLM_SESSION_ID")
    if not session_id:
        raise RuntimeError(
            "bash(persistent=True) needs a saved session (RLM_SESSION_ID is unset): "
            "the shell is assigned to the session that started it"
        )
    home = _persistent_home()
    shell_id = secrets.token_hex(16)
    os.makedirs(home, exist_ok=True)
    shell = _shell()
    script = f'{{\n{_with_prefix(command)}\n}}\n__prime_status=$?\nwait\nexit "$__prime_status"\n'
    with open(_persistent_file(home, shell_id, "out"), "wb") as out:
        proc = subprocess.Popen(
            [shell, "-c", _PERSISTENT_WRAPPER, "prime-agent-persistent", shell, script,
             _persistent_file(home, shell_id, "rc")],
            cwd=os.getcwd(),
            env=_child_env(),
            stdin=subprocess.PIPE,
            stdout=out,
            stderr=subprocess.STDOUT,
            start_new_session=True,
        )
    gate = cast("Any", proc.stdin)
    try:
        # The wrapper runs nothing until the shell is registered: a failure
        # (or a kernel death) before the gate byte closes the pipe instead.
        start_id = _process_start_id(proc.pid)
        if start_id is None:
            raise RuntimeError("bash(persistent=True): the shell's start identity is unreadable")
        started_at = datetime.now(timezone.utc).isoformat()
        record = {
            "id": shell_id, "pid": proc.pid, "startId": start_id, "command": command,
            "startedAt": started_at, "sessionId": session_id,
        }
        path = _persistent_file(home, shell_id, "json")
        with open(f"{path}.tmp", "w") as f:
            json.dump(record, f)
        os.replace(f"{path}.tmp", path)
        gate.write(b"\n")
    finally:
        gate.close()
    return PersistentBashHandle(command, shell_id, proc.pid, start_id, started_at, home, proc)


def persistent_shells() -> list[BashHandle]:
    """This kernel's persistent bash() handles, including the ones re-attached at boot.

    After a kernel restart (or a worker/daemon restart), call this to get the
    session's persistent shells back. A shell that finished while no kernel ran
    is listed once, finished, in the first kernel after it ended.
    """
    with _live_lock:
        return [h for h in _activity_handles.values() if isinstance(h, PersistentBashHandle)]


def _rehydrate_persistent_shells() -> None:
    """Kernel boot: re-attach this session's live shells, surface the ones that
    finished while no kernel ran, and remove its dead ones. Records with an
    unprovable identity and other sessions' records stay untouched."""
    session_id = os.environ.get("RLM_SESSION_ID")
    if not session_id or not _IS_POSIX:
        return
    home = _persistent_home()
    for record in _session_records(home, session_id):
        identity = _shell_identity(record["pid"], record["startId"])
        if identity is None:
            continue
        if identity or os.path.exists(_persistent_file(home, record["id"], "rc")):
            PersistentBashHandle(
                record["command"], record["id"], record["pid"], record["startId"], record["startedAt"],
                home, None, identity,
            )
        elif _reap_persistent_group(record["pid"], record["startId"]):
            _remove_shell_files(home, record["id"])


def _reap_persistent_group(pid: int, start_id: str, leader_exit_witnessed: bool = False) -> bool:
    """Reap stragglers without ever signalling a live recycled or unverified pid."""
    # Existence is distinct from liveness: a recycled zombie can still own an
    # unrelated group. It must pass the same start-identity check as a live pid.
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        if leader_exit_witnessed:
            return _signal_group(pid, signal.SIGKILL)
        # A durable record can outlive its original group. An extant group
        # without the recorded leader may be a reused PGID: retain it, do not kill.
        try:
            os.killpg(pid, 0)
        except ProcessLookupError:
            return True
        except OSError:
            return False
        return False
    except PermissionError:
        pass
    current = _process_start_id(pid)
    if current == start_id:
        return _signal_group(pid, signal.SIGKILL)
    return current is not None


def _taskkill_tree(pid: int) -> bool:
    # Windows has no process groups to signal; taskkill /T kills the whole tree.
    try:
        return (
            subprocess.run(
                [_system32("taskkill.exe"), "/PID", str(pid), "/T", "/F"],
                capture_output=True,
                timeout=10,
                env=_helper_env(),
            ).returncode
            == 0
        )
    except (OSError, subprocess.SubprocessError):
        return False


def _process_start_id(pid: int) -> str | None:
    if os.name == "nt":
        # Mirrors getWindowsProcessStartId in session-lease.ts byte-for-byte so
        # the host's identity comparison matches the journaled string.
        try:
            out = subprocess.run(
                [
                    _system32("WindowsPowerShell", "v1.0", "powershell.exe"),
                    "-NoLogo",
                    "-NoProfile",
                    "-NonInteractive",
                    "-Command",
                    f"([System.Diagnostics.Process]::GetProcessById({pid})).StartTime.ToUniversalTime().Ticks",
                ],
                capture_output=True,
                text=True,
                timeout=5,
                env=_helper_env(),
            ).stdout.strip()
            return f"win:{out}" if out.isdigit() else None
        except (OSError, subprocess.SubprocessError):
            return None
    try:
        with open(f"/proc/{pid}/stat", "r") as f:
            stat = f.read()
        fields = stat[stat.rindex(")") + 2 :].split(" ")
        if len(fields) > 19 and fields[19]:
            return f"proc:{fields[19]}"
    except (OSError, ValueError):
        pass
    try:
        # macOS has no /proc; /bin/ps is always present there, so use the
        # absolute path (bare `ps` stays only as the exotic-POSIX last resort).
        ps = "/bin/ps" if sys.platform == "darwin" else "ps"
        # `lstart` renders in the subprocess timezone and locale, so pin both
        # for a durable identity (TS getPsProcessStartId; the Rust host reads
        # the same pinned values - an unpinned match would drift on non-UTC
        # hosts and the identity comparison would never agree).
        out = subprocess.run(
            [ps, "-p", str(pid), "-o", "lstart="],
            capture_output=True,
            text=True,
            timeout=5,
            env={**os.environ, "LC_ALL": "C", "LC_TIME": "C", "LANG": "C", "TZ": "UTC"},
        ).stdout.strip()
        return f"ps:{out}" if out else None
    except (OSError, subprocess.SubprocessError):
        return None


def _record_journal(pid: int, active: bool) -> bool:
    # Best-effort per the TS (core/orphan-process-journal.ts): journaling
    # failures never fail the spawn - a misconfigured owner pid is the only
    # hard False. Identity-free records (no processStartId) are valid and
    # still safely reaped on POSIX (the group-scoped kill).
    path = os.environ.get("PRIME_AGENT_INTERNAL_ORPHAN_PROCESS_JOURNAL")
    owner = os.environ.get("PRIME_AGENT_KERNEL_OWNER_PID")
    if not path or not owner:
        return True
    try:
        owner_pid = int(owner)
    except ValueError:
        return False
    start_id = _process_start_id(pid) if active else None
    record: dict[str, Any] = {
        "version": 1,
        "pid": pid,
        "ownerPid": owner_pid,
        # The host reaps bash children per kernel pid when it kills or loses this kernel.
        "kernelPid": os.getpid(),
        **({"processStartId": start_id} if start_id else {}),
        "active": active,
        "recordedAt": datetime.now(timezone.utc).isoformat(),
    }
    data = (json.dumps(record) + "\n").encode()
    # TS parity (core/orphan-process-journal.ts): process tracking must not
    # make a successfully spawned command fail - a journal that cannot be
    # written (a vanished dir, a full disk) means the command runs untracked,
    # never that the spawn dies. The short-write guard still drops truncated
    # lines (the host discards them) but returns True: the command is alive.
    try:
        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
        try:
            view = memoryview(data)
            while view:
                written = os.write(fd, view)
                if written <= 0:
                    break
                view = view[written:]
            os.fsync(fd)
        finally:
            os.close(fd)
    except OSError:
        pass
    return True


def _kill_live_handles() -> None:
    with _live_lock:
        handles = list(_live_handles)
    for handle in handles:
        if _IS_POSIX:
            delivered = _signal_group(handle._pid, signal.SIGKILL)
        else:
            with handle._kill_lock:
                if handle._reaped:
                    continue
                delivered = handle._job is not None and _winjob.terminate(handle._job)
                if not delivered:
                    delivered = _taskkill_tree(handle._pid)
                if not delivered:
                    # Leader-only fallback cannot prove the tree died: never
                    # justifies an inactive record.
                    try:
                        handle._proc.kill()
                    except OSError:
                        pass
        if delivered:
            _record_journal(handle._pid, active=False)


def _install_shutdown_hook() -> None:
    global _hook_installed
    with _hook_lock:
        if _hook_installed:
            return
        _hook_installed = True
    atexit.register(_kill_live_handles)


def activity_request(action: str, activity_id: str | None = None, lines: int = 50) -> dict[str, Any]:
    """Inspect/stop only handles created by this kernel; called off the cell queue."""
    with _live_lock:
        if action == "list":
            handles = list(_activity_handles.items())
        else:
            handle = _activity_handles.get(activity_id or "")
            if handle is None:
                raise KeyError("Unknown kernel bash activity")
    if action == "list":
        rows = [
            {
                "id": key,
                "command": handle.command[:512],
                "pid": handle._pid,
                "startedAt": handle._started_at,
                "durationMs": int((handle._result.duration if handle._result else time.monotonic() - handle._started) * 1000),
                "status": "finished" if handle._reaped else "running",
                "exitCode": handle._result.exit_code if handle._result else None,
                "persistent": isinstance(handle, PersistentBashHandle),
            }
            for key, handle in handles
        ]
        # The serialized list frame stays under the same 16 KiB cap as the
        # tail: long commands are truncated per row first, then rows drop
        # until the response fits - finished rows drop before running ones,
        # so live processes never fall off the activity list while they
        # are still the ones the user can act on.
        while len(json.dumps({"activities": rows})) > 16_384 and len(rows) > 1:
            victim = next(
                (index for index, row in enumerate(rows) if row["status"] != "running"),
                0,
            )
            rows.pop(victim)
        return {"activities": rows}
    if action == "tail":
        if isinstance(lines, bool) or not isinstance(lines, int) or not 1 <= lines <= 200:
            raise ValueError("lines must be an integer between 1 and 200")
        # Each retained buffer is bounded, and the response has a further byte cap.
        tail = "\n".join(handle._buffer.text().splitlines()[-lines:])
        payload = tail.encode("utf-8")[-16_384:].decode("utf-8", errors="replace")
        # json escaping can expand one character to six bytes, so a
        # byte-slice of the decoded text cannot bound the serialized size
        # alone. Trim the wrapped payload from the oldest end; the repl
        # handler enforces the same cap on the complete response frame.
        while len(json.dumps({"tail": payload})) > 16_384:
            excess = len(json.dumps({"tail": payload})) - 16_384
            keep = max(1, len(payload) - excess // 6 - 1)
            payload = payload[-keep:]
        return {"activityId": activity_id, "tail": payload}
    if action == "kill":
        if handle._reaped:
            return {"activityId": activity_id, "killed": False}
        handle.kill()
        return {"activityId": activity_id, "killed": True}
    raise ValueError("Unknown kernel bash action")