fix(tui+lsp): resolve CI failures and CodeRabbit findings; harden RunAgents

Make the PR branch green and address the review.

CI failures (15 tests + ruff):
- Update agent-spec / config-dump / pyinstaller snapshots for the new LSP tool
- Add explicit encoding to LSP framing/symbol_context/tool sources (static check)
- Sync dark prompt frame/separator/dialog borders to their core theme tokens
- Flush the live view immediately for external (approval/steer) messages and
  supervise the frame/status refresh loops so a refresh failure surfaces instead
  of silently freezing the view (fixes 3 external-approval tests)
- Wire `_mode` + completer onto the bottom-toolbar unit test's bare session
- Fix import sorting / line length

CodeRabbit findings:
- Critical: inline code spans now actually clear an inherited background
  (Rich `Style(bgcolor=None)` is a no-op; mutate the copied style instead)
- LSP: bounded JSON-RPC frame size + graceful-shutdown timeout, didChange
  document version tracking, open-doc state cleared on restart, empty
  diagnostics payloads clear stale entries, code-0 dedup key, TOCTOU re-check,
  documentSymbol file_count
- Theme picker: compare resolved themes by identity so distinct Catppuccin
  variants no longer match
- Usage activity: anchor the chart to the payload window (not wall-clock) and
  fix the current-streak partial-today contract
- Config: validate LSP numeric settings; `/usage` rejects extra activity args;
  `/theme code <Name>` preserves case; guard install-script cursor escapes to
  animated mode; drop unused worklog icon params

RunAgents: strip stray whitespace-only string entries the model emits between
agent objects so a multi-agent launch no longer fails validation.

Also: AGENTS.md gains a "Pre-PR gate" checklist (run the full gate, snapshot
fix-direction, encoding/bundling/changelog checks) to stop these slipping to CI.

Author: elkaix

AGENTS.md

@@ -224,6 +224,41 @@ Pick the smallest reliable gate for the change, then run broader gates before re
 If a gate cannot run because of missing system tools (for example `npm`), report that explicitly
 instead of claiming success.
 
+## Pre-PR gate (run before pushing or opening a PR)
+
+CI failures that "slip to GitHub" almost always trace to pushing after a *partial* local check
+(for example running `ruff`/`pyright` on a single file instead of the whole package). Before you
+push a branch or open a PR that touches shipped code, run the full gate and clear every item below.
+Running a focused check on only the files you edited is **not** sufficient — snapshot, static, and
+bundling tests fail on files you did not touch.
+
+1. **Full gate, not partial.** Run `make check-pythinker-code` (ruff + format + pyright) **and**
+   `make test-pythinker-code`. Paste/confirm the actual "All checks passed" / passing summary — a
+   green `ruff` alone is not a green `check` (pyright and format are separate). For changes to
+   another workspace package, run that package's `make check-* && make test-*` too.
+2. **Include `tests_e2e`.** CI runs `tests` and `tests_e2e`. New slash commands, wire events, or
+   agent-spec/tool changes move the wire-handshake snapshot and the agent-spec/config/pyinstaller
+   snapshots. Re-run the affected tests; apply deliberate snapshot updates with
+   `uv run pytest <node> --inline-snapshot=fix` and **read the resulting diff** before committing.
+3. **Snapshot fix-direction.** A hardcoded expected value that changed deliberately → update the
+   **test**. An invariant of the form "two values must stay equal" (e.g. a prompt token that must
+   track a core theme token) → fix the **code** that drifted, never the test.
+4. **New source files clear the static checks.** `tests/test_ai_static_requirements.py` enforces
+   explicit text encoding (`encoding="utf-8"`, `errors="replace"` for tool decodes) and other
+   invariants across `src/pythinker_code/**`. Note the ruff-vs-static conflict: ruff `UP012` strips
+   `"utf-8"` from a **string-literal** `.encode("utf-8")`, but the static check wants an explicit
+   `encoding=`. Encode/decode via a **local variable or call result**, not a literal, so both gates
+   pass (see `lsp/framing.py`).
+5. **New bundled files/tools update the manifests.** A new tool `*.md`, prompt, or package adds
+   entries to `tests/utils/test_pyinstaller_utils.py` (`datas` + `hiddenimports`) and, for new
+   config keys, `tests/core/test_config.py::test_default_config_dump`.
+6. **Changelog.** Any change to shipped paths (`src/*`, `packages/*`, installers, release
+   workflows, `pythinker.spec`) needs a new `- ...` line under `## Unreleased` in `CHANGELOG.md`, or
+   the `changelog-entry-required` check fails the PR.
+7. **Confirm what is actually new.** Diff against `origin/main` (`git log origin/main..HEAD`,
+   `git diff origin/main...HEAD --stat`) so the PR scope — and the review/verification surface — is
+   what you intend, not stale local commits.
+
 ## Project architecture
 
 ### Runtime path

