ccx-native 0.0.1 → 0.1.0

package/ccx/claude/host/hooks.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+import json
+import os
+import pathlib
+import socket
+import sys
+import time
+from ccx.constants import (
+    BOUNDARY_SEND_ACK_S,
+    HOOK_RELAY_RETRY_POLL_S,
+    HOOK_RELAY_RETRY_S,
+    PERMISSION_HOOK_TIMEOUT_S,
+    PERMISSION_POLL_INTERVAL_S,
+)
+from ccx.store.liveness import lifecycle_host_alive
+from ccx.store.paths import sock_path
+from ccx.store.records import (
+    read_record,
+)
+from ccx.claude.transcript import (
+    api_error_from_event,
+)
+from ccx.claude.host.subagents import _hook_subagent_id
+
+
+def _read_new_api_error(transcript_path: str | pathlib.Path, start_pos: int = 0) -> tuple[dict | None, int]:
+    """Scan newly-appended JSONL transcript bytes for a terminal API error.
+
+    Returns ``(summary, new_pos)``. If the file is truncated or recreated, the
+    scan restarts at byte 0. A partial final line is left unread so the next poll
+    can parse it after Claude finishes writing.
+    """
+    path = pathlib.Path(transcript_path)
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return None, start_pos
+    pos = max(0, int(start_pos or 0))
+    if pos > size:
+        pos = 0
+    if pos == size:
+        return None, size
+    try:
+        with path.open("rb") as f:
+            f.seek(pos)
+            while True:
+                line_start = f.tell()
+                raw = f.readline()
+                if not raw:
+                    return None, f.tell()
+                try:
+                    evt = json.loads(raw.decode("utf-8"))
+                except (UnicodeDecodeError, ValueError):
+                    if not raw.endswith(b"\n"):
+                        return None, line_start
+                    continue
+                if isinstance(evt, dict) and evt.get("isSidechain") is True:
+                    continue  # a subagent's error is not the session's
+                api_error = api_error_from_event(evt)
+                if api_error:
+                    return api_error, f.tell()
+    except OSError:
+        return None, pos
+
+
+def _native_interrupt_row(
+    evt: dict, prompt_ids: set[str] | None = None, *, strict: bool = False,
+) -> bool:
+    """A native cancellation marker, not user/assistant text quoting its words.
+
+    Claude's plain interruption row carries interruptedMessageId. Its tool
+    variant is an error tool_result. Sidechains are never parent cancellation.
+    Where Claude supplies promptId, it must match the current turn's UPS IDs.
+    """
+    if (not isinstance(evt, dict) or evt.get("type") != "user"
+            or evt.get("isSidechain") is True):
+        return False
+    pid = evt.get("promptId")
+    if prompt_ids and pid is not None and pid not in prompt_ids:
+        return False
+    content = (evt.get("message") or {}).get("content")
+    markers = {"[Request interrupted by user]",
+               "[Request interrupted by user for tool use]"}
+    if isinstance(content, str):
+        return content in markers and (not strict or bool(evt.get("interruptedMessageId")))
+    if isinstance(content, list):
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if (block.get("type") == "tool_result" and block.get("is_error") is True
+                    and isinstance(block.get("content"), str)
+                    and block["content"] in markers):
+                return True
+            if (block.get("type") == "text" and block.get("text") in markers
+                    and evt.get("interruptedMessageId")):
+                return True
+    return False
+
+
+def _read_interrupt_marker(
+    transcript_path: str | pathlib.Path, start_pos: int = 0,
+    *, prompt_ids: set[str] | None = None, strict: bool = False,
+) -> tuple[bool, int]:
+    """Passively scan only complete, current parent JSONL rows for a marker.
+
+    An earlier interrupt, a quoted marker, a partial line, and a sidechain row
+    cannot confirm this turn. The scan offset is caller-owned and bounded by
+    the start of the current real turn; on truncated transcripts restart at 0.
+    """
+    path = pathlib.Path(transcript_path)
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return False, start_pos
+    pos = max(0, int(start_pos or 0))
+    if pos > size:
+        pos = 0
+    if pos == size:
+        return False, size
+    try:
+        with path.open("rb") as f:
+            f.seek(pos)
+            while True:
+                line_start = f.tell()
+                raw = f.readline()
+                if not raw:
+                    return False, f.tell()
+                if not raw.endswith(b"\n"):
+                    return False, line_start
+                if b"[Request interrupted by user" not in raw:
+                    continue
+                try:
+                    evt = json.loads(raw.decode("utf-8"))
+                except (UnicodeDecodeError, ValueError):
+                    continue
+                if _native_interrupt_row(evt, prompt_ids, strict=strict):
+                    return True, f.tell()
+    except OSError:
+        return False, pos
+
+
+def _permission_response(
+    decision: str,
+    tool_input: dict | None = None,
+    reason: str | None = None,
+    *,
+    updated_input: dict | None = None,
+    user_modified: bool = False,
+) -> dict:
+    behavior = "allow" if decision == "allow" else "deny"
+    default_reason = "ccx approved" if behavior == "allow" else "ccx rejected"
+    dec = {
+        "behavior": behavior,
+        "decisionReason": reason or default_reason,
+    }
+    if behavior == "allow":
+        dec["updatedInput"] = updated_input if updated_input is not None else (tool_input or {})
+        dec["userModified"] = user_modified
+    else:
+        # Claude surfaces a denied tool's message to the model from
+        # `decision.message`, not from `decisionReason`. Mirror the reason there
+        # so `ccx reject --reason` is visible in the interrupted turn.
+        dec["message"] = reason or default_reason
+    return {"hookSpecificOutput": {"hookEventName": "PermissionRequest", "decision": dec}}
+
+
+def _recv_json_line(sock: socket.socket, timeout: float) -> dict:
+    sock.settimeout(timeout)
+    buf = bytearray()
+    while True:
+        chunk = sock.recv(4096)
+        if not chunk:
+            return {"ok": False, "error": "no reply"}
+        buf.extend(chunk)
+        if b"\n" in buf:
+            line = bytes(buf).split(b"\n", 1)[0]
+            try:
+                return json.loads(line)
+            except ValueError:
+                return {"ok": False, "error": "bad reply"}
+
+
+def _relay_connect(short: str, *, timeout: float = 2.0,
+                   retry_s: float = 0.0) -> socket.socket:
+    """Connect to the host socket, retrying a busy host for up to ``retry_s``.
+
+    The host serves its socket from one select loop. While that loop is busy
+    the listen backlog fills, and a further ``connect`` then fails at once with
+    EAGAIN (or times out). That is a host that is alive but behind, not a
+    host that is gone, so it is retried within the budget. A missing socket or
+    a refused connection means no host at all and is raised immediately.
+    """
+    deadline = time.monotonic() + max(0.0, retry_s)
+    while True:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            s.connect(str(sock_path(short)))
+            return s
+        except (BlockingIOError, socket.timeout):
+            s.close()
+            if time.monotonic() >= deadline:
+                raise
+            time.sleep(HOOK_RELAY_RETRY_POLL_S)
+        except BaseException:
+            s.close()
+            raise
+
+
+def _host_rpc(short: str, msg: dict, timeout: float = 2.0, *,
+              connect_retry_s: float = 0.0) -> dict:
+    if msg.get("op") in ("permission-request", "elicitation-request",
+                         "permission-poll", "permission-timeout"):
+        # Unlike native hook-event frames, these require the host's existing
+        # same-connection full-owner handshake; do not exempt them server-side.
+        from ccx.rpc.rpc import _rpc
+        return _rpc(short, msg, timeout=timeout)
+    with _relay_connect(short, timeout=timeout, retry_s=connect_retry_s) as s:
+        s.sendall((json.dumps(msg) + "\n").encode())
+        return _recv_json_line(s, timeout)
+
+
+def hook_relay_retry_s(data) -> float:
+    """Connect budget for one hook's delivery to the host.
+
+    Parent hooks are lifecycle evidence (a lost Stop leaves the worker busy
+    forever), so they wait out a busy host. Subagent hooks only feed
+    attributed tool events and keep the single attempt."""
+    return 0.0 if _hook_subagent_id(data) is not None else HOOK_RELAY_RETRY_S
+
+
+def _relay_broker_permission(short: str, data: dict, *,
+                             register_op: str = "permission-request",
+                             gone: dict | None = None,
+                             timed_out: dict | None = None) -> dict | None:
+    """Register a no-skip permission request with the host and poll until a
+    decision arrives, the host dies, or the hook-timeout budget elapses.
+
+    Returns the decision dict ({"decision": "allow"|"deny", "reason": str}) or
+    None if the request could not even be registered (host unreachable).
+
+    Transient poll failures leave the request pending: the host may be busy
+    servicing the PTY. Polling ends only on a decision, a missing socket with
+    a dead host PID, or the hook-timeout deadline. The caller denies on timeout
+    so the blocked turn can proceed.
+
+    The Elicitation hook reuses the same poll loop with ``register_op=
+    "elicitation-request"`` and cancel-shaped ``gone``/``timed_out`` results."""
+    try:
+        reply = _host_rpc(short, {"op": register_op, "data": data}, timeout=2.0,
+                          connect_retry_s=HOOK_RELAY_RETRY_S)
+    except Exception:
+        return None
+    request_id = reply.get("request_id")
+    if not (reply.get("ok") and request_id):
+        return None
+    host_lifecycle = (read_record(short) or {}).get("lifecycle") or {}
+    deadline = time.time() + max(1.0, PERMISSION_HOOK_TIMEOUT_S - 1.0)
+    while time.time() < deadline:
+        time.sleep(PERMISSION_POLL_INTERVAL_S)
+        try:
+            poll = _host_rpc(short, {"op": "permission-poll", "request_id": request_id}, timeout=2.0)
+        except Exception:
+            poll = None
+        if poll and poll.get("ok"):
+            if poll.get("decision"):
+                return poll["decision"]
+            if poll.get("unknown"):
+                # A restarted host that never saw this request: nobody can
+                # decide it any more.
+                return gone or {"decision": "deny",
+                                "reason": "ccx: session host restarted before approval"}
+            continue  # host answered, still no decision — keep waiting
+        # Transient/garbled reply. Only give up if the host is genuinely gone;
+        # otherwise keep polling until the real deadline.
+        if not sock_path(short).exists() and not lifecycle_host_alive(host_lifecycle):
+            return gone or {"decision": "deny", "reason": "ccx: session ended before approval"}
+    # Hook-timeout: notify the host (it clears the prompt and stays usable) and
+    # auto-deny so Claude unblocks instead of falling back to an interactive
+    # prompt that would hang this head-less PTY forever.
+    try:
+        _host_rpc(short, {"op": "permission-timeout", "request_id": request_id}, timeout=2.0)
+    except Exception:
+        pass
+    return timed_out or {"decision": "deny", "reason": "ccx: no approval within timeout, auto-denied"}
+
+
+def _elicitation_response(action: str, content: dict | None = None) -> dict:
+    """Claude `Elicitation` hook output: answer the MCP server directly.
+
+    Returning an action suppresses Claude's own dialog, which would otherwise
+    block a head-less PTY forever. ``cancel`` is the safe default for every
+    failure: it means "dismissed", so the server records no decision on the
+    user's behalf (a ``decline`` is an explicit no that servers may persist)."""
+    out: dict = {"hookEventName": "Elicitation", "action": action}
+    if action == "accept" and content is not None:
+        out["content"] = content
+    return {"hookSpecificOutput": out}
+
+
+def _relay_elicitation(short: str, data: dict) -> dict:
+    """Broker one Elicitation hook through the host; always returns hook output."""
+    decision = _relay_broker_permission(
+        short, data,
+        register_op="elicitation-request",
+        gone={"action": "cancel", "reason": "ccx: session ended before a response"},
+        timed_out={"action": "cancel", "reason": "ccx: no response within timeout"},
+    )
+    if not decision:
+        return _elicitation_response("cancel")
+    action = decision.get("action")
+    if action not in ("accept", "decline", "cancel"):
+        action = "cancel"
+    return _elicitation_response(action, decision.get("content"))
+
+
+def cmd_hooks_relay(args):
+    """Read JSON hook payload from stdin, forward to the host socket as a hook-event op,
+    print the hook's response to stdout.
+
+    For most events: respond with "{}" (no-op continue).
+    For PermissionRequest on skip-permissions sessions: auto-allow ordinary tool
+    permissions with the original tool_input. AskUserQuestion is not a permission:
+    always broker it so the thread blocks for a real answer instead of silently
+    producing an empty/non-answer. For --no-skip-permissions sessions, never emit
+    an allow decision, even if an older frozen settings file still contains the hook."""
+    from ccx.constants import SELF_ENGINE_ENV, SELF_WORKER_ID_ENV
+    from ccx.claude.settings import HOOKS_WE_CARE_ABOUT
+
+    raw = sys.stdin.read()
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except ValueError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    # In V2 read_record raises for missing/foreign/short/corrupt workers.
+    # Missing proof can never authorize a permission (or a native hook event).
+    try:
+        rec = read_record(args.short)
+    except Exception:
+        rec = None
+    native = rec.get("native") if isinstance(rec, dict) else None
+    native_sid = native.get("sessionId") if isinstance(native, dict) else None
+    original = (
+        isinstance(rec, dict)
+        and rec.get("engine") == "claude"
+        and rec.get("workerId") == args.short
+        and isinstance(native_sid, str) and bool(native_sid)
+        and data.get("session_id") == native_sid
+        and os.environ.get(SELF_WORKER_ID_ENV) == args.short
+        and os.environ.get(SELF_ENGINE_ENV) == "claude"
+        and args.event in HOOKS_WE_CARE_ABOUT
+    )
+    if not original:
+        if args.event == "PermissionRequest":
+            sys.stdout.write(json.dumps(_permission_response(
+                "deny", data.get("tool_input"),
+                "ccx: unverified original managed worker hook",
+            )) + "\n")
+        elif args.event == "Elicitation":
+            sys.stdout.write(json.dumps(_elicitation_response("cancel")) + "\n")
+        else:
+            sys.stdout.write("{}\n")
+        return
+    if args.event == "UserPromptSubmit":
+        # Capture before the host ACK wait. Native paths can have hashed/long
+        # project slugs; this is only a byte-offset hint, never read authority.
+        transcript_path = data.get("transcript_path")
+        if (isinstance(transcript_path, str)
+                and os.path.isabs(transcript_path)
+                and os.path.basename(transcript_path) == native_sid + ".jsonl"):
+            try:
+                data["_ccx_report_start_offset"] = os.path.getsize(transcript_path)
+            except FileNotFoundError:
+                data["_ccx_report_start_offset"] = 0
+            except OSError:
+                pass
+    dargs = rec.get("createArgs") or {}
+    auto_allow_permissions = dargs.get("skip_permissions", True)
+    if args.event == "Elicitation":
+        # An MCP server asked the user for input mid-tool. Like AskUserQuestion
+        # it is a real question, brokered even on skip-permissions sessions.
+        sys.stdout.write(json.dumps(_relay_elicitation(args.short, data)) + "\n")
+        return
+    if args.event == "PermissionRequest":
+        tool_name = data.get("tool_name")
+        if auto_allow_permissions and tool_name != "AskUserQuestion":
+            sys.stdout.write(json.dumps(_permission_response(
+                "allow",
+                data.get("tool_input", {}),
+                "ccx auto-allow (--dangerously-skip-permissions session)",
+            )) + "\n")
+            return
+        # Broker through the host and wait for a CLI decision. Every failure mode
+        # resolves to a *deny* rather than a bare "{}": a no-op "{}" lets Claude
+        # fall back to its own interactive permission prompt, which in a head-less
+        # ccx PTY hangs forever. Denying keeps the session responsive and is the
+        # safe default whenever we cannot obtain an explicit allow.
+        tool_input = data.get("tool_input", {})
+        decision = _relay_broker_permission(args.short, data)
+        if decision is None:
+            sys.stdout.write(json.dumps(_permission_response(
+                "deny", tool_input, "ccx: session host unreachable, cannot broker approval")) + "\n")
+            return
+        if decision.get("external") is True:
+            # The native PostToolUse(/Failure) already resolved this exact
+            # original input. Empty hook output makes no second decision.
+            sys.stdout.write("{}\n")
+            return
+        sys.stdout.write(json.dumps(_permission_response(
+            decision.get("decision", "deny"),
+            tool_input,
+            decision.get("reason"),
+            updated_input=decision.get("updatedInput"),
+            user_modified=bool(decision.get("userModified")),
+        )) + "\n")
+        return
+
+    # When Claude fired this hook, not when the host reads it: relays run as
+    # separate processes and can deliver late or reordered.
+    data["_ccx_relay_ms"] = int(time.time() * 1000)
+    msg = {"op": "hook-event", "event": args.event, "data": data}
+    retry_s = hook_relay_retry_s(data)
+    try:
+        # Keep the relay connected until the host has consumed the complete
+        # event: Darwin may drop a just-closed relay before the host loop reads
+        # it. The bounded acknowledgement is never a reason to replay a hook.
+        # Hosts started before every event was acknowledged don't answer
+        # Notification or SubagentStart, so those wait only briefly.
+        brief = args.event in ("Notification", "SubagentStart")
+        _host_rpc(args.short, msg,
+                  timeout=1.0 if brief else BOUNDARY_SEND_ACK_S + 2.0,
+                  connect_retry_s=retry_s)
+    except Exception:
+        # Hook must not fail Claude. Swallow errors silently.
+        pass
+    sys.stdout.write("{}\n")

