feat(tui+lsp): streaming polish, tool card renderers, and LSP implementation guard

.gitignore

@@ -66,6 +66,7 @@ static/
 !.claude/hooks/**
 .pythinker/
 .worktrees/
+reference-scan/
 blackbox/
 
 # pythinker-review
@@ -81,4 +82,7 @@ htmlcov/
 *.scratchpad.lock
 
 .playwright-mcp/
-.playwright/
+.playwright/
+
+# Cursor debug-mode session logs (machine-local NDJSON)
+.cursor/debug-*.log

AGENTS.md

@@ -355,6 +355,11 @@ see `docs/en/customization/architecture.md`. This list is a quick orientation on
 - Side-effecting tools must respect approval/runtime policy. Read-only helpers should be clearly
   documented as read-only.
 - Tool results should be concise, structured, and safe to replay into model context.
+- **Prefer `LSP` when available.** The `LSP` tool (default agent + `coder` subagent) uses
+  plugin-backed language servers for semantic code intelligence. When `config.lsp.enabled` is true
+  and a server covers the file type, use it for go-to-definition, references, hover, symbols, and
+  call hierarchy instead of brute-force `Grep`/`ReadFile` scanning. Fall back to text search when LSP
+  is unavailable, still initializing, or returns no results. See `docs/en/customization/lsp.md`.
 
 ### Context, compaction, and session longevity
 
@@ -428,7 +433,9 @@ Pythinker agents should behave like coordinated specialists, not one long-runnin
 everything sequentially.
 
 - **Preview before deep work**: for non-trivial tasks, scan the tree, file headers, relevant docs,
-  and nearby tests before choosing an implementation path.
+  and nearby tests before choosing an implementation path. When the `LSP` tool is available, prefer
+  it for symbol navigation (definitions, references, call hierarchy, hover) over manual grep/read
+  sweeps; fall back to `Grep`/`ReadFile` when no language server covers the file type.
 - **Keep work visible**: use todo/plan tooling for multi-step root-agent work and update it as
   evidence changes the plan.
 - **Parallelize independent work**: batch unrelated reads/searches/checks in one turn. If an
@@ -452,8 +459,8 @@ everything sequentially.
   default. Include goal, scope, paths, constraints, success criteria, and expected output.
 - **Use map-reduce workflows**: scout -> plan -> implement -> review -> fix -> verify -> judge.
 - **Verify evidence**: after reads, confirm exact paths/line ranges; after grep, confirm relevance;
-  after shell, inspect stdout/stderr; after subagent reports, cross-check at least one load-bearing
-  finding directly.
+  after LSP, spot-check one cited definition/reference in source; after shell, inspect
+  stdout/stderr; after subagent reports, cross-check at least one load-bearing finding directly.
 - **Subagent final reports** should include `SUMMARY`, `EVIDENCE`, `CHANGES`, `RISKS`, and
   `BLOCKERS`. `EVIDENCE` should cite concrete file paths, line ranges, commands, or search hits.
 
@@ -513,7 +520,7 @@ everything sequentially.
 - Line length is 100.
 - Ruff handles lint and format (`E`, `F`, `UP`, `B`, `SIM`, `I`).
 - Pyright runs in standard mode with strict coverage for `src/pythinker_code/**/*.py`.
-- `ty` is run but currently non-blocking in Makefile targets.
+- `ty` is run and **blocking** in `check-pythinker-code`; other package targets still use `|| true` due to third-party type stubs. Keep `pythinker-code` ty-clean.
 - Tests use `pytest` and `pytest-asyncio`; unit tests are `tests/test_*.py`.
 - Prefer explicit async boundaries; avoid blocking calls in async runtime paths.
 - Keep exceptions actionable. User-facing CLI errors should explain what to do next.

CHANGELOG.md

@@ -15,10 +15,46 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Cleaner terminal report rendering.** Structured ` ```report ` outputs now suppress duplicated trailing summaries, keep only artifact footers after the report, compact long finding locations, and switch large reports to a borderless dashboard layout for faster terminal scanning.
+- **Unknown subagent-type recovery hints.** Invalid types still fail loudly, but
+  `Agent`/`RunAgents` errors now include best-effort suggestions for common
+  cross-harness aliases (e.g. `general-purpose` → `coder`) and close typos when the
+  suggested subagent exists in the current session. No silent substitution; the full
+  valid-type list is unchanged.
+- **TUI: smoother agent-working streaming.** Buffered text now reveals at an even,
+  bounded rate instead of backlog-proportional lurches, and completed prose is no
+  longer committed to scrollback mid-stream — it stays in the in-place live preview
+  and is flushed once at a tool transition or turn end, so the prompt no longer
+  pops/flickers on every paragraph boundary during a stream. The prompt stays in a
+  **Finalizing** state (not a false idle `❯`) while scrollback is pending, and clipped
+  live output shows an **earlier output hidden · Ctrl+O expand** marker instead of
+  silently dropping rows.
+
+- **TUI tool-card diffs use syntax highlighting.** Edit/Write inline diffs now share the
+  approval/pager ``PythinkerSyntax`` pipeline (``tui.code_theme``, file-extension lexer) while
+  keeping the compact boxless card layout.
+- **TUI tool-card diff wrap alignment.** Compact edit/write diffs now render in a three-column
+  grid (line number, ``+``/``-`` marker, code body) so wrapped continuation rows stay aligned
+  under the code column and repeat the diff sign instead of orphaning at column 0.
+
+- **TUI: fix fossilized pinned spinner in interactive mode.** All scrollback emissions in `_PromptLiveView` (content blocks, tool cards, notifications, steer echoes, turn recaps) now route through `run_in_terminal` instead of calling `console.print` directly, preventing prompt_toolkit's ephemeral preamble from being captured into permanent scrollback. `ty` type checker is now blocking for the `pythinker-code` package.
+
+- **TUI report prose blocks:** Agent summaries with a parent bullet plus aligned field rows (`Issue` / `Anchor`, `Finding` / `Severity`, etc.) now render as structured blocks with preserved hierarchy, per-block label columns, and correct continuation wrap indent instead of flattening into sibling markdown bullets.
+- **LSP `go_to_implementation` now returns a structured error when the server does not advertise `implementationProvider`** instead of surfacing a raw exception. The client also advertises `implementation` capability during the LSP handshake so servers like Pyright enable the provider automatically.
+- **TUI Rich Live streaming matches interactive smoothness.** Non-interactive
+  shell mode now emits stable markdown to scrollback during streams, drains paced
+  text before tool/think transitions, batches wire delivery, and uses diff-based
+  live refresh on terminals to reduce flicker.
+
 - **TUI composing preview wraps space-aligned report prose cleanly.** The
   streaming preview now runs the same lightweight space-column normalizer used at
   finalize and wraps long `Severity`/`Location`/`What` rows with a hanging
   continuation indent, so wrapped fragments no longer orphan at column 0.
