orcho-core 0.1.0__py3-none-any.whl

agents/__init__.py

@@ -0,0 +1,41 @@
+"""
+agents — Provider wrappers, Protocols, entities, and the agent registry.
+
+Public surface (re-exported here so callers can ``from agents import X``):
+
+    Protocol         IAgentRuntime, SessionMode
+    Entities         SubTask, TestResult
+    Registry         AgentRegistry, PhaseAgentConfig
+    Runtimes         ClaudeAgent, CodexAgent
+    Streaming        _stream_run, set_agent_log, set_stdout_echo
+    subprocess       re-exported for tests that monkeypatch agents.subprocess
+"""
+
+import subprocess  # re-exported so tests can `monkeypatch.setattr(agents.subprocess, ...)`
+
+from agents.entities import SubTask, TestResult
+from agents.protocols import IAgentRuntime, SessionMode
+from agents.registry import AgentRegistry, PhaseAgentConfig
+from agents.runtimes import ClaudeAgent, CodexAgent
+from agents.stream import StreamAbort, _stream_run, set_agent_log, set_stdout_echo
+
+__all__ = [
+    # Protocol
+    "IAgentRuntime",
+    "SessionMode",
+    # Entities
+    "SubTask",
+    "TestResult",
+    # Registry
+    "AgentRegistry",
+    "PhaseAgentConfig",
+    # Providers
+    "ClaudeAgent",
+    "CodexAgent",
+    # Streaming
+    "_stream_run",
+    "StreamAbort",
+    "set_agent_log",
+    "set_stdout_echo",
+    "subprocess",
+]

agents/command_guard.py

