- Remove the per-file cap from _around_one_file; cap only at op_around's

  single-file and dir-aggregate returns. Fixes double-capping (per-file +
  aggregate both 16KB) and interleaved truncation footers in dir fan-out.
- _cap_context_window: nl >= 0 (was > 0) so a newline at offset 0 still
  trims; consistent byte-accounting for the dropped count.
- Tests: +dir-aggregate cap (single footer), +single-giant-line no-newline.
- Docs: note grep:PATTERN:PATH:LIMIT:CONTEXT shares the grep_around cap;
  align .supertool.json descriptions.

Co-Authored-By: Max <noreply>

Author: fdaviddpt

.supertool.json

@@ -52,13 +52,13 @@
     },
     "around": {
       "syntax": "around:PATTERN:PATH[:N]",
-      "description": "First match + N lines ctx (def 10). 1-shot grep+read. Output capped ~16KB (max_bytes)",
+      "description": "First match + N lines ctx (def 10). 1-shot grep+read. Output capped ~16KB (max_bytes) — truncates at line boundary",
       "example": "around:def dispatch:supertool.py:15",
       "hint": true
     },
     "grep_around": {
       "syntax": "grep_around:PATTERN:PATH[:N[:LIMIT]]",
-      "description": "Every match + N ctx lines (def 3, limit 10). Bulk usage scan. Output capped ~16KB (max_bytes)",
+      "description": "Every match + N ctx lines (def 3, limit 10). Bulk usage scan. Output capped ~16KB (max_bytes) — truncates at line boundary",
       "example": "grep_around:def dispatch:supertool.py:5",
       "hint": true
     },

docs/operations/search.md

@@ -18,6 +18,8 @@ Pattern-based ops for finding content across files or zooming into a known locat
 
 A large `:N` context on a file of long (e.g. minified) lines can over-fetch — one op can dump hundreds of KB and blow your context budget. `around:` and `grep_around:` cap their output at **~16KB**, truncating at a line boundary with a footer that points at the narrower tools (smaller `:N`, or `between:` for a whole symbol). Tune via `builtin-ops.around.max_bytes` / `builtin-ops.grep_around.max_bytes` in `.supertool.json` (or `SUPERTOOL_AROUND_MAX_BYTES` / `SUPERTOOL_GREP_AROUND_MAX_BYTES`). See [configuration.md](../configuration.md#builtin-ops).
 
+`grep:` with an explicit `CONTEXT` argument (`grep:PATTERN:PATH:LIMIT:CONTEXT`) shares the `grep_around:` code path, so it is capped under the same `grep_around.max_bytes` budget. Plain `grep:` (no context) is unaffected — it has its own `LIMIT`/`max_results` bound.
+
 ## Common patterns
 
 Find all usages of a function across a codebase, with 2 lines of context:

supertool.py

@@ -1225,10 +1225,13 @@ def _cap_context_window(text: str, op_name: str) -> str:
     if len(encoded) <= cap:
         return text
     clipped = encoded[:cap].decode("utf-8", errors="ignore")
+    # Truncate at the last line boundary so we never cut mid-line. nl == -1
+    # means a single line longer than the cap — nothing to trim to, pass the
+    # partial through (the footer still flags it).
     nl = clipped.rfind("\n")
-    if nl > 0:
+    if nl >= 0:
         clipped = clipped[:nl + 1]
-    dropped = len(encoded) - len(clipped.encode("utf-8", errors="surrogateescape"))
+    dropped = len(encoded) - len(clipped.encode("utf-8", errors="ignore"))
     return (clipped +
             f"… truncated (~{dropped} more bytes) — narrow context (:N) "
             f"or use between: for the whole symbol\n")
@@ -1272,7 +1275,7 @@ def _around_one_file(regex: "re.Pattern[str]", path: str, n: int) -> str:
         marker = "→" if i == match_lineno else " "
         out.append(f"{i + 1:>6}{marker}{lines[i]}")
     out.append("\n")
-    return _cap_context_window("".join(out), "around")
+    return "".join(out)
 
 
 def op_around(pattern: str, path: str, n: int = 10) -> str:
@@ -1331,7 +1334,7 @@ def op_around(pattern: str, path: str, n: int = 10) -> str:
     rendered = _around_one_file(regex, path, n)
     if not rendered:
         return f"(no match for {pattern!r} in {path})\n\n"
-    return rendered
+    return _cap_context_window(rendered, "around")
 
 
 def op_between_symbol(symbol: str, path: str) -> str:

tests/test_around_byte_cap_241.py

@@ -71,3 +71,27 @@ def test_around_env_override(tmp_path: Path, monkeypatch) -> None:
     out = supertool.op_around("TARGET20", str(f), 40)
     assert len(out.encode()) <= 4000 + 200, f"env cap ignored: {len(out)} bytes"
     assert "truncated" in out
+
+
+def test_around_dir_aggregate_capped(tmp_path: Path) -> None:
+    """Dir fan-out caps the TOTAL op output, not just each file (#241 review)."""
+    d = tmp_path / "pkg"
+    d.mkdir()
+    for i in range(10):
+        (d / f"f{i}.js").write_text(f"head{i}\n{LONG} TARGET\n{LONG}\n")
+    out = supertool.op_around("TARGET", str(d), 20)
+    assert len(out.encode()) <= 16000 + 200, f"dir aggregate not capped: {len(out)}"
+    assert "truncated" in out
+    # Exactly one truncation footer — the per-file cap was removed, so footers
+    # don't appear interleaved between files.
+    assert out.count("… truncated") == 1
+
+
+def test_around_single_giant_line_no_newline(tmp_path: Path) -> None:
+    """A single line longer than the cap: pass the partial through + footer,
+    never crash (nl == -1 branch)."""
+    f = tmp_path / "min.js"
+    f.write_text("TARGET " + "y" * 40000)  # one line, no trailing context lines
+    out = supertool.op_around("TARGET", str(f), 0)
+    assert len(out.encode()) <= 16000 + 200, f"giant line not capped: {len(out)}"
+    assert "truncated" in out