+- **TUI streaming finalize continuity and interrupt safety.** Content blocks
+  promote to scrollback once with a paint-before-print step in Rich Live mode;
+  interrupted open ` ```report ` fences show a short note instead of raw JSON in
+  scrollback; paced transitions use bounded reveal instead of dumping large
+  backlogs before tool cards.
 - **ToolSearch hidden from models that can't use it.** `ToolSearch` is now offered
   only when the active model genuinely supports the deferred tool-search workflow
   (Anthropic's `tool_reference`/`defer_loading` beta on `api.anthropic.com`). The
@@ -28,10 +64,10 @@ GitHub Releases page; `0.8.0` is the new starting line.
   with `ENABLE_TOOL_SEARCH=true|false`. The tool's description no longer claims that
   hidden/deferred tools exist (pythinker loads no tools lazily), removing the prompt
   that primed the loop in the first place.
-- **Output-token-limit nudge text aligned with reference.** The system-reminder injected when a response is cut off by the output token limit now matches the reference byte-exactly: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces."
+- **Output-token-limit nudge text.** The system-reminder injected when a response is cut off by the output token limit now reads: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces."
 - **`SetTodoList` accepts Cursor-style todo payloads.** Todo items sent with `content` instead of `title` (the shape models learn from Cursor/Claude `TodoWrite`) are normalized at the validation boundary (`content` → `title` when `title` is absent; canonical `title` wins; `content` is dropped) and persist as title-only session state instead of failing with missing-`title` errors.
 - **Failed `SetTodoList` cards stay compact.** Validation failures no longer render a broken todo tree with blank labels plus a raw Pydantic dump; the card shows a short actionable summary (with full detail only when expanded).
-- **ToolSearch scrollback suppression.** Consecutive `ToolSearch` probes during deferred tool discovery are now collapsed: only the last probe in each run is shown in the transcript, mirroring the blackbox `isAbsorbedSilently` contract. Intermediate discovery calls no longer produce repeated "Tools(…)" lines.
+- **ToolSearch scrollback suppression.** Consecutive `ToolSearch` probes during deferred tool discovery are now collapsed: only the last probe in each run is shown in the transcript (`isAbsorbedSilently` contract). Intermediate discovery calls no longer produce repeated "Tools(…)" lines.
 - **Bare skill/flow slash names.** The slash menu now matches `skill:`/`flow:`
   commands on their bare segment, so typing `/designer` (or `/design`) surfaces
   `/skill:designer-skill`; accepting inserts the canonical command name. When no
@@ -48,7 +84,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
 - **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.
-- **pythinker-x theme port.** Diff palette, 32 bundled syntax theme names, Catppuccin
+- **Bundled TUI theme pack.** Diff palette, 32 bundled syntax theme names, Catppuccin
   Frappe/Macchiato styles, and `/theme code` syntax picker aligned with the Pythinker-X TUI.
 - **TUI inline code color.** Inline `` `code` `` highlights and the `pythinker-ansi`
   syntax theme now use brand periwinkle/accent and blue ANSI roles instead of cyan.
@@ -182,7 +218,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
   `budget_exhausted` stop.
 - **The Agent tool description now gives clearer prompt-briefing guidance.** Fresh subagents should
   receive the goal, scope, expected output contract, and verification criteria; the Haiku-style
-  tool-use summary from the blackbox reference was deliberately not ported.
+  tool-use summary from the upstream reference was deliberately not ported.
 
 Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.47.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
 
@@ -713,11 +749,11 @@ Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.12.0`,
 ### What changed in this release
 
 - **Fixed PyPI install conflict (was failing on Windows and every other platform).** `pip install pythinker-code==0.10.0` failed with `fastmcp 3.2.0 depends on mcp<2.0 and >=1.24.0` vs `pythinker-core 1.1.0 depends on mcp<1.17 and >=1`. 0.11.0 pins the republished `pythinker-core 1.1.1`, whose widened `mcp>=1.23,<2` constraint lets the resolver pick a single `mcp` version compatible with `fastmcp==3.2.0`.
