taut-summon 0.5.0__tar.gz

taut_summon-0.5.0/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.venv/
+.taut.db
+.taut.lock
+.taut.db-wal
+.taut.db-shm
+.envrc
+.taut.toml
+.weft
+.broker*

taut_summon-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Van Lindberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taut_summon-0.5.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: taut-summon
+Version: 0.5.0
+Summary: Summon extension for Taut: host an agent harness as a workspace member
+Author-email: Van Lindberg <van.lindberg@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: taut>=0.5.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# taut-summon
+
+Summon extension for Taut: host an existing agent harness (Claude Code and
+friends) as an ordinary member of a taut workspace.
+
+This package is intentionally separate from `taut`. The summon driver is the
+agent's terminal, not its runtime: it injects chat into the harness's own
+live session (its ears), and the agent speaks through the ordinary `taut`
+CLI selected by its continuity token (its mouth). The full contract lives in
+the core repository at `docs/specs/04-summon.md`.
+
+## Status
+
+Functional. The CLI surface (`taut-summon run|stop|status`) and the core
+delegation verbs (`taut summon`, `taut dismiss`), the foreground driver
+(bootstrap, chat injection, event pump, crash-resume, clean shutdown), the
+session ledger with a single-driver guard and PTY `wired` flag, the control
+plane (STOP/STATUS/PING) with a rate backstop, the default persona, and the
+provider adapters are implemented. `pty` is the default adapter for the
+interactive harnesses (`claude`, `codex`, `coder`, `grok`, `qwen`, `kimi`,
+`opencode`, `pi`); `claude-stream` remains available for Claude Code's
+structured stream-json mode. See
+`docs/plans/2026-07-06-taut-summon-plan.md`,
+`docs/plans/2026-07-07-taut-summon-pty-harness-adapter-plan.md`, and
+`docs/implementation/05-taut-summon-architecture.md` for the design.
+
+## Requirements
+
+- Python 3.11+
+- Core `taut` and `taut-summon` installed in the same environment
+- A SQL-sidecar backend (SQLite or Postgres) — summon state rides sidecar
+  tables
+
+## Installation
+
+Taut releases are GitHub-only until package-name clearance changes. Install
+the core package first, then inject the extension wheel into the same
+environment:
+
+```bash
+pipx install "git+https://github.com/VanL/taut.git@vX.Y.Z"
+pipx inject taut ./taut_summon-0.1.0-py3-none-any.whl
+```
+
+## Usage
+
+```bash
+taut summon claude              # summon a claude into #general
+taut summon reviewer --provider claude dev
+taut summon reviewer --provider claude-stream dev
+taut dismiss reviewer
+taut-summon status
+```
+
+`taut summon`/`taut dismiss` delegate argv verbatim to `taut-summon
+run`/`taut-summon stop`; both surfaces share one resolution contract.
+
+On first PTY use, summon attaches your terminal so you can answer trust,
+login, or model prompts in the real harness UI. Detach with `Ctrl-\ Ctrl-\`.
+After detach the member is marked wired and future summons run detached.
+Use `taut summon --attach NAME` to re-enter setup, or `--detach` for an
+explicit detached run. PTY output is never parsed as speech; the agent speaks
+by running `taut say`.
+
+## Testing
+
+From the repository root:
+
+```bash
+uv run pytest extensions/taut_summon/tests
+```
+
+Local runs attempt the live PTY harness smoke matrix by default. A provider
+skips with an explicit reason when its binary is absent, the fresh test
+database has not been onboarded with a real attach/detach cycle, or status
+cannot reach a usable detached session. CI skips the real-harness matrix
+unless `TAUT_SUMMON_LIVE_HARNESS=1` is set. For a fast local loop, use:
+
+```bash
+TAUT_SUMMON_LIVE_HARNESS=0 uv run pytest extensions/taut_summon/tests
+```
+
+Run `taut summon --attach <name>` once for a provider that still needs trust,
+login, or model setup before expecting its detached live smoke to pass.
+For a hard local external-provider smoke, use strict mode. It prewires the
+temporary test session to model an already-onboarded provider and fails on
+missing binaries, readiness gaps, status timeouts, unanswered terminal queries,
+or injection catch-up failures. The external-provider lane does not require
+hosted CLIs to auto-execute shell commands; the local LLM lane below owns the
+deterministic sentinel-posting proof.
+
+```bash
+TAUT_SUMMON_LIVE_HARNESS_STRICT=1 uv run pytest extensions/taut_summon/tests/test_live_harness.py
+```
+
+The local LLM smoke runs locally by default when a loopback OpenAI-compatible
+endpoint lists the served model, and it runs in CI through the dedicated
+Ollama-backed workflow job. Defaults:
+
+```bash
+TAUT_SUMMON_LOCAL_LLM_ENDPOINT=http://127.0.0.1:11434/v1
+TAUT_SUMMON_LOCAL_LLM_MODEL=taut-summon-local-model:latest
+```
+
+To run it locally with Ollama:
+
+```bash
+ollama pull qwen2.5:0.5b
+cat > /tmp/TautSummonModelfile <<'EOF'
+FROM qwen2.5:0.5b
+PARAMETER num_ctx 2048
+PARAMETER num_predict 64
+PARAMETER temperature 0
+EOF
+ollama create taut-summon-local-model:latest -f /tmp/TautSummonModelfile
+uv run pytest extensions/taut_summon/tests/test_live_local_llm.py
+```
+
+Use `TAUT_SUMMON_LOCAL_LLM=0` to skip the local LLM smoke locally, or
+`TAUT_SUMMON_LOCAL_LLM=1` to make missing endpoint/model setup fail instead of
+skip.

taut_summon-0.5.0/README.md

@@ -0,0 +1,121 @@
+# taut-summon
+
+Summon extension for Taut: host an existing agent harness (Claude Code and
+friends) as an ordinary member of a taut workspace.
+
+This package is intentionally separate from `taut`. The summon driver is the
+agent's terminal, not its runtime: it injects chat into the harness's own
+live session (its ears), and the agent speaks through the ordinary `taut`
+CLI selected by its continuity token (its mouth). The full contract lives in
+the core repository at `docs/specs/04-summon.md`.
+
+## Status
+
+Functional. The CLI surface (`taut-summon run|stop|status`) and the core
+delegation verbs (`taut summon`, `taut dismiss`), the foreground driver
+(bootstrap, chat injection, event pump, crash-resume, clean shutdown), the
+session ledger with a single-driver guard and PTY `wired` flag, the control
+plane (STOP/STATUS/PING) with a rate backstop, the default persona, and the
+provider adapters are implemented. `pty` is the default adapter for the
+interactive harnesses (`claude`, `codex`, `coder`, `grok`, `qwen`, `kimi`,
+`opencode`, `pi`); `claude-stream` remains available for Claude Code's
+structured stream-json mode. See
+`docs/plans/2026-07-06-taut-summon-plan.md`,
+`docs/plans/2026-07-07-taut-summon-pty-harness-adapter-plan.md`, and
+`docs/implementation/05-taut-summon-architecture.md` for the design.
+
+## Requirements
+
+- Python 3.11+
+- Core `taut` and `taut-summon` installed in the same environment
+- A SQL-sidecar backend (SQLite or Postgres) — summon state rides sidecar
+  tables
+
+## Installation
+
+Taut releases are GitHub-only until package-name clearance changes. Install
+the core package first, then inject the extension wheel into the same
+environment:
+
+```bash
+pipx install "git+https://github.com/VanL/taut.git@vX.Y.Z"
+pipx inject taut ./taut_summon-0.1.0-py3-none-any.whl
+```
+
+## Usage
+
+```bash
+taut summon claude              # summon a claude into #general
+taut summon reviewer --provider claude dev
+taut summon reviewer --provider claude-stream dev
+taut dismiss reviewer
+taut-summon status
+```
+
+`taut summon`/`taut dismiss` delegate argv verbatim to `taut-summon
+run`/`taut-summon stop`; both surfaces share one resolution contract.
+
+On first PTY use, summon attaches your terminal so you can answer trust,
+login, or model prompts in the real harness UI. Detach with `Ctrl-\ Ctrl-\`.
+After detach the member is marked wired and future summons run detached.
+Use `taut summon --attach NAME` to re-enter setup, or `--detach` for an
+explicit detached run. PTY output is never parsed as speech; the agent speaks
+by running `taut say`.
+
+## Testing
+
+From the repository root:
+
+```bash
+uv run pytest extensions/taut_summon/tests
+```
+
+Local runs attempt the live PTY harness smoke matrix by default. A provider
+skips with an explicit reason when its binary is absent, the fresh test
+database has not been onboarded with a real attach/detach cycle, or status
+cannot reach a usable detached session. CI skips the real-harness matrix
+unless `TAUT_SUMMON_LIVE_HARNESS=1` is set. For a fast local loop, use:
+
+```bash
+TAUT_SUMMON_LIVE_HARNESS=0 uv run pytest extensions/taut_summon/tests
+```
+
+Run `taut summon --attach <name>` once for a provider that still needs trust,
+login, or model setup before expecting its detached live smoke to pass.
+For a hard local external-provider smoke, use strict mode. It prewires the
+temporary test session to model an already-onboarded provider and fails on
+missing binaries, readiness gaps, status timeouts, unanswered terminal queries,
+or injection catch-up failures. The external-provider lane does not require
+hosted CLIs to auto-execute shell commands; the local LLM lane below owns the
+deterministic sentinel-posting proof.
+
+```bash
+TAUT_SUMMON_LIVE_HARNESS_STRICT=1 uv run pytest extensions/taut_summon/tests/test_live_harness.py
+```
+
+The local LLM smoke runs locally by default when a loopback OpenAI-compatible
+endpoint lists the served model, and it runs in CI through the dedicated
+Ollama-backed workflow job. Defaults:
+
+```bash
+TAUT_SUMMON_LOCAL_LLM_ENDPOINT=http://127.0.0.1:11434/v1
+TAUT_SUMMON_LOCAL_LLM_MODEL=taut-summon-local-model:latest
+```
+
+To run it locally with Ollama:
+
+```bash
+ollama pull qwen2.5:0.5b
+cat > /tmp/TautSummonModelfile <<'EOF'
+FROM qwen2.5:0.5b
+PARAMETER num_ctx 2048
+PARAMETER num_predict 64
+PARAMETER temperature 0
+EOF
+ollama create taut-summon-local-model:latest -f /tmp/TautSummonModelfile
+uv run pytest extensions/taut_summon/tests/test_live_local_llm.py
+```
+
+Use `TAUT_SUMMON_LOCAL_LLM=0` to skip the local LLM smoke locally, or
+`TAUT_SUMMON_LOCAL_LLM=1` to make missing endpoint/model setup fail instead of
+skip.

taut_summon-0.5.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taut-summon"
+version = "0.5.0"
+description = "Summon extension for Taut: host an agent harness as a workspace member"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+license-files = ["LICENSE"]
+authors = [
+    {name = "Van Lindberg", email = "van.lindberg@gmail.com"},
+]
+dependencies = [
+    # Floor is the core version shipping the `summon`/`dismiss` delegation
+    # verbs and the blessed identity/state surfaces this extension builds on.
+    "taut>=0.5.0",
+]
+
+[project.scripts]
+taut-summon = "taut_summon.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.0",
+    "pytest>=7.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.0",
+    "ruff>=0.1.0",
+]
+
+[tool.uv.sources]
+taut = { path = "../..", editable = true }
+
+[tool.hatch.build]
+include = [
+    "/taut_summon/**/*.py",
+    "/taut_summon/py.typed",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+addopts = "-ra -q --strict-markers -n auto --dist loadgroup"
+markers = [
+    "requires_claude: live smoke tests that spawn the installed claude CLI (skipped when absent)",
+    "requires_live_harness: live PTY harness smoke tests; local by default, CI opt-in",
+    "requires_local_llm: local-LLM-backed PTY smoke tests; local by default, prepared CI opt-in",
+    "requires_codex: live smoke tests that spawn the installed codex CLI",
+    "requires_coder: live smoke tests that spawn the installed coder CLI",
+    "requires_grok: live smoke tests that spawn the installed grok CLI",
+    "requires_qwen: live smoke tests that spawn the installed qwen CLI",
+    "requires_kimi: live smoke tests that spawn the installed kimi CLI",
+    "requires_opencode: live smoke tests that spawn the installed opencode CLI",
+    "requires_pi: live smoke tests that spawn the installed pi CLI",
+    "xdist_group: group tests that share global external resources",
+    "sqlite_only: tests that validate built-in SQLite/path behavior",
+]

taut_summon-0.5.0/taut_summon/__init__.py

@@ -0,0 +1,40 @@
+"""Summon extension for Taut: host an agent harness as a workspace member.
+
+Spec: docs/specs/04-summon.md ([SUM-1]-[SUM-12]) in the core repository.
+
+The adapter surface is exported here because the ``scripted`` adapter
+ships for downstream integrators ([SUM-7.2]): conformance runners spawn
+it as a real subprocess speaking real stream shapes ([SUM-12]).
+"""
+
+from __future__ import annotations
+
+from taut_summon._adapter import (
+    ActivityEvent,
+    AdapterError,
+    AdapterEvent,
+    AdapterHandle,
+    AssistantTextEvent,
+    ExitEvent,
+    ProviderAdapter,
+    SessionEvent,
+    UnknownAdapterError,
+    adapter_names,
+    get_adapter,
+)
+from taut_summon._scripted import ScriptedAdapter
+
+__all__ = [
+    "ActivityEvent",
+    "AdapterError",
+    "AdapterEvent",
+    "AdapterHandle",
+    "AssistantTextEvent",
+    "ExitEvent",
+    "ProviderAdapter",
+    "ScriptedAdapter",
+    "SessionEvent",
+    "UnknownAdapterError",
+    "adapter_names",
+    "get_adapter",
+]

taut_summon-0.5.0/taut_summon/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point: ``python -m taut_summon``."""
+
+from __future__ import annotations
+
+from taut_summon.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

taut_summon-0.5.0/taut_summon/_adapter.py

@@ -0,0 +1,212 @@
+"""Provider adapter interface: the [SUM-7.1] contract and the registry.
+
+An adapter owns exactly four things — spawn, inject, events, interrupt —
+and translates its provider's native streaming envelope into the closed
+``AdapterEvent`` union below. There is no summon-defined wire protocol:
+adapters translate, they do not define ([SUM-7.1]).
+
+Contract requirements on every adapter (enforced by the conformance
+tests, exercised today through the ``scripted`` adapter):
+
+- ``inject()`` returns only after the event is written *and flushed* to
+  the child's stdin, and surfaces failures synchronously ([SUM-5.4]'s
+  at-least-once delivery to the harness process boundary depends on it).
+- ``interrupt()`` and ``close()`` are thread-safe and unblock any
+  in-flight ``inject()`` — [SUM-9]'s STOP path must always be able to
+  stop a stalled harness.
+- ``events()`` must be drained continuously by its (single) consumer; an
+  undrained stream is a child-stdout deadlock waiting to happen. The
+  stream ends with exactly one ``ExitEvent``.
+- ``env`` passed to ``spawn`` is merged over the parent environment —
+  it carries additions such as ``TAUT_TOKEN``/``TAUT_DB`` ([SUM-6]),
+  not a replacement environment.
+
+Spec references:
+- docs/specs/04-summon.md [SUM-7.1], [SUM-7.2]
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable, Iterator, Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class AdapterError(Exception):
+    """An adapter operation failed (spawn, inject, or stream translation)."""
+
+
+class UnknownAdapterError(AdapterError):
+    """No adapter is registered under the requested provider name."""
+
+
+@dataclass(frozen=True, slots=True)
+class AssistantTextEvent:
+    """Assistant-authored text (posted to chat only in terminal mode)."""
+
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityEvent:
+    """Tool use or comparable liveness signal — feeds presence, never chat."""
+
+    description: str
+
+
+@dataclass(frozen=True, slots=True)
+class SessionEvent:
+    """The provider announced or changed its session id (resume handle)."""
+
+    session_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExitEvent:
+    """The harness child exited; the event stream ends after this."""
+
+    returncode: int
+
+
+AdapterEvent = AssistantTextEvent | ActivityEvent | SessionEvent | ExitEvent
+
+
+class AdapterHandle(Protocol):
+    """A live harness child owned by an adapter."""
+
+    @property
+    def session_id(self) -> str | None:
+        """Current provider session id, updated as ``SessionEvent``s arrive."""
+        ...
+
+    @property
+    def pid(self) -> int:
+        """Harness child pid — the [SUM-4] re-anchor evidence.
+
+        The summoned member's identity anchor is ultimately the harness
+        child process; the driver builds its rejoin capture from this pid,
+        so exposing it is part of the handle surface.
+        """
+        ...
+
+    def inject(self, text: str) -> None:
+        """Write one user-role event; return only after a flushed write."""
+        ...
+
+    def events(self) -> Iterator[AdapterEvent]:
+        """Typed output stream; single consumer, ends with ``ExitEvent``."""
+        ...
+
+    def interrupt(self) -> None:
+        """Harness-graceful stop; unblocks an in-flight ``inject()``."""
+        ...
+
+    def close(self) -> None:
+        """Stop (bounded escalation), reap the child, release the pipes."""
+        ...
+
+    def status_fields(self) -> dict[str, str]:
+        """Adapter-specific STATUS fields; empty for structured adapters."""
+        ...
+
+
+class ProviderAdapter(Protocol):
+    """One provider harness family (claude, scripted, codex...)."""
+
+    name: str
+    supports_terminal_mode: bool
+    supports_attach: bool
+    orientation_via_inject: bool
+
+    def spawn(
+        self,
+        *,
+        session_id: str | None,
+        system_prompt: str,
+        env: Mapping[str, str],
+    ) -> AdapterHandle:
+        """Start the harness child, resuming ``session_id`` when given."""
+        ...
+
+
+def _scripted_factory() -> ProviderAdapter:
+    from taut_summon._scripted import ScriptedAdapter
+
+    return ScriptedAdapter()
+
+
+def _claude_factory() -> ProviderAdapter:
+    from taut_summon._claude import ClaudeAdapter
+
+    return ClaudeAdapter()
+
+
+def _pty_factory() -> ProviderAdapter:
+    from taut_summon._pty import PtyAdapter, PtySpec
+
+    raw_argv = os.environ.get("TAUT_SUMMON_PTY_ARGV")
+    if raw_argv:
+        parsed = json.loads(raw_argv)
+        if not isinstance(parsed, list) or not all(
+            isinstance(item, str) and item for item in parsed
+        ):
+            raise AdapterError("TAUT_SUMMON_PTY_ARGV must be a JSON string list")
+        spec = PtySpec(
+            name="pty",
+            argv=tuple(parsed),
+            rows=int(os.environ.get("TAUT_SUMMON_PTY_ROWS", "24")),
+            cols=int(os.environ.get("TAUT_SUMMON_PTY_COLS", "80")),
+            stall_s=float(os.environ.get("TAUT_SUMMON_PTY_STALL_S", "10.0")),
+            quiet_ms=int(os.environ.get("TAUT_SUMMON_PTY_QUIET_MS", "500")),
+            max_settle_s=float(os.environ.get("TAUT_SUMMON_PTY_MAX_SETTLE_S", "10.0")),
+        )
+        return PtyAdapter(spec)
+    return PtyAdapter()
+
+
+def _pty_harness_factory(name: str, binary: str) -> Callable[[], ProviderAdapter]:
+    def _factory() -> ProviderAdapter:
+        from taut_summon._pty import PtyAdapter, PtySpec
+
+        return PtyAdapter(PtySpec(name=name, argv=(binary,)))
+
+    return _factory
+
+
+_FACTORIES: dict[str, Callable[[], ProviderAdapter]] = {
+    "claude": _pty_harness_factory("claude", "claude"),
+    "claude-stream": _claude_factory,
+    "codex": _pty_harness_factory("codex", "codex"),
+    "coder": _pty_harness_factory("coder", "coder"),
+    "grok": _pty_harness_factory("grok", "grok"),
+    "kimi": _pty_harness_factory("kimi", "kimi"),
+    "opencode": _pty_harness_factory("opencode", "opencode"),
+    "pi": _pty_harness_factory("pi", "pi"),
+    "pty": _pty_factory,
+    "qwen": _pty_harness_factory("qwen", "qwen"),
+    "scripted": _scripted_factory,
+}
+
+
+def adapter_names() -> tuple[str, ...]:
+    """Return the registered provider names, sorted."""
+
+    return tuple(sorted(_FACTORIES))
+
+
+def get_adapter(name: str) -> ProviderAdapter:
+    """Return the adapter registered under ``name``.
+
+    Raises ``UnknownAdapterError`` naming the known adapters ([SUM-3]
+    resolution step 4).
+    """
+
+    factory = _FACTORIES.get(name)
+    if factory is None:
+        known = ", ".join(adapter_names())
+        raise UnknownAdapterError(
+            f"no adapter named '{name}' (known adapters: {known})"
+        )
+    return factory()

taut_summon-0.5.0/taut_summon/_broker_retry.py

@@ -0,0 +1,64 @@
+"""taut-summon's broker-specific retry policy, over the generic engine.
+
+Mirrors simplebroker's own layering: the generic, re-vendorable loop lives
+in ``_retry.py`` and the domain-specific policy — which errors are
+transient, how many attempts, how to back off — sits on top here, the way
+``simplebroker/helpers.py`` layers ``_execute_with_retry`` /
+``_execute_watcher_operational_retry`` over the same engine.
+
+``_retry.py`` is **vendored byte-for-byte** from ``simplebroker/_retry.py``
+(simplebroker 5.1.0), which is published as a copy-me module for exactly
+this use. It is kept pristine (no local edits) so it stays a diffable
+drop-in copy; all provenance lives here, not inside that file. Re-vendor by
+re-copying the upstream file when its ``__version__`` bumps. taut's
+facades-only rule forbids importing ``simplebroker._retry`` directly, which
+is why the engine is vendored rather than imported.
+
+Spec reference: docs/specs/04-summon.md [SUM-9] (control-plane retry defense).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TypeVar
+
+from taut._broker_retry import is_transient_broker_error
+from taut_summon._retry import execute_retry, expo, stop_after_attempt
+
+logger = logging.getLogger("taut_summon.broker")
+
+T = TypeVar("T")
+
+_BROKER_RETRIES = 30
+_BROKER_RETRY_DELAY = 0.05
+_BROKER_RETRY_MAX_DELAY = 0.5
+
+
+def broker_retry(
+    fn: Callable[[], T], *, what: str, attempts: int = _BROKER_RETRIES
+) -> T:
+    """Run a bare broker op, riding out transient WAL read errors.
+
+    Bare ``read_one``/``write`` on the control queues go through this so a
+    command or reply is not lost to a checkpoint-race transient (core's
+    watcher retries its own ops; bare ops do not). A persistent failure —
+    real corruption, or a non-transient class — is re-raised after the
+    bounded budget, so nothing genuinely broken is masked.
+    """
+
+    def _log(state: object, exc: Exception, delay: float) -> None:
+        logger.debug("transient broker error on %s; retrying: %s", what, exc)
+
+    return execute_retry(
+        fn,
+        retry_on=is_transient_broker_error,
+        wait_gen=expo,
+        wait_gen_kwargs={
+            "base": 2,
+            "factor": _BROKER_RETRY_DELAY,
+            "max_value": _BROKER_RETRY_MAX_DELAY,
+        },
+        stop=stop_after_attempt(attempts),
+        before_sleep=_log,
+    )