code-puppy-core-plugins 0.0.45__tar.gz → 0.0.47__tar.gz

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.45
+Version: 0.0.47
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.15,>=3.11
 Requires-Dist: httpx<1,>=0.24.1
-Requires-Dist: pydantic-ai-slim[anthropic,mcp,openai]<3,>=2.31.0
+Requires-Dist: pydantic-ai-slim[anthropic,mcp,openai]<3,>=2.35.0
 Description-Content-Type: text/markdown
 
 # Code Puppy Core Plugins

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/code_puppy_core_plugins/claude_code_oauth/model_provider.py

@@ -123,10 +123,15 @@ def create_claude_code_model(model_name: str, model_config: Dict, config: Dict)
         ),
     )
 
+    # The transport already retries 429/5xx/connection errors with backoff,
+    # and the agent runtime retries the turn on top of that. The SDK's own
+    # retries would multiply every hard failure 3x -- a 429 storm is exactly
+    # when hammering the endpoint makes things worse.
     anthropic_client = AsyncAnthropic(
         base_url=url,
         http_client=client,
         auth_token=api_key,
+        max_retries=0,
     )
 
     def _update_runtime_token(access_token: str) -> None:

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/code_puppy_core_plugins/herdr/README.md

@@ -11,13 +11,14 @@ This plugin teaches code-puppy to report that state authoritatively.
 
 ## What it does
 
-herdr injects three environment variables into every pane it owns:
+herdr injects four environment variables into every pane it owns:
 
 | variable            | meaning                                   |
 | ------------------- | ----------------------------------------- |
 | `HERDR_ENV=1`       | this shell is running inside a herdr pane |
 | `HERDR_SOCKET_PATH` | herdr's local control socket              |
 | `HERDR_PANE_ID`     | the pane this process owns (e.g. `w1:p1`) |
+| `HERDR_TAB_ID`      | the workspace tab (e.g. `w1:t1`)          |
 
 On startup the plugin checks for those. If they're absent it does
 **nothing** -- zero overhead, zero output, no behaviour change, no socket,
@@ -94,6 +95,55 @@ when the reference actually changes (after `/clear`, `/session new`,
 This is a stable *reference*; automatic process restoration from it is
 **unverified** and not claimed here.
 
+## Conversation titles
+
+The `session_namer` plugin auto-names every conversation (the titles you
+see in `/resume`). This plugin propagates the current session's title to
+two herdr surfaces:
+
+* the pane's **presentation title**, which herdr renders as the pane
+  border label and the sidebar `pane` token, and
+* the **workspace tab label** in herdr's tab bar -- but only while the
+  tab holds a single pane (the one running this code-puppy). The tab bar
+  is a user-managed surface, so a tab shared with other panes is never
+  touched.
+
+Add the `pane` token to `rows_by_agent` to show the title in the sidebar
+too:
+
+```toml
+[ui.sidebar.agents.rows_by_agent]
+codepuppy = [
+  ["state_icon", "workspace", "tab"],
+  ["agent", "$model", "pane"],
+  ["$context", "$tokens"],
+]
+```
+
+The title is read from the session metadata sidecar that `session_namer`
+maintains (the same store `/resume` reads). The pane presentation title
+rides the same `pane.report_metadata` envelope as the token payload:
+herdr replaces the whole per-source metadata entry on each report, so
+every turn-end report re-sends the title (or a `clear_title` on a
+set-to-none transition) and a title change is reported title-only the
+moment it is seen. The tab label follows the same title changes via
+`tab.rename`, guarded by a `tab.get` read of the tab's `pane_count`; on
+a clean exit the original label is restored -- but only while the tab
+still shows the label we last set, so a tab you renamed by hand is never
+clobbered (a crashed exit simply leaves the last title in place, like
+the stale-pane case above).
+
+Because the namer names the session *asynchronously* after each autosave,
+a bounded background wait (2s ticks, 90s ceiling -- the namer's own model
+call is capped at 60s) picks the title up a few seconds after the turn
+ends instead of waiting for the next turn. The wait is single-flight,
+pinned to the session that triggered it, and skipped when the
+`session_namer` plugin is disabled via its `session_namer` config value.
+A session switch clears the previous session's title on the next prompt
+(and restores the tab label). As with the token payload, the pane title
+self-expires after the 24h metadata TTL, and all of this is decorative:
+it never touches the authoritative state and is a no-op outside herdr.
+
 ## Notifications are herdr's job
 
 The plugin sends no notifications itself. herdr derives attention and
@@ -103,7 +153,8 @@ plugin's only job is to report accurate state.
 
 ## Release on exit
 
-On `session_end` / `shutdown` the plugin calls `pane.release_agent` once
+On `session_end` / `shutdown` the plugin restores the workspace tab label
+(if it relabelled one) and then calls `pane.release_agent` once
 (idempotent, bounded) so herdr knows code-puppy has let go of the pane --
 no lingering stale `working`. There is no intermediate `idle` report on
 shutdown; if herdr is unavailable the release is bounded and can never
@@ -147,9 +198,9 @@ state, metadata, and activity.
 | ----------------------- | ------------------------------------------- |
 | `client.py`             | herdr socket transport (JSON, worker thread)|
 | `reporter.py`           | event -> state machine (refcount + dedup)   |
-| `sources.py`            | fail-soft adapters (tokens / session / msg) |
+| `sources.py`            | fail-soft adapters (tokens / title / session / msg) |
 | `register_callbacks.py` | callback wiring + env activation guard       |
-| `smoke.py`              | manual live smoke test (disposable pane)     |
+| `smoke.py`              | manual live smoke test (disposable pane + tab) |
 
 ## Live smoke test
 
@@ -163,6 +214,6 @@ python -m code_puppy_core_plugins.herdr.smoke
 
 It creates its **own** disposable pane, drives the real client through
 every protocol-16 method (state edges, session reference, metadata,
-release), reads each result back with `herdr pane get`, then closes the
-disposable pane -- your working pane is never touched. Exits non-zero if
-any check fails.
+conversation title, release), reads each result back with
+`herdr pane get`, then closes the disposable pane -- your working pane is
+never touched. Exits non-zero if any check fails.

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/code_puppy_core_plugins/herdr/client.py

