athena-python-docx 0.8.0__tar.gz → 0.9.0__tar.gz

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/CLAUDE.md

@@ -181,6 +181,27 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   and the follow-up `doc.insert` is buffered, so plain cell
   assignments are 0 HTTP requests until the next flush. See
   ``docx.table._is_plain_text`` for the trigger predicate.
+- **Partial-failure cascade fix (0.9.0+):** when an HTTP batch raises
+  on a 207 partial-failure (e.g. one cell-paragraph mistake mid-script),
+  the SDK now rewrites ``proxy_id_refs`` for the ``applied`` prefix
+  the server reports as successful — BEFORE re-raising. Pre-0.9.0 the
+  rewrite was inside the success-path-only branch, so every Create that
+  committed server-side left its Python proxy stuck on the client UUID;
+  the next batch shipped dead client UUIDs and the cascade restarted.
+  Preview-session ``thread_bafba02b`` turned one cell-paragraph error
+  into thirteen downstream "Block not found" failures + a
+  ``DOCUMENT_IDENTITY_CONFLICT`` before this fix. The path goes
+  ``_http_post_json`` (attaches ``applied[]`` via
+  ``DocxError.with_partial_applied``) → ``CommandBuffer.flush`` /
+  ``_eager_flush_with`` (catches ``DocxError``, drains the prefix
+  through ``_apply_proxy_id_rewrites``, re-raises). See
+  ``tests/test_partial_failure_cascade.py`` for the contract.
+- **Table-query hint (0.9.0+):** ``BlockNotFoundError`` on
+  ``TablesGet`` / ``TablesGetCells`` / etc. used to fall through with
+  no hint (the cell-paragraph workaround doesn't apply). Now carries
+  a dedicated "stale client-table-UUID" hint pointing at the actual
+  recovery (``doc.save()`` to drain pending + re-anchor proxies). See
+  ``_TABLE_CLIENT_ID_HINT`` in ``docx/_http_doc.py``.
 - The path-proxy in `_http_doc.py` is an internal translation layer:
   call sites that look like `await self._session.doc.create.paragraph(p)`
   resolve to `CommandBuffer.call(CreateParagraph(**p))`. Rewriting call

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.8.0
+Version: 0.9.0
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/docx/_buffer.py

@@ -35,11 +35,94 @@ from typing import TYPE_CHECKING, Any
 
 from docx import _ptc
 from docx.commands import Command, is_response_bearing, must_flush_immediately
+from docx.errors import DocxError
+
+
+def _apply_proxy_id_rewrites(
+    results: list[Any],
+    proxy_id_refs: "dict[str, list[tuple[object, str]]]",
+) -> None:
+    """Walk ``results`` and rewrite registered proxy ids from client UUIDs
+    to the real SuperDoc ids the applier echoed back.
+
+    Shared by the success path in :meth:`CommandBuffer.flush` /
+    :meth:`_eager_flush_with` AND by the **partial-failure recovery
+    path** (the SDK now reads ``DocxError.partial_applied`` on raise
+    and applies the same rewrite for the prefix that committed before
+    the server hit its first failure). Without this, every Create that
+    succeeded server-side would leave its Python proxy stuck on the
+    client UUID and the next batch would ship the dead id straight
+    back to the server — that cascade is what turned one cell-
+    paragraph mistake in preview-session ``thread_bafba02b`` into
+    thirteen downstream "Block not found" errors.
+
+    Tolerant of legacy / transitional applier results that don't
+    include ``client_node_id`` / ``real_node_id`` echoes — we simply
+    leave those proxies on their client id; the applier's per-batch
+    ``clientIdMap`` rewrite still resolves them server-side on the
+    *next* call.
+    """
+    if not proxy_id_refs:
+        return
+    for result in results:
+        if not isinstance(result, dict):
+            continue
+        for cli_key, real_key in (
+            ("client_node_id", "real_node_id"),
+            ("client_entity_id", "real_entity_id"),
+        ):
+            cli = result.get(cli_key)
+            real = result.get(real_key)
+            if not (isinstance(cli, str) and isinstance(real, str)):
+                continue
+            refs = proxy_id_refs.pop(cli, [])
+            for proxy, attr in refs:
+                try:
+                    setattr(proxy, attr, real)
+                except Exception:  # noqa: BLE001
+                    # A proxy that rejected setattr (slots without the
+                    # attr, frozen dataclass, etc.) silently keeps its
+                    # client_id — the applier's rewriter will still
+                    # resolve it correctly on the next batch.
+                    pass
+
+
+def _extract_partial_results(exc: BaseException) -> list[Any]:
+    """Pull per-command ``result`` dicts out of a partial-failure error.
+
+    The HTTP layer attaches the server's ``applied`` array to
+    :class:`DocxError` (and subclasses) as ``partial_applied``. Each
+    entry is the wire-format ``{index, type, result}`` triple. We
+    return just the ``result`` dicts so the rewrite path can share its
+    success-path code without caring whether it's running on a happy
+    batch or a salvaged prefix.
+    """
+    applied = getattr(exc, "partial_applied", None)
+    if not isinstance(applied, list):
+        return []
+    out: list[Any] = []
+    for entry in applied:
+        if isinstance(entry, dict):
+            result = entry.get("result")
+            if isinstance(result, dict):
+                out.append(result)
+    return out
 
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
 
 
+# Only commands whose class name is in this set produce PTC sub-tool-cards.
+# Every Command subclass is a candidate, but each emit is now a synchronous
+# HTTP POST to agora (see ``_ptc._send``), so emitting one card per low-level
+# mutation produces hundreds of sub-cards per script and pays full network
+# RTT on every one. The allow-list keeps the per-action signal — one card
+# per logical paragraph creation — without the spam or the cumulative
+# latency. Asset-level creation events (``CreateDocument``) are emitted
+# from ``Document.create`` directly, not through this buffer path.
+_PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph"})
+
+
 def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
     """Emit a PTC ``end`` event for every cmd that received a ``begin``.
 
@@ -85,9 +168,7 @@ def _unregister(buffer: "CommandBuffer") -> None:
     """
     with _registry_lock:
         _active_buffers[:] = [
-            ref
-            for ref in _active_buffers
-            if (b := ref()) is not None and b is not buffer
+            ref for ref in _active_buffers if (b := ref()) is not None and b is not buffer
         ]
 
 
@@ -170,14 +251,10 @@ class CommandBuffer:
         # real nodeId after flush. Populated by ``add_paragraph`` /
         # ``add_heading`` / etc. when they queue a Create with a
         # client-assigned id. Drained on every flush.
-        self._proxy_id_refs: dict[
-            str, list[tuple[object, str]]
-        ] = {}
+        self._proxy_id_refs: dict[str, list[tuple[object, str]]] = {}
         _register(self)
 
-    def register_proxy_id_ref(
-        self, client_id: str, proxy: object, attr: str = "_node_id"
-    ) -> None:
+    def register_proxy_id_ref(self, client_id: str, proxy: object, attr: str = "_node_id") -> None:
         """Register that ``proxy.<attr>`` should be rewritten from
         ``client_id`` to the real node id once the queue flushes.
 
@@ -215,9 +292,7 @@ class CommandBuffer:
         ``"direct"``, ``"tracked"``, or ``None`` to clear.
         """
         if mode is not None and mode not in ("direct", "tracked"):
-            raise ValueError(
-                f"change_mode must be 'direct', 'tracked', or None; got {mode!r}"
-            )
+            raise ValueError(f"change_mode must be 'direct', 'tracked', or None; got {mode!r}")
         with self._lock:
             current = self._change_mode
         if current == mode:
@@ -269,16 +344,19 @@ class CommandBuffer:
                 f"CommandBuffer for {self._asset_id} is closed",
             )
 
