@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.1

package/python-runtime/python/lib/python3.12/site-packages/steerable_sidecar/workspace_tools.py

@@ -0,0 +1,1472 @@
+"""In-process bash / file tools scoped to a workspace directory.
+
+Harbor Terminal-Bench (and the ACP adapter's default surface) run the
+CoreLoop *inside* the trial container. File content flows through a
+``WorkspaceFs`` channel and bash through a ``BashRunner`` — both default
+to local disk/subprocess; the ACP adapter substitutes the editor-backed
+bridges (3.4.3) when the client advertises the capabilities.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import math
+import os
+import re
+import signal
+import subprocess
+from collections.abc import Iterable
+from io import BytesIO
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from PIL import Image, UnidentifiedImageError
+from steerable_agent_harness.safety import CommandSafetyConfig
+from steerable_agent_protocol.generated import ToolResult
+from steerable_agent_runtime import ToolRouter
+from steerable_agent_runtime.llm import LLMMessage
+
+from .file_edit import EditError, EditOp, apply_edits, content_version
+from .png_ascii import ascii_png_preview, decode_bmp_rgb, encode_png_rgb
+from .workspace_fs import LOCAL_FS, LocalFs, WorkspaceFs, WorkspaceFsError
+
+_MAX_OUTPUT = 100_000
+# Catalog-89 bn-fit-modify: a no_artifact retry overwrote a 10k-row sample
+# with two write_file rows. Refuse shrinking an already-large file that far.
+_MIN_KEEP_BYTES = 8192
+# TB compiles, QEMU, and training exceed the old 5 min cap; Claude Code
+# does not kill a single bash at 300s. Harbor's long-task kill is ~180 min.
+_BASH_TIMEOUT_SEC = 3600
+# Native pixels for PNG/JPEG ``read_file``. Off by default; flaky arm B
+# sets ``STEERABLE_READ_IMAGES=1``. ``capture_display`` always attaches
+# (same size cap). ASCII preview stays either way. BMP stays ASCII:
+# vision endpoints accept PNG/JPEG, not BMP.
+_IMAGE_MAX_SOURCE_BYTES = 10 * 1024 * 1024
+_IMAGE_ATTACH_MAX_BYTES = 400_000
+_VIEW_IMAGE_MAX_ENCODED_BYTES = 5 * 1024 * 1024
+_IMAGE_DEFAULT_MAX_EDGE = 1568
+
+#: One-shot bash execution behind the tool: (command, cwd) → result.
+#: The local default spawns a subprocess; the ACP terminal bridge runs the
+#: command on the editor's terminal instead (3.4.3.2).
+BashRunner = Callable[[str, Path], Awaitable[ToolResult]]
+
+_BASH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "command": {
+            "type": "string",
+            "description": (
+                "Shell command to run in the workspace. Timeout is 3600s; do "
+                "not poll with `sleep 290`. Do not wrap compile, VM, or train "
+                "in `timeout N` with N under 300 — bash already caps at 3600s. "
+                "Do not wait with `while pgrep -f ...` (pgrep matches the "
+                "wait loop). Do not `tail -f` a log until a string appears. "
+                "Background long jobs and `wait $!`, or poll a "
+                "pidfile."
+            ),
+        },
+    },
+    "required": ["command"],
+}
+# `while pgrep -f <script>` matches the wait loop itself and never exits.
+_PGREP_SELF_WAIT = re.compile(
+    r"while\b[\s\S]{0,80}?\bpgrep\s+-[a-zA-Z]*f\b",
+    re.IGNORECASE,
+)
+_PGREP_WAIT_ERROR = (
+    "Refusing `while pgrep -f ...`: pgrep matches this wait loop and never "
+    "exits. Background the job (`cmd & pid=$!`) and `wait \"$pid\"`, or poll "
+    "a pidfile."
+)
+# Catalog-89 mteb-leaderboard: `sleep 290; cat log` under the old 300s bash
+# cap. Bash now waits 3600s — `wait $!` instead of a long sleep-then-cat.
+_SLEEP_POLL = re.compile(
+    r"\bsleep\s+(\d+)\s*(?:;|&&|\n)\s*(?:cat|tail|ls|head)\b",
+    re.IGNORECASE,
+)
+_SLEEP_POLL_MIN_SEC = 120
+_SLEEP_POLL_ERROR = (
+    "Refusing a long `sleep N; cat/tail/ls` poll. Bash already waits up to "
+    "3600s. Background the job (`cmd & pid=$!`) and `wait \"$pid\"`."
+)
+# Catalog-89 make-doom-for-mips: `timeout 120 node vm.js` killed the VM
+# before /tmp/frame.bmp existed. qemu-startup: `timeout 10 qemu-system`
+# dies before the verifier can telnet the login prompt. Bash already
+# caps at 3600s.
+_SHORT_TIMEOUT = re.compile(
+    r"\btimeout\s+(?:--signal=\S+\s+|-[A-Za-z]\s+\S+\s+)*(\d+)\s+"
+    r"(?=[^;\n]{0,80}\b(?:node|make|gcc|g\+\+|rustc|clang\+\+|clang|"
+    r"qemu-system)\b)",
+    re.IGNORECASE,
+)
+_SHORT_TIMEOUT_MAX_SEC = 299
+_SHORT_TIMEOUT_ERROR = (
+    "Refusing `timeout N` around compile/VM with N under 300s. Bash already "
+    "caps at 3600s. Drop the timeout wrapper so the job can finish."
+)
+# cheap-12 compile-compcert hung Harbor 7200s on
+# `tail -f … | grep -m1 BUILD_SUCCESS`. Same class as pgrep-self-wait:
+# the bash tool never returns, so Harbor's wait_for raises AgentTimeoutError
+# and evals.run fails the smoke job.
+_FOLLOW_LOG_CMD = re.compile(r"\btail\b[^\n|;]{0,80}", re.IGNORECASE)
+_FOLLOW_LOG_FLAG = re.compile(
+    r"(?:--follow\b|(?<![-\w])-F\b|(?<![-\w])-\w*f\w*)",
+    re.IGNORECASE,
+)
+_FOLLOW_LOG_ERROR = (
+    "Refusing `tail -f` / `tail --follow`: it blocks this bash call until "
+    "the file grows or the 3600s cap. Background the job "
+    "(`cmd & pid=$!`) and `wait \"$pid\"`, or poll a pidfile."
+)
+_READ_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "File path relative to the workspace"},
+    },
+    "required": ["path"],
+}
+_VIEW_IMAGE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {
+            "type": "string",
+            "description": "Image file path: PNG, JPEG, WebP, or BMP.",
+        },
+        "region": {
+            "type": "object",
+            "description": (
+                "Optional crop {x,y,w,h}; use either pixels or all-normalized "
+                "0–1 values."
+            ),
+            "properties": {
+                "x": {"type": "number"},
+                "y": {"type": "number"},
+                "w": {"type": "number"},
+                "h": {"type": "number"},
+            },
+            "required": ["x", "y", "w", "h"],
+            "additionalProperties": False,
+        },
+        "maxEdge": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 4096,
+            "description": "Maximum longest output edge (default 1568).",
+        },
+        "format": {
+            "type": "string",
+            "enum": ["png", "jpeg"],
+            "description": "Output encoding. JPEG usually uses fewer bytes/tokens.",
+        },
+    },
+    "required": ["path"],
+    "additionalProperties": False,
+}
+_WRITE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "File path relative to the workspace"},
+        "content": {
+            "type": "string",
+            "description": (
+                "Full file contents to write. Do not replace an existing "
+                "complete output with a truncated body."
+            ),
+        },
+        "expectedVersion": {
+            "type": "string",
+            "description": (
+                "Optional. The `version` returned by your last read_file of this "
+                "path; when provided the write is rejected if the file changed since."
+            ),
+        },
+    },
+    "required": ["path", "content"],
+}
+_EDIT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "File path relative to the workspace"},
+        "edits": {
+            "type": "array",
+            "description": "One or more targeted replacements, applied together.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "oldText": {
+                        "type": "string",
+                        "description": "Exact snippet to replace; include enough context to be unique.",
+                    },
+                    "newText": {"type": "string", "description": "Replacement text."},
+                },
+                "required": ["oldText", "newText"],
+            },
+        },
+        "expectedVersion": {
+            "type": "string",
+            "description": (
+                "Optional. The `version` returned by your last read_file of this "
+                "path; when provided the edit is rejected on conflict."
+            ),
+        },
+    },
+    "required": ["path", "edits"],
+}
+
+
+_GREP_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "query": {"type": "string", "description": "Text or regex to search for."},
+        "isRegex": {
+            "type": "boolean",
+            "description": "Treat query as a regular expression (default false).",
+        },
+        "ignoreCase": {"type": "boolean", "description": "Case-insensitive match."},
+        "limit": {
+            "type": "integer",
+            "description": "Max hits returned (default 200, capped at 1000).",
+        },
+    },
+    "required": ["query"],
+}
+
+_GLOB_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "pattern": {
+            "type": "string",
+            "description": "fnmatch pattern against repo-relative paths (e.g. '**/*.py').",
+        },
+        "limit": {"type": "integer", "description": "Max paths returned."},
+    },
+    "required": ["pattern"],
+}
+
+_APPLY_PATCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "patches": {
+            "type": "array",
+            "description": (
+                "Edits across one or more files, applied atomically: every file "
+                "is planned against original bytes first; a failure anywhere "
+                "rolls back everything already written."
+            ),
+            "items": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path relative to the workspace.",
+                    },
+                    "edits": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "oldText": {"type": "string"},
+                                "newText": {"type": "string"},
+                            },
+                            "required": ["oldText", "newText"],
+                        },
+                    },
+                },
+                "required": ["path", "edits"],
+            },
+        },
+    },
+    "required": ["patches"],
+}
+
+_BASH_SESSION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "command": {
+            "type": "string",
+            "description": "Optional command to run immediately after opening.",
+        },
+        "yieldMs": {
+            "type": "integer",
+            "description": "How long to wait for initial output (default 1000).",
+        },
+        "maxOutput": {
+            "type": "integer",
+            "description": "Max bytes of output returned per read.",
+        },
+    },
+}
+
+_CAPTURE_DISPLAY_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "target": {
+            "type": "string",
+            "description": (
+                "Remote display the client or grader sees. RFB/VNC: "
+                "vnc://host:1, :1, host:5901. Display numbers 0-99 map to "
+                "TCP 5900+N. This is the VNC framebuffer, not a hypervisor "
+                "screendump."
+            ),
+        },
+        "path": {
+            "type": "string",
+            "description": "Optional workspace path to write the captured PNG.",
+        },
+        "nudge": {
+            "type": "boolean",
+            "description": (
+                "Send a tiny pointer move over RFB before the snapshot so a "
+                "stale client framebuffer refreshes."
+            ),
+        },
+    },
+    "required": ["target"],
+}
+
+_WRITE_STDIN_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "sessionId": {"type": "string", "description": "The bash_session id."},
+        "chars": {
+            "type": "string",
+            "description": "Input to write (empty polls). '\\x03' sends Ctrl-C.",
+        },
+        "yieldMs": {"type": "integer", "description": "Wait for output (ms)."},
+        "maxOutput": {"type": "integer", "description": "Max bytes returned."},
+        "close": {
+            "type": "boolean",
+            "description": "Close the session instead of writing.",
+        },
+    },
+    "required": ["sessionId"],
+}
+
+
+# Harbor/headless already runs inside the trial container. Keep host-killing
+# rules (rm -rf /, fork bomb, chmod -R 777 /). Allow TB disk-image work:
+# password-recovery and qemu tasks use ``dd if=`` / mkfs as ordinary steps.
+_JAILED_DISABLED_SAFETY = ("sudo", "dd_if", "dd", "mkfs")
+
+#: Hard gate (CC read-before-write parity), ON by default: overwriting an
+#: existing file the session never read is rejected outright, not just
+#: conflict-checked. Set to 0/false/no/off to opt out. Creating new files
+#: stays allowed either way.
+_REQUIRE_READ_ENV = "STEERABLE_REQUIRE_READ_BEFORE_WRITE"
+
+#: Tools whose results carry ``data.path`` + ``data.version`` — the
+#: read-before-write evidence a resumed session can re-seed from.
+_FILE_STATE_TOOLS = frozenset({"read_file", "write_file", "edit_file"})
+
+
+def read_file_state_from_messages(messages: Iterable[LLMMessage]) -> dict[str, str]:
+    """Rebuild path → version evidence from recorded file-tool results.
+
+    The durable record's tool messages carry the full result JSON
+    (``data.path`` / ``data.version``; ``apply_patch`` carries a
+    ``data.versions`` mapping), so a resumed session re-seeds its
+    read-before-write state without the model re-reading everything — CC
+    ``seed_read_state`` parity. Entries that fail to parse (spilled or
+    folded bodies) are skipped: a missing entry only means one fewer CAS
+    check, never a wrong write. Later entries overwrite earlier ones, so the
+    state ends at each path's latest recorded version.
+    """
+    state: dict[str, str] = {}
+    for message in messages:
+        if message.role != "tool":
+            continue
+        try:
+            payload = json.loads(message.content_text)
+        except ValueError:
+            continue
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if not isinstance(data, dict):
+            continue
+        if message.name == "apply_patch":
+            versions = data.get("versions")
+            if isinstance(versions, dict):
+                for path, version in versions.items():
+                    if isinstance(path, str) and isinstance(version, str):
+                        state[path] = version
+            continue
+        if message.name not in _FILE_STATE_TOOLS:
+            continue
+        path = data.get("path")
+        version = data.get("version")
+        if isinstance(path, str) and isinstance(version, str):
+            state[path] = version
+    return state
+
+
+def workspace_tools_for_cwd(
+    cwd: str | Path,
+    *,
+    jailed: bool = False,
+    fs: WorkspaceFs = LOCAL_FS,
+    run_command: BashRunner | None = None,
+    web_tools: bool = True,
+    run_code: bool | None = None,
+    ptc_js: bool | None = None,
+    read_file_state: dict[str, str] | None = None,
+) -> ToolRouter:
+    """Return a router whose bash/read/write calls stay under ``cwd``.
+
+    ``jailed=True`` is for Harbor/headless: the process already runs inside
+    the trial container, so ``sudo`` and ``dd if=`` are normal TB agent steps,
+    not host privilege escalation. ``rm -rf /`` stays critical. File tools
+    may write anywhere in the container (hidden tests name ``/tmp`` and
+    ``/app``); non-jailed ACP sessions stay cwd-scoped.
+
+    ``fs`` is the file-content channel (3.4.3.1) and ``run_command`` the
+    one-shot bash execution (3.4.3.2); both default to local disk and a
+    local subprocess.
+
+    ``web_tools=False`` omits the network-read pair. A caller whose task
+    contract is offline must say so: TB 2.1 tasks are solved from the
+    container alone, and a reachable ``web_fetch`` both confounds a harness
+    comparison and lets a trial answer from outside the environment under
+    test. ``capture_display`` stays registered: it reads a display inside
+    the workspace, not the public web.
+
+    ``run_code`` defaults to ``STEERABLE_RUN_CODE=1``. Harbor does not
+    special-case it the way web tools are omitted; leave the env unset
+    unless the trial wants programmatic tool calls.
+
+    ``read_file_state`` is the session's read-before-write evidence
+    (path → version of the last content read or written, CC ``readFileState``
+    parity). The caller owns the dict so the evidence survives per-prompt
+    router rebuilds (ACP) and can be re-seeded from the durable record on
+    resume (``read_file_state_from_messages``); ``None`` starts fresh.
+    Writes and edits auto-check it when the model passes no explicit
+    ``expectedVersion``, and refresh it after every successful write.
+    The hard gate is ON by default (CC parity): overwriting an existing
+    file the session never read is rejected outright, and so is a full
+    overwrite of a file the session only read partially (display clipped
+    at ``_MAX_OUTPUT``; a CAS-checked ``edit_file`` stays allowed).
+    ``STEERABLE_REQUIRE_READ_BEFORE_WRITE=0`` opts out; creating new files
+    is never gated.
+    """
+    root = Path(cwd).expanduser().resolve()
+    safety = (
+        CommandSafetyConfig(disabled_pattern_ids=list(_JAILED_DISABLED_SAFETY))
+        if jailed
+        else None
+    )
+    router = ToolRouter(shell_safety=safety)
+    # Per-path serialisation for read-modify-write, so concurrent edits to the
+    # same file cannot interleave (pi's file-mutation-queue). Keyed by resolved
+    # path; distinct files proceed independently.
+    file_locks: dict[str, asyncio.Lock] = {}
+    read_state = read_file_state if read_file_state is not None else {}
+    # Tracks files the session read only partially (display clipped at
+    # _MAX_OUTPUT): the model has not seen the whole content, so a blind
+    # full-file overwrite is rejected (CC isPartialView parity) while a
+    # CAS-checked edit stays allowed. Cleared by a full read or a write.
+    partial_reads: set[str] = set()
+    require_read_before_write = (os.environ.get(_REQUIRE_READ_ENV) or "").strip() not in {
+        "0",
+        "false",
+        "no",
+        "off",
+    }
+
+    def _lock_for(target: Path) -> asyncio.Lock:
+        key = str(target)
+        lock = file_locks.get(key)
+        if lock is None:
+            lock = asyncio.Lock()
+            file_locks[key] = lock
+        return lock
+
+    def _conflict_message(target: Path) -> str:
+        return (
+            f"冲突：{target} 在你读取后已被修改（版本令牌不匹配）。为避免覆盖"
+            "他人/其它操作的改动，本次写入已拒绝——请重新 read_file 拿到最新"
+            "内容与 version，再基于它重新编辑。"
+        )
+
+    async def _exists(target: Path) -> bool:
+        if isinstance(fs, LocalFs):
+            return target.exists()
+        try:
+            await fs.read_text(target)
+        except (OSError, ValueError, WorkspaceFsError):
+            return False
+        return True
+
+    async def _check_version(
+        target: Path, expected: str, *, automatic: bool = False
+    ) -> str | None:
+        try:
+            current = await fs.read_text(target)
+        except (OSError, WorkspaceFsError):
+            # Auto-CAS guards files the session read; one that vanished since
+            # makes the write a plain create, not an overwrite.
+            if automatic:
+                return None
+            return (
+                f"无法冲突检测：读取 {target} 失败（文件可能不存在）。"
+                "若确认要新建，请去掉 expectedVersion。"
+            )
+        except ValueError:
+            # No longer the UTF-8 text the session read — treat as changed.
+            return _conflict_message(target)
+        if content_version(current) != expected:
+            return _conflict_message(target)
+        return None
+
+    def _effective_expected(target: Path, expected_version: str | None) -> str | None:
+        """Explicit expectedVersion wins; otherwise fall back to the session's
+        read state (automatic CAS)."""
+        if expected_version is not None:
+            return expected_version
+        return read_state.get(str(target))
+
+    def _run_bash(
+        command: str, cwd: Path, live_pids: list[int] | None = None
+    ) -> ToolResult:
+        # Shells reset SIGHUP on exec; trap so background qemu-system
+        # survives this tool returning (session-leader HUP).
+        proc = subprocess.Popen(
+            "trap '' HUP; " + command,
+            shell=True,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            start_new_session=True,
+        )
+        if live_pids is not None:
+            live_pids.append(proc.pid)
+        try:
+            stdout, stderr = proc.communicate(timeout=_BASH_TIMEOUT_SEC)
+        except subprocess.TimeoutExpired:
+            _kill_process_group(proc.pid)
+            try:
+                proc.communicate(timeout=5)
+            except (subprocess.TimeoutExpired, OSError):
+                pass
+            return ToolResult(
+                success=False,
+                error=f"bash timed out after {_BASH_TIMEOUT_SEC}s",
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=proc.returncode == 0,
+            data={
+                "exitCode": proc.returncode,
+                "stdout": _clip(stdout or ""),
+                "stderr": _clip(stderr or ""),
+            },
+            error=None if proc.returncode == 0 else f"exit {proc.returncode}",
+            needsFollowup=proc.returncode != 0,
+        )
+
+    async def _run_local(command: str, cwd: Path) -> ToolResult:
+        # Off the event loop so CoreLoop parallel_tools can overlap bash.
+        # Cancelling this await (tool timeout / hard timeout) must kill the
+        # session; otherwise communicate(timeout=3600) pins the default
+        # executor and Harbor never sees EOF.
+        live_pids: list[int] = []
+        try:
+            return await asyncio.to_thread(_run_bash, command, cwd, live_pids)
+        except asyncio.CancelledError:
+            if live_pids:
+                _kill_process_group(live_pids[0])
+            raise
+
+    run = run_command or _run_local
+
+    async def bash(command: str = "", cmd: str = "", script: str = "") -> ToolResult:
+        command = command or cmd or script
+        if not command or not command.strip():
+            return ToolResult(success=False, error="command is empty", needsFollowup=True)
+        if pgrep_self_wait(command):
+            return ToolResult(
+                success=False, error=_PGREP_WAIT_ERROR, needsFollowup=True
+            )
+        if sleep_poll(command):
+            return ToolResult(
+                success=False, error=_SLEEP_POLL_ERROR, needsFollowup=True
+            )
+        if short_timeout_wrap(command):
+            return ToolResult(
+                success=False, error=_SHORT_TIMEOUT_ERROR, needsFollowup=True
+            )
+        if follow_log_wait(command):
+            return ToolResult(
+                success=False, error=_FOLLOW_LOG_ERROR, needsFollowup=True
+            )
+        return await run(command, root)
+
+    async def read_file(path: str) -> ToolResult:
+        try:
+            target = _resolve_under(root, path, jailed=jailed)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        if isinstance(fs, LocalFs):
+            # Byte path: binary files get an ASCII preview instead of a
+            # decode failure (Harbor image/PNG tasks).
+            try:
+                raw = target.read_bytes()
+            except (OSError, ValueError) as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            try:
+                text = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                return _binary_read_result(target, raw)
+        else:
+            try:
+                text = await fs.read_text(target)
+            except (OSError, ValueError, WorkspaceFsError) as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        clipped = _clip(text)
+        version = content_version(text)
+        read_state[str(target)] = version
+        partial = len(clipped) != len(text)
+        if partial:
+            partial_reads.add(str(target))
+        else:
+            partial_reads.discard(str(target))
+        return ToolResult(
+            success=True,
+            data={
+                "path": str(target),
+                "content": clipped,
+                # Version of the FULL content (not the clipped preview), so a
+                # read-before-write token stays valid even on large files.
+                "version": version,
+                # The model only SAW the clipped preview; a full overwrite
+                # would destroy content it never read (CC isPartialView).
+                "partial": partial,
+            },
+        )
+
+    async def view_image(
+        path: str,
+        region: dict[str, float] | None = None,
+        maxEdge: int = _IMAGE_DEFAULT_MAX_EDGE,
+        format: str | None = None,
+    ) -> ToolResult:
+        try:
+            target = _resolve_under(root, path, jailed=jailed)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        try:
+            raw = target.read_bytes()
+        except (OSError, ValueError) as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        if len(raw) > _IMAGE_MAX_SOURCE_BYTES:
+            return ToolResult(
+                success=False,
+                error=(
+                    f"{target} is {len(raw)} bytes, over the "
+                    f"{_IMAGE_MAX_SOURCE_BYTES}-byte source limit."
+                ),
+                needsFollowup=True,
+            )
+        if (
+            isinstance(maxEdge, bool)
+            or not isinstance(maxEdge, int)
+            or maxEdge < 1
+            or maxEdge > 4096
+        ):
+            return ToolResult(
+                success=False,
+                error="maxEdge must be an integer from 1 through 4096",
+                needsFollowup=True,
+            )
+        if format not in (None, "png", "jpeg"):
+            return ToolResult(
+                success=False,
+                error="format must be png or jpeg",
+                needsFollowup=True,
+            )
+        try:
+            with Image.open(BytesIO(raw)) as opened:
+                opened.load()
+                source_format = (opened.format or "").upper()
+                image = opened.copy()
+        except (OSError, UnidentifiedImageError):
+            return ToolResult(
+                success=False,
+                error=(
+                    f"{target} is not a readable PNG, JPEG, WebP, or BMP image "
+                    f"({len(raw)} bytes)."
+                ),
+                needsFollowup=True,
+            )
+
+        if region is not None:
+            try:
+                crop = _resolve_image_region(region, image.width, image.height)
+            except ValueError as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            image = image.crop(crop)
+
+        if max(image.size) > maxEdge:
+            image.thumbnail((maxEdge, maxEdge), Image.Resampling.LANCZOS)
+
+        output_format = format or ("jpeg" if source_format in {"JPEG", "JPG"} else "png")
+        encoded = BytesIO()
+        if output_format == "jpeg":
+            image.convert("RGB").save(encoded, format="JPEG", quality=85, optimize=True)
+            media_type = "image/jpeg"
+        else:
+            image.save(encoded, format="PNG", optimize=True)
+            media_type = "image/png"
+        pixels = encoded.getvalue()
+        if (
+            len(pixels) > _VIEW_IMAGE_MAX_ENCODED_BYTES
+            and format is None
+            and output_format == "png"
+        ):
+            encoded = BytesIO()
+            image.convert("RGB").save(encoded, format="JPEG", quality=80, optimize=True)
+            pixels = encoded.getvalue()
+            media_type = "image/jpeg"
+        if len(pixels) > _VIEW_IMAGE_MAX_ENCODED_BYTES:
+            return ToolResult(
+                success=False,
+                error=(
+                    f"{target} is {len(pixels)} bytes, over the "
+                    f"{_VIEW_IMAGE_MAX_ENCODED_BYTES}-byte attach limit. Reduce maxEdge "
+                    "or use format=jpeg."
+                ),
+                needsFollowup=True,
+            )
+        blob = _image_blob(pixels, max_bytes=_VIEW_IMAGE_MAX_ENCODED_BYTES)
+        assert blob is not None
+        data: dict[str, object] = {
+            "sourcePath": str(target),
+            "width": image.width,
+            "height": image.height,
+            "mediaType": blob["media_type"],
+            "_image": blob,
+        }
+        preview = ascii_png_preview(pixels)
+        if preview is not None:
+            data["content"] = preview
+        return ToolResult(success=True, data=data)
+
+    async def write_file(
+        path: str, content: str, expectedVersion: str | None = None
+    ) -> ToolResult:
+        try:
+            target = _resolve_under(root, path, jailed=jailed)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        async with _lock_for(target):
+            try:
+                expected = _effective_expected(target, expectedVersion)
+                if (
+                    expected is None
+                    and require_read_before_write
+                    and await _exists(target)
+                ):
+                    return ToolResult(
+                        success=False,
+                        error=(
+                            f"拒绝写入：{target} 已存在但本会话尚未读过它"
+                            "（STEERABLE_REQUIRE_READ_BEFORE_WRITE）。请先 "
+                            "read_file 确认现有内容，再基于读到的 version 写入；"
+                            "新建文件不受此限。"
+                        ),
+                        needsFollowup=True,
+                    )
+                if str(target) in partial_reads:
+                    return ToolResult(
+                        success=False,
+                        error=(
+                            f"拒绝整体覆写：{target} 过大，本会话只读到部分内容"
+                            "（显示截断于 "
+                            f"{_MAX_OUTPUT} 字符），覆写会销毁未见内容。请改用 "
+                            "edit_file 做定点修改；确需整体重写时先分段读完。"
+                        ),
+                        needsFollowup=True,
+                    )
+                if expected is not None:
+                    conflict = await _check_version(
+                        target, expected, automatic=expectedVersion is None
+                    )
+                    if conflict:
+                        return ToolResult(
+                            success=False, error=conflict, needsFollowup=True
+                        )
+                if isinstance(fs, LocalFs):
+                    shrink = _truncated_overwrite_error(target, content)
+                    if shrink:
+                        return ToolResult(
+                            success=False, error=shrink, needsFollowup=True
+                        )
+                # LocalFs.write_text is write-then-rename: a crash mid-write
+                # never leaves a truncated file, and parents are created.
+                await fs.write_text(target, content)
+            except (OSError, ValueError, WorkspaceFsError) as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            version = content_version(content)
+            # Our own write is the freshest known state — without the update
+            # the next auto-CAS write would reject against the pre-write
+            # version (iterative editing is the norm). The model authored the
+            # full content, so the partial-view bar no longer applies.
+            read_state[str(target)] = version
+            partial_reads.discard(str(target))
+            return ToolResult(
+                success=True,
+                data={
+                    "path": str(target),
+                    "bytes": len(content.encode("utf-8")),
+                    "version": version,
+                },
+            )
+
+    async def edit_file(
+        path: str, edits: list[dict], expectedVersion: str | None = None
+    ) -> ToolResult:
+        try:
+            target = _resolve_under(root, path, jailed=jailed)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        ops = [
+            EditOp(old_text=str(e.get("oldText", "")), new_text=str(e.get("newText", "")))
+            for e in edits
+            if isinstance(e, dict)
+        ]
+        async with _lock_for(target):
+            try:
+                current = await fs.read_text(target)
+            except (OSError, WorkspaceFsError) as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            expected = _effective_expected(target, expectedVersion)
+            if expected is None and require_read_before_write:
+                # edit_file only reaches here on an existing file (the read
+                # above succeeded), so the gate is unconditional.
+                return ToolResult(
+                    success=False,
+                    error=(
+                        f"拒绝编辑：{target} 已存在但本会话尚未读过它"
+                        "（STEERABLE_REQUIRE_READ_BEFORE_WRITE）。请先 "
+                        "read_file 确认现有内容，再基于读到的 version 编辑。"
+                    ),
+                    needsFollowup=True,
+                )
+            # Compare against the copy already read for this edit — no
+            # second read, and the check covers the auto-CAS fallback too.
+            if expected is not None and content_version(current) != expected:
+                return ToolResult(
+                    success=False, error=_conflict_message(target), needsFollowup=True
+                )
+            try:
+                result = apply_edits(current, ops, file_path=target.name)
+            except EditError as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            try:
+                await fs.write_text(target, result.content)
+            except (OSError, WorkspaceFsError) as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            version = content_version(result.content)
+            read_state[str(target)] = version
+            return ToolResult(
+                success=True,
+                data={
+                    "path": str(target),
+                    "version": version,
+                    "diff": result.diff,
+                    "applied": len(result.matches),
+                    "matches": [
+                        {
+                            "level": m.level,
+                            "startLine": m.start_line,
+                            "oldLineCount": m.old_line_count,
+                        }
+                        for m in result.matches
+                    ],
+                },
+            )
+
+    router.register(
+        bash,
+        name="bash",
+        mode="other",
+        description=(
+            "Run a shell command in the workspace directory. The working "
+            "directory persists across calls; exported variables and aliases "
+            "do not — use bash_session for that."
+        ),
+        schema=_BASH_SCHEMA,
+        require_consent=False,
+        metadata={"shell_command_param": "command"},
+    )
+    read_desc = (
+        "Read a UTF-8 text file from the workspace. Prefer an absolute path. "
+        "PNG/JPEG files attach as images the model can see, plus an ASCII preview."
+        if _read_images_enabled()
+        else (
+            "Read a UTF-8 text file from the workspace. Prefer an absolute path. "
+            "PNG/JPEG/BMP files return an ASCII preview, not UTF-8; view_image "
+            "shows the pixels."
+        )
+    )
+    router.register(
+        read_file,
+        name="read_file",
+        mode="read",
+        description=read_desc,
+        schema=_READ_SCHEMA,
+        require_consent=False,
+    )
+    router.register(
+        view_image,
+        name="view_image",
+        mode="read",
+        description=(
+            "Look at a PNG, JPEG, WebP, or BMP image. The result contains an "
+            "actual image part you can see, not a path or base64 text. Use "
+            "region for a pixel or normalized 0–1 crop, maxEdge to bound the "
+            "longest edge, and format=jpeg to reduce payload size."
+        ),
+        schema=_VIEW_IMAGE_SCHEMA,
+        require_consent=False,
+    )
+    router.register(
+        write_file,
+        name="write_file",
+        mode="safe_write",
+        description="Write a UTF-8 text file in the workspace (creates parents).",
+        schema=_WRITE_SCHEMA,
+        require_consent=False,
+    )
+    router.register(
+        edit_file,
+        name="edit_file",
+        mode="safe_write",
+        description=(
+            "Make targeted edits to an existing file WITHOUT rewriting it whole. "
+            "Each edit's oldText is located (exact → whitespace-tolerant → "
+            "Unicode-normalised) and replaced by newText; all edits match against "
+            "the original, must not overlap, and apply together. Prefer this over "
+            "write_file when modifying existing files."
+        ),
+        schema=_EDIT_SCHEMA,
+        require_consent=False,
+    )
+
+    # W1.4.1: structured search + atomic multi-file patch. These replace the
+    # bash idioms (grep -r, find, hand-rolled sed loops) whose raw output
+    # burned context and whose partial writes corrupted workspaces.
+    def grep(
+        query: str,
+        isRegex: bool = False,
+        ignoreCase: bool = False,
+        limit: int = 200,
+    ) -> ToolResult:
+        from .search_tools import search
+
+        try:
+            hits = search(
+                root, query, is_regex=isRegex, ignore_case=ignoreCase, limit=limit
+            )
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        return ToolResult(
+            success=True,
+            data={
+                "hits": [
+                    {"path": h.path, "line": h.line, "text": h.text} for h in hits
+                ],
+                "truncated": len(hits) >= min(max(1, limit), 1000),
+            },
+        )
+
+    def glob(pattern: str, limit: int = 200) -> ToolResult:
+        from .search_tools import glob_files
+
+        try:
+            paths = glob_files(root, pattern, limit=limit)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        return ToolResult(success=True, data={"paths": paths})
+
+    async def apply_patch_tool(patches: list[dict]) -> ToolResult:
+        from .multi_file_edit import FilePatch, apply_patch
+
+        entries = [
+            FilePatch(
+                path=str(p.get("path", "")),
+                edits=tuple(
+                    EditOp(
+                        old_text=str(e.get("oldText", "")),
+                        new_text=str(e.get("newText", "")),
+                    )
+                    for e in p.get("edits", [])
+                    if isinstance(e, dict)
+                ),
+            )
+            for p in patches
+            if isinstance(p, dict)
+        ]
+        # Serialise against concurrent single-file edits: a patch touching a
+        # file another edit holds must not interleave its read-modify-write.
+        try:
+            targets = sorted({_resolve_under(root, p.path) for p in entries})
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        locks = [_lock_for(t) for t in targets]
+        for lock in locks:
+            await lock.acquire()
+        try:
+            summary = await apply_patch(
+                root,
+                entries,
+                resolve=lambda p: _resolve_under(root, p),
+                fs=fs,
+            )
+            # Same write-updates-state rule as write_file/edit_file: later
+            # auto-CAS checks must compare against the post-patch versions.
+            for changed_path, changed_version in summary.versions:
+                read_state[changed_path] = changed_version
+        except (ValueError, EditError) as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        finally:
+            for lock in locks:
+                lock.release()
+        return ToolResult(
+            success=True,
+            data={
+                "filesChanged": list(summary.files_changed),
+                "diffs": list(summary.diffs),
+                # Resolved path → version, so the durable record carries the
+                # evidence a resumed session re-seeds from.
+                "versions": dict(summary.versions),
+            },
+        )
+
+    router.register(
+        grep,
+        name="grep",
+        mode="read",
+        description=(
+            "Search file contents across the workspace (ripgrep when available). "
+            "Returns structured {path, line, text} hits; the workspace ignore "
+            "set (node_modules, .git, …) is always applied. Call this instead of "
+            "bash grep, rg, or find."
+        ),
+        schema=_GREP_SCHEMA,
+        require_consent=False,
+    )
+    router.register(
+        glob,
+        name="glob",
+        mode="read",
+        description=(
+            "List workspace files matching an fnmatch pattern. The ignore set "
+            "is shared with grep. Call this instead of bash find or ls."
+        ),
+        schema=_GLOB_SCHEMA,
+        require_consent=False,
+    )
+    router.register(
+        apply_patch_tool,
+        name="apply_patch",
+        mode="safe_write",
+        description=(
+            "Edit several files in one atomic call: all files are planned "
+            "against original bytes, then written; any failure rolls back "
+            "everything. Prefer this over multiple edit_file calls when a "
+            "change spans files."
+        ),
+        schema=_APPLY_PATCH_SCHEMA,
+        require_consent=False,
+    )
+
+    # W1.5: persistent interactive shell sessions (REPLs, prompts, Ctrl-C).
+    # The manager is exposed on the router so the owner (headless run,
+    # sidecar shutdown) can close_all() — sessions are real processes.
+    from .shell_session import ShellSessionManager
+
+    shell_sessions = ShellSessionManager()
+    router.shell_sessions = shell_sessions  # type: ignore[attr-defined]
+
+    def bash_session(
+        command: str | None = None,
+        yieldMs: int = 1000,
+        maxOutput: int = 30_000,
+    ) -> ToolResult:
+        try:
+            read = shell_sessions.open(
+                cwd=root, command=command, yield_ms=yieldMs, max_output=maxOutput
+            )
+        except (ValueError, OSError) as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        return ToolResult(
+            success=True,
+            data={
+                "sessionId": read.session_id,
+                "output": read.output,
+                "exited": read.exited,
+                "exitCode": read.exit_code,
+            },
+        )
+
+    def write_stdin(
+        sessionId: str,
+        chars: str = "",
+        yieldMs: int = 1000,
+        maxOutput: int = 30_000,
+        close: bool = False,
+    ) -> ToolResult:
+        try:
+            if close:
+                shell_sessions.close(sessionId)
+                return ToolResult(success=True, data={"sessionId": sessionId, "closed": True})
+            read = shell_sessions.write_stdin(
+                sessionId, chars, yield_ms=yieldMs, max_output=maxOutput
+            )
+        except (ValueError, OSError) as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        return ToolResult(
+            success=True,
+            data={
+                "sessionId": read.session_id,
+                "output": read.output,
+                "exited": read.exited,
+                "exitCode": read.exit_code,
+            },
+        )
+
+    router.register(
+        bash_session,
+        name="bash_session",
+        mode="other",
+        description=(
+            "Open a persistent interactive shell session (a real terminal: "
+            "REPLs, prompts, and Ctrl-C work). Returns a sessionId; feed it "
+            "with write_stdin. Prefer plain bash for one-shot commands."
+        ),
+        schema=_BASH_SESSION_SCHEMA,
+        require_consent=False,
+        metadata={"shell_command_param": "command"},
+    )
+    router.register(
+        write_stdin,
+        name="write_stdin",
+        mode="other",
+        description=(
+            "Write to a bash_session's stdin (empty chars polls output) or "
+            "close it. Send '\\x03' for Ctrl-C."
+        ),
+        schema=_WRITE_STDIN_SCHEMA,
+        require_consent=False,
+    )
+
+    async def capture_display(
+        target: str,
+        path: str | None = None,
+        nudge: bool = False,
+    ) -> ToolResult:
+        from .display import DisplayError, capture_rfb, parse_display_target
+
+        try:
+            spec = parse_display_target(target)
+        except ValueError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        try:
+            frame = await asyncio.to_thread(
+                capture_rfb, spec.host, spec.port, nudge=bool(nudge)
+            )
+        except DisplayError as exc:
+            return ToolResult(success=False, error=str(exc), needsFollowup=True)
+        png = encode_png_rgb(frame.width, frame.height, frame.rgb)
+        preview = ascii_png_preview(png) or f"PNG {frame.width}x{frame.height}"
+        data: dict[str, object] = {
+            "target": spec.canonical,
+            "protocol": spec.protocol,
+            "host": spec.host,
+            "port": spec.port,
+            "width": frame.width,
+            "height": frame.height,
+            "nudged": bool(nudge),
+            "content": preview,
+            "kind": "png_ascii",
+        }
+        if path:
+            try:
+                dest = _resolve_under(root, path, jailed=jailed)
+            except ValueError as exc:
+                return ToolResult(success=False, error=str(exc), needsFollowup=True)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(png)
+            data["path"] = str(dest)
+        blob = _image_blob(png)
+        if blob is not None:
+            data["_image"] = blob
+        return ToolResult(success=True, data=data)
+
+    router.register(
+        capture_display,
+        name="capture_display",
+        mode="read",
+        description=(
+            "Capture the client-visible remote display (RFB/VNC framebuffer). "
+            "Use this when a VM, noVNC page, or grader will look at VNC — "
+            "not QEMU screendump or another hypervisor-private screenshot. "
+            "The PNG is attached as an image you can look at; the JSON is "
+            "only an ASCII preview. Optional path writes the PNG."
+        ),
+        schema=_CAPTURE_DISPLAY_SCHEMA,
+        require_consent=False,
+    )
+
+    # web_search / web_fetch: the network-read pair. Registered here so the
+    # headless and ACP surfaces carry the same implementation the desktop
+    # delegates to; web_search only registers when a search backend is
+    # configured (see web_tools.py). A malformed STEERABLE_WEB_* bound raises
+    # here — headless/ACP fail at load rather than run with untended bounds.
+    if web_tools:
+        from .web_tools import register_web_tools
+
+        register_web_tools(router)
+    if run_code is None:
+        from .run_code import run_code_enabled as _run_code_enabled
+
+        run_code = _run_code_enabled()
+    if run_code:
+        from .run_code import register_run_code
+
+        register_run_code(router)
+    if ptc_js is None:
+        from .ptc_js import ptc_js_enabled as _ptc_js_enabled
+
+        ptc_js = _ptc_js_enabled()
+    if ptc_js:
+        from .ptc_js import register_ptc_js
+
+        register_ptc_js(router)
+    return router
+
+
+def refuse_truncated_overwrite(existing_bytes: int, new_bytes: int) -> bool:
+    """True when replacing a large file with a much smaller body."""
+    if existing_bytes < _MIN_KEEP_BYTES:
+        return False
+    return new_bytes < max(512, existing_bytes // 4)
+
+
+def _read_images_enabled() -> bool:
+    raw = os.environ.get("STEERABLE_READ_IMAGES")
+    if raw is None or not str(raw).strip():
+        return False
+    return str(raw).strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _image_blob(
+    raw: bytes, *, max_bytes: int = _IMAGE_ATTACH_MAX_BYTES
+) -> dict[str, str] | None:
+    """PNG/JPEG bytes for the next LLM request; None if too large or not those types.
+
+    ``read_file`` decides whether to call this. ``capture_display`` and
+    ``view_image`` always do: both exist so the model can look at something,
+    and neither has a job left once the pixels are dropped.
+    """
+    if len(raw) > max_bytes:
+        return None
+    if raw.startswith(b"\x89PNG"):
+        media = "image/png"
+    elif raw[:2] == b"\xff\xd8":
+        media = "image/jpeg"
+    else:
+        return None
+    return {
+        "b64": base64.b64encode(raw).decode("ascii"),
+        "media_type": media,
+    }
+
+
+def _resolve_image_region(
+    region: dict[str, float], width: int, height: int
+) -> tuple[int, int, int, int]:
+    """Resolve a pixel or all-normalized crop into Pillow's box coordinates."""
+    try:
+        values = tuple(float(region[key]) for key in ("x", "y", "w", "h"))
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ValueError("region requires finite numeric x, y, w, and h") from exc
+    if not all(math.isfinite(value) for value in values):
+        raise ValueError("region requires finite numeric x, y, w, and h")
+    x_value, y_value, w_value, h_value = values
+    normalized = all(0 <= value <= 1 for value in values)
+    if normalized:
+        x = int(x_value * width)
+        y = int(y_value * height)
+        crop_width = math.ceil(w_value * width)
+        crop_height = math.ceil(h_value * height)
+    else:
+        x = round(x_value)
+        y = round(y_value)
+        crop_width = round(w_value)
+        crop_height = round(h_value)
+    if (
+        x < 0
+        or y < 0
+        or crop_width < 1
+        or crop_height < 1
+        or x + crop_width > width
+        or y + crop_height > height
+    ):
+        raise ValueError(f"region exceeds image bounds {width}x{height}")
+    return x, y, x + crop_width, y + crop_height
+
+
+def _attachable_pixels(raw: bytes) -> bytes | None:
+    """Bytes a vision endpoint accepts: PNG/JPEG as they are, BMP re-encoded.
+
+    ``None`` when the bytes are not an image this module can hand to a model.
+    """
+    if raw.startswith(b"\x89PNG") or raw[:2] == b"\xff\xd8":
+        return raw
+    decoded = decode_bmp_rgb(raw)
+    if decoded is None:
+        return None
+    width, height, rgb = decoded
+    return encode_png_rgb(width, height, rgb)
+
+
+def _binary_read_result(target: Path, raw: bytes) -> ToolResult:
+    """Tool result for a non-UTF-8 file: ASCII preview when the image format
+    is known, otherwise a decode instruction (never a guessed content)."""
+    preview = ascii_png_preview(raw)
+    if preview is not None:
+        data: dict[str, object] = {
+            "path": str(target),
+            "content": preview,
+            "kind": (
+                "jpeg_ascii"
+                if preview.startswith("JPEG ")
+                else "bmp_ascii"
+                if preview.startswith("BMP ")
+                else "png_ascii"
+            ),
+        }
+        blob = _image_blob(raw) if _read_images_enabled() else None
+        if blob is not None:
+            data["_image"] = blob
+        else:
+            data["pixels"] = (
+                f"ASCII preview only. Call view_image on {target} to see the image."
+            )
+        return ToolResult(success=True, data=data)
+    kind = (
+        "PNG"
+        if raw.startswith(b"\x89PNG")
+        else "JPEG"
+        if raw[:2] == b"\xff\xd8"
+        else "BMP"
+        if raw[:2] == b"BM"
+        else "binary"
+    )
+    hint = (
+        "Decode it with Python (PIL/numpy) or `file`"
+        if kind == "binary"
+        else "Call view_image to look at it, or decode it with Python (PIL/numpy)"
+    )
+    return ToolResult(
+        success=False,
+        error=(
+            f"{target} is {kind} ({len(raw)} bytes), not UTF-8 text. {hint}; "
+            "do not guess contents from the filename."
+        ),
+        needsFollowup=True,
+    )
+
+
+def _truncated_overwrite_error(target: Path, content: str) -> str | None:
+    try:
+        existing = target.stat().st_size
+    except OSError:
+        return None
+    new_len = len(content.encode("utf-8"))
+    if not refuse_truncated_overwrite(existing, new_len):
+        return None
+    return (
+        f"Refusing to overwrite {existing}-byte {target} with {new_len} bytes. "
+        "The existing file is already complete. Use edit_file for a patch, or "
+        "bash to replace it after reading the current contents."
+    )
+
+
+def pgrep_self_wait(command: str) -> bool:
+    """True when ``command`` is a ``while pgrep -f`` wait that matches itself."""
+    return bool(_PGREP_SELF_WAIT.search(command or ""))
+
+
+def sleep_poll(command: str) -> bool:
+    """True when ``command`` is a long sleep followed by cat/tail/ls/head."""
+    for match in _SLEEP_POLL.finditer(command or ""):
+        if int(match.group(1)) >= _SLEEP_POLL_MIN_SEC:
+            return True
+    return False
+
+
+def short_timeout_wrap(command: str) -> bool:
+    """True when ``command`` wraps compile/VM in ``timeout N`` with N under 300s."""
+    for match in _SHORT_TIMEOUT.finditer(command or ""):
+        if int(match.group(1)) <= _SHORT_TIMEOUT_MAX_SEC:
+            return True
+    return False
+
+
+def follow_log_wait(command: str) -> bool:
+    """True when ``command`` follows a file with ``tail -f`` / ``--follow``.
+
+    A one-shot ``tail -n 20`` is fine. ``tail -f … | grep -m1`` is not:
+    bash holds the loop until the compile finishes or Harbor kills the trial.
+    """
+    text = command or ""
+    return any(
+        _FOLLOW_LOG_FLAG.search(chunk.group(0))
+        for chunk in _FOLLOW_LOG_CMD.finditer(text)
+    )
+
+
+def _resolve_under(root: Path, path: str, *, jailed: bool = False) -> Path:
+    if not path or not str(path).strip():
+        raise ValueError("path is empty")
+    raw = Path(path)
+    target = raw.resolve() if raw.is_absolute() else (root / raw).resolve()
+    if not jailed and target != root and root not in target.parents:
+        raise ValueError(f"path escapes workspace: {path}")
+    return target
+
+
+def _kill_process_group(pid: int) -> None:
+    """SIGKILL the bash session, not only the shell, so pipelines release pipes."""
+    if hasattr(os, "killpg"):
+        try:
+            os.killpg(pid, signal.SIGKILL)
+            return
+        except (ProcessLookupError, PermissionError, OSError):
+            pass
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError, OSError):
+        pass
+
+
+def _clip(text: str) -> str:
+    """Bound tool output without dropping the tail.
+
+    Catalog-89 train/compile logs put the accuracy line, linker error, or
+    qemu boot banner at the end. A prefix-only clip (then spill of that
+    prefix) hid those lines, so the model stopped on a truncated success
+    or never saw the failure.
+    """
+    if len(text) <= _MAX_OUTPUT:
+        return text
+    head = _MAX_OUTPUT // 5
+    tail = _MAX_OUTPUT - head
+    omitted = len(text) - head - tail
+    return f"{text[:head]}\n...[{omitted} chars truncated]...\n{text[-tail:]}"