@@ -7,13 +7,16 @@ environment variables:
 * ``HERDR_ENV=1``          -- marks the pane as herdr-managed
 * ``HERDR_SOCKET_PATH``    -- path to herdr's local control socket
 * ``HERDR_PANE_ID``        -- the pane this process owns (e.g. ``w1:p1``)
+* ``HERDR_TAB_ID``         -- the workspace tab (e.g. ``w1:t1``); optional
 
 This module speaks herdr's newline-delimited JSON socket protocol far
 enough to call ``pane.report_agent`` / ``pane.report_agent_session`` /
-``pane.report_metadata`` / ``pane.release_agent``. It reads herdr's ack
-(and retries a few times if it doesn't come) so an authoritative state
-edge is never silently lost, but it never raises into the caller:
-reporting agent state must never be able to disturb the agent itself.
+``pane.report_metadata`` / ``pane.release_agent`` -- plus ``tab.get`` /
+``tab.rename`` for the workspace-tab label (only while the tab holds a
+single pane). It reads herdr's ack (and retries a few times if it
+doesn't come) so an authoritative state edge is never silently lost, but
+it never raises into the caller: reporting agent state must never be
+able to disturb the agent itself.
 
 Delivery runs on a single daemon worker thread fed by **coalescing
 mailbox slots** rather than an unbounded queue:
@@ -75,6 +78,8 @@ _M_STATE = "pane.report_agent"
 _M_SESSION = "pane.report_agent_session"
 _M_METADATA = "pane.report_metadata"
 _M_RELEASE = "pane.release_agent"
+_M_TAB_GET = "tab.get"
+_M_TAB_RENAME = "tab.rename"
 
 
 class HerdrClient:
@@ -84,9 +89,11 @@ class HerdrClient:
         self,
         socket_path: Optional[str] = None,
         pane_id: Optional[str] = None,
+        tab_id: Optional[str] = None,
     ) -> None:
         self._socket_path = socket_path or os.environ.get("HERDR_SOCKET_PATH")
         self._pane_id = pane_id or os.environ.get("HERDR_PANE_ID")