@@ -0,0 +1,336 @@
+"""Runtime guardrails for agent-issued shell commands.
+
+The prompts tell write-capable agents not to discard user-owned work, but
+prompts are advisory. This module is the runtime backstop for the specific
+class of failure that live repeated-run testing exposed: destructive git
+rollback commands issued through Claude's Bash tool.
+
+A second, *diagnostic-only* guard flags unsafe free-text process polling
+(``pgrep -f`` / ``pkill -f``). Unlike the destructive-git guard — which aborts
+the call — the process-polling guard never aborts and never kills: it carries
+the :class:`agents.stall_protocol.StallReason` ``unsafe_process_polling``
+category so the runtime can emit a ``warn`` diagnostic and keep running.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from agents.stall_protocol import StallReason
+
+ORCHO_GUARDRAIL_BLOCKED = "ORCHO_GUARDRAIL_BLOCKED"
+
+#: Guardrail category for the destructive-git guard (abort semantics).
+GUARDRAIL_DESTRUCTIVE_GIT = "destructive_git"
+#: Guardrail category for the unsafe free-text process-polling guard
+#: (diagnostic ``warn`` only — never abort/kill). Equal to the
+#: ``StallReason.unsafe_process_polling`` value so the two layers agree.
+GUARDRAIL_UNSAFE_PROCESS_POLLING = str(StallReason.UNSAFE_PROCESS_POLLING)
+
+
+@dataclass(frozen=True)
+class BlockedCommand:
+    """A shell command flagged by a runtime guardrail.
+
+    ``guardrail`` names the category so callers can route the verdict: the
+    default ``destructive_git`` is an abort, while ``unsafe_process_polling``
+    is a diagnostic warn that must NOT abort or kill the subprocess.
+    """
+
+    command: str
+    reason: str
+    guardrail: str = GUARDRAIL_DESTRUCTIVE_GIT
+
+
+_SEGMENT_SPLIT_RE = re.compile(r"(?:&&|\|\||;|\n)")
+_ENV_ASSIGN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+_TEXT_PREFIX_RE = re.compile(
+    r"^(?:tool\s+Bash:|Bash:|command:|cmd:|shell:|run:|exec:)\s*",
+    re.IGNORECASE,
+)
+
+
+def blocked_destructive_git_command(
+    command: str,
+    *,
+    worktree_cwd_path: str | Path | None = None,
+) -> BlockedCommand | None:
+    """Return a block reason when ``command`` contains risky git mutation.
+
+    The guard is intentionally small and targeted. It does not try to be a
+    general shell sandbox; it catches the rollback/switch commands that can
+    erase or hide pre-existing working-tree state during Orcho write phases.
+
+    When ``worktree_cwd_path`` is set, the agent's effective cwd is an
+    orcho-managed isolated worktree (ADR 0033). Destructive git inside the
+    worktree cannot harm user-owned work, so the block is lifted — the agent
+    has full git freedom inside its own sandbox. Outside the worktree (or
+    when the parameter is None) the existing detection stands unchanged.
+    """
+    if worktree_cwd_path is not None:
+        return None
+    for segment in _SEGMENT_SPLIT_RE.split(command or ""):
+        argv = _safe_split(segment)
+        if not argv:
+            continue
+        argv = _strip_prefixes(argv)
+        if len(argv) < 2 or argv[0] != "git":
+            continue
+        subcommand = argv[1]
+        if subcommand in {"reset", "restore", "clean", "revert", "switch"}:
+            return BlockedCommand(
+                command=command,
+                reason=f"git {subcommand} can discard or hide working-tree state",
+            )
+        if subcommand == "checkout":
+            return BlockedCommand(
+                command=command,
+                reason="git checkout can discard file changes or switch context",
+            )
+    return None
+
+
+# ── unsafe free-text process polling guard ───────────────────────────────────
+
+# A pgrep/pkill invocation, even when wrapped in command substitution or
+# backticks. ``\b`` matches at the start of the binary name when preceded by
+# ``$(`` or `` ` `` (both non-word) just as well as at a line/whitespace start.
+_PGREP_PKILL_RE = re.compile(r"\b(?:pgrep|pkill)\b")
+# A short-option cluster that includes the ``-f`` (full-command-line match)
+# flag — ``-f``, ``-fl``, ``-lf``, ``-af`` … A leading boundary keeps this a
+# flag rather than a substring of an argument.
+_F_FLAG_RE = re.compile(r"(?:^|\s)-[A-Za-z]*f[A-Za-z]*\b")
+# Characters that end the pgrep/pkill argument scope, so an unrelated ``-f``
+# elsewhere in a compound line is not mis-attributed to the pgrep call.
+_CMD_BOUNDARY_RE = re.compile(r"[;&|)`\n]")
+
+
+def blocked_unsafe_process_polling(
+    command: str,
+    *,
+    worktree_cwd_path: str | Path | None = None,
+) -> BlockedCommand | None:
+    """Flag unsafe free-text process polling (``pgrep -f`` / ``pkill -f``).
+
+    Detects the full-command-line, free-text process matching an agent reaches
+    for when it wants to wait on a backgrounded command, including the compound
+    and loop forms:
+
+    * ``pgrep -f "pytest -q -m"`` / ``pkill -f ...``
+    * ``kill -0 $(pgrep -f "pytest -q -m")``
+    * ``while kill -0 $(pgrep -f ...); do sleep 1; done``
+
+    Free-text argv matching is unsafe because it can match *unrelated* host
+    processes — the dogfood hazard is a real ``pytest -q -m`` running elsewhere
+    on the machine being mistaken for the run's own command. Polling the run's
+    OWN child by PID (``kill -0 <pid>``) matches nothing here and is correctly
+    left alone.
+
+    Unlike :func:`blocked_destructive_git_command`, an orcho-managed worktree
+    does **not** relax this check — matching foreign processes by argv is a
+    hazard regardless of cwd. ``worktree_cwd_path`` is accepted only for
+    call-site symmetry and is intentionally ignored.
+
+    The verdict is derived purely from the command TEXT; this guard never
+    scans, signals, or kills any process. The returned ``BlockedCommand``
+    carries ``guardrail=unsafe_process_polling`` so the runtime routes it as a
+    diagnostic ``warn``, never an abort.
+    """
+    text = command or ""
+    for match in _PGREP_PKILL_RE.finditer(text):
+        tail = text[match.end():]
+        boundary = _CMD_BOUNDARY_RE.search(tail)
+        scope = tail[: boundary.start()] if boundary else tail
+        if _F_FLAG_RE.search(scope):
+            return BlockedCommand(
+                command=command,
+                reason=(
+                    "free-text process polling (pgrep/pkill -f) can match "
+                    "unrelated processes by command line; poll the run's own "
+                    "child by PID instead"
+                ),
+                guardrail=GUARDRAIL_UNSAFE_PROCESS_POLLING,
+            )
+    return None
+
+
+def claude_bash_commands_from_jsonl(line: str) -> Iterator[str]:
+    """Yield Bash command strings from one Claude stream-json line."""
+    line = (line or "").strip()
+    if not line.startswith("{"):
+        return
+    try:
+        payload = json.loads(line)
+    except json.JSONDecodeError:
+        return
+    if payload.get("type") != "assistant":
+        return
+    message = payload.get("message")
+    if not isinstance(message, dict):
+        return
+    for block in message.get("content", []) or []:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") != "tool_use" or block.get("name") != "Bash":
+            continue
+        tool_input = block.get("input")
+        if not isinstance(tool_input, dict):
+            continue
+        command = tool_input.get("command")
+        if isinstance(command, str) and command.strip():
+            yield command
+
+
+def blocked_claude_write_tool_use(
+    line: str,
+    *,
+    worktree_cwd_path: str | Path | None = None,
+) -> BlockedCommand | None:
+    """Detect blocked Bash tool use in one Claude stream-json line."""
+    for command in claude_bash_commands_from_jsonl(line):
+        blocked = blocked_destructive_git_command(command, worktree_cwd_path=worktree_cwd_path)
+        if blocked is not None:
+            return blocked
+    return None
+
+
+def gemini_shell_commands_from_jsonl(line: str) -> Iterator[str]:
+    """Yield shell command strings from one Gemini stream-json line.
+
+    Gemini CLI 0.40 emits ``tool_use`` events as top-level JSONL records
+    (not wrapped in an assistant content array like Claude). The
+    shell-executing tool is ``run_shell_command`` and the command lands
+    under ``parameters.command``. Tool names may change across CLI
+    releases — ``run_shell_command`` is the documented 0.40 name. The
+    yield is empty for every other tool (``read_file``, ``glob``, ...)
+    and for malformed input.
+    """
+    line = (line or "").strip()
+    if not line.startswith("{"):
+        return
+    try:
+        payload = json.loads(line)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(payload, dict) or payload.get("type") != "tool_use":
+        return
+    if payload.get("tool_name") != "run_shell_command":
+        return
+    params = payload.get("parameters")
+    if not isinstance(params, dict):
+        return
+    command = params.get("command")
+    if isinstance(command, str) and command.strip():
+        yield command
+
+
+def blocked_gemini_write_tool_use(
+    line: str,
+    *,
+    worktree_cwd_path: str | Path | None = None,
+) -> BlockedCommand | None:
+    """Detect blocked shell tool use in one Gemini stream-json line."""
+    for command in gemini_shell_commands_from_jsonl(line):
+        blocked = blocked_destructive_git_command(
+            command, worktree_cwd_path=worktree_cwd_path,
+        )
+        if blocked is not None:
+            return blocked
+    return None
+
+
+def blocked_agent_stream_line(
+    line: str,
+    *,
+    worktree_cwd_path: str | Path | None = None,
+) -> BlockedCommand | None:
+    """Detect blocked commands in a write-agent stream line.
+
+    Claude and Gemini emit structured stream-json with tool calls;
+    Codex prints human-readable command lines. This function supports
+    every shape so provider wrappers can share one guardrail.
+    """
+    # Destructive-git guard first: it aborts the call and is worktree-relaxable.
+    structured = blocked_claude_write_tool_use(line, worktree_cwd_path=worktree_cwd_path)
+    if structured is not None:
+        return structured
+    structured = blocked_gemini_write_tool_use(line, worktree_cwd_path=worktree_cwd_path)
+    if structured is not None:
+        return structured
+    for candidate in shell_command_candidates_from_text(line):
+        blocked = blocked_destructive_git_command(candidate, worktree_cwd_path=worktree_cwd_path)
+        if blocked is not None:
+            return blocked
+    # Unsafe free-text process polling: a diagnostic warn (never abort/kill),
+    # provider-neutral over every command shape, and never worktree-relaxed.
+    for command in agent_commands_from_stream_line(line):
+        unsafe = blocked_unsafe_process_polling(
+            command, worktree_cwd_path=worktree_cwd_path,
+        )
+        if unsafe is not None:
+            return unsafe
+    return None
+
+
+def _clean_stream_text(line: str) -> str:
+    """Normalise one human-readable stream line into a bare command string.
+
+    Strips ANSI, surrounding backticks, the ``tool Bash:`` / ``command:`` …
+    prefixes, and a leading shell-prompt sigil (``$`` / ``>`` / ``+``). Returns
+    ``""`` for an empty / whitespace-only line.
+    """
+    text = _ANSI_RE.sub("", line or "").strip()
+    if not text:
+        return ""
+    text = text.strip("`")
+    text = _TEXT_PREFIX_RE.sub("", text).strip()
+    for prefix in ("$", ">", "+"):
+        if text.startswith(prefix):
+            text = text[len(prefix):].strip()
+    if text.startswith("tool Bash:"):
+        text = text.removeprefix("tool Bash:").strip()
+    return text
+
+
+def shell_command_candidates_from_text(line: str) -> Iterator[str]:
+    """Yield git-command-looking strings from one human-readable stream line."""
+    text = _clean_stream_text(line)
+    if text.startswith("git ") or text.startswith("command git ") or text.startswith("sudo git "):
+        yield text
+
+
+def agent_commands_from_stream_line(line: str) -> Iterator[str]:
+    """Yield every candidate shell command from one stream line, any provider.
+
+    Unions the structured tool-use commands (Claude Bash, Gemini
+    ``run_shell_command``) with the cleaned human-readable text (Codex). Unlike
+    :func:`shell_command_candidates_from_text`, the text candidate is yielded
+    regardless of leading binary, because process-polling forms
+    (``pgrep -f`` / ``kill -0 $(pgrep -f ...)``) do not start with ``git``.
+    """
+    yield from claude_bash_commands_from_jsonl(line)
+    yield from gemini_shell_commands_from_jsonl(line)
+    text = _clean_stream_text(line)
+    if text:
+        yield text
+
+
+def _safe_split(segment: str) -> list[str]:
+    try:
+        return shlex.split(segment)
+    except ValueError:
+        return segment.strip().split()
+
+
+def _strip_prefixes(argv: list[str]) -> list[str]:
+    out = list(argv)
+    while out and _ENV_ASSIGN_RE.match(out[0]):
+        out.pop(0)
+    while out and out[0] in {"command", "sudo"}:
+        out.pop(0)
+    return out

agents/entities.py

@@ -0,0 +1,70 @@
+"""agents/entities.py — Domain entities for the agent pipeline.
+
+Plan parsing now lives in :mod:`pipeline.plan_parser`; the canonical PLAN
+object is ``ParsedPlan``. This module keeps the agent-adjacent entities that
+do not depend on pipeline runtime wiring.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class SubTask:
+    """A team-lead-decomposed unit of work with explicit DAG dependencies.
+
+    Produced by the PLAN phase when the architect emits the structured
+    ``## Task N`` / JSON-fence format. ``depends_on`` references other SubTask
+    ``id``s — the runner topo-sorts and (later) groups into parallel waves.
+    ``skill`` is an optional name resolved against the plugin's skill registry
+    (auto-discovered from the plugin folder); when empty, the runner falls
+    back to the per-phase build agent. ``done_criteria`` are checkable
+    conditions the per-task QA gate validates before marking the subtask done.
+
+    Phase 1 redesign extensions (additive):
+      * ``owned_files`` — glob patterns the subtask writes to. Used by
+        Milestone 9 wave executor for proactive conflict avoidance:
+        subtasks with overlapping owned_files are scheduled in different
+        waves rather than racing on merge.
+      * ``architectural_decision`` — flag for the artifact pipeline. When
+        ``ArtifactProfile.ADR`` (or higher) is selected, an ADR is emitted
+        per subtask carrying this flag (Milestone 11).
+    """
+    id: str
+    goal: str
+    spec: str = ""
+    files: tuple[str, ...] = field(default_factory=tuple)
+    skill: str | None = None
+    model: str | None = None
+    depends_on: tuple[str, ...] = field(default_factory=tuple)
+    done_criteria: tuple[str, ...] = field(default_factory=tuple)
+    owned_files: tuple[str, ...] = field(default_factory=tuple)
+    # Companion modifications the reviewer may accept for THIS task beyond
+    # the project-wide ``allowed_modifications`` (lockfiles, regenerated
+    # snapshots, derived artifacts). This is an *informational review
+    # allowance* surfaced in the Plan Contract — NOT a write-scope
+    # primitive for the wave planner, which schedules on ``owned_files``.
+    allowed_modifications: tuple[str, ...] = field(default_factory=tuple)
+    architectural_decision: bool = False
+
+
+@dataclass(frozen=True)
+class TestResult:
+    """Result of running the project's test suite as a shell step.
+
+    Produced by the orchestrator's ``run_tests()`` shell wrapper, not by an
+    LLM. ``output`` is the combined stdout+stderr fed back into the repair_changes prompt
+    when tests fail. ``skipped`` is True when the plugin defines no
+    ``run_command`` — the pipeline must treat that as success.
+    """
+    # Tell pytest not to collect this as a test class (the leading "Test"
+    # in the name would otherwise trigger PytestCollectionWarning).
+    __test__ = False
+
+    skipped: bool = False
+    passed: bool = True
+    output: str = ""
+    duration: float = 0.0
+
+    @property
+    def failed(self) -> bool:
+        return not self.skipped and not self.passed