package/ccx/claude/host/pty.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+import fcntl
+import os
+import re
+import select
+import struct
+import termios
+import time
+from ccx.constants import (
+    CLEAR_KILL_REPEAT,
+    POST_CLEAR_SETTLE_S,
+    PASTE_INLINE_MAX_NEWLINES,
+    PASTE_INLINE_MAX_UNITS,
+    PASTE_INLINE_ROWS_RESERVED,
+    PASTE_SUBMIT_DELAY_S,
+    PASTE_STAGED_BYTES_PER_S,
+    PASTE_STAGED_MAX_DELAY_S,
+    PASTE_STAGED_THRESHOLD_BYTES,
+    PTY_QUIESCENCE_S,
+    PTY_WRITE_TIMEOUT_S,
+)
+
+
+def set_winsize(fd, rows, cols):
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+
+def paste_bytes(text: str) -> bytes:
+    """Frame text as one bracketed paste, without the submitting Enter.
+
+    Claude's decoder emits the pasted text only after the closing marker. The
+    caller sends Enter separately after this complete payload has drained.
+    """
+    return b"\x1b[200~" + text.encode() + b"\x1b[201~"
+
+
+def paste_submit_delay(text: str) -> float:
+    """How long Ink gets to materialize a paste before CCX presses Enter.
+
+    Small prompts remain effectively immediate. Large prompts are staged: Ink
+    asynchronously turns them into a collapsed ``[Pasted text …]`` attachment,
+    and an Enter delivered before that work finishes is silently discarded.
+    The caller must wait without blocking the host loop so PTY output continues
+    to drain during this interval.
+    """
+    size = len(text.encode())
+    if size <= PASTE_STAGED_THRESHOLD_BYTES:
+        return PASTE_SUBMIT_DELAY_S
+    return min(PASTE_STAGED_MAX_DELAY_S, size / PASTE_STAGED_BYTES_PER_S)
+
+
+def get_winsize_rows(fd) -> int:
+    """The PTY's current row count (viewers may resize it at any time)."""
+    rows, _cols, _x, _y = struct.unpack(
+        "HHHH", fcntl.ioctl(fd, termios.TIOCGWINSZ, b"\0" * 8))
+    return rows
+
+
+def inline_paste_newline_cap(rows: int) -> int:
+    """Line breaks one paste may carry and still be inserted as typed text."""
+    return max(0, min(rows - PASTE_INLINE_ROWS_RESERVED, PASTE_INLINE_MAX_NEWLINES))
+
+
+def paste_chunks(text: str, max_newlines: int,
+                 max_units: int = PASTE_INLINE_MAX_UNITS) -> list[str] | None:
+    """Split text into pastes small enough for Claude to insert as typed text.
+
+    Sizes are measured the way Claude's paste handler measures them: UTF-16
+    units after it normalizes CRLF/CR to LF and expands tabs to four spaces.
+    A CRLF pair is never split. Returns None when the text has a line break but
+    no paste may carry one (a PTY under ``PASTE_INLINE_ROWS_RESERVED + 1``
+    rows), so the caller falls back to a single paste.
+    """
+    chunks: list[str] = []
+    cur: list[str] = []
+    units = newlines = 0
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch == "\r" and text[i + 1:i + 2] == "\n":
+            ch = "\r\n"
+        is_newline = ch in ("\n", "\r", "\r\n")
+        if is_newline and max_newlines < 1:
+            return None
+        cost = 4 if ch == "\t" else 2 if ord(ch[0]) > 0xFFFF else 1
+        if cur and units + cost > max_units:
+            chunks.append("".join(cur))
+            cur, units, newlines = [], 0, 0
+        cur.append(ch)
+        units += cost
+        i += len(ch)
+        if is_newline:
+            newlines += 1
+            if newlines >= max_newlines:
+                chunks.append("".join(cur))
+                cur, units, newlines = [], 0, 0
+    if cur:
+        chunks.append("".join(cur))
+    return chunks
+
+
+def prompt_paste(text: str, rows: int) -> tuple[bytes, float, int]:
+    """Frame a prompt for Claude's editor: ``(payload, submit_delay, pastes)``.
+
+    Normally a run of small pastes (see ``paste_chunks``) that Claude inserts
+    verbatim, so the submitted prompt reaches the model as the user's own
+    words rather than wrapped in <pasted_content> tags, and Enter can follow
+    immediately. A PTY too short for inline line breaks falls back to one
+    paste with the size-aware staged submit.
+    """
+    chunks = paste_chunks(text, inline_paste_newline_cap(rows))
+    if chunks is None:
+        return paste_bytes(text), paste_submit_delay(text), 1
+    chunks = chunks or [text]
+    return b"".join(paste_bytes(c) for c in chunks), PASTE_SUBMIT_DELAY_S, len(chunks)
+
+
+def clear_input_bytes() -> bytes:
+    """Ctrl-C (Claude's app:interrupt). At an idle prompt it empties the whole
+    editor however many lines it holds, where a Ctrl-U burst only removes one
+    wrapped visual line per press. On an empty editor it only arms Claude's
+    exit confirmation, so a second press within 800ms would exit the worker:
+    the host spaces these presses at least ``CLEAR_INPUT_MIN_GAP_S`` apart."""
+    return b"\x03"
+
+
+def stalled_paste_clear_action(slot: dict, now: float, last_pty: float) -> str | None:
+    """Only reject a partial PTY write after an explicit quiet editor clear."""
+    if not last_pty or now - last_pty < PTY_QUIESCENCE_S:
+        return None
+    unstuck = slot.get("stalled_unstuck_at")
+    if unstuck is None:
+        return "unstick"
+    if now - unstuck < POST_CLEAR_SETTLE_S:
+        return None
+    cleared = slot.get("stalled_cleared_at")
+    if cleared is None:
+        return "clear"
+    if now - cleared < POST_CLEAR_SETTLE_S:
+        return None
+    return "reject"
+
+
+def write_all(fd: int, payload: bytes, *, timeout_s: float = PTY_WRITE_TIMEOUT_S,
+              absolute_timeout_s: float | None = None,
+              on_partial=None, on_read=None) -> bool:
+    """Drain short PTY writes, reading peer output to avoid bidirectional stalls.
+
+    The timeout bounds *lack of write progress*, not total payload time. A busy
+    Ink renderer can fill the opposite PTY buffer, stop reading input, and
+    deadlock a write-only host. ``on_read`` drains that output through the same
+    path as the host loop; it returns False on EOF. PTY write boundaries do not
+    change the logical bracketed pastes. ``absolute_timeout_s`` is an
+    optional non-renewable elapsed-time budget used only by attached-terminal
+    input; normal semantic writes preserve their progress-based timeout.
+    """
+    start = time.monotonic()
+    deadline = start + timeout_s
+    absolute_deadline = (start + absolute_timeout_s
+                         if absolute_timeout_s is not None else None)
+    sent = 0
+    while sent < len(payload):
+        if absolute_deadline is not None and time.monotonic() >= absolute_deadline:
+            return False
+        try:
+            written = os.write(fd, payload[sent:])
+        except InterruptedError:
+            continue
+        except BlockingIOError:
+            written = 0
+        except OSError:
+            return False
+
+        if written > 0:
+            sent += written
+            deadline = time.monotonic() + timeout_s
+            if sent < len(payload) and on_partial is not None:
+                on_partial(written, sent, len(payload))
+            continue
+
+        remaining = deadline - time.monotonic()
+        if absolute_deadline is not None:
+            remaining = min(remaining, absolute_deadline - time.monotonic())
+        if remaining <= 0:
+            return False
+        try:
+            readable, writable, _ = select.select(
+                [fd] if on_read is not None else [], [fd], [], remaining
+            )
+        except InterruptedError:
+            continue
+        except OSError:
+            return False
+        if readable and on_read() is False:
+            return False
+        if not readable and not writable:
+            return False
+    return True
+
+
+_ANSI_RE = re.compile(
+    rb"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)"
+    rb"|\x1b\[[0-9;?]*[ -/]*[@-~]"
+    rb"|\x1b[@-Z\\-_]"
+)
+
+
+def pty_tail_reason(buf: bytes | bytearray, *, max_chars: int = 300) -> str | None:
+    """Distill a dead worker's last PTY output into a one-line failure reason.
+
+    A worker that dies at boot (an unknown `--agent`, a rejected `--model`, an
+    onboarding/trust gate) prints why on the PTY and exits. Nothing else records
+    that: the host log holds only the launcher's stdio, so without this the
+    record kept an opaque state=crashed with lastError=None and the operator had
+    no way to tell a typo'd flag from a real crash.
+
+    Returns None when there is nothing quotable. Box-drawing and spinner residue
+    from a half-rendered TUI is dropped — a line must carry alphanumeric text to
+    count as a message — and consecutive duplicate lines (Ink re-renders the same
+    frame) collapse to one.
+    """
+    text = _ANSI_RE.sub(b"", bytes(buf)).decode("utf-8", "replace")
+    lines: list[str] = []
+    for raw in text.replace("\r", "\n").split("\n"):
+        line = "".join(c for c in raw if c.isprintable()).strip()
+        if not line or not any(c.isalnum() for c in line):
+            continue
+        if not lines or lines[-1] != line:
+            lines.append(line)
+    if not lines:
+        return None
+    return " ".join(lines[-3:])[:max_chars]
+
+
+def unstick_bytes() -> bytes:
+    """A lone closing bracketed-paste marker (\\x1b[201~). If a lost first paste
+    left Claude's decoder stuck IN_PASTE (its closing marker never arrived),
+    control keys are swallowed into the paste buffer and ignored; this marker
+    forces the decoder back to normal and materializes whatever partial it held
+    into the visible editor, where a kill key can then remove it."""
+    return b"\x1b[201~"
+
+
+def drain_bytes(kill_repeat: int = CLEAR_KILL_REPEAT) -> bytes:
+    """A burst of Ctrl-U (\\x15), used for the single-line ``/compact``
+    residue. Ctrl-U is bound to delete-to-line-start, not whole-buffer clear:
+    each press removes one wrapped visual line, so it cannot empty a long
+    multi-line prompt (see clear_input_bytes()). No-op once the buffer is
+    empty."""
+    return b"\x15" * kill_repeat