squackit 0.8.2__tar.gz → 0.8.4__tar.gz

{squackit-0.8.2 → squackit-0.8.4}/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## 0.8.4
+
+A review of 0.8.1–0.8.3 found both fixes had reached the macro-tool layer and
+stopped there. The compound tools have their own parameters and never pass
+through `apply_defaults`, so each gap was reachable through a different door.
+
+### Fixed — the compound tools did not anchor explicit patterns
+
+0.8.1 anchored caller-supplied relative patterns, but only in the macro-tool
+wrapper. `investigate`, `review` and `search` take `file_pattern` themselves and
+handed it to the macro unchanged, so a relative glob still resolved against the
+process working directory. On a server whose cwd is not the corpus — the exact
+deployment 0.8.1 was written for — this reproduced the original failure:
+
+    investigate(name="parse_config", file_pattern="src/**/*.py")
+    -> IOException: Failed to initialize file processing ... Permission
+
+Verified against the published 0.8.3 before fixing. The 0.8.1 note that
+"caller-supplied relative patterns are anchored too" was true of the macro path
+only; it is now true of both. Absolute patterns are still passed through
+untouched, and an explicit pattern still works without a defaults object.
+
+### Fixed — briefing sections named no cause
+
+`_section` wraps every part of `explore`, `review` and `search`, and
+`investigate`'s Source/Called-by/Calls. It caught everything, logged at DEBUG —
+invisible at normal levels — and rendered a bare `(could not load)`. A
+permission error, a missing git revision and an unloaded macro were
+indistinguishable from each other and from a section that legitimately had
+nothing.
+
+That is the same defect 0.8.3 fixed in `investigate`'s primary lookup and did
+not carry to the siblings. Sections now report the exception type and message,
+capped at 200 characters with the truncation marked, and log at WARNING. One
+failing section still cannot take down a briefing.
+
+
+## 0.8.3
+
+Three fixes with one theme: a failure must not be representable as an ordinary
+result. Nothing here changes what a working call returns.
+
+### Fixed — `investigate` reported failed lookups as confirmed absences (#14)
+
+Every exception from the definition query was caught and rendered with the
+sentence used for a genuine miss:
+
+    No definition found for 'X'. Try a broader pattern or check spelling.
+
+So a permission error, a binder error and "that symbol isn't here" were
+indistinguishable, and the advice actively misdirected — the pattern was never
+the problem. This is how the 0.8.1 sandbox bug presented: every symbol in a
+healthy project reported missing, for hours, while the server called all its
+tools healthy.
+
+A failed lookup now says so, names the underlying error, and reports the
+pattern it searched. The friendly wording is kept for the genuine empty case,
+where it is good advice.
+
+### Fixed — a raising pluckin lost its tools silently (#14)
+
+`collect_pluckin_tools` swallowed per-pluckin exceptions with a bare `pass`,
+under a comment claiming the error would be "surfaced contextually". Nothing
+surfaced it. The guard is right — one broken pluckin must not take down the
+registry — but it now logs a warning naming the pluckin and the error.
+
+Not reachable today (no shipped pluckin defines `squackit_tools`), fixed as
+latent. The symptom it would produce — a silently shorter tool surface — was
+independently hit through another mechanism and cost a four-combination version
+bisection, because a shorter tool list doesn't read as a failure. It reads as a
+different, reasonable version of the product.
+
+### Fixed — `ast_replace` / `ast_patch` read as mutating and are not (#16)
+
+Connection macros are published with a description generated from the
+signature, so these carried no semantics at all:
+
+    Query: ast_replace(source, selector, new_text, language)
+
+These are sitting_duck SQL macros. A SQL macro cannot write files — it computes
+the patched source and returns it, which is coherent, and sitting_duck is not
+misbehaving. But over MCP the caller reads a verb. One did: it called
+`ast_replace` to repair a bug, got a successful-looking table back, and changed
+nothing on disk.
+
+Generated descriptions for macros whose *name* implies an effect now state that
+they return the patched result and modify nothing. Read-only macros are
+unchanged — a disclaimer on all ninety is context every agent pays for.
+
+For an actually-mutating primitive, see #17.
+
+### Fixed — `__version__` was four releases stale (#15, #2)
+
+`squackit.__version__` was a hand-written `"0.4.1"` against a distribution
+version of `0.8.2`, and survived `--force-reinstall` because it derived from
+nothing. It is now read from `importlib.metadata`, and the smoke test asserts
+that correspondence rather than a literal — which is what let both drift in
+agreement with each other and with nothing else.
+
 ## 0.8.2
 
 ### Fixed — AST tools could not read a source outside the working directory