agents/protocols.py

@@ -0,0 +1,135 @@
+"""
+agents/protocols.py — Public agent contract.
+
+:class:`IAgentRuntime` is the single Protocol every runtime implements. One
+``invoke()`` entry point: it receives a fully-composed prompt (the composer
+builds it) plus per-call flags and returns raw text. Callers parse plans /
+critiques / etc. from the returned string.
+
+``session_id`` is the bridge handle. A runtime instance carries it across
+phase boundaries so subsequent invocations can ``--resume`` the same
+conversation. Runtimes without resumable sessions leave it ``None``. The
+orchestrator decides per-call whether to resume via ``continue_session=True``;
+the runtime is mechanical and never raises on cross-mutation resume — that
+policy lives in the orchestrator.
+
+``mutates_artifacts`` declares whether the call may modify project artifacts
+on disk (code, configs, generated files in ``cwd``). Maps to the CLI write
+flags. Default ``False`` is safe; ``build`` / ``fix`` phases opt in. The flag
+is per-call, not per-session — one bridge can carry both mutating and
+non-mutating invocations.
+
+``attachments`` is multimodal-only (IMAGE / BINARY). TEXT attachments are
+rendered into the prompt outside the runtime by
+``builtin._plan_prompt_prefix`` via ``render_text_block``; passing TEXT into
+``invoke(attachments=...)`` is a caller bug and the runtime raises
+``ValueError`` to prevent double injection.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pipeline.runtime.steps import Attachment
+
+
+class SessionMode(str, Enum):  # noqa: UP042  # StrEnum changes __str__; appears in SDK schema snapshot, keep stable
+    """How the orchestrator should chain calls between phases."""
+
+    AUTO      = "auto"
+    STATELESS = "stateless"
+    CHAIN     = "chain"
+    HYBRID    = "hybrid"
+
+
+@runtime_checkable
+class IAgentRuntime(Protocol):
+    """Unified agent runtime contract.
+
+    A concrete implementation backs one CLI / SDK (Claude Code, Codex CLI,
+    Gemini, …). It receives a fully-composed prompt and returns the agent's
+    raw textual response. Plan parsing, review verdict extraction, and any
+    other downstream interpretation happen in the caller.
+
+    Fields:
+        model: identifier of the underlying model.
+        session_id: bridge handle. ``None`` until the first successful call,
+            or for runtimes without resumable sessions. Same instance, same
+            session through the pipeline; reset with :meth:`reset_session`.
+        _followup_resume_pending: optional follow-up seed flag. When true and
+            ``session_id`` is set, the next ``invoke`` must pass that id to the
+            runtime resume flag even if the caller did not request continuation.
+        _last_resumed_session_id: the exact id passed to the runtime resume
+            flag on the most recent call, or ``None`` when the call was fresh.
+        _last_followup_parent_session_id: the parent-run session id consumed by
+            a follow-up seed on the most recent call, or ``None`` otherwise.
+    """
+
+    model: str
+    session_id: str | None
+    _followup_resume_pending: bool
+    _last_resumed_session_id: str | None
+    _last_followup_parent_session_id: str | None
+
+    def invoke(
+        self,
+        prompt: str,
+        cwd: str,
+        *,
+        mutates_artifacts: bool = False,
+        continue_session: bool = False,
+        attachments: tuple[Attachment, ...] = (),
+    ) -> str:
+        """Run the agent on ``prompt`` inside working directory ``cwd``.
+
+        Args:
+            prompt: fully-composed prompt text (composer built it).
+            cwd: project working directory.
+            mutates_artifacts: when ``True`` the call may modify files on
+                disk in ``cwd``. Maps to the underlying CLI's write flags.
+                Default ``False`` is read-only.
+            continue_session: when ``True`` and ``self.session_id`` is set,
+                resume that session (``--resume``) so this call inherits the
+                bridge's accumulated context. Otherwise start fresh and
+                capture a new ``session_id``.
+            attachments: multimodal attachments (IMAGE / BINARY) the runtime
+                must hand to the CLI. **TEXT attachments are forbidden here**
+                — they are rendered into ``prompt`` outside the runtime; if
+                a TEXT entry leaks in, the runtime raises ``ValueError``.
+
+        Returns:
+            Raw assistant text. Callers parse plans/critiques/etc. from it.
+        """
+        ...
+
+    def reset_session(self) -> None:
+        """Clear ``session_id`` so the next ``invoke()`` starts fresh.
+
+        Use to deliberately burn the bridge (e.g. when a human operator
+        requested a clean restart from a paused run).
+        """
+        ...
+
+    # ── Optional capability: account identity diagnostics ────────────────
+    #
+    # A runtime MAY implement ``probe_identity(self) -> RuntimeIdentity`` to
+    # report which provider account / organization it is executing under. It
+    # is intentionally NOT declared as a required method on this Protocol:
+    # the capability is structural, so a third-party runtime that omits it
+    # simply yields an ``unavailable`` identity via
+    # :func:`agents.runtimes.identity.probe_runtime_identity`.
+    #
+    # Contract for implementers:
+    #   * Diagnostic only — never an authorization or delivery decision.
+    #   * Best-effort and non-interactive: read a status surface the provider
+    #     already shows users, with a short timeout. Any failure (missing
+    #     binary, timeout, non-zero exit, unparsable output, no account field)
+    #     returns ``RuntimeIdentity.unavailable(...)``; it must never raise.
+    #   * Sanitized: populate only ``account_label`` / ``email`` (values the
+    #     provider already surfaces). Never read or return tokens, cookies,
+    #     auth-file paths, or raw auth JSON.
+    #   * Lazy: must not be called from the constructor, profile listing, or
+    #     dry-run rendering. Resolving the CLI binary here (first real use) is
+    #     fine; the orchestrator only calls it during real run setup.

agents/pty_diagnostics.py

@@ -0,0 +1,43 @@
+"""Diagnostics for startup-time pseudo-terminal allocation failures."""
+
+from __future__ import annotations
+
+import errno
+
+PTY_EXHAUSTED_SENTINEL = "ORCHO_SYSTEM_PTY_EXHAUSTED"
+
+
+def is_pty_exhaustion(exc: OSError) -> bool:
+    """Return True when ``pty.openpty`` failed because no PTYs are available."""
+    message = str(exc).lower()
+    return (
+        exc.errno in {errno.ENOSPC, errno.EAGAIN}
+        or "out of pty devices" in message
+        or "no available pty" in message
+        or "device not configured" in message
+    )
+
+
+def render_pty_exhaustion_diagnostic(exc: OSError) -> str:
+    """Human recovery text for a system PTY pool exhaustion blocker."""
+    return "\n".join((
+        f"{PTY_EXHAUSTED_SENTINEL}: PTY pool exhausted before agent startup.",
+        "",
+        "Orcho could not allocate a pseudo-terminal for the agent runtime.",
+        "This is a system resource blocker, not a task, plan, or code-review failure.",
+        "It is usually caused by external orphaned PTY holders, such as terminal",
+        "sessions or computer-use/browser automation clients that were not cleaned up.",
+        "",
+        "Diagnostics:",
+        "  python -c \"import pty; print(pty.openpty())\"",
+        "  lsof 2>/dev/null | grep -E '/dev/(ttys|ptmx|pty)' | "
+        "awk '{print $1, $2, $9}' | sort | uniq -c | sort -nr | head",
+        "  ps aux | grep '[S]kyComputerUseClient'",
+        "  ps aux | grep '[p]ty'",
+        "",
+        "Recovery:",
+        "  close or restart the leaking client, or terminate orphaned PTY holders;",
+        "  then rerun the same Orcho command.",
+        "",
+        f"Original error: {exc}",
+    ))