+        self._tab_id = tab_id or os.environ.get("HERDR_TAB_ID")
         self._active = bool(
             os.environ.get("HERDR_ENV") == "1"
             and self._socket_path
@@ -102,6 +109,13 @@ class HerdrClient:
         # Decorative lane (latest-wins, discarded on release).
         self._message: Optional[Dict[str, Any]] = None
         self._metadata: Optional[Dict[str, Any]] = None
+        # Tab-label job slot (latest-wins; survives release scheduling so
+        # the exit-time restore still drains before the release).
+        self._tab: Optional[Dict[str, Any]] = None
+        # Tab-label ownership state (guarded by ``self._cond``).
+        self._tab_original: Optional[str] = None
+        self._tab_renamed = False
+        self._tab_last_label: Optional[str] = None
         # Terminal release slot.
         self._release: Optional[Dict[str, Any]] = None
 
@@ -173,17 +187,74 @@ class HerdrClient:
             return
         self._put("_session", params)
 
-    def report_metadata(self, tokens: Dict[str, Any]) -> None:
-        """Report pane metadata (model / context / tokens) on the decorative lane."""
-        if not tokens:
+    def report_metadata(
+        self,
+        tokens: Optional[Dict[str, Any]] = None,
+        *,
+        title: Optional[str] = None,
+        clear_title: bool = False,
+    ) -> None:
+        """Report pane metadata on the decorative lane (latest wins).
+
+        ``tokens`` are herdr's ``$token`` sidebar values; ``title`` sets the
+        pane presentation title (pane border + sidebar ``pane`` token);
+        ``clear_title`` drops it. No-op when nothing is set: herdr rejects
+        empty metadata envelopes. Note herdr replaces the whole per-source
+        metadata entry on each report, so a caller that sets a title must
+        keep re-sending it on later tokens-only reports or it is wiped.
+        """
+        if clear_title and title is not None:
+            # Caller bug: herdr rejects setting and clearing in one report.
+            # Clearing wins -- a stale title is less wrong than a rejected one.
+            title = None
+        if not clear_title and title is None and not tokens:
             return
         params: Dict[str, Any] = {
             "applies_to_source": SOURCE,
             "ttl_ms": _METADATA_TTL_MS,
-            "tokens": dict(tokens),
         }
+        if clear_title:
+            params["clear_title"] = True
+        elif title is not None:
+            params["title"] = title
+        if tokens:
+            params["tokens"] = dict(tokens)
         self._put("_metadata", params)
 
+    def set_tab_label(
+        self, label: Optional[str], *, expected: Optional[str] = None
+    ) -> None:
+        """Set the label of the herdr workspace tab we run in, or restore it.
+
+        ``label=None`` restores the label that was in place when we first
+        took ownership (and only while the tab still shows ``expected`` --
+        a label the user changed meanwhile is left alone). The tab is only
+        ever relabelled when it holds a single pane: the tab bar is a
+        user-managed surface, and a tab shared with other panes is never
+        touched. Enqueued on the decorative lane; never blocks the caller,
+        and is a no-op when ``HERDR_TAB_ID`` is unset.
+        """
+        if not self._active or not self._tab_id:
+            return
+        with self._cond:
+            if label is not None:
+                if label == self._tab_last_label:
+                    return
+                if (
+                    self._tab is not None
+                    and self._tab["op"] == "set"
+                    and self._tab["label"] == label
+                ):
+                    return  # an identical set is already queued
+            elif not self._tab_renamed and self._tab is None:
+                return  # never renamed and nothing queued: nothing to restore
+            self._tab = {
+                "op": "restore" if label is None else "set",
+                "label": label,
+                "expected": expected,
+            }
+            self._cond.notify()
+
     def _put(self, slot: str, params: Dict[str, Any]) -> None:
         if not self._active:
             return
@@ -249,6 +320,11 @@ class HerdrClient:
             if self._metadata is not None:
                 params, self._metadata = self._metadata, None
                 return _M_METADATA, params
+        # The tab job drains even while closing: the exit-time label
+        # restore is shutdown work and must land before the release.
+        if self._tab is not None:
+            job, self._tab = self._tab, None
+            return _M_TAB_RENAME, job
         if self._closing and self._release is not None:
             params, self._release = self._release, None
             return _M_RELEASE, params
@@ -266,7 +342,10 @@ class HerdrClient:
                     self._cond.wait()
                     job = self._take_next_locked()
                 method, params = job
-            self._send(method, params)
+            if method == _M_TAB_RENAME:
+                self._do_tab(params)
+            else:
+                self._send(method, params)
             if method == _M_RELEASE:
                 self._released.set()
                 return
@@ -286,6 +365,10 @@ class HerdrClient:
                 **params,
             },
         }
+        self._transmit(method, envelope)
+
+    def _transmit(self, method: str, envelope: Dict[str, Any]) -> None:
+        """Fire-and-forget send with retry-until-acked. Never raises."""
         payload = (json.dumps(envelope) + "\n").encode("utf-8")
         last_exc: Optional[Exception] = None
         for attempt in range(_SEND_ATTEMPTS):