-        # PTC begin: one event per user-facing method call, before any
-        # batching. Failures here can't crash the user's code path.
-        try:
-            cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
-                type(cmd).__name__,
-                cmd.to_dict(),
-                asset_id=self._asset_id,
-            )
-        except Exception:  # noqa: BLE001
-            pass
+        # PTC begin: emit only for commands in the allow-list. Other
+        # commands still flow through the buffer (and through the batched
+        # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
+        # is automatically skipped because no ``_ptc_call_id`` was set.
+        if type(cmd).__name__ in _PTC_EMIT_TOOLS:
+            try:
+                cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
+                    type(cmd).__name__,
+                    cmd.to_dict(),
+                    asset_id=self._asset_id,
+                )
+            except Exception:  # noqa: BLE001
+                pass
 
         if must_flush_immediately(cmd) and not self._has_client_id(cmd):
             return self._eager_flush_with(cmd)
@@ -300,12 +378,9 @@ class CommandBuffer:
         legacy callers) keep their eager-flush semantics so callers
         that read the response still see real data.
         """
-        return (
-            is_response_bearing(cmd)
-            and (
-                getattr(cmd, "client_node_id", None) is not None
-                or getattr(cmd, "client_entity_id", None) is not None
-            )
+        return is_response_bearing(cmd) and (
+            getattr(cmd, "client_node_id", None) is not None
+            or getattr(cmd, "client_entity_id", None) is not None
         )
 
     def flush(self) -> list[Any]:
@@ -339,37 +414,22 @@ class CommandBuffer:
                 change_mode=change_mode,
                 user=user,
             )
+        except DocxError as exc:
+            # Partial-failure cascade protection: even though the batch
+            # raised, the server's ``applied`` prefix tells us which
+            # commands DID commit before the failure. Rewrite the
+            # corresponding proxy ids before re-raising so the next
+            # batch ships REAL ids for the survivors (vs. dead client
+            # UUIDs that would cascade into another "Block not found").
+            # See ``_apply_proxy_id_rewrites`` for the full rationale.
+            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _ptc_emit_end_batch(pending, is_error=True)
+            raise
         except Exception:
             _ptc_emit_end_batch(pending, is_error=True)
             raise
         _ptc_emit_end_batch(pending, is_error=False)
-        # Rewrite registered proxies from client-side UUIDs to the real
-        # SuperDoc ids the applier echoed back. Defensive: tolerate
-        # missing fields (legacy or transitional applier without the
-        # client-id support).
-        if proxy_id_refs:
-            for result in results:
-                if not isinstance(result, dict):
-                    continue
-                for cli_key, real_key in (
-                    ("client_node_id", "real_node_id"),
-                    ("client_entity_id", "real_entity_id"),
-                ):
-                    cli = result.get(cli_key)
-                    real = result.get(real_key)
-                    if not (isinstance(cli, str) and isinstance(real, str)):
-                        continue
-                    refs = proxy_id_refs.pop(cli, [])
-                    for proxy, attr in refs:
-                        try:
-                            setattr(proxy, attr, real)
-                        except Exception:  # noqa: BLE001
-                            # A proxy that rejected setattr (slots without
-                            # the attr, frozen dataclass, etc.) silently
-                            # keeps its client_id — the rewriter in the
-                            # applier will still resolve it correctly
-                            # for the next batch.
-                            pass
+        _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
 
     def close(self) -> None:
@@ -409,30 +469,22 @@ class CommandBuffer:
                 change_mode=change_mode,
                 user=user,
             )
+        except DocxError as exc:
+            # Same partial-failure cascade protection as :meth:`flush` —
+            # rewrite proxy ids for the prefix the server reports as
+            # ``applied`` before re-raising. Critical here because the
+            # eager-flush path is hit by every query in user code (e.g.
+            # ``table.cell(0, 0)`` → ``tables.get``), so a failure on
+            # the trailing ``cmd`` would otherwise abandon every
+            # buffered Create's rewrite at once.
+            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _ptc_emit_end_batch(all_cmds, is_error=True)
+            raise
         except Exception:
             _ptc_emit_end_batch(all_cmds, is_error=True)
             raise
         _ptc_emit_end_batch(all_cmds, is_error=False)
-        # Apply the same proxy-rewrite pass as ``flush()`` — see comment
-        # there for the contract.
-        if proxy_id_refs:
-            for result in results:
-                if not isinstance(result, dict):
-                    continue
-                for cli_key, real_key in (
-                    ("client_node_id", "real_node_id"),
-                    ("client_entity_id", "real_entity_id"),
-                ):
-                    cli = result.get(cli_key)
-                    real = result.get(real_key)
-                    if not (isinstance(cli, str) and isinstance(real, str)):
-                        continue
-                    refs = proxy_id_refs.pop(cli, [])
-                    for proxy, attr in refs:
-                        try:
-                            setattr(proxy, attr, real)
-                        except Exception:  # noqa: BLE001
-                            pass
+        _apply_proxy_id_rewrites(results, proxy_id_refs)
         if not results:
             return {}
         return results[-1]

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/docx/_http_doc.py

@@ -154,17 +154,102 @@ def _looks_like_block_not_found(err_obj: dict) -> bool:
     return 'block "' in lower or ('block ' in lower and ' was not found' in lower)
 
 
+# Commands that target a paragraph block (or its inline range) and
+# therefore trip the SuperDoc 1.8.1 cell-paragraph addressing gap when
+# the target paragraph is nested inside a ``tableCell``. Used by the
+# ``BlockNotFoundError`` hint logic to decide whether to surface the
+# materialization workaround. Membership is checked against the
+# ``err_obj["type"]`` field that ``apps/api`` echoes back on partial
+# failure, so the gate covers both error-message shapes the SuperDoc
+# CLI emits:
+#
+# * ``Block "paragraph:<uuid>" was not found.`` (SetParagraph*, etc.)
+# * ``Block "<uuid>" not found.``                (Insert)
+#
+# Without this gate, the hint either fired for stale-id misses on
+# unrelated command types (Greptile #20555) or skipped the Insert form
+# entirely (preview session
+# thread_b952794f, where 3 of 4 failures were bare-UUID Inserts and
+# the agent burned 4 retries without ever seeing the workaround).
+_PARAGRAPH_TARGETING_COMMANDS: frozenset[str] = frozenset(
+    {
+        "Insert",
+        "FormatApply",
+        "SetParagraphAlignment",
+        "ClearParagraphAlignment",
+        "SetParagraphStyle",
+        "SetParagraphIndentation",
+        "ClearParagraphIndentation",
+        "SetParagraphSpacing",
+        "ClearParagraphSpacing",
+        "SetParagraphKeepOptions",
+        "SetParagraphFlowOptions",
+        "SetParagraphTabStop",
+        "ClearParagraphTabStops",
+        "Replace",
+        "InsertLineBreak",
+        "InsertTab",
+    }
+)
+
+
 _CELL_PARAGRAPH_HINT: str = (
     "\n\nHint: SuperDoc 1.8.1 cannot format paragraphs nested inside "
     "table cells via SetParagraphAlignment / SetParagraphStyle / "
-    "SetParagraphIndentation / SetParagraphSpacing or doc.insert with "
-    "a paragraph-block target. The cell's inner paragraph id is "
-    "returned by cell.getNodeById but isn't a top-level addressable "
-    "block. Materialize the cell's paragraph first via "
-    '``cell.text = "value"``, then re-read ``cell.paragraphs[0]`` and '
-    "apply format ops to that post-materialization Paragraph proxy. "
-    "Tracked upstream at docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md "
-    "§ 'cell-inner paragraph addressing'."
+    "SetParagraphIndentation / SetParagraphSpacing / doc.insert with "
+    "a paragraph-block target, or any FormatApply on a cell-inner run. "
+    "The cell's inner paragraph id is returned by cell.getNodeById but "
+    "isn't a top-level addressable block. Materialize the cell's "
+    'paragraph first via ``cell.text = "value"``, then re-read '
+    "``cell.paragraphs[0]`` and apply format ops to that post-"
+    "materialization Paragraph proxy. Tracked upstream at "
+    "docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md § 'cell-inner paragraph "
+    "addressing'."
+)
+
+
+# ``tables.get`` / ``tables.getCells`` / ``tables.getProperties`` carry
+# the table id at the top-level ``nodeId`` field — and the agent code
+# that triggers them (``table.cell(0, 0)``, ``table.rows``, etc.) runs
+# *immediately* after ``doc.add_table(...)``. The first such query
+# triggers an eager flush that drains the buffered CreateTable in the
+# same HTTP batch, so the applier's per-batch ``clientIdMap`` rewrite
+# normally catches it. But when an EARLIER batch (e.g. a doomed cell-
+# paragraph mutation a few lines up in the user script) raised before
+# the SDK could rewrite ``proxy_id_refs``, the Table proxy still holds
+# the client UUID. The next batch ships the dead id straight to SuperDoc
+# and we land here. The hint points the agent at the canonical recovery
+# pattern (force a save() to reseat the proxy refs, or split the
+# offending mutation into its own execution).
+_TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
+    {
+        "TablesGet",
+        "TablesGetCells",
+        "TablesGetProperties",
+        "TablesSetStyle",
+        "TablesSetLayout",
+        "TablesSetTableOptions",
+        "TablesSetCellProperties",
+        "TablesSetColumnWidth",
+        "TablesSetRowHeight",
+        "TablesInsertRow",
+        "TablesInsertColumn",
+        "TablesMergeCells",
+    }
+)
+
+
+_TABLE_CLIENT_ID_HINT: str = (
+    "\n\nHint: this looks like a stale client-side table UUID "
+    '(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution '
+    "raised before the SDK could rewrite the Table proxy's id from the "
+    "client UUID to the real SuperDoc id, OR the table belongs to a "
+    "prior execution whose state has been discarded. Recover by calling "
+    "``doc.save()`` to drain pending mutations + re-anchor live "
+    "proxies, then re-query via ``doc.tables`` to get fresh proxies "
+    "with real ids. If you saw a cell-paragraph error in the same "
+    "execution, address that first — its partial-failure is what "
+    "abandoned the rewrite."
 )
 
 
@@ -314,6 +399,20 @@ def _http_post_json(
             parsed = json.loads(body) if body else {}
         except json.JSONDecodeError:
             parsed = {"raw": body}
+        # Extract the ``applied`` prefix so callers can rewrite
+        # ``proxy_id_refs`` for commands that DID succeed before the
+        # batch hit its first failure. Without this, the SDK throws
+        # away every successful Create's client-UUID → real-id mapping
+        # the moment ONE command fails, and the next batch keeps
+        # shipping dead client UUIDs. That cascade turned the preview-
+        # session thread_bafba02b's first cell-paragraph mistake into
+        # thirteen downstream "Block not found" errors and finally a
+        # ``DOCUMENT_IDENTITY_CONFLICT``. The structure is wire-shape:
+        # ``[{index, type, result: {client_node_id, real_node_id, …}}]``.
+        applied_raw = parsed.get("applied") if isinstance(parsed, dict) else None
+        partial_applied: list[dict] = []
+        if isinstance(applied_raw, list):
+            partial_applied = [a for a in applied_raw if isinstance(a, dict)]
         # If the failing command's error looks like "no such entity",
         # raise a typed :class:`NotFoundError` so speculative-read call
         # sites (``Comments.get``) can coerce it to ``None`` without
@@ -325,27 +424,44 @@ def _http_post_json(
             # likely targeting a cell-inner paragraph or stale-session
             # block id. Surface the typed exception plus an agent-readable
             # workaround so the next attempt doesn't repeat the same
-            # mistake. The cell-paragraph hint only applies when the
-            # missing id has the ``paragraph:`` prefix (SuperDoc's quoted-
-            # id error format) — stale list-item / table-row / image ids
-            # would benefit from a different hint or none at all, and a
-            # red-herring "use cell.text" pointer would just waste the
-            # next retry.
+            # mistake.
+            #
+            # The cell-paragraph hint applies when the failing command is
+            # a paragraph-targeting op (Insert, FormatApply, SetParagraph*,
+            # …). We can't gate on the ``paragraph:`` prefix alone — the
+            # bare-UUID ``Block "<uuid>" not found.`` shape that SuperDoc's
+            # CLI emits for ``Insert`` failures is the dominant form of
+            # this bug in practice (preview-session thread_b952794f hit
+            # it 3 of 4 times without ever seeing the workaround under the
+            # prefix-only gate).
             if _looks_like_block_not_found(err_obj):
-                msg_str = err_obj.get("message")
-                paragraph_block = (
-                    isinstance(msg_str, str)
-                    and "paragraph:" in msg_str.lower()
+                cmd_type = err_obj.get("type")
+                paragraph_targeting = (
+                    isinstance(cmd_type, str)
+                    and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
                 )
+                table_query = (
+                    isinstance(cmd_type, str)
+                    and cmd_type in _TABLE_QUERY_COMMANDS
+                )
+                if paragraph_targeting:
+                    hint = _CELL_PARAGRAPH_HINT
+                elif table_query:
+                    hint = _TABLE_CLIENT_ID_HINT
+                else:
+                    hint = ""
                 raise BlockNotFoundError(
-                    base_msg + (_CELL_PARAGRAPH_HINT if paragraph_block else ""),
+                    base_msg + hint,
                     payload=err_obj,
-                )
+                ).with_partial_applied(partial_applied)
             if _looks_like_not_found(err_obj):
-                raise NotFoundError(base_msg, payload=err_obj)
+                raise NotFoundError(
+                    base_msg,
+                    payload=err_obj,
+                ).with_partial_applied(partial_applied)
         raise DocxError(
             f"docx-studio batch reported a partial failure: {parsed!r}",
-        )
+        ).with_partial_applied(partial_applied)
 
     if 200 <= resp.status_code < 300:
         try:

{athena_python_docx-0.8.0 → athena_python_docx-0.9.0}/docx/_ptc.py

@@ -8,10 +8,15 @@ verbatim, and the server derives identity from the token.
 
 Without ``ATHENA_PTC_URL`` set, every call here is a no-op.
 
-Emits are fire-and-forget on a background daemon thread:
-
-- Never raise into user code.
-- Never block the calling thread.
+Emits are **synchronous, best-effort** HTTP POSTs:
+
+- Never raise into user code (all transport errors are swallowed).
+- Block the caller for the duration of one POST (sub-millisecond on
+  localhost, tens of milliseconds against agora over the network).
+  This is intentional: the agora-side ``PTCRunRegistry`` tears down
+  its in-flight call set as soon as the parent tool's sandbox returns,
+  so an async outbox would let ``end`` events arrive after teardown
+  and the sub-tool-card would force-fail with "ended before end event".
 - Re-read ``ATHENA_PTC_URL`` on every emit so updates between sandbox
   executions take effect immediately (the SDK module itself is cached
   across runs).
@@ -28,67 +33,45 @@ from __future__ import annotations
 
 import json
 import os
-import queue
-import threading
 import time
 import urllib.error
 import urllib.request
 import uuid
 from typing import Any
 
-_MAX_QUEUE = 4096
 _MAX_BODY = 64 * 1024
 _HTTP_TIMEOUT = 2.0
 
-# Singleton state. PTC has exactly one outbox per process.
-_outbox: queue.Queue[tuple[str, dict[str, Any]]] = queue.Queue(maxsize=_MAX_QUEUE)
-_thread_lock = threading.Lock()
-_thread_started = False
 # call_id -> URL snapshot at begin time; lets emit_end target the
 # original run's endpoint even if ATHENA_PTC_URL changed since.
 _call_url: dict[str, str] = {}
 
 
-def _drain() -> None:
-    while True:
-        item = _outbox.get()
-        if item is None:
-            return
-        url, body = item
-        try:
-            raw = json.dumps(body).encode("utf-8")
-            if len(raw) > _MAX_BODY:
-                key = "args" if body.get("phase") == "begin" else "result"
-                body[key] = {"__truncated__": True}
-                raw = json.dumps(body).encode("utf-8")
-            req = urllib.request.Request(
-                url,
-                data=raw,
-                method="POST",
-                headers={"Content-Type": "application/json"},
-            )
-            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
-        except (urllib.error.URLError, OSError, ValueError):
-            pass  # never propagate
-
-
-def _ensure_thread() -> None:
-    global _thread_started
-    if _thread_started:
-        return
-    with _thread_lock:
-        if _thread_started:
-            return
-        threading.Thread(target=_drain, name="athena-ptc", daemon=True).start()
-        _thread_started = True
-
-
 def _send(url: str, body: dict[str, Any]) -> None:
-    _ensure_thread()
+    """Synchronously POST one PTC event. Best-effort; never raises.
+
+    Was previously an enqueue onto a background daemon thread. Made
+    synchronous so the agora-side ``PTCRunRegistry`` can rely on
+    "``emit_begin``/``emit_end`` returned" ⇒ "the registry has received
+    the event" — eliminating a teardown race that surfaced as every
+    sub-tool-card showing "ended before end event". See
+    ``docs/plans/2026-05-14-ptc-flush-race.md`` for the rationale.
+    """
     try:
-        _outbox.put_nowait((url, body))
-    except queue.Full:
-        pass  # drop on backpressure; never block user code
+        raw = json.dumps(body).encode("utf-8")
+        if len(raw) > _MAX_BODY:
+            key = "args" if body.get("phase") == "begin" else "result"
+            body[key] = {"__truncated__": True}
+            raw = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=raw,
+            method="POST",
+            headers={"Content-Type": "application/json"},
+        )
+        urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+    except (urllib.error.URLError, OSError, ValueError):
+        pass  # never propagate — PTC is best-effort
 
 
 def emit_begin(