python-agent-harness 1.5.4.1__tar.gz → 1.5.4.3__tar.gz

{python_agent_harness-1.5.4.1/python_agent_harness.egg-info → python_agent_harness-1.5.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.4.1
+Version: 1.5.4.3
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author: huming
 License-Expression: MIT
@@ -146,8 +146,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     }
   },
   "context_windows": {
-    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or fnmatch patterns (e.g. deepseek-v4* = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py.",
-    "deepseek-v4*": 1000000
+    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g. deepseek-v4 = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py.",
+    "deepseek-v4": 1000000
   },
   "subagent_llm": {
     "profile": null,
@@ -188,7 +188,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 - **`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
-- **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or fnmatch patterns (e.g., `deepseek-v4*`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
+- **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
@@ -248,7 +248,7 @@ python_agent_harness/
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and macOS.
 
 ```sh
 make test                           # unit tests

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/README.md

@@ -123,8 +123,8 @@ All LLM settings live in a single JSON configuration file. Environment variables
     }
   },
   "context_windows": {
-    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or fnmatch patterns (e.g. deepseek-v4* = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py.",
-    "deepseek-v4*": 1000000
+    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g. deepseek-v4 = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py.",
+    "deepseek-v4": 1000000
   },
   "subagent_llm": {
     "profile": null,
@@ -165,7 +165,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 - **`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
-- **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or fnmatch patterns (e.g., `deepseek-v4*`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
+- **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
@@ -225,7 +225,7 @@ python_agent_harness/
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and macOS.
 
 ```sh
 make test                           # unit tests

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.4.1"
+version = "1.5.4.3"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 readme = "README.md"
 requires-python = ">=3.11"

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/__init__.py

@@ -5,7 +5,7 @@ from .mcp.manager import MCPManager
 from .models import AgentMode, Message, ToolCall, ToolSpec
 from .session import Session
 
-__version__ = "1.5.4.1"
+__version__ = "1.5.4.3"
 
 __all__ = [
     "Session",

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/client.py

@@ -200,7 +200,7 @@ class Client:
     ) -> None:
         self.base_url = (base_url or config.DEFAULT_BASE_URL).rstrip("/")
         self.api_key = api_key or _default_api_key()
-        self.model = model or config.DEFAULT_MODEL
+        self.model: str = model or config.DEFAULT_MODEL
         self.timeout = timeout
         self.verify = verify if verify is not None else _resolve_ca_bundle()
         self.retry_max = config.API_RETRY_MAX if retry_max is None else retry_max
@@ -212,8 +212,6 @@ class Client:
         )
         self._config_path = config_path
         self._http = httpx.Client(timeout=timeout, verify=self.verify)
-        # Resolve context window for this model (API discovery + fallbacks)
-        self._context_window = None  # lazy-loaded
         # True while the in-flight request was aborted (Ctrl-C): a
         # connection error on an aborted request must NOT be retried —
         # the user asked to stop.  Cleared at the start of each chat()
@@ -233,19 +231,17 @@ class Client:
 
         Resolution order: config-file ``context_windows`` overrides
         (via ``config.get_context_window_for_model``) -> CONTEXT_WINDOWS
-        pattern match -> DEFAULT_CONTEXT_WINDOW.  The resolved value is
-        cached for the life of the client.
+        pattern match -> DEFAULT_CONTEXT_WINDOW.  Resolved on every
+        access (no caching), so a runtime model switch or config-file
+        edit takes effect immediately; a malformed config falls back to
+        the default for that access and recovers once the file is fixed.
         """
-        if self._context_window is None:
-            try:
-                self._context_window = config.get_context_window_for_model(
-                    self.model, config_path=self._config_path
-                )
-            except Exception:
-                # a malformed context_windows section must not break
-                # the loop: cache the safe default
-                self._context_window = config.DEFAULT_CONTEXT_WINDOW
-        return self._context_window
+        try:
+            return config.get_context_window_for_model(self.model, config_path=self._config_path)
+        except Exception:
+            # a malformed context_windows section must not break the
+            # loop: use the safe default, retry on the next access
+            return config.DEFAULT_CONTEXT_WINDOW
 
     def close(self) -> None:
         self._http.close()

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/config.py

@@ -5,7 +5,6 @@ Mirrors the defcustom defaults of the Emacs gptel-agent-harness.
 
 from __future__ import annotations
 
-import fnmatch
 import json
 import os
 from pathlib import Path
@@ -16,32 +15,22 @@ from .mcp.config import MCPConfig
 CONTEXT_TRIGGER = 0.70
 
 # Entries are matched in order (first match wins): put more specific
-# patterns before general ones. Supports wildcards (*).  Trailing `*`
-# on explicit entries preserves prefix matching for suffixed model
-# names (e.g. "deepseek-v4-flash" -> deepseek-v4*), matching the
-# legacy substring behavior.
+# patterns before general ones.
 CONTEXT_WINDOWS: list[tuple[str, int]] = [
-    ("gpt-5-mini*", 128_000),
-    ("gpt-5*", 400_000),
-    ("gpt-oss-120b*", 128_000),
-    ("claude*", 200_000),
-    ("deepseek-v3*", 128_000),
-    ("deepseek-v4*", 1_000_000),
-    ("qwen3.5*", 131_072),
-    ("qwen3.6*", 262_144),
-    ("qwen3.8*", 262_144),
-    ("qwen3*", 131_072),
-    ("glm-5.2*", 1_000_000),
-    ("glm-5.1*", 128_000),
-    ("kimi-k2.7*", 256_000),
-    ("kimi*", 128_000),
-    # Wildcard fallbacks for unknown models
-    ("gpt-*", 128_000),
-    ("claude-*", 200_000),
-    ("deepseek-*", 128_000),
-    ("qwen-*", 128_000),
-    ("glm-*", 128_000),
-    ("kimi-*", 128_000),
+    ("gpt-5-mini", 128_000),
+    ("gpt-5", 400_000),
+    ("gpt-oss-120b", 128_000),
+    ("claude", 200_000),
+    ("deepseek-v3", 128_000),
+    ("deepseek-v4", 1_000_000),
+    ("qwen3.5", 131_072),
+    ("qwen3.6", 262_144),
+    ("qwen3.8", 262_144),
+    ("qwen3", 131_072),
+    ("glm-5.2", 1_000_000),
+    ("glm-5.1", 128_000),
+    ("kimi-k2.7", 256_000),
+    ("kimi", 128_000),
 ]
 DEFAULT_CONTEXT_WINDOW = 128_000
 
@@ -233,8 +222,8 @@ CONFIG_TEMPLATE = """\
     }}
   }},
   "context_windows": {{
-    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or fnmatch patterns (e.g. deepseek-v4* = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py. Remove this section to use the built-in table.",
-    "deepseek-v4*": 1000000
+    "_comment": "Optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g. deepseek-v4 = 1000000); matched in file order, first match wins. Overrides the built-in CONTEXT_WINDOWS table in config.py. Remove this section to use the built-in table.",
+    "deepseek-v4": 1000000
   }},
   "subagent_llm": {{
     "_comment": "Optional overrides for sub-agent (Agent tool) requests, e.g. a cheaper model. Every key is optional; unset keys inherit the main llm settings above. Set 'profile' to a name from the 'models' section to reuse a model profile (profile settings win over explicit keys below).",
@@ -476,7 +465,7 @@ def mask_secret(value: str | None) -> str:
 
 
 def _match_context_window(model: str) -> int | None:
-    """Match model name against CONTEXT_WINDOWS patterns (supports wildcards).
+    """Match model name against CONTEXT_WINDOWS entries (substring match).
 
     Args:
         model: The model ID to match (e.g., "gpt-5-mini", "claude-3-opus")
@@ -486,7 +475,7 @@ def _match_context_window(model: str) -> int | None:
     """
     lowered = model.lower()
     for pattern, size in CONTEXT_WINDOWS:
-        if fnmatch.fnmatch(lowered, pattern.lower()):
+        if pattern.lower() in lowered:
             return size
     return None
 
@@ -497,7 +486,7 @@ def load_context_windows_config(
     """Load per-model context-window overrides from the config file.
 
     Reads the ``context_windows`` object: a mapping of model names or
-    fnmatch patterns (matched in file order, first match wins) to token
+    substrings (matched in file order, first match wins) to token
     counts.  Keys starting with ``_`` are comments and skipped.  A
     missing file, missing section, or unreadable JSON yields ``[]``
     (callers fall back to the built-in table); a malformed section or
@@ -530,7 +519,7 @@ def get_context_window_for_model(
     the built-in table, then the default.
 
     The config file's ``context_windows`` object (user overrides) is
-    consulted first (fnmatch over its patterns, first match wins,
+    consulted first (substring match over its keys, first match wins,
     case-insensitive); then the CONTEXT_WINDOWS table in config.py;
     then DEFAULT_CONTEXT_WINDOW.
 
@@ -544,7 +533,7 @@ def get_context_window_for_model(
     """
     lowered = model.lower()
     for pattern, size in load_context_windows_config(config_path):
-        if fnmatch.fnmatch(lowered, pattern.lower()):
+        if pattern.lower() in lowered:
             return size
     matched = _match_context_window(model)
     if matched is not None:

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/context_manager.py

@@ -21,9 +21,9 @@ class ContextManager:
     from the loop's delegate so the call site keeps resolving them
     through the ``agent`` module namespace (tests patch
     ``python_agent_harness.agent.estimate_payload_tokens``).  The
-    context window comes from the session's client (cached, config-
-    file aware); ``context_window_for`` is only the fallback for
-    clients without the property.
+    context window comes from the session's client (config-file aware,
+    resolved per access); ``context_window_for`` is only the fallback
+    for clients without the property.
     """
 
     def __init__(self, loop: Any) -> None:
@@ -42,9 +42,9 @@ class ContextManager:
         )
         loop.session.calibrator.last_raw_estimate = raw
         calibrated = loop.session.calibrator.calibrate(raw)
-        # Prefer the client's cached window (config overrides ->
-        # patterns -> default); fall back to the static resolver for
-        # clients without the property (test doubles).
+        # Prefer the client's window (config overrides -> patterns ->
+        # default, resolved per access); fall back to the static
+        # resolver for clients without the property (test doubles).
         client = loop.session.client
         window = getattr(client, "context_window", None)
         if window is None:

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/mcp/manager.py

@@ -23,6 +23,7 @@ SDK/connection errors that the tool adapter turns into error strings.
 from __future__ import annotations
 
 import asyncio
+import concurrent.futures
 import contextlib
 import threading
 import time
@@ -102,7 +103,10 @@ class _LoopThread:
         while True:
             try:
                 exc = future.exception(timeout=0.1)
-            except TimeoutError:
+            # concurrent.futures.TimeoutError is the builtin TimeoutError on
+            # 3.11+ but a distinct class on 3.10 — catch the futures one so
+            # the poll-timeout branch works on every supported Python.
+            except concurrent.futures.TimeoutError:
                 # future still running: enforce deadline / cancellation
                 if deadline is not None and time.monotonic() >= deadline:
                     future.cancel()

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/planmode.py

@@ -64,8 +64,11 @@ class PlanMode:
         os.makedirs(os.path.dirname(path), exist_ok=True)
         if not os.path.exists(path):
             Path(path).write_text("", encoding="utf-8")
-        self.plan_file = path
-        return path
+        # Store the canonical path so the plan-mode write guard (which
+        # compares against realpath'd tool targets) matches — on macOS
+        # TMPDIR (/var) is a symlink to /private/var.
+        self.plan_file = os.path.realpath(path)
+        return self.plan_file
 
     def cleanup_plan_file(self) -> None:
         if not self.plan_file:

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/session.py

@@ -687,6 +687,9 @@ class Session:
         self.client.model = merged["model"]
         self.model = merged["model"]
         self.store.model = merged["model"]
+        # the calibration factor is tokenizer-specific: a factor tuned
+        # to the previous model must not skew estimates for the new one
+        self.calibrator.reset()
         self.backend = merged["backend"]
         self.store.backend = merged["backend"]
         self.temperature = merged["temperature"]

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/token_estimator.py

@@ -44,9 +44,9 @@ def context_window_for(model: str, config_path: str | os.PathLike | None = None)
     """Return the context window for MODEL, or a safe fallback.
 
     Delegates to ``config.get_context_window_for_model``: config-file
-    ``context_windows`` overrides (config.json) first, then fnmatch
-    over CONTEXT_WINDOWS (first match wins, case-insensitive), then
-    DEFAULT_CONTEXT_WINDOW.
+    ``context_windows`` overrides (config.json) first, then substring
+    match over CONTEXT_WINDOWS (first match wins, case-insensitive),
+    then DEFAULT_CONTEXT_WINDOW.
 
     Args:
         model: The model ID to look up.
@@ -68,6 +68,12 @@ class TokenCalibrator:
         self.factor = 1.0
         self.last_raw_estimate: int | None = None
 
+    def reset(self) -> None:
+        """Drop the calibration factor (model switch: the old factor
+        was tuned to the previous model's tokenizer)."""
+        self.factor = 1.0
+        self.last_raw_estimate = None
+
     def update(self, actual_input: int | None) -> None:
         raw = self.last_raw_estimate
         if actual_input is None or actual_input <= 0 or raw is None or raw <= 0:

{python_agent_harness-1.5.4.1 → python_agent_harness-1.5.4.3}/python_agent_harness/tools/__init__.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import sys
+
 from .agent_tool import AgentTool
 from .base import PendingToolResult, Registry, Tool, ToolContext
 from .bash import Bash
-from .filesystem import Edit, GlobTool, Grep, Insert, Mkdir, Read, Write
+from .edit import Edit
+from .edit_mac import EditMac
+from .filesystem import GlobTool, Grep, Insert, Mkdir, Read, Write
 from .mcp import MCPTool, mcp_tools_from_manager, normalize_mcp_result
 from .planexit import PlanExit
 from .question import Question
@@ -20,6 +24,7 @@ __all__ = [
     "AgentTool",
     "Bash",
     "Edit",
+    "EditMac",
     "GlobTool",
     "Grep",
     "Insert",
@@ -38,6 +43,10 @@ __all__ = [
 
 def default_registry() -> Registry:
     reg = Registry()
+    # macOS's BSD patch rejects well-formed hunks that GNU patch accepts,
+    # so macOS uses EditMac (pure-Python diff applier); Linux keeps the
+    # patch-binary Edit.  Both register under the name "Edit".
+    edit_tool = EditMac() if sys.platform == "darwin" else Edit()
     for tool in (
         AgentTool(),
         TodoWrite(),
@@ -45,7 +54,7 @@ def default_registry() -> Registry:
         Grep(),
         Read(),
         Insert(),
-        Edit(),
+        edit_tool,
         Write(),
         Mkdir(),
         Bash(),

python_agent_harness-1.5.4.3/python_agent_harness/tools/diffapply.py

@@ -0,0 +1,246 @@
+"""Pure-Python unified diff applier (macOS Edit backend).
+
+macOS ships Apple's old BSD ``/usr/bin/patch`` (patch 2.0-12u11-Apple),
+which rejects well-formed hunks that GNU patch accepts: asymmetric
+context (leading but no trailing context, or vice versa), hunks whose
+last body line is a ``---``-rendered content line, etc.  Rather than
+rewriting every diff into a shape that specific patch binary likes, the
+macOS Edit tool applies diffs here, in Python:
+
+- the diff is parsed STRUCTURALLY, so hunk-header counts are advisory
+  (they are recounted from the body, like ``_fix_patch_headers``) and
+  ``---``/``+++`` content lines are only file headers when followed by
+  their ``+++``/``---`` partner;
+- hunks are matched against the file by content with fuzz (context
+  lines may mismatch up to ``FUZZ`` times, removed lines must match
+  exactly), preferring the position the header claims;
+- hunks are applied bottom-up so earlier positions stay valid;
+- files are written only when every hunk of the section matched.
+
+The applier is platform-independent, so its behavior is covered by
+tests on every OS.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+_FILE_OLD_RE = re.compile(r"^---[ \t]")
+_FILE_NEW_RE = re.compile(r"^\+\+\+[ \t]")
+_HUNK_BOUNDARY_RE = re.compile(r"^@@ ")
+
+# Maximum number of context lines that may mismatch when anchoring a
+# hunk (removed lines must always match exactly).
+FUZZ = 3
+
+
+class _Hunk:
+    __slots__ = ("old_start", "body")
+
+    def __init__(self, old_start: int, body: list[tuple[str, str, bool]]) -> None:
+        # body entries: (kind, content, no_newline); kind in ' ', '-', '+'.
+        self.old_start = old_start
+        self.body = body
+
+    def old_seq(self) -> list[tuple[str, str]]:
+        """(kind, content-without-newline) for the lines that must exist
+        in the old file (' ' context and '-' removed lines)."""
+        return [
+            (kind, content.rstrip("\n")) for kind, content, _ in self.body if kind in (" ", "-")
+        ]
+
+
+class _Section:
+    __slots__ = ("new_path", "hunks")
+
+    def __init__(self, new_path: str, hunks: list[_Hunk]) -> None:
+        self.new_path = new_path
+        self.hunks = hunks
+
+
+def _section_header_at(lines: list[str], idx: int) -> bool:
+    """Whether lines[idx] begins a file section: a ``--- path`` line
+    immediately followed by a ``+++ path`` line.  Removed/added content
+    lines rendered ``---``/``+++`` inside a hunk body are only mistaken
+    for headers when the pair shape matches, so the trailing ``+++``
+    partner is required (mirrors ``_starts_file_section``)."""
+    if idx + 1 >= len(lines):
+        return False
+    return bool(_FILE_OLD_RE.match(lines[idx]) and _FILE_NEW_RE.match(lines[idx + 1]))
+
+
+def _parse(diff_text: str) -> list[_Section]:
+    """Parse a unified diff into file sections (paths + hunks)."""
+    lines = diff_text.splitlines(keepends=True)
+    sections: list[_Section] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        if not _section_header_at(lines, i):
+            i += 1
+            continue
+        new_path = lines[i + 1][len("+++") :].strip()
+        i += 2
+        hunks: list[_Hunk] = []
+        while i < n:
+            m = _HUNK_HEADER_RE.match(lines[i])
+            if m:
+                old_start = int(m.group(1))
+                body: list[tuple[str, str, bool]] = []
+                i += 1
+                while (
+                    i < n
+                    and not _HUNK_BOUNDARY_RE.match(lines[i])
+                    and not _section_header_at(lines, i)
+                ):
+                    line = lines[i]
+                    if line.startswith("\\"):  # ""
+                        if body and body[-1][0] in (" ", "-", "+"):
+                            kind, content, _ = body[-1]
+                            body[-1] = (kind, content, True)
+                    elif line[:1] in (" ", "-", "+"):
+                        body.append((line[0], line[1:], False))
+                    i += 1
+                hunks.append(_Hunk(old_start, body))
+                continue
+            if _section_header_at(lines, i):
+                break
+            i += 1  # stray line (e.g. "diff --git", "index ...") — skip
+        sections.append(_Section(new_path, hunks))
+    return sections
+
+
+def _candidate_positions(start: int, limit: int) -> list[int]:
+    """Match offsets around *start* (0-based), closest first, within
+    ``FUZZ`` lines and bounded by [0, *limit*]."""
+    out: list[int] = []
+    seen: set[int] = set()
+    for d in range(FUZZ + 1):
+        for p in (start - d, start + d):
+            if 0 <= p <= limit and p not in seen:
+                seen.add(p)
+                out.append(p)
+    return out
+
+
+def _match_hunk(hunk: _Hunk, file_lines: list[str]) -> int | None:
+    """Find the 0-based position where the hunk's old lines match.
+
+    Removed lines must match exactly; up to ``FUZZ`` context lines may
+    mismatch (patch-style fuzz).  Pure-insertion hunks (no old lines)
+    anchor at ``old_start - 1``.
+    """
+    old_seq = hunk.old_seq()
+    if not old_seq:
+        p = hunk.old_start - 1
+        return max(0, min(p, len(file_lines)))
+    start = hunk.old_start - 1
+    limit = len(file_lines) - len(old_seq)
+    for p in _candidate_positions(start, limit):
+        mismatches = 0
+        ok = True
+        for i, (kind, content) in enumerate(old_seq):
+            file_content = file_lines[p + i].rstrip("\n")
+            if kind == "-":
+                if file_content != content:
+                    ok = False
+                    break
+            elif file_content != content:
+                mismatches += 1
+                if mismatches > FUZZ:
+                    ok = False
+                    break
+        if ok:
+            return p
+    return None
+
+
+def _apply_hunk(hunk: _Hunk, pos: int, file_lines: list[str]) -> None:
+    """Replace the matched region with the hunk's new lines in place."""
+    old_count = sum(1 for kind, _, _ in hunk.body if kind in (" ", "-"))
+    new_block: list[str] = []
+    p = pos
+    for kind, content, no_newline in hunk.body:
+        if kind == " ":
+            new_block.append(file_lines[p])
+            p += 1
+        elif kind == "-":
+            p += 1
+        else:  # "+"
+            if no_newline:
+                new_block.append(content.rstrip("\n"))
+            elif content.endswith("\n"):
+                new_block.append(content)
+            else:
+                new_block.append(content + "\n")
+    file_lines[pos : pos + old_count] = new_block
+
+
+def _resolve_target(new_path: str, cwd: str, fallback_path: str | None) -> str:
+    """Resolve a diff's ``+++ path`` against *cwd*, with the single-file
+    *fallback_path* as backup when the name does not match an existing
+    file (e.g. the model wrote a bare basename for a deep path)."""
+    name = new_path
+    for prefix in ("a/", "b/"):
+        if name.startswith(prefix):
+            name = name[len(prefix) :]
+            break
+    if os.path.isabs(name):
+        return name
+    target = os.path.join(cwd, name)
+    if not os.path.isfile(target) and fallback_path and os.path.isfile(fallback_path):
+        return fallback_path
+    return target
+
+
+def _apply_section(section: _Section, cwd: str, fallback_path: str | None) -> tuple[bool, str]:
+    target = _resolve_target(section.new_path, cwd, fallback_path)
+    if not os.path.isfile(target):
+        return False, f"target file does not exist: {target}"
+    try:
+        with open(target, encoding="utf-8", errors="replace") as f:
+            file_lines = f.readlines()
+    except OSError as e:
+        return False, f"cannot read {target}: {e}"
+    # Match every hunk against the ORIGINAL content first; only write
+    # when all matched (a failed hunk leaves the file untouched).
+    plan: list[tuple[_Hunk, int]] = []
+    for hunk in section.hunks:
+        pos = _match_hunk(hunk, file_lines)
+        if pos is None:
+            return (
+                False,
+                f"hunk at line {hunk.old_start} failed to match the file content",
+            )
+        plan.append((hunk, pos))
+    new_lines = list(file_lines)
+    for hunk, pos in reversed(plan):  # bottom-up: earlier positions stay valid
+        _apply_hunk(hunk, pos, new_lines)
+    try:
+        with open(target, "w", encoding="utf-8") as f:
+            f.writelines(new_lines)
+    except OSError as e:
+        return False, f"cannot write {target}: {e}"
+    return True, f"patched {target}"
+
+
+def apply_unified_diff(
+    diff_text: str, cwd: str, fallback_path: str | None = None
+) -> tuple[bool, str]:
+    """Apply a unified diff to files under *cwd*.
+
+    Returns ``(ok, message)``; on failure no file is written.  Multi-file
+    diffs are applied section by section.  *fallback_path* is used when a
+    section's target cannot be resolved to an existing file (single-file
+    mode).
+    """
+    sections = _parse(diff_text)
+    if not sections:
+        return False, "no file sections found in diff"
+    for section in sections:
+        ok, msg = _apply_section(section, cwd, fallback_path)
+        if not ok:
+            return False, msg
+    return True, f"applied {len(sections)} file section(s)"