@@ -335,5 +418,101 @@ class HerdrClient:
             pipe.write(payload)
             return bool(pipe.readline(_ACK_BYTES))
 
+    # -- tab label -----------------------------------------------------
+
+    def _do_tab(self, job: Dict[str, Any]) -> None:
+        """Apply a tab-label set or restore, with the ownership gate.
+
+        Runs on the worker. The tab is only ever relabelled by us while it
+        holds exactly one pane: herdr's tab bar is a user-managed surface,
+        and a tab shared with other panes is never touched. The original
+        label is captured on first takeover and restored on a clean exit
+        -- but only while the tab still shows the label we last set, so a
+        manual rename by the user is never clobbered.
+        """
+        info = self._request(_M_TAB_GET, {"tab_id": self._tab_id}) or {}
+        result = info.get("result") if isinstance(info.get("result"), dict) else {}
+        tab = result.get("tab") if isinstance(result.get("tab"), dict) else {}
+        if tab.get("pane_count") != 1:
+            return  # shared or vanished tab: leave its label alone
+        current = tab.get("label")
+        label = job.get("label")
+        with self._cond:
+            if label is None:  # restore
+                if not (self._tab_renamed and self._tab_original):
+                    return
+                expected = job.get("expected")
+                if expected is not None and current != expected:
+                    return  # the user changed it meanwhile; leave it
+                target = self._tab_original
+            else:
+                if not self._tab_renamed:
+                    self._tab_original = current
+                self._tab_renamed = True
+                self._tab_last_label = label
+                target = label
+        if current != target:
+            seq = self._next_seq()
+            self._transmit(
+                _M_TAB_RENAME,
+                {
+                    "id": f"{SOURCE}:{seq}",
+                    "method": _M_TAB_RENAME,
+                    "params": {"tab_id": self._tab_id, "label": target},
+                },
+            )
+        if label is None:
+            with self._cond:
+                self._tab_renamed = False
+                self._tab_original = None
+                self._tab_last_label = None
+
+    def _request(self, method: str, params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """One request/response round-trip on a fresh connection.
+
+        Used only for the tab-info read (``tab.get``). Unlike fire-and-forget
+        reports, the response carries data we need; any failure degrades to
+        ``None`` and the caller simply skips the operation.
+        """
+        seq = self._next_seq()
+        envelope = {"id": f"{SOURCE}:{seq}", "method": method, "params": params}
+        payload = (json.dumps(envelope) + "\n").encode("utf-8")
+        try:
+            raw = (
+                self._request_pipe(payload)
+                if os.name == "nt"
+                else self._request_unix(payload)
+            )
+        except (OSError, ValueError):
+            logger.debug("herdr %s failed", method, exc_info=True)
+            return None
+        if not raw:
+            return None
+        try:
+            reply = json.loads(raw.decode("utf-8", "replace"))
+        except ValueError:
+            return None
+        return reply if isinstance(reply, dict) else None
+
+    def _request_unix(self, payload: bytes) -> bytes:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+            sock.settimeout(_CONNECT_TIMEOUT_S)
+            sock.connect(self._socket_path)  # type: ignore[arg-type]
+            sock.sendall(payload)
+            line = b""
+            while not line.endswith(b"\n") and len(line) < 65536:
+                chunk = sock.recv(_ACK_BYTES)
+                if not chunk:
+                    break
+                line += chunk
+        return line
+
+    def _request_pipe(self, payload: bytes) -> bytes:
+        # Same named-pipe mapping as ``_deliver_pipe`` (see there).
+        pipe_name = "\\\\.\\pipe\\" + str(self._socket_path)
+        with open(pipe_name, "r+b", buffering=0) as pipe:
+            pipe.write(payload)
+            return pipe.readline(65536)
+
 
 __all__ = ["HerdrClient", "SOURCE", "AGENT"]

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/code_puppy_core_plugins/herdr/register_callbacks.py

@@ -31,13 +31,15 @@ Callback -> effect:
 * ``agent_run_cancel`` / ``interactive_turn_end`` .... reset -> idle
 * ``interactive_turn_cancel`` ........................ reset -> idle
 * ``awaiting_user_input`` ............................ blocked <-> not
+* ``post_autosave`` .................................. title refresh / wait
 
 Session identity is the durable autosave (name, path) resolved by
 ``sources.current_session_ref`` -- NOT the per-run ``group_id`` UUID, which
-changes every turn. Pane metadata (model / context / tokens) and the
-best-effort activity ``message`` are decorative: they never perturb the
-authoritative state and never delay a state edge, session reference, or the
-final ``pane.release_agent`` on exit.
+changes every turn. Pane metadata (model / context / tokens), the
+session namer's conversation title, and the best-effort activity
+``message`` are decorative: they never perturb the authoritative state and
+never delay a state edge, session reference, or the final
+``pane.release_agent`` on exit.
 
 Handlers are plain sync functions that swallow every argument: the callback
 dispatcher passes hook args positionally and runs sync callbacks happily
@@ -90,6 +92,11 @@ def _on_turn_end(*_args, **_kw) -> None:
     _reporter.on_turn_end()
 
 
+def _on_post_autosave(*_args, **_kw) -> None:
+    # (SessionMetadata,) -- the reporter reads the sidecar itself.
+    _reporter.on_post_autosave()
+
+
 def _on_tool_start(*args, **kwargs):
     # (tool_name, tool_args, context=None). Decorative only -> return None so
     # the tool is never blocked or transformed.
@@ -127,6 +134,7 @@ if _reporter.active:
     register_callback("agent_run_cancel", _on_run_cancel)
     register_callback("interactive_turn_end", _on_turn_end)
     register_callback("interactive_turn_cancel", _on_turn_end)
+    register_callback("post_autosave", _on_post_autosave)
     register_callback("pre_tool_call", _on_tool_start)
     register_callback("post_tool_call", _on_tool_complete)
     register_callback("awaiting_user_input", _on_awaiting_user_input)

{code_puppy_core_plugins-0.0.45 → code_puppy_core_plugins-0.0.47}/code_puppy_core_plugins/herdr/reporter.py

@@ -26,12 +26,19 @@ Effective state::
 Sub-agents fire the same ``agent_run_start`` / ``agent_run_end`` hooks as the
 root agent, so we refcount active runs (the same pattern the puppy_spinner
 plugin uses) rather than flipping idle when a sub-agent finishes.
+
+Beyond state, the reporter propagates the session namer's auto-generated
+conversation title to the pane (presentation title: herdr's pane border and
+the sidebar ``pane`` token). The namer names the session asynchronously
+after each autosave, so a bounded background wait re-reads the sidecar and
+reports the title the moment it lands, without waiting for the next turn.
 """
 
 from __future__ import annotations
 
 import logging
 import threading
+import time
 from typing import Optional, Tuple
 
 from .client import HerdrClient
@@ -48,6 +55,11 @@ IDLE = "idle"
 THINKING = "thinking"
 AWAITING = "awaiting input"
 
+# The namer's model call has its own 60s timeout; the wait for a fresh
+# title must cover that plus queueing slack, then give up.
+_TITLE_WAIT_INTERVAL_S = 2.0
+_TITLE_WAIT_TIMEOUT_S = 90.0
+
 
 class HerdrReporter:
     """Thread-safe, dedup-ing bridge from callbacks to :class:`HerdrClient`."""
@@ -66,6 +78,13 @@ class HerdrReporter:
         # Durable session reference (name, pickle_path) — NOT the per-run group_id UUID,
         # which changes every turn and can't identify a resumable session.
         self._session_ref: Optional[Tuple[str, str]] = None
+        # The title we believe herdr currently shows for our source (herdr
+        # replaces the whole per-source metadata entry per report, so this
+        # must always match the last envelope we sent).
+        self._reported_title: Optional[str] = None
+        # Single-flight background wait for the namer's async title write.
+        self._title_wait: Optional[threading.Thread] = None
+        self._title_wait_session: Optional[str] = None
 
     @property
     def active(self) -> bool:
@@ -139,6 +158,26 @@ class HerdrReporter:
     def on_user_prompt(self, *_ignored) -> None:
         # Ignore the callback's per-run group_id; resolve the durable session.
         self._refresh_session()
+        # The title belongs to the session: a resumed or fresh session shows
+        # its own title (or none) without waiting for the next turn.
+        self._refresh_title()
+
+    def on_post_autosave(self, *_ignored) -> None:
+        """A session was just saved: report a fresh title, or wait for one.
+
+        The namer names the conversation asynchronously after this event, so
+        a title typically lands seconds later. When the session is still
+        unnamed and the namer is enabled, a bounded background wait reports
+        the title as soon as it appears. No-op outside herdr.
+        """
+        if not self._client.active:
+            return
+        if sources.current_session_title() is not None:
+            self._refresh_title()
+            return
+        if not sources.naming_enabled():
+            return
+        self._start_title_wait()
 
     def on_run_start(self, *_ignored) -> None:
         with self._lock:
@@ -190,10 +229,88 @@ class HerdrReporter:
         self._emit_metadata()
 
     def _emit_metadata(self) -> None:
-        """Compute and enqueue pane metadata. Never holds the reporter lock."""
-        payload = sources.current_tokens_payload()
-        if payload:
-            self._client.report_metadata(payload)
+        """Compute and enqueue pane metadata. Never holds the reporter lock.
+
+        The tokens payload and the session title ride one envelope: herdr
+        replaces the whole per-source metadata entry on each report, so a
+        tokens report that omits the title would silently wipe it.
+        """
+        tokens = sources.current_tokens_payload()
+        title = sources.current_session_title()
+        changed, previous = self._claim_title(title)
+        if tokens is None and not changed:
+            return
+        # Clear only on a set->None transition; when a tokens report is
+        # present, its entry replacement clears any stale title for us.
+        self._client.report_metadata(
+            tokens, title=title, clear_title=changed and title is None
+        )
+        if changed:
+            self._client.set_tab_label(title, expected=previous)
+
+    # -- session title propagation --------------------------------------
+
+    def _claim_title(self, title: Optional[str]) -> Tuple[bool, Optional[str]]:
+        """Record ``title`` as the herdr-side value.
+
+        Returns ``(changed, previous)`` -- ``previous`` is the value herdr
+        showed before this claim, so a clear can tell the tab-label restore
+        what label it should find there. Both title paths (turn-end
+        metadata and title-only refresh) go through here, so
+        ``_reported_title`` is the single source of truth for what herdr
+        currently shows for our source.
+        """
+        with self._lock:
+            previous = self._reported_title
+            if title == previous:
+                return False, previous
+            self._reported_title = title
+            return True, previous
+
+    def _refresh_title(self) -> bool:
+        """Report the current session's title (or its absence). Title-only.
+
+        Returns True when a report was enqueued. Safe to call whenever:
+        deduped by :meth:`_claim_title`.
+        """
+        title = sources.current_session_title()
+        changed, previous = self._claim_title(title)
+        if not changed:
+            return False
+        self._client.report_metadata(None, title=title, clear_title=(title is None))
+        self._client.set_tab_label(title, expected=previous)
+        return True
+
+    def _start_title_wait(self) -> None:
+        """Arm a bounded, session-pinned background wait for a fresh title.
+
+        Single-flight: at most one wait at a time. The wait stops on title
+        arrival, session change, shutdown (daemon thread), or timeout.
+        """
+        session = sources.current_session_name()
+        with self._lock:
+            wait = self._title_wait
+            if wait is not None and wait.is_alive():
+                return
+            wait = threading.Thread(
+                target=self._title_wait_loop, name="herdr-title-wait", daemon=True
+            )
+            self._title_wait = wait
+            self._title_wait_session = session
+        wait.start()
+
+    def _title_wait_loop(self) -> None:
+        """Re-check the sidecar until the title lands, the session changes,
+        or the timeout elapses. Runs on its own daemon thread; every step
+        is fail-soft."""
+        deadline = time.monotonic() + _TITLE_WAIT_TIMEOUT_S
+        pinned = self._title_wait_session
+        while time.monotonic() < deadline:
+            time.sleep(_TITLE_WAIT_INTERVAL_S)
+            if sources.current_session_name() != pinned:
+                return  # the new prompt's refresh owns the new session's title
+            if self._refresh_title():
+                return  # title landed (or its absence was reported)
 
     def on_awaiting_user_input(self, awaiting: bool, *, notify: bool = True) -> None:
         """Track an interactive wait, notifying only when requested."""
@@ -203,6 +320,14 @@ class HerdrReporter:
         self._sync()
 
     def on_shutdown(self) -> None:
+        # If we relabelled the workspace tab, restore its original label
+        # first: the client drains the tab job ahead of the release on its
+        # worker. A title currently displayed means the tab may be ours;
+        # no title ever shown means no tab job is needed at all.
+        with self._lock:
+            expected = self._reported_title
+        if expected is not None:
+            self._client.set_tab_label(None, expected=expected)
         # Release pane authority directly (no intermediate idle report).
         # release_and_close() is idempotent and bounded, so calling it from both
         # session_end and shutdown can never delay process exit.