CHANGELOG.md

@@ -15,6 +15,13 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **TUI composing preview gap.** Removed the visible double-blank row between
+  `Composing…` and the in-progress preview (leading newline from commit
+  boundaries no longer leaks through the plain-text preview path), and aligned
+  the Rich `Live` paint rate with the 25 Hz reveal scheduler (was 10 Hz).
+- **ToolSearch TUI display.** `ToolSearch` results now render as a compact
+  "N tools discovered (Agent, Grep, …)" summary instead of dumping the full
+  tool catalog with descriptions; ctrl+o expands to tool names only.
 - **Tool header highlights.** Read/Write/Edit/Grep and similar tool-call subjects
   now use the brand periwinkle `accent` token instead of cyan `info`; line ranges
   stay on the yellow `warning` token.
@@ -48,6 +55,23 @@ GitHub Releases page; `0.8.0` is the new starting line.
   total tokens consumed each day, with a `Lifetime · Peak · Streak · Longest task` summary
   line and a footer that lets the user switch between daily/weekly/cumulative views. Data is
   read from the local session wire files; the per-provider adapter behavior is unchanged.
+- **RunAgents tolerates blank list entries.** Models occasionally emit bare `"\n"` strings
+  between the agent objects in the `agents` array; those are now stripped before validation so
+  a multi-agent launch no longer fails with a validation error, while genuinely invalid entries
+  are still rejected.
+- **Report panel rendering.** Standardized report panels render only the panel title and section
+  headers bold (body prose stays regular weight), tag finding locations with a file marker, and
+  use a dedicated `secondary` theme token for scope/note text.
+- **Theme token consistency.** The dark prompt frame/separator/dialog borders and the prompt
+  glyph now track their canonical core theme tokens, and inline code spans correctly drop an
+  inherited background.
+- **External approvals repaint promptly.** Out-of-band approval requests and steer input now
+  force an immediate live-view repaint instead of waiting for the streaming frame budget, and
+  the live-view refresh loop is supervised so a refresh-loop failure surfaces instead of
+  silently freezing the view.
+- **LSP robustness.** Bounded JSON-RPC frame size and graceful-shutdown timeout, document
+  version tracking for `didChange`, open-document state cleared on server restart, empty
+  diagnostics payloads clear stale entries, and tightened `/usage` activity-argument validation.
 
 ## 0.47.0 (2026-06-16)
 

docs/public/install.sh

@@ -641,13 +641,17 @@ until release_has_assets; do
     fail "release assets for v${VERSION} are not available after ~${max_elapsed}s: ${tarball_url}
 The latest release may still be publishing. Try again shortly, or pin a known-good version with --version X.Y.Z"
   fi
-  printf '\033[%d;1H\033[K  %s%-11s%s release assets, retrying in %s%ss%s' "$PROGRESS_ROW" "$DIM" "Waiting" "$RESET" "$BAR" "$delay" "$RESET"
+  if [ -n "$_anim" ]; then
+    printf '\033[%d;1H\033[K  %s%-11s%s release assets, retrying in %s%ss%s' "$PROGRESS_ROW" "$DIM" "Waiting" "$RESET" "$BAR" "$delay" "$RESET"
+  else
+    printf '  Waiting for release assets, retrying in %ss\n' "$delay"
+  fi
   sleep "$delay"
   elapsed=$((elapsed + delay))
   delay=$((delay * 2))
   [ "$delay" -gt 120 ] && delay=120
 done
-[ "$attempt" -gt 0 ] && printf '\033[%d;1H\033[K' "$PROGRESS_ROW"
+[ -n "$_anim" ] && [ "$attempt" -gt 0 ] && printf '\033[%d;1H\033[K' "$PROGRESS_ROW"
 
 # --- download + verify --------------------------------------------------
 tmpdir="$(mktemp -d -t pythinker-install.XXXXXX)"

scripts/install-native.sh