{squackit-0.8.2 → squackit-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: squackit
-Version: 0.8.2
+Version: 0.8.4
 Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
 Project-URL: Homepage, https://github.com/teaguesterling/squackit
 Project-URL: Documentation, https://squackit.readthedocs.io

{squackit-0.8.2 → squackit-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.8.2"
+version = "0.8.4"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"

squackit-0.8.4/squackit/__init__.py

@@ -0,0 +1,17 @@
+"""squackit: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."""
+
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+# Derived, never written by hand. The literal that used to live here read
+# "0.4.1" while the installed distribution was 0.8.2 — four releases stale, and
+# immune to --force-reinstall because it was not derived from anything. Someone
+# debugging an unrelated problem read it, concluded they had a mixed install,
+# and went looking for a packaging fault that did not exist. A version string
+# that lies makes a healthy install look broken, which is the most expensive
+# direction to send a reader.
+try:
+    __version__ = _dist_version("squackit")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

{squackit-0.8.2 → squackit-0.8.4}/squackit/tool_config.py

@@ -37,6 +37,21 @@ _FALLBACK_NUMERIC = {
 }
 
 
+#: Name tokens that read as an effect. A macro whose name contains one of these
+#: gets an explicit "does not modify any file" note in its generated
+#: description. Missing a verb costs nothing beyond the status quo; a false
+#: positive adds a sentence that is true of every SQL macro anyway.
+_MUTATION_VERBS = frozenset({
+    "replace", "patch", "apply", "write", "insert", "update", "delete",
+    "remove", "rename", "edit", "set", "modify", "save", "commit",
+})
+
+
+def _name_implies_mutation(name: str) -> bool:
+    """True when a tool's NAME reads as an effect it does not perform."""
+    return any(token in _MUTATION_VERBS for token in name.split("_"))
+
+
 @dataclass
 class ToolPresentation:
     """Wraps fledgling ToolInfo with squackit's presentation/UX config."""
@@ -100,7 +115,23 @@ class ToolPresentation:
     def description(self) -> str:
         if self.description_override is not None:
             return self.description_override
-        return self.info.description or f"Query: {self.name}({', '.join(self.params)})"
+        if self.info.description:
+            return self.info.description
+        signature = f"{self.name}({', '.join(self.params)})"
+        if _name_implies_mutation(self.name):
+            # SQL macros cannot write files — they compute and return a result
+            # set. But a caller reads a verb: `ast_replace` was called to repair
+            # a bug, returned a successful-looking table, and changed nothing on
+            # disk. The bare signature said nothing either way, and the only
+            # hint was the "Query:" prefix — a category label competing against
+            # an imperative. Spell it out for the names where it misleads, and
+            # only those: a disclaimer on all ~90 macros is context every agent
+            # pays for on every call.
+            return (
+                f"Query: {signature} — computes and RETURNS the patched result "
+                f"as text. Does not modify any file."
+            )
+        return f"Query: {signature}"
 
     @property
     def parameters_schema(self) -> dict | None:

{squackit-0.8.2 → squackit-0.8.4}/squackit/tools.py

@@ -9,6 +9,7 @@ fledgling macro tools. They take priority over fledgling equivalents
 from __future__ import annotations
 
 import hashlib
+import logging
 import os
 import re
 import tempfile
@@ -16,6 +17,8 @@ import tempfile
 from fledgling.tools import ToolInfo
 from squackit.tool_config import ToolPresentation
 
+log = logging.getLogger(__name__)
+
 
 #: How much source text ``read_ast`` puts in the ``peek`` column when squackit
 #: materializes its own table. ``'smart'`` matches what pluckit's cache uses by
@@ -305,10 +308,20 @@ def collect_pluckin_tools(plucker) -> list:
         if callable(fn):
             try:
                 tools.extend(fn())
-            except Exception:
-                # A broken pluckin shouldn't break the whole registry.
-                # Squackit's server/CLI will surface the error contextually.
-                pass
+            except Exception as exc:
+                # Keep the guard — one broken pluckin must not take down the
+                # whole registry — but SAY SO. Dropping its tools silently
+                # yields a shorter tool surface, and a shorter tool list does
+                # not read as a failure: it reads as a different, reasonable
+                # version of the product, so callers reason forward from it
+                # instead of doubting it. (An earlier comment here claimed the
+                # server/CLI would "surface the error contextually". Nothing
+                # did.)
+                log.warning(
+                    "pluckin %s failed to contribute squackit tools (%s); its "
+                    "tools are missing from this session's registry",
+                    type(pluckin).__name__, exc, exc_info=True,
+                )
     return tools
 
 

{squackit-0.8.2 → squackit-0.8.4}/squackit/workflows.py

@@ -32,20 +32,41 @@ def _format_briefing(title: str, sections: list[tuple[str, str]]) -> str:
     return "\n".join(parts)
 
 
+#: How much of a failing section's error text reaches the briefing. DuckDB
+#: errors run to hundreds of characters and a briefing is prose, but a cause
+#: the reader cannot see is the thing this whole clause exists to avoid.
+_SECTION_ERROR_CHARS = 200
+
+
 def _section(heading: str, fn):
     """Run fn() with error handling, return (heading, content) tuple.
 
-    Returns "(no data)" for empty/None results,
-    "(could not load)" on exceptions.
+    Returns "(no data)" for empty/None results, and "(could not load — <type>:
+    <message>)" on exceptions.
+
+    THE CAUSE IS IN THE TEXT ON PURPOSE. This wrapper covers every section of
+    explore/review/search and investigate's Source/Called-by/Calls. It used to
+    return a bare "(could not load)" and log at DEBUG, which is invisible at
+    normal levels — so a permission error, a missing git revision and a macro
+    that simply is not loaded all rendered identically, and none of them said
+    why. That is the same "a failure must not be representable as an ordinary
+    result" defect fixed in investigate's primary lookup in 0.8.3; it was not
+    extended to the sibling sections until 0.8.4.
+
+    Still non-fatal: one broken section must not take down the briefing, which
+    is why the guard stays.
     """
     try:
         content = fn()
         if not content:
             return (heading, "(no data)")
         return (heading, content)
-    except Exception:
-        log.debug("section %s failed", heading, exc_info=True)
-        return (heading, "(could not load)")
+    except Exception as exc:
+        log.warning("section %r failed: %s", heading, exc, exc_info=True)
+        detail = str(exc).strip().replace("\n", " ")
+        if len(detail) > _SECTION_ERROR_CHARS:
+            detail = detail[:_SECTION_ERROR_CHARS] + "…"
+        return (heading, f"(could not load — {type(exc).__name__}: {detail})")
 
 
 def _has_module(con, module_name: str) -> bool:
@@ -92,6 +113,31 @@ def _sorted_table(con, macro_name, kwargs, sort_col, max_rows, descending=True):
 # ── Compound tools ─────────────────────────────────────────────────
 
 
+def _anchored(defaults, file_pattern):
+    """Root a caller-supplied file pattern, the way apply_defaults does.
+
+    The compound tools take `file_pattern` as their own parameter and never
+    pass through `apply_defaults`, so 0.8.1's anchoring of explicit relative
+    patterns reached the macro tools only. A relative glob handed to
+    `investigate`/`review`/`search` still resolved against the process cwd and,
+    under fledgling's sandbox, failed outright — the same deployment shape
+    0.8.1 was written for, reached through a different door.
+
+    `anchor()` passes absolute patterns through untouched, so a caller who
+    named a path in full still gets it.
+
+    Tolerates ``defaults=None``. An explicit ``file_pattern`` previously needed
+    no defaults object at all — the caller had already said where to look — and
+    callers rely on that: several tests drive ``investigate`` with a fake
+    connection and no defaults to isolate the name-matching logic. There is
+    also nothing to anchor *against* without a root, which is the same reason
+    ``anchor()`` itself passes patterns through when ``root`` is None.
+    """
+    if file_pattern is None or defaults is None:
+        return file_pattern
+    return defaults.anchor(file_pattern)
+
+
 def explore(con, defaults, path=None):
     """First-contact codebase briefing."""
     # Scope patterns to path if provided
@@ -144,6 +190,7 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
         path: Project root to scope the search to. Defaults to process cwd.
             Only consulted when file_pattern is None.
     """
+    file_pattern = _anchored(defaults, file_pattern)
     if file_pattern is None:
         from squackit.runtime import resolve_scope_path
         # Precedence: explicit path -> runtime.active_root -> process cwd.
@@ -160,13 +207,22 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
     #    the whole briefing describe the wrong symbol. Fall back to the full
     #    substring set only when nothing matches exactly, preserving the
     #    forgiving lookup for partial names / typos.
+    # A FAILED LOOKUP IS NOT AN ABSENT SYMBOL. Both used to return the "no
+    # definition found" sentence below, which made a permission error, a binder
+    # error and a genuine miss indistinguishable — and told the reader to
+    # broaden a pattern that was never the problem. That is exactly how the
+    # 0.8.1 sandbox bug presented: every symbol in a healthy project reported
+    # missing, for hours, while the server called all its tools healthy.
+    lookup_error: Exception | None = None
     try:
         rel = con.find_definitions(
             file_pattern=file_pattern, name_pattern=f"%{name}%",
         )
         defs = rel.fetchall()
         def_cols = rel.columns
-    except Exception:
+    except Exception as exc:
+        log.debug("find_definitions failed for %r", name, exc_info=True)
+        lookup_error = exc
         defs = []
         def_cols = []
 
@@ -176,6 +232,14 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
         if _exact:
             defs = _exact
 
+    if lookup_error is not None:
+        return (
+            f"Could not look up '{name}' — the definition query failed, so "
+            f"whether this symbol exists is UNKNOWN.\n"
+            f"{type(lookup_error).__name__}: {lookup_error}\n"
+            f"Searched: {file_pattern}"
+        )
+
     if not defs:
         return f"No definition found for '{name}'. Try a broader pattern or check spelling."
 
@@ -271,7 +335,7 @@ def review(con, defaults, from_rev=None, to_rev=None, file_pattern=None):
     """Code review prep for a revision range."""
     from_rev = from_rev or defaults.from_rev
     to_rev = to_rev or defaults.to_rev
-    file_pattern = file_pattern or defaults.code_glob
+    file_pattern = _anchored(defaults, file_pattern) or defaults.code_glob
 
     sections = []
 
@@ -351,7 +415,7 @@ def review(con, defaults, from_rev=None, to_rev=None, file_pattern=None):
 
 def search(con, defaults, query, file_pattern=None):
     """Multi-source search across code, docs, and git."""
-    file_pattern = file_pattern or defaults.code_glob
+    file_pattern = _anchored(defaults, file_pattern) or defaults.code_glob
 
     sections = []
 

squackit-0.8.4/tests/test_error_visibility.py

@@ -0,0 +1,253 @@
+"""A failure must not be representable as an ordinary result.
+
+Three places used to violate that, each in a different way:
+
+* ``investigate`` caught every query exception and rendered it with the same
+  sentence it uses for a genuine miss — so a permission error, a binder error
+  and "that symbol isn't here" were indistinguishable, and the advice offered
+  ("try a broader pattern") actively misdirected. This is not hypothetical: it
+  is exactly how the 0.8.1 sandbox bug presented, for hours, while the server
+  reported every tool healthy.
+* ``collect_pluckin_tools`` dropped a raising pluckin's tools with a bare
+  ``pass`` under a comment claiming the error would be surfaced elsewhere.
+  Nothing surfaced it. A silently shorter tool surface is worse than a silently
+  empty result — an empty result prompts "did that work?", a shorter tool list
+  reads as a different, reasonable version of the product.
+* Auto-generated macro descriptions were a bare signature, so a SQL macro named
+  ``ast_replace`` — which computes patched source and writes nothing, because a
+  SQL macro *cannot* write — read as a mutation to any caller.
+
+See issues #14 and #16.
+"""
+
+import logging
+
+import pytest
+
+from squackit.defaults import ProjectDefaults
+from squackit.tool_config import ToolPresentation
+from squackit.tools import collect_pluckin_tools
+from squackit.workflows import investigate
+
+
+# ── investigate: a failed query is not a miss ───────────────────────
+
+
+class _Rel:
+    def __init__(self, rows, cols):
+        self._rows, self.columns = rows, cols
+
+    def fetchall(self):
+        return self._rows
+
+
+class _ConRaises:
+    """A connection whose lookup fails the way a sandboxed one does."""
+
+    def __init__(self, exc):
+        self._exc = exc
+
+    def find_definitions(self, **kw):
+        raise self._exc
+
+
+class _ConEmpty:
+    """A connection that works and genuinely has no match."""
+
+    def find_definitions(self, **kw):
+        return _Rel([], ["file_path", "name", "kind",
+                         "start_line", "end_line", "signature"])
+
+
+@pytest.fixture
+def defaults(tmp_path):
+    return ProjectDefaults(code_pattern="**/*.py", root=str(tmp_path))
+
+
+class TestInvestigateDistinguishesFailureFromMiss:
+
+    def test_genuine_miss_keeps_the_helpful_message(self, defaults):
+        """The friendly wording is right when it IS a miss — keep it."""
+        out = investigate(_ConEmpty(), defaults, "nonexistent_symbol")
+        assert "No definition found" in out
+        assert "nonexistent_symbol" in out
+
+    def test_query_failure_does_NOT_claim_the_symbol_is_absent(self, defaults):
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "No definition found" not in out, (
+            "a failed lookup was reported as a confirmed absence"
+        )
+
+    def test_query_failure_says_it_failed(self, defaults):
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "could not" in out.lower() or "failed" in out.lower()
+
+    def test_query_failure_surfaces_the_underlying_error(self, defaults):
+        """The 0.8.1 bug was diagnosable only from this text."""
+        exc = RuntimeError(
+            'Permission Error: Cannot access file "**/*.py" '
+            "- file system operations are disabled by configuration"
+        )
+        out = investigate(_ConRaises(exc), defaults, "parse_config")
+        assert "Permission Error" in out, out
+
+    def test_query_failure_does_NOT_advise_broadening_the_pattern(self, defaults):
+        """That advice sends the reader at the wrong thing entirely."""
+        out = investigate(_ConRaises(RuntimeError("boom")), defaults, "parse_config")
+        assert "broader pattern" not in out
+
+
+# ── collect_pluckin_tools: a dropped pluckin is logged ───────────────
+
+
+class _Pluckin:
+    def __init__(self, tools=None, exc=None):
+        self._tools, self._exc = tools or [], exc
+
+    def squackit_tools(self):
+        if self._exc:
+            raise self._exc
+        return self._tools
+
+
+class _Plucker:
+    def __init__(self, pluckins):
+        self.pluckins = pluckins
+
+
+class TestPluckinFailuresAreVisible:
+
+    def test_a_raising_pluckin_does_not_break_the_registry(self):
+        """The guard itself is correct and stays."""
+        good = _Pluckin(tools=["t1", "t2"])
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        assert collect_pluckin_tools(_Plucker([bad, good])) == ["t1", "t2"]
+
+    def test_a_raising_pluckin_is_LOGGED(self, caplog):
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([bad]))
+        assert caplog.records, "a pluckin's tools vanished with no log record"
+
+    def test_the_log_names_the_pluckin_and_the_error(self, caplog):
+        bad = _Pluckin(exc=RuntimeError("plugin exploded"))
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([bad]))
+        text = " ".join(r.getMessage() for r in caplog.records)
+        assert "_Pluckin" in text, text
+        assert "plugin exploded" in text, text
+
+    def test_healthy_pluckins_log_nothing(self, caplog):
+        with caplog.at_level(logging.WARNING, logger="squackit.tools"):
+            collect_pluckin_tools(_Plucker([_Pluckin(tools=["t1"])]))
+        assert not caplog.records
+
+
+# ── generated descriptions state their semantics ─────────────────────
+
+
+class _Info:
+    """Stand-in for fledgling's ToolInfo carrying no description of its own.
+
+    ToolPresentation derives `name` and `params` from the info object, so the
+    stub has to supply macro_name/params rather than the presentation taking
+    them directly.
+    """
+
+    def __init__(self, macro_name, params, description=None):
+        self.macro_name = macro_name
+        self.tool_name = None
+        self.params = list(params)
+        self.description = description
+        self.required = None
+        self.required_params = []
+        self.format = None
+        self.parameters_schema = None
+
+
+def _presentation(name, params):
+    return ToolPresentation(info=_Info(name, params))
+
+
+class TestMutationNamedMacrosSayTheyDoNotMutate:
+
+    def test_ast_replace_states_it_does_not_modify(self):
+        d = _presentation("ast_replace", ["source", "selector", "new_text"])
+        assert "does not modify" in d.description.lower(), d.description
+
+    def test_ast_patch_states_it_does_not_modify(self):
+        d = _presentation("ast_patch", ["edits", "files"])
+        assert "does not modify" in d.description.lower(), d.description
+
+    def test_the_signature_is_still_there(self):
+        d = _presentation("ast_replace", ["source", "selector", "new_text"])
+        assert "ast_replace(source, selector, new_text)" in d.description
+
+    def test_read_only_macros_are_NOT_cluttered(self):
+        """A disclaimer on all 90 macros is context every agent pays for."""
+        d = _presentation("find_definitions", ["file_pattern", "name_pattern"])
+        assert "does not modify" not in d.description.lower()
+
+    def test_a_real_description_still_wins(self):
+        info = _Info("ast_replace", ["source"], description="The macro's own words.")
+        assert ToolPresentation(info=info).description == "The macro's own words."
+
+    def test_an_override_still_wins(self):
+        d = ToolPresentation(info=_Info("ast_replace", ["source"]),
+                             description_override="Overridden.")
+        assert d.description == "Overridden."
+
+
+# ── Briefing sections name their failure (#2 from the 0.8.3 review) ──
+
+
+class TestSectionFailuresAreNamed:
+    """`_section` wraps every part of explore/review/search/investigate.
+
+    It caught everything, logged at DEBUG (invisible at normal levels) and
+    rendered "(could not load)" — a string that cannot be told apart from a
+    section that legitimately has nothing, and which names no cause. 0.8.3
+    fixed exactly this shape in investigate's primary lookup but never reached
+    the sibling sections, so the same permission error that motivated 0.8.1
+    still arrived as undifferentiated text in three of the four compound tools.
+    """
+
+    def test_a_failing_section_still_reports_could_not_load(self):
+        """Keep the recognisable phrase — callers and tests match on it."""
+        from squackit.workflows import _section
+
+        heading, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("boom")))
+        assert heading == "Diffs"
+        assert "could not load" in content.lower()
+
+    def test_a_failing_section_names_the_error(self):
+        from squackit.workflows import _section
+
+        _heading, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("permission denied on **/*.py")))
+        assert "RuntimeError" in content, content
+        assert "permission denied" in content, content
+
+    def test_an_empty_section_is_distinguishable_from_a_failed_one(self):
+        from squackit.workflows import _section
+
+        _h, empty = _section("Docs", lambda: "")
+        _h2, failed = _section("Docs", lambda: (_ for _ in ()).throw(
+            RuntimeError("boom")))
+        assert empty != failed
+        assert "no data" in empty.lower()
+
+    def test_a_very_long_error_is_capped_visibly(self):
+        """DuckDB errors run to hundreds of characters; a briefing is prose."""
+        from squackit.workflows import _section
+
+        _h, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("x" * 4000)))
+        assert len(content) < 400, len(content)
+        assert "…" in content or "..." in content, content
+
+    def test_a_working_section_is_untouched(self):
+        from squackit.workflows import _section
+
+        assert _section("Docs", lambda: "| a | b |") == ("Docs", "| a | b |")