-- **Blackbox-style TUI port — phase 1.** Shell design primitives, compact transcript activity rows, blackbox-style motion status, standardized shell dialogs, aligned footer status styling, and a restyled tool-result surface land together. The TUI now shares a coherent visual language across rows, dialogs, and motion.
+- **Reference TUI port — phase 1.** Shell design primitives, compact transcript activity rows, reference motion status, standardized shell dialogs, aligned footer status styling, and a restyled tool-result surface land together. The TUI now shares a coherent visual language across rows, dialogs, and motion.
 - **Refreshed TUI accent palette.** Dark/light theme accent retuned to a cleaner sky-blue (`#7dd3fc` dark, `#0284c7` light) for better contrast against the new tool-result surfaces.
 - **Markdown + report polish.** Report spacing and markdown code blocks render with improved breathing room and consistent fences.
 - **Rotating thinking-word indicator restored** with a leading space before the live stream status so the spinner no longer abuts surrounding text.
-- **Internal audit + smoke evaluation.** A blackbox TUI scope map, prompt/agent audit, and a recorded visual smoke evaluation join the repo to govern future TUI work.
+- **Internal audit + smoke evaluation.** A TUI scope map, prompt/agent audit, and a recorded visual smoke evaluation join the repo to govern future TUI work.
 
 Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==0.11.0`.
 
@@ -731,7 +767,7 @@ Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==0.11.0
 - **Shell command enhancements.** New shell slash-command plumbing improves discoverability and keeps interactive workflows smoother.
 - **TUI renderer polish.** Tool cards now share more consistent status glyphs, truncation behavior, and result summaries across bash, read, write, edit, grep, find, web, subagent, background, ask-user, and think renderers.
 - **Clipboard handling hardening.** Clipboard helpers now degrade more cleanly when platform clipboard access is unavailable.
-- **Release and TUI specs.** The repository now includes the blackbox TUI port design and a visual smoke-test criterion for future terminal UI work.
+- **Release and TUI specs.** The repository now includes the reference TUI port design and a visual smoke-test criterion for future terminal UI work.
 
 Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==0.10.0`.
 

Makefile

@@ -69,11 +69,11 @@ format-web: ## Auto-format web sources with npm run format.
 .PHONY: check check-pythinker-code check-pythinker-core check-pythinker-host check-pythinker-review check-pythinker-sdk check-web
 check: check-pythinker-code check-pythinker-core check-pythinker-host check-pythinker-review check-pythinker-sdk check-web ## Run linting and type checks for all packages.
 check-pythinker-code: ## Run linting and type checks for Pythinker Code.
-	@echo "==> Checking Pythinker Code (ruff + pyright + ty; ty is non-blocking)"
+	@echo "==> Checking Pythinker Code (ruff + pyright + ty)"
 	@uv run ruff check
 	@uv run ruff format --check
 	@uv run pyright
-	@uv run ty check || true
+	@uv run ty check
 check-pythinker-core: ## Run linting and type checks for Pythinker core.
 	@echo "==> Checking Pythinker core (ruff + pyright + ty; ty is non-blocking)"
 	@uv run --directory packages/pythinker-core ruff check

docs/en/customization/architecture.md

@@ -12,8 +12,8 @@ here for detail. Paths are relative to the repository root unless noted.
 
 The CLI is a uv workspace: the application lives under `src/pythinker_code/`, and reusable
 layers are split into `packages/pythinker-core`, `packages/pythinker-host`,
-`packages/pythinker-review`, and `sdks/pythinker-sdk`. The vendored reference repositories
-under `blackbox/` are out of scope and are not part of this map.
+`packages/pythinker-review`, and `sdks/pythinker-sdk`. Local gitignored reference clones are
+out of scope and are not part of this map.
 
 ## How AGENTS.md guidance loads