@@ -641,13 +641,17 @@ until release_has_assets; do
     fail "release assets for v${VERSION} are not available after ~${max_elapsed}s: ${tarball_url}
 The latest release may still be publishing. Try again shortly, or pin a known-good version with --version X.Y.Z"
   fi
-  printf '\033[%d;1H\033[K  %s%-11s%s release assets, retrying in %s%ss%s' "$PROGRESS_ROW" "$DIM" "Waiting" "$RESET" "$BAR" "$delay" "$RESET"
+  if [ -n "$_anim" ]; then
+    printf '\033[%d;1H\033[K  %s%-11s%s release assets, retrying in %s%ss%s' "$PROGRESS_ROW" "$DIM" "Waiting" "$RESET" "$BAR" "$delay" "$RESET"
+  else
+    printf '  Waiting for release assets, retrying in %ss\n' "$delay"
+  fi
   sleep "$delay"
   elapsed=$((elapsed + delay))
   delay=$((delay * 2))
   [ "$delay" -gt 120 ] && delay=120
 done
-[ "$attempt" -gt 0 ] && printf '\033[%d;1H\033[K' "$PROGRESS_ROW"
+[ -n "$_anim" ] && [ "$attempt" -gt 0 ] && printf '\033[%d;1H\033[K' "$PROGRESS_ROW"
 
 # --- download + verify --------------------------------------------------
 tmpdir="$(mktemp -d -t pythinker-install.XXXXXX)"

src/pythinker_code/config.py

@@ -1036,15 +1036,15 @@ class LspServerConfig(BaseModel):
     initialization_options: dict[str, Any] | None = Field(
         default=None, alias="initializationOptions"
     )
-    startup_timeout: float = Field(default=30.0, alias="startupTimeout")
-    max_restarts: int = Field(default=3, alias="maxRestarts")
+    startup_timeout: float = Field(default=30.0, alias="startupTimeout", gt=0)
+    max_restarts: int = Field(default=3, alias="maxRestarts", ge=0)
 
 
 class LspConfig(BaseModel):
     enabled: bool = True
     recommendation_disabled: bool = False
     recommendation_never: list[str] = Field(default_factory=list)
-    recommendation_ignored_count: int = 0
+    recommendation_ignored_count: int = Field(default=0, ge=0)
 
 
 class PluginsConfig(BaseModel):

src/pythinker_code/lsp/client.py

@@ -24,6 +24,8 @@
 NotificationHandler = Callable[[Any], None] | Callable[[Any], Awaitable[None]]
 RequestHandler = Callable[[Any], Any] | Callable[[Any], Awaitable[Any]]
 
+_SHUTDOWN_TIMEOUT_S = 2.0
+
 
 class LspClient:
     """Minimal LSP client: spawn via Host.exec, JSON-RPC over Content-Length framing."""
@@ -137,8 +139,12 @@ async def stop(self) -> None:
 
         proc = self._proc
         if proc is not None and proc.returncode is None:
+            # Bound the graceful handshake: a hung server must not block teardown.
+            # On timeout (or any error) we fall through to killing the process below.
             with suppress(Exception):
-                await self.send_request("shutdown", None)
+                await asyncio.wait_for(
+                    self.send_request("shutdown", None), timeout=_SHUTDOWN_TIMEOUT_S
+                )
             with suppress(Exception):
                 await self.send_notification("exit", None)
 

src/pythinker_code/lsp/diagnostics.py

@@ -86,7 +86,7 @@ def diagnostic_key(entry: DiagnosticEntry) -> str:
                 },
             },
             "source": entry.source or None,
-            "code": entry.code or None,
+            "code": entry.code if entry.code is not None else None,
         },
         sort_keys=True,
         separators=(",", ":"),
@@ -281,10 +281,17 @@ async def handler(params: Any) -> None:
             parsed = PublishDiagnosticsParams.model_validate(params)
             path = uri_to_path(parsed.uri) or parsed.uri
             entries = [diagnostic_entry_from_lsp(item) for item in parsed.diagnostics]
-            registry.register_pending(
-                server_name,
-                [DiagnosticFile(uri=parsed.uri, path=path, diagnostics=entries)],
-            )
+            if not entries:
+                # An empty payload means "no problems now" for this file, so drop
+                # any previously stored diagnostics for it. clear_for_file clears
+                # across all servers and the sent-key LRU; that is safe here
+                # because routing is one server per extension.
+                registry.clear_for_file(parsed.uri)
+            else:
+                registry.register_pending(
+                    server_name,
+                    [DiagnosticFile(uri=parsed.uri, path=path, diagnostics=entries)],
+                )
             failure_count = 0
         except Exception as exc:
             failure_count += 1

src/pythinker_code/lsp/framing.py

@@ -73,7 +73,9 @@ async def read_message(stdout: AsyncReadable) -> dict[str, Any]:
 
 async def write_message(stdin: AsyncWritable, message: dict[str, Any]) -> None:
     """Write one LSP message with Content-Length framing."""
-    body = json.dumps(message, separators=(",", ":")).encode()
-    header = f"Content-Length: {len(body)}\r\n\r\n".encode()
-    stdin.write(header + body)
+    body = json.dumps(message, separators=(",", ":")).encode(encoding="utf-8")
+    # Encode via a local (not a string literal) so the explicit encoding survives
+    # ruff UP012 while satisfying the explicit-encoding static check.
+    header = f"Content-Length: {len(body)}\r\n\r\n"
+    stdin.write(header.encode(encoding="utf-8") + body)
     await stdin.drain()

src/pythinker_code/lsp/manager.py

@@ -31,6 +31,7 @@ def __init__(
         self._instances: dict[str, LspServerInstance] = {}
         self._ext_map: dict[str, list[str]] = {}
         self._opened_files: dict[str, str] = {}
+        self._doc_versions: dict[str, int] = {}
 
     async def initialize(self) -> None:
         errors: list[str] = []
@@ -82,6 +83,7 @@ async def shutdown(self) -> None:
         self._instances.clear()
         self._ext_map.clear()
         self._opened_files.clear()
+        self._doc_versions.clear()
 
         stop_errors = [
             f"{to_stop[i][0]}: {result}"
@@ -105,9 +107,19 @@ async def ensure_started(self, path: str) -> LspServerInstance | None:
         if server is None:
             return None
         if server.state in (LspState.STOPPED, LspState.ERROR):
+            # A (re)start spawns a fresh process with no open documents. Drop any
+            # stale per-server open-file and version state so didOpen is re-sent
+            # instead of being skipped as already-open on the new process.
             await server.start()
+            self._clear_server_doc_state(server.name)
         return server
 
+    def _clear_server_doc_state(self, server_name: str) -> None:
+        stale_uris = [uri for uri, name in self._opened_files.items() if name == server_name]
+        for uri in stale_uris:
+            self._opened_files.pop(uri, None)
+            self._doc_versions.pop(uri, None)
+
     async def send_request(self, path: str, method: str, params: Any) -> Any | None:
         server = await self.ensure_started(path)
         if server is None:
@@ -143,6 +155,7 @@ async def open_file(self, path: str, content: str) -> None:
             },
         )
         self._opened_files[file_uri] = server.name
+        self._doc_versions[file_uri] = 1
 
     async def change_file(self, path: str, content: str) -> None:
         server = self.server_for_file(path)
@@ -155,10 +168,12 @@ async def change_file(self, path: str, content: str) -> None:
             await self.open_file(path, content)
             return
 
+        version = self._doc_versions.get(file_uri, 1) + 1
+        self._doc_versions[file_uri] = version
         await server.send_notification(
             "textDocument/didChange",
             {
-                "textDocument": {"uri": file_uri, "version": 1},
+                "textDocument": {"uri": file_uri, "version": version},
                 "contentChanges": [{"text": content}],
             },
         )
@@ -183,6 +198,7 @@ async def close_file(self, path: str) -> None:
             {"textDocument": {"uri": file_uri}},
         )
         self._opened_files.pop(file_uri, None)
+        self._doc_versions.pop(file_uri, None)
 
 
 def _file_uri(path: str) -> str:

src/pythinker_code/lsp/service.py

@@ -97,6 +97,14 @@ async def save_file(self, path: str) -> None:
         await manager.save_file(path)
 
     async def reinitialize(self, *, servers: dict[str, LspServerConfig] | None = None) -> None:
+        # Cancel any in-flight init before replacing the event/manager. Otherwise
+        # the stale task's finally can set the old event (waking callers parked in
+        # wait_for_init on a future that never completes) and _kickoff_init would
+        # return early while PENDING.
+        if self._init_task is not None and not self._init_task.done():
+            self._init_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._init_task
         if servers is not None:
             self._servers = servers
         if self._manager is not None: