From 1ca428f881adc4353704ca7be4ac5af4e5828c6b Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 28 Jul 2026 10:09:57 +0800
Subject: [PATCH 01/17] chore(dev): bump to 0.11.3-dev

Post-release development-phase marker after shipping 0.11.2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/desktop/package.json | 2 +-
 package-lock.json         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index e5e8f328..6f6f0220 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@meebox/desktop",
-  "version": "0.11.2",
+  "version": "0.11.3-dev",
   "private": true,
   "description": "meebox Electron desktop app",
   "author": {
diff --git a/package-lock.json b/package-lock.json
index 647509c0..7cf37584 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -32,7 +32,7 @@
     },
     "apps/desktop": {
       "name": "@meebox/desktop",
-      "version": "0.11.2",
+      "version": "0.11.3-dev",
       "dependencies": {
         "@iconify-json/material-icon-theme": "^1.2.66",
         "@iconify/react": "^5.2.1",

From 03a1fc168703aabe5dbafe63d4301af4972bab54 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 28 Jul 2026 10:35:33 +0800
Subject: [PATCH 02/17] ci(pages): rebuild the website when the changelog
 changes

The site changelog is synced from CHANGELOG.md / CHANGELOG.zh-CN.md, but they
weren't in pages.yml's path filter, so a release that only touched the
changelog (+ code) didn't redeploy the website and its changelog went stale.
Add both to the push / pull_request paths, and document the coupling (plus the
manual-dispatch fallback) in the release guide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/pages.yml           | 6 ++++++
 docs/development/packaging-release.md | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 2fc91f60..d818ab5a 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -2,17 +2,23 @@ name: Deploy Website (GitHub Pages)
 
 # Brand website (website/, VitePress). Decoupled from the v* release pipeline:
 # build on every PR touching the site/docs (as a check), deploy on push to master.
+# CHANGELOG.md / CHANGELOG.zh-CN.md are included because the site changelog is synced from them (see
+# website/scripts/sync-docs.mjs) — a release merges the changelog to master and must rebuild the site.
 on:
   push:
     branches: [master]
     paths:
       - 'website/**'
       - 'docs/**'
+      - 'CHANGELOG.md'
+      - 'CHANGELOG.zh-CN.md'
       - '.github/workflows/pages.yml'
   pull_request:
     paths:
       - 'website/**'
       - 'docs/**'
+      - 'CHANGELOG.md'
+      - 'CHANGELOG.zh-CN.md'
       - '.github/workflows/pages.yml'
   workflow_dispatch:
 
diff --git a/docs/development/packaging-release.md b/docs/development/packaging-release.md
index 644278ca..aaea7145 100644
--- a/docs/development/packaging-release.md
+++ b/docs/development/packaging-release.md
@@ -48,6 +48,8 @@ Complete these **in the same batch of changes**, flowing through `dev` → `mast
 
 1. **Version** — set the `version` in [apps/desktop/package.json](../../apps/desktop/package.json) to the target version (drop the `v` prefix; prereleases carry a suffix like `0.5.0-alpha.1`). electron-builder's `artifactName: code-meeseeks-${version}-...` reads this value directly — not updating it means the installer filename won't match the tag. After the change, run `npm install` to sync the lockfile.
 2. **CHANGELOG** — the changelog is **bilingual, two files**: [CHANGELOG.md](../../CHANGELOG.md) is the English canonical and [CHANGELOG.zh-CN.md](../../CHANGELOG.zh-CN.md) is the Chinese mirror (**keep both in sync**). In **each** file, rename `## [Unreleased]` to `## [<version>] - <YYYY-MM-DD>` and add a `[<version>]: …/compare/…` link reference at the bottom. **Releasing consumes Unreleased — leave no empty section**; create a new one (in both files) on the next development-phase changelog change. release.yml extracts the `## [<version>]` section **from the English canonical** (CHANGELOG.md) literally to inject into the Release body — the GitHub Release page is **single-language English**, and RELEASE_NOTES.md **leads with per-language deep-links to this version on the bilingual [website changelog](https://huhamhire.github.io/code-meeseeks/changelog)** — `[English](…) · [简体中文](…)` markdown links (EN root, ZH under `/zh/`, both landing on this version) — for readers of either language; a missing section means the body falls back with no change notes. The deep-link is a stable, date-independent anchor `changelog#v<version with dots → hyphens>` (e.g. `0.10.0` → `#v0-10-0`): [sync-docs.mjs](../../website/scripts/sync-docs.mjs) injects that `{#…}` anchor onto each version heading in both locales' site copies (GitHub's CHANGELOG stays clean), and release.yml builds the same slug from the tag to fill RELEASE_NOTES.md's `%%CHANGELOG_URL_EN%%` / `%%CHANGELOG_URL_ZH%%` placeholders — so the two always agree without hand-maintenance. **If the stable release's content comes from a prior alpha/prerelease**: the development phase usually has no separate Unreleased (the content is already in the prerelease section), so just rename that prerelease section to the stable-version section and remove the corresponding `[<x>-alpha.N]:` link reference (the content merges into the stable section, no empty stub left); other prerelease sections with no corresponding stable version are kept.
+
+   **Website changelog auto-syncs** — the site changelog is built from `CHANGELOG.md` / `CHANGELOG.zh-CN.md` (via [sync-docs.mjs](../../website/scripts/sync-docs.mjs)), and [pages.yml](../../.github/workflows/pages.yml) lists both in its `paths` filter, so the `dev → master` release merge (which always updates the changelog) auto-triggers the Pages deploy and the website changelog updates on its own. No manual step in the normal flow; if a deploy is ever skipped, run it by hand: `gh workflow run pages.yml --ref master`.
 3. **Proofread** — confirm the `## [<version>]` section covers every key point (Added / Changed / Fixed) merged into `dev` since the last version, **in both language files** (the English canonical and the Chinese mirror must not drift).
 
 The tag name and the package.json version must match (`v<version>`). A prerelease tag with a `-` in the name (e.g. `-alpha.N`) is automatically marked prerelease by release.yml and does not claim Latest.

From 4dbe9937bdaa6bdb9a578887ee41f29e952e0c16 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Mon, 7 Sep 2026 17:32:45 +0800
Subject: [PATCH 03/17] fix(agent): surface the real LLM failure cause and hint
 an unavailable model

pr-agent's retry_with_fallback_models logs the underlying exception into
loguru's `artifact=` field, which the default format never prints, so a failed
LLM call reached the run card as nothing but "all fallback models failed". For
the local CLI providers this was compounded twice over: codex reports its
failures on stdout (turn.failed / error events in the JSONL stream) and leaves
stderr empty, while a turn that dies on a tool failure exits 0 with no assistant
message at all, which then failed downstream as an unexplained empty prompt.

- shim: extract the cause from the codex event stream on a non-zero exit, and
  raise explicitly when a zero exit carries an empty reply;
- shim: emit `@@MEEBOX_LLM_ERROR@@` on stderr, alongside the usage sentinel, so
  the cause travels past pr-agent's lossy retry log;
- main: prefer that sentinel over the generic marker for errorMessage, and
  classify it into errorHint (currently `model-unavailable`);
- renderer: render one localized remedy line under the raw cause, since a local
  CLI provider's model lives in that CLI's own configuration.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 11 +++++
 CHANGELOG.zh-CN.md                            | 11 +++++
 .../meebox_pragent_shim/cli/install.py        | 30 ++++++++++---
 .../meebox_pragent_shim/cli/parsers.py        | 42 ++++++++++++++++++
 .../meebox_pragent_shim/cli/specs.py          |  5 ++-
 .../pragent-shim/meebox_pragent_shim/usage.py | 26 ++++++++++-
 .../main/services/pr-agent/run-executor.ts    | 19 +++++---
 .../src/main/services/pr-agent/usage.ts       | 44 +++++++++++++++++--
 .../chat/components/RunResultView.tsx         |  6 +++
 .../src/renderer/src/i18n/locales/de-DE.json  |  3 ++
 .../src/renderer/src/i18n/locales/en-US.json  |  3 ++
 .../src/renderer/src/i18n/locales/ja-JP.json  |  3 ++
 .../src/renderer/src/i18n/locales/zh-CN.json  |  3 ++
 .../src/styles/features/chat/run.scss         |  8 ++++
 docs/arch/02-agent/05-pragent-runtime.md      |  5 +++
 packages/poller/src/parse-output.ts           | 29 ++++++++++++
 packages/poller/tests/parse-output.test.ts    | 31 +++++++++++++
 packages/shared/src/poller-contract.ts        |  7 +++
 18 files changed, 270 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a487e0b3..57dd4253 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,17 @@
 All notable changes to this project are recorded here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the versioning follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### ✨ Added
+
+- A review that fails because the model is unavailable now says so and tells you what to do — with a local CLI provider (claude / codex) the model comes from that CLI's own configuration, so it has to be changed there.
+
+### 🔧 Fixed
+
+- A failed review now shows the provider's actual error instead of only "all fallback models failed" — the real cause (an unavailable model, an expired login, an exhausted quota) was previously swallowed and never reached the run card.
+- A local CLI provider that exits successfully but returns an empty reply is now reported as a failure naming that cause, rather than as an unexplained LLM failure.
+
 ## [0.11.2] - 2026-07-28
 
 > Highlights of this release:
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 7b3a085e..7af6d2b5 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -5,6 +5,17 @@
 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [Unreleased]
+
+### ✨ 新增
+
+- 因模型不可用而失败的评审现在会明确说明，并给出处理方式——使用本地 CLI 供应商（claude / codex）时，模型来自该 CLI 自身的配置，需要在那里更换。
+
+### 🔧 修复
+
+- 评审失败时现在会展示供应商返回的真实错误，而不再只有一句「所有备选模型均调用失败」——真正的原因（模型不可用、登录过期、额度耗尽）此前被吞掉，从未出现在运行卡片上。
+- 本地 CLI 供应商正常退出却返回空回复时，现在会作为失败上报并指明该原因，而不再表现为一次无从解释的 LLM 调用失败。
+
 ## [0.11.2] - 2026-07-28
 
 > 本次发布要点：
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/install.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/install.py
index 8d4c3e09..caa0e91b 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/install.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/install.py
@@ -11,7 +11,7 @@
 import sys
 
 from ..runtime import _debug, strip_cache_break
-from ..usage import _emit_usage_tokens
+from ..usage import _emit_llm_error, _emit_usage_tokens
 from .specs import _CLI_SPECS
 
 
@@ -88,12 +88,18 @@ async def run_cli_chat(bin_name, system, user) -> str:
     except Exception as exc:  # noqa: BLE001
         raise RuntimeError(f"failed to start CLI '{bin_name}': {exc}") from exc
     out, err = await proc.communicate(prompt.encode("utf-8"))
+    out_text = (out or b"").decode("utf-8", "replace")
     if proc.returncode != 0:
-        raise RuntimeError(
-            f"CLI '{bin_name}' exit code {proc.returncode}: "
-            f"{(err or b'').decode('utf-8', 'replace')[:500]}"
-        )
-    text, usage = spec["parser"]((out or b"").decode("utf-8", "replace"))
+        # Error source: some CLIs report the failure only on **stdout** (codex writes turn.failed / error events into its
+        # JSONL stream and leaves stderr empty), which would otherwise surface as an empty reason and lose the real cause
+        # (auth / model unavailable / quota). When the spec provides an extractor, take stdout's verdict first and fall
+        # back to stderr; either way keep the raise contract (pr-agent turns it into "all fallback models failed").
+        extractor = spec.get("error_extractor")
+        detail = (extractor(out_text) if extractor else None) or (err or b"").decode("utf-8", "replace")
+        detail = (detail or "<no output>")[:500]
+        _emit_llm_error(bin_name, detail)
+        raise RuntimeError(f"CLI '{bin_name}' exit code {proc.returncode}: {detail}")
+    text, usage = spec["parser"](out_text)
     if usage:
         # prompt_tokens ≈ total input-side size, output_tokens ≈ completion (input/output_tokens share the same names across both).
         # The cache fields differ in convention between the two:
@@ -115,6 +121,18 @@ async def run_cli_chat(bin_name, system, user) -> str:
             cache_read_tokens=cache_read if isinstance(cache_read, int) else None,
             turns=turns if isinstance(turns, int) else None,
         )
+    # Empty reply on a zero exit code: the CLI ran to completion but produced no assistant message (codex does this when a turn
+    # dies on a tool/feature failure, e.g. Code Mode failing closed because its host binary is missing). Downstream this became
+    # an empty prompt into pr-agent's load_yaml → the opaque "all fallback models failed"; raise here instead, carrying any error
+    # event the stream did report, so the run card names the actual cause. Usage is emitted first, keeping the token count truthful.
+    if not (text or "").strip():
+        extractor = spec.get("error_extractor")
+        detail = (extractor(out_text) if extractor else None) or ""
+        msg = f"CLI '{bin_name}' returned an empty reply" + (
+            f": {detail[:500]}" if detail else " (no error reported in its output)"
+        )
+        _emit_llm_error(bin_name, msg)
+        raise RuntimeError(msg)
     return text
 
 
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/parsers.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/parsers.py
index 5dc7b27c..7e504720 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/parsers.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/parsers.py
@@ -71,3 +71,45 @@ def _parse_codex_output(stdout):
     if isinstance(usage, dict) and turns:
         usage["num_turns"] = turns
     return (text if isinstance(text, str) else ""), usage
+
+
+def _extract_codex_error(stdout):
+    """Pull the failure cause out of the `codex exec --json` event stream, returning a message string or None.
+
+    codex reports failures on **stdout** (the JSONL stream) and leaves stderr empty, so without this the caller would
+    raise with an empty detail and the real cause (auth, model 404, quota ...) would never reach the logs. Precedence:
+      - `turn.failed` → error.message is the terminal verdict, most accurate;
+      - otherwise the last `type=="error"` event (the intermediate retry notices carry the same upstream message);
+      - otherwise the last `item.completed` whose item.type=="error" (startup-stage errors, e.g. an unavailable feature host).
+    """
+    import json
+
+    turn_failed = None
+    last_error = None
+    last_item_error = None
+    for line in (stdout or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            ev = json.loads(line)
+        except Exception:  # noqa: BLE001 - skip non-JSON lines (logs, etc.)
+            continue
+        if not isinstance(ev, dict):
+            continue
+        etype = ev.get("type")
+        if etype == "turn.failed":
+            err = ev.get("error")
+            if isinstance(err, dict) and isinstance(err.get("message"), str):
+                turn_failed = err["message"]
+        elif etype == "error":
+            msg = ev.get("message")
+            if isinstance(msg, str):
+                last_error = msg
+        elif etype == "item.completed":
+            item = ev.get("item")
+            if isinstance(item, dict) and item.get("type") == "error":
+                msg = item.get("message")
+                if isinstance(msg, str):
+                    last_item_error = msg
+    return turn_failed or last_error or last_item_error
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/specs.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/specs.py
index 8145fd61..9e0ef3af 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/specs.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/cli/specs.py
@@ -1,6 +1,6 @@
 """Spec table for adapted local CLI commands: argv flags (the prompt always goes via stdin) + output parser + billing env to strip.
 Registering one entry here is enough for a new command; the renderer-side whitelist validation must stay in sync (see LlmProfileForm.validateProfile)."""
-from .parsers import _parse_claude_output, _parse_codex_output
+from .parsers import _extract_codex_error, _parse_claude_output, _parse_codex_output
 
 # `low_effort_flags`: argv to append for the low-effort tier (only enabled by the Agent orchestration channel via MEEBOX_CLI_REASONING,
 # see install.py). Commands with a trailing `-` (stdin) insert these flags before the `-`, keeping `-` last.
@@ -30,6 +30,9 @@
         ],
         "low_effort_flags": ["-c", "model_reasoning_effort=low"],
         "parser": _parse_codex_output,
+        # codex writes its failures into the stdout event stream and leaves stderr empty, so a non-zero exit needs
+        # the cause extracted from stdout (see install.py); commands without this key just fall back to stderr.
+        "error_extractor": _extract_codex_error,
         "strip_env": ("OPENAI_API_KEY", "CODEX_API_KEY"),
     },
 }
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/usage.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/usage.py
index bccf7e6b..74b45105 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/usage.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/usage.py
@@ -1,5 +1,10 @@
 """Real token usage collection: emitted to stderr as a sentinel line `@@MEEBOX_USAGE@@ {json}`, which the main process onLine
-accumulates from (see apps/desktop/src/main/ipc.ts). Takes only tokens, not cost. Fault-tolerant throughout."""
+accumulates from (see apps/desktop/src/main/ipc.ts). Takes only tokens, not cost. Fault-tolerant throughout.
+
+The same stderr sentinel channel also carries `@@MEEBOX_LLM_ERROR@@ {json}` (see _emit_llm_error): pr-agent's
+retry_with_fallback_models logs the underlying exception into loguru's `artifact=` field, which the default format never
+prints, so a failing LLM call reaches stdout as nothing but "Failed to generate prediction with any model". The sentinel
+carries the real cause out of band, past that lossy log line."""
 import sys
 
 from .runtime import _debug
@@ -67,3 +72,22 @@ def _emit_usage_tokens(
         print(f"@@MEEBOX_USAGE@@ {json.dumps(rec)}", file=sys.stderr, flush=True)
     except Exception as exc:  # noqa: BLE001
         _debug(f"emit cli usage failed (ignored): {exc}")
+
+
+def _emit_llm_error(cli, message) -> None:
+    """Emit the real cause of a failed LLM call to stderr as `@@MEEBOX_LLM_ERROR@@ {json}`, right before raising.
+
+    Emitting is purely additive — the exception is still raised and pr-agent still runs its fallback retry; this only
+    keeps the cause from being swallowed by that retry's log line, so the run card can show what actually went wrong
+    (and classify it, e.g. an unavailable model) instead of the generic "all fallback models failed".
+    """
+    try:
+        import json
+
+        print(
+            f"@@MEEBOX_LLM_ERROR@@ {json.dumps({'cli': cli, 'message': message})}",
+            file=sys.stderr,
+            flush=True,
+        )
+    except Exception as exc:  # noqa: BLE001
+        _debug(f"emit llm error failed (ignored): {exc}")
diff --git a/apps/desktop/src/main/services/pr-agent/run-executor.ts b/apps/desktop/src/main/services/pr-agent/run-executor.ts
index 398e0234..7701eb8f 100644
--- a/apps/desktop/src/main/services/pr-agent/run-executor.ts
+++ b/apps/desktop/src/main/services/pr-agent/run-executor.ts
@@ -15,6 +15,7 @@ import {
 } from '@meebox/pr-agent-bridge';
 import {
   addFindingClosure,
+  classifyLlmFailure,
   dropPendingFindingDrafts,
   finishReviewRun,
   parseReviewOutput,
@@ -37,7 +38,8 @@ import {
   accumulateUsageSentinel,
   finalizeUsage,
   newUsageAcc,
-  stripUsageSentinels,
+  parseLlmErrorSentinel,
+  stripShimSentinels,
 } from './usage.js';
 import { neutralizeWorktreeInstructions } from './worktree-sanitize.js';
 
@@ -171,12 +173,18 @@ export class RunExecutor {
       durationMs: Date.now() - t0,
       exitCode: result.exitCode,
       stdout,
-      stderr: stripUsageSentinels(result.stderr),
+      stderr: stripShimSentinels(result.stderr),
       tokenUsage,
     };
     if (parsed.llmFailure) {
+      // pr-agent's fallback retry only logs "Failed to generate prediction with any model" to stdout and hides the real
+      // exception in loguru's artifact field, so prefer the shim's stderr sentinel when present — it carries the actual
+      // provider/CLI error, which is also the only text worth classifying into an actionable hint.
+      const sentinel = parseLlmErrorSentinel(result.stderr);
+      const message = sentinel?.message ?? parsed.llmFailure.message;
+      const errorHint = classifyLlmFailure(message);
       this.ctx.logger.warn(
-        { runId, reason: parsed.llmFailure.message },
+        { runId, reason: message, cli: sentinel?.cli, hint: errorHint },
         'pragent exit 0 but LLM call failed; marking run as failed',
       );
       // Failed runs get no structured collection — findings set empty, UI shows only raw output (no chatpane finding card).
@@ -184,7 +192,8 @@ export class RunExecutor {
         ...base,
         status: 'failed',
         errorReason: 'llm-error',
-        errorMessage: parsed.llmFailure.message,
+        errorMessage: message,
+        ...(errorHint ? { errorHint } : {}),
         findings: [],
       };
     }
@@ -225,7 +234,7 @@ export class RunExecutor {
         errorReason: err.reason,
         errorMessage: err.message,
         stdout: err.result.stdout,
-        stderr: stripUsageSentinels(err.result.stderr),
+        stderr: stripShimSentinels(err.result.stderr),
         findings: [],
         tokenUsage,
       };
diff --git a/apps/desktop/src/main/services/pr-agent/usage.ts b/apps/desktop/src/main/services/pr-agent/usage.ts
index 33ba4076..922fac06 100644
--- a/apps/desktop/src/main/services/pr-agent/usage.ts
+++ b/apps/desktop/src/main/services/pr-agent/usage.ts
@@ -73,13 +73,51 @@ export function finalizeUsage(acc: UsageAcc): TokenUsage | undefined {
 }
 
 /**
- * Strip usage sentinel lines from stderr before persistence: onLine already intercepts them in real time without forwarding, but exec internally
+ * Strip shim sentinel lines from stderr before persistence: onLine already intercepts them in real time without forwarding, but exec internally
  * accumulates all stderr into result.stderr (including sentinels), so clear these noise lines before persisting.
  */
-export function stripUsageSentinels(stderr: string | undefined): string | undefined {
+export function stripShimSentinels(stderr: string | undefined): string | undefined {
   if (!stderr) return stderr;
   return stderr
     .split('\n')
-    .filter((l) => !l.includes(USAGE_SENTINEL))
+    .filter((l) => !l.includes(USAGE_SENTINEL) && !l.includes(LLM_ERROR_SENTINEL))
     .join('\n');
 }
+
+/**
+ * LLM-error sentinel-line prefix (kept consistent with the shim's usage._emit_llm_error). Shares the stderr sentinel
+ * channel with usage: pr-agent's fallback retry logs the underlying exception into loguru's `artifact=` field, which the
+ * default format drops, so the real cause never reaches stdout — the shim routes it out of band through this line.
+ */
+export const LLM_ERROR_SENTINEL = '@@MEEBOX_LLM_ERROR@@';
+
+/**
+ * Pull the LLM-call cause out of stderr sentinel lines, returning the **last** one (a run may retry several times; the last
+ * is what actually sank the run). Bad JSON / a missing message is ignored — this is a diagnostic enrichment, never a
+ * reason to fail differently.
+ */
+export function parseLlmErrorSentinel(
+  stderr: string | undefined,
+): { cli?: string; message: string } | undefined {
+  if (!stderr) return undefined;
+  let found: { cli?: string; message: string } | undefined;
+  for (const line of stderr.split('\n')) {
+    const i = line.indexOf(LLM_ERROR_SENTINEL);
+    if (i < 0) continue;
+    try {
+      const rec = JSON.parse(line.slice(i + LLM_ERROR_SENTINEL.length).trim()) as {
+        cli?: unknown;
+        message?: unknown;
+      };
+      if (typeof rec.message === 'string' && rec.message.trim()) {
+        found = {
+          cli: typeof rec.cli === 'string' ? rec.cli : undefined,
+          message: rec.message.trim(),
+        };
+      }
+    } catch {
+      // Malformed sentinel → skip, keep any earlier one.
+    }
+  }
+  return found;
+}
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
index 2387d75c..610122f7 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
@@ -229,6 +229,12 @@ export function RunResultView({
           {run.errorMessage && !isCancelled && (
             <pre className="chat-error-detail">{run.errorMessage}</pre>
           )}
+          {/* Actionable hint on top of the raw cause: the message above is the provider's own wording (English, technical),
+              which doesn't tell the user what to do. A recognized kind adds one localized line of remedy — currently
+              「the model is unavailable, change it」, whose fix lives outside the app for a local CLI provider. */}
+          {run.errorHint === 'model-unavailable' && !isCancelled && (
+            <p className="chat-error-hint">{t('chatPane.llmErrorHint.modelUnavailable')}</p>
+          )}
           {/* Failed / cancelled no longer show a separate output block: the pr-agent log is already in the collapsible「raw output」above (stdout contains
               the [pr-agent stdout log] segment, same source as stderr), avoiding duplicating the same log into two blocks. */}
         </div>
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index f4083b55..47f5e205 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -98,6 +98,9 @@
     "goToSettings": "Zu den Einstellungen",
     "inputAria": "Chat-Eingabe",
     "llmCallFailed": "LLM-Aufruf fehlgeschlagen",
+    "llmErrorHint": {
+      "modelUnavailable": "Das angeforderte Modell ist nicht verfügbar. Bei einem lokalen CLI-Anbieter stammt das Modell aus der Konfiguration dieser CLI — stellen Sie dort auf ein unterstütztes Modell um und führen Sie den Lauf erneut aus."
+    },
     "mergeConfirmLabel": "Mergen",
     "mergeConfirmMessage": "„{{title}}“ in den Zielbranch mergen? Dies kann nicht rückgängig gemacht werden.",
     "mergeConfirmTitle": "PR mergen",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index def9c738..45fbae10 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -98,6 +98,9 @@
     "goToSettings": "Go to Settings",
     "inputAria": "Chat input",
     "llmCallFailed": "LLM call failed",
+    "llmErrorHint": {
+      "modelUnavailable": "The requested model is unavailable. With a local CLI provider the model comes from that CLI's own configuration — switch it to a supported model there, then run again."
+    },
     "mergeConfirmLabel": "Merge",
     "mergeConfirmMessage": "Merge \"{{title}}\" into its target branch? This can't be undone.",
     "mergeConfirmTitle": "Merge PR",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index 5f1542f7..2929031a 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -98,6 +98,9 @@
     "goToSettings": "設定へ移動",
     "inputAria": "チャット入力",
     "llmCallFailed": "LLM の呼び出しに失敗しました",
+    "llmErrorHint": {
+      "modelUnavailable": "要求されたモデルは利用できません。ローカル CLI プロバイダーの場合、モデルはその CLI 自身の設定で決まります。CLI 側でサポートされているモデルに変更してから再実行してください。"
+    },
     "mergeConfirmLabel": "マージ",
     "mergeConfirmMessage": "「{{title}}」をターゲットブランチにマージしますか？この操作は取り消せません。",
     "mergeConfirmTitle": "PR をマージ",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index e220dc1b..ad5bec2d 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -98,6 +98,9 @@
     "goToSettings": "去设置",
     "inputAria": "聊天输入框",
     "llmCallFailed": "LLM 调用失败",
+    "llmErrorHint": {
+      "modelUnavailable": "所请求的模型不可用。使用本地 CLI 供应商时，模型由该 CLI 自身的配置决定，请在 CLI 中改用受支持的模型后重新运行。"
+    },
     "mergeConfirmLabel": "合并",
     "mergeConfirmMessage": "确定将「{{title}}」合并到目标分支？此操作不可撤销。",
     "mergeConfirmTitle": "合并 PR",
diff --git a/apps/desktop/src/renderer/src/styles/features/chat/run.scss b/apps/desktop/src/renderer/src/styles/features/chat/run.scss
index 020a84a3..4a861667 100644
--- a/apps/desktop/src/renderer/src/styles/features/chat/run.scss
+++ b/apps/desktop/src/renderer/src/styles/features/chat/run.scss
@@ -41,6 +41,14 @@
   color: $text-muted;
 }
 
+// Actionable remedy line under the raw cause: prose (not mono like .chat-error-detail), so it reads as guidance
+// from the app rather than as more provider output.
+.chat-error-hint {
+  margin: $space-2 0 0;
+  font-size: $fs-xs;
+  line-height: 1.5;
+}
+
 // stderr / stdout collapsible area embedded in a failed run: one extra level of indentation inside the chat-error red banner
 .chat-error-stderr,
 .chat-error-stdout {
diff --git a/docs/arch/02-agent/05-pragent-runtime.md b/docs/arch/02-agent/05-pragent-runtime.md
index b0b904e2..f253597a 100644
--- a/docs/arch/02-agent/05-pragent-runtime.md
+++ b/docs/arch/02-agent/05-pragent-runtime.md
@@ -104,6 +104,11 @@ litellm**.
 - **Reuse the CLI's own login state**: the subprocess inherits `HOME`/`USERPROFILE`, and the CLI reads its own login credentials (e.g. `~/.claude`) to run.
   To avoid a stray API key in the local environment leaking in and overriding the CLI's own login method, the shim explicitly strips
   `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from the subprocess env. The model used, the quota and compliance are all decided by that CLI's account and the user's authorization.
+- **Error source on a non-zero exit**: not every CLI reports its failure on stderr — `codex exec --json` writes `turn.failed` / `error`
+  events into the **stdout** JSONL stream and leaves stderr empty, so taking stderr alone would raise with an empty reason and the real
+  cause (auth expired / model unavailable / quota) would never reach the log, leaving only pr-agent's generic "all fallback models failed".
+  A spec may therefore declare an `error_extractor` that pulls the verdict out of stdout (precedence `turn.failed` → the last `error`
+  event → an `item.completed` error item), with stderr as the fallback for commands without one.
 - **Proxy auto pass-through**: the subprocess env is copied from `os.environ` (only the two API keys above removed), and `HTTP(S)_PROXY` / `NO_PROXY`
   are kept as-is → `claude`'s egress automatically goes through the user-configured proxy (see [Networking & proxy](../99-core/03-networking-proxy.md)), no extra setup needed.
 - **token usage**: from the claude JSON's `usage`, construct the same `@@MEEBOX_USAGE@@` sentinel, accumulated by the same main-process path. The ↑ total input takes
diff --git a/packages/poller/src/parse-output.ts b/packages/poller/src/parse-output.ts
index 0a3bf21d..265119ea 100644
--- a/packages/poller/src/parse-output.ts
+++ b/packages/poller/src/parse-output.ts
@@ -22,6 +22,35 @@ export interface ParsedReviewOutput {
   llmFailure?: { message: string };
 }
 
+/**
+ * Actionable classification of an LLM failure, used by the UI to add a "what to do about it" hint on top of the raw
+ * technical message. Only cases with a concrete user action get a kind; everything else stays unclassified (undefined)
+ * and renders the message alone.
+ *
+ * - `model-unavailable`: the model the provider was asked for does not exist / is not accessible for this account.
+ *   Typical with a local CLI provider, whose model is pinned in the CLI's own config (e.g. `~/.codex/config.toml`)
+ *   and can be retired upstream at any time — the app never chose it, so the fix is to change it there.
+ */
+export type LlmFailureKind = 'model-unavailable';
+
+/**
+ * Classify an LLM failure message into an actionable kind, or undefined when nothing actionable is recognized.
+ * Matches the wording of both the direct-API path (litellm `NotFoundError` / `model_not_found`) and the local CLI path
+ * (codex's `The model \`x\` does not exist or you do not have access to it` / `is not supported when using ...`).
+ */
+export function classifyLlmFailure(message: string): LlmFailureKind | undefined {
+  const m = stripAnsi(message);
+  if (
+    /model_not_found/i.test(m) ||
+    /\bmodel\b[^\n]{0,80}\bdoes not exist\b/i.test(m) ||
+    /\bmodel\b[^\n]{0,80}\bis not supported\b/i.test(m) ||
+    /\bdo(?:es)? not have access to (?:it|this model)\b/i.test(m)
+  ) {
+    return 'model-unavailable';
+  }
+  return undefined;
+}
+
 /**
  * Scan stdout for a marker of all LLM calls failing. When pr-agent's fallback retry exhausts all alternate
  * models and still fails, it only logger.error's one line "Failed to <tool> PR: Failed to generate
diff --git a/packages/poller/tests/parse-output.test.ts b/packages/poller/tests/parse-output.test.ts
index 0e26e369..0de269ab 100644
--- a/packages/poller/tests/parse-output.test.ts
+++ b/packages/poller/tests/parse-output.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import {
+  classifyLlmFailure,
   parseReviewOutput,
   parseStructuredAsk,
   sectionToFinding,
@@ -698,3 +699,33 @@ describe('parseStructuredAsk', () => {
     expect(parseReviewOutput('<summary>x</summary>', 'ask').askVerdict).toBeUndefined();
   });
 });
+
+describe('classifyLlmFailure', () => {
+  it('codex: model retired upstream (404 wording) → model-unavailable', () => {
+    expect(
+      classifyLlmFailure(
+        "CLI 'codex' exit code 1: unexpected status 404 Not Found: The model `gpt-5.5` does not exist or you do not have access to it., url: https://chatgpt.com/backend-api/codex/responses",
+      ),
+    ).toBe('model-unavailable');
+  });
+
+  it('codex: model not entitled for the account → model-unavailable', () => {
+    expect(
+      classifyLlmFailure(
+        "The 'gpt-5.1-codex' model is not supported when using Codex with a ChatGPT account.",
+      ),
+    ).toBe('model-unavailable');
+  });
+
+  it('direct API: litellm model_not_found → model-unavailable', () => {
+    expect(
+      classifyLlmFailure('litellm.NotFoundError: The model `x` was not found (model_not_found)'),
+    ).toBe('model-unavailable');
+  });
+
+  it('unrelated failures stay unclassified (no misleading remedy)', () => {
+    expect(classifyLlmFailure('litellm.AuthenticationError: invalid api key')).toBeUndefined();
+    expect(classifyLlmFailure('Read timed out after 600s')).toBeUndefined();
+    expect(classifyLlmFailure("CLI 'codex' returned an empty reply")).toBeUndefined();
+  });
+});
diff --git a/packages/shared/src/poller-contract.ts b/packages/shared/src/poller-contract.ts
index 5b6ecd5b..be2e9380 100644
--- a/packages/shared/src/poller-contract.ts
+++ b/packages/shared/src/poller-contract.ts
@@ -345,6 +345,13 @@ export interface ReviewRun {
   exitCode?: number;
   errorReason?: ReviewRunFailureReason;
   errorMessage?: string;
+  /**
+   * Actionable classification of the failure, when one is recognized (see poller's classifyLlmFailure). errorMessage stays
+   * the raw technical cause; this drives an extra "how to fix it" line in the UI, localized by the frontend from the kind.
+   * Currently only `model-unavailable` (the provider rejected the requested model — for a local CLI provider the model
+   * lives in that CLI's own config, so the user has to change it there). Historical runs don't have it.
+   */
+  errorHint?: 'model-unavailable';
   /** Raw stdout text; still kept after M3-B2 parses it into findings, for "see original" debugging */
   stdout?: string;
   /** Raw stderr text */

From f39375ae67809a9957aa45f31125ee921dd00b9a Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Mon, 7 Sep 2026 20:28:54 +0800
Subject: [PATCH 04/17] feat(pr): reconcile remote state after merge and review
 verdicts

A merge or review verdict returns as soon as the remote accepts it, while the
state the UI reads is recomputed asynchronously and lands seconds later: a
merged PR keeps reporting open and keeps coming back in the discovery list, and
mergeStatus.canMerge still holds its pre-verdict value. Refreshing the instant
the action returned therefore read pre-action state and looked like nothing had
happened -- the merged PR sat in the list, and the merge button stayed hidden
after the approval that had just unblocked it, both until the next periodic poll.

Both actions now start a bounded backoff re-check in main: refresh that one PR
on a growing delay until the expected change appears, broadcasting prs:changed
for the renderer to reload. It is fire-and-forget (the IPC never waits on the
remote settling) and past its window the periodic poll remains the backstop.

A confirmed merge archives that one PR directly, via a new Poller method. The
list filters on archivedAt rather than PR state, so a merged PR disappears only
once archived -- and running a whole poll tick for it would put every
connection's discovery fetch in front of the departure the user is waiting on.
The departure a poll infers from absence is already established by the confirmed
remote state, so it is asserted directly. For the same reason the renderer no
longer fires a full poll on merge: that round is guaranteed to read pre-merge
state, spending a round-trip to redraw the same list.

Living in main covers every entry point with one implementation -- the buttons,
the chat commands, and the CLI's review write actions share these controllers.
The single-PR refresh is extracted for reuse, with comment-cache invalidation
made opt-in: a background re-check must not make the open comment / diff panes
re-fetch for a state the user never asked about.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +
 CHANGELOG.zh-CN.md                            |   2 +
 apps/desktop/src/main/controllers/pr.ts       |  74 +++----
 .../src/main/services/pr-post-action.ts       | 187 ++++++++++++++++++
 .../features/pr/hooks/usePullRequests.ts      |  12 +-
 .../src/renderer/src/hooks/useBootstrap.ts    |  10 +
 docs/arch/01-platform/03-review-workflow.md   |   1 +
 packages/ipc/src/events.ts                    |   7 +
 packages/poller/src/poller.ts                 |  26 +++
 packages/poller/tests/poller.test.ts          |  27 +++
 10 files changed, 293 insertions(+), 55 deletions(-)
 create mode 100644 apps/desktop/src/main/services/pr-post-action.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57dd4253..e5798ef1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,8 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 - A failed review now shows the provider's actual error instead of only "all fallback models failed" — the real cause (an unavailable model, an expired login, an exhausted quota) was previously swallowed and never reached the run card.
 - A local CLI provider that exits successfully but returns an empty reply is now reported as a failure naming that cause, rather than as an unexplained LLM failure.
+- A merged PR now leaves the list on its own shortly after you merge it, instead of lingering until the next periodic sync — the remote takes a few seconds to actually mark it merged, and the app now waits for that rather than refreshing too early and finding nothing changed.
+- Approving a PR now updates whether it can be merged, so the merge button appears as soon as your approval satisfies the last requirement — previously it stayed hidden until the next periodic sync, because the remote recomputes mergeability only after the approval returns.
 
 ## [0.11.2] - 2026-07-28
 
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 7af6d2b5..d41aafa9 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -15,6 +15,8 @@
 
 - 评审失败时现在会展示供应商返回的真实错误，而不再只有一句「所有备选模型均调用失败」——真正的原因（模型不可用、登录过期、额度耗尽）此前被吞掉，从未出现在运行卡片上。
 - 本地 CLI 供应商正常退出却返回空回复时，现在会作为失败上报并指明该原因，而不再表现为一次无从解释的 LLM 调用失败。
+- 合并 PR 后，该 PR 会在稍后自动从列表中消失，而不再滞留到下一次周期同步——远端需要几秒才真正标记为已合并，应用现在会等待这一刻，而不是过早刷新、结果什么都没变。
+- 批准 PR 后会重新判断其是否可合并，当你的批准满足最后一项要求时合并按钮即刻出现——此前它会一直隐藏到下一次周期同步，因为远端要在批准返回之后才重新计算可合并性。
 
 ## [0.11.2] - 2026-07-28
 
diff --git a/apps/desktop/src/main/controllers/pr.ts b/apps/desktop/src/main/controllers/pr.ts
index 106c6467..176ff52f 100644
--- a/apps/desktop/src/main/controllers/pr.ts
+++ b/apps/desktop/src/main/controllers/pr.ts
@@ -31,6 +31,11 @@ import {
 } from '@meebox/shared';
 import { annotateOwnership } from '../services/comments.js';
 import { getContext } from '../services/context.js';
+import {
+  confirmMergeSettled,
+  confirmMergeabilityAfterReview,
+  refreshSinglePr,
+} from '../services/pr-post-action.js';
 import type { IpcController } from './types.js';
 
 /*
@@ -322,56 +327,8 @@ export const refreshPrs: IpcController<'prs:refresh'> = () => getContext().polle
  * the mirror has the new commits so the diff renders the new code. Returns the updated PR; the renderer then reloads the
  * list locally (no network poll of other PRs).
  */
-export const refreshOnePr: IpcController<'prs:refreshOne'> = async (_event, req) => {
-  const ctx = getContext();
-  const existing = await ctx.pr.findPrOrThrow(req.localId);
-  const adapter = ctx.pr.adapterForOrThrow(existing);
-  // Remote fetch of just this PR. 403/404 normalize to error codes (matching openPrByUrl); other errors bubble up.
-  let fresh;
-  try {
-    fresh = await adapter.prs.getSinglePullRequest(
-      { projectKey: existing.repo.projectKey, repoSlug: existing.repo.repoSlug },
-      existing.remoteId,
-    );
-  } catch (err) {
-    const status = (err as { status?: number } | null)?.status;
-    if (status === 403) throw new AppError(ERROR_CODES.PR_FORBIDDEN, undefined, 'forbidden');
-    if (status === 404) throw new AppError(ERROR_CODES.PR_NOT_FOUND, undefined, 'not found');
-    throw err;
-  }
-  // localStatus mirrors the remote current user's reviewer status (remote authoritative, same mapping as the poll);
-  // when the current user is unknown (ping incomplete) keep the recorded status rather than downgrading to pending.
-  const me = adapter.connection.getCurrentUser();
-  const mineStatus = me ? fresh.reviewers.find((r) => r.name === me.name)?.status : undefined;
-  const localStatus = !me
-    ? existing.localStatus
-    : mineStatus === 'approved'
-      ? 'approved'
-      : mineStatus === 'needsWork'
-        ? 'needs_work'
-        : 'pending';
-  const stored: StoredPullRequest = {
-    ...fresh,
-    localId: existing.localId,
-    platform: existing.platform,
-    connectionId: existing.connectionId,
-    localStatus,
-    // Preserve local-only bookkeeping (a single-PR refresh isn't a discovery pass).
-    discoveryFilters: existing.discoveryFilters,
-    discoveredAt: existing.discoveredAt,
-    lastSeenAt: new Date().toISOString(),
-  };
-  await writePrMeta(await ctx.pr.storeForPr(req.localId), req.localId, stored);
-  await ctx.pr.invalidateCommentsCache(req.localId);
-  if (fresh.sourceRef.sha !== existing.sourceRef.sha) {
-    try {
-      await ctx.pr.ensureMirrorReadyForPr(stored);
-    } catch {
-      /* non-fatal: the diff view self-heals / surfaces a readable error if the mirror still lacks the sha */
-    }
-  }
-  return stored;
-};
+export const refreshOnePr: IpcController<'prs:refreshOne'> = (_event, req) =>
+  refreshSinglePr(getContext(), req.localId, { invalidateComments: true });
 
 /**
  * The Poller's most recent completion time (used for startup initialization).
@@ -382,6 +339,11 @@ export const getLastSync: IpcController<'prs:lastSync'> = () => ({
 
 /**
  * Set review status: write remote first (on failure the frontend is unchanged), and persist locally after the remote is OK.
+ *
+ * A verdict can change the remote's mergeability verdict (an approval satisfying the last required rule makes the PR
+ * mergeable), but the remote recomputes that asynchronously — the value returned here is still the pre-verdict one. So
+ * kick off a background re-check that lands the new canMerge, rather than leaving the merge button a poll interval
+ * behind reality (see services/pr-post-action.ts).
  */
 export const setPrStatus: IpcController<'prs:setLocalStatus'> = async (_event, req) => {
   const ctx = getContext();
@@ -398,7 +360,9 @@ export const setPrStatus: IpcController<'prs:setLocalStatus'> = async (_event, r
     pr.remoteId,
     remoteStatus,
   );
-  return setLocalStatus(ctx.stateStore, req.localId, req.status);
+  const updated = await setLocalStatus(ctx.stateStore, req.localId, req.status);
+  confirmMergeabilityAfterReview(ctx, req.localId, pr.mergeStatus.canMerge);
+  return updated;
 };
 
 /**
@@ -408,7 +372,12 @@ export const markRead: IpcController<'prs:markRead'> = (_event, req) =>
   markPrRead(getContext().stateStore, req.localId);
 
 /**
- * Merge a PR; do not persist locally here, relying on renderer refresh → poll soft-delete to finish, to avoid local and remote disagreeing.
+ * Merge a PR; do not persist locally here, relying on refresh → poll soft-delete to finish, to avoid local and remote disagreeing.
+ *
+ * The remote does not settle synchronously: for a moment after the merge is accepted the PR still reports open and still
+ * comes back in the discovery list, so an immediate refresh would show it sitting in the list untouched. A background
+ * re-check confirms it actually left the open state and then archives it through a poll tick (see
+ * services/pr-post-action.ts); it is deliberately not awaited, so the caller isn't blocked on the remote settling.
  */
 export const mergePr: IpcController<'prs:merge'> = async (_event, req) => {
   const ctx = getContext();
@@ -418,6 +387,7 @@ export const mergePr: IpcController<'prs:merge'> = async (_event, req) => {
     { projectKey: pr.repo.projectKey, repoSlug: pr.repo.repoSlug },
     pr.remoteId,
   );
+  confirmMergeSettled(ctx, req.localId);
 };
 
 /**
diff --git a/apps/desktop/src/main/services/pr-post-action.ts b/apps/desktop/src/main/services/pr-post-action.ts
new file mode 100644
index 00000000..a1c6ebd5
--- /dev/null
+++ b/apps/desktop/src/main/services/pr-post-action.ts
@@ -0,0 +1,187 @@
+import { writePrMeta } from '@meebox/poller';
+import { AppError, ERROR_CODES, type StoredPullRequest } from '@meebox/shared';
+import type { ServiceContext } from './context.js';
+
+/**
+ * Post-action remote reconciliation: after a write action (merge / review verdict) the platform does **not** settle
+ * synchronously — the call returns as soon as the request is accepted, while the state the UI reads is recomputed
+ * asynchronously on the remote and lands some seconds later:
+ *
+ * - **merge**: the PR keeps reporting `state: 'open'` and keeps appearing in the discovery list for a moment, so a
+ *   refresh fired the instant the merge returns still shows the PR sitting in the list as if nothing happened;
+ * - **review verdict**: `mergeStatus.canMerge` is a server-side verdict over approvals / builds / branch protection.
+ *   An approval that satisfies the last required rule flips it to true — but only once the remote has recomputed it,
+ *   which is after the approve call has already returned.
+ *
+ * A single immediate refresh therefore reads pre-action state and looks like nothing happened; leaving it to the
+ * periodic poll means waiting a whole interval. So both actions kick off a **backoff re-check** here: refresh the one
+ * PR on a growing delay until the expected change shows up (or the attempts run out, where the periodic poll remains
+ * the backstop), and broadcast `prs:changed` whenever the state actually moved so the renderer reloads.
+ *
+ * Living in main rather than in the renderer keeps every entry point covered by one implementation: the merge / approve
+ * buttons, the chat `/merge` `/approve` commands, and the CLI's review write actions all route through the same
+ * controllers (see services/api-server/routes/pr.ts).
+ */
+
+/**
+ * Delays before each re-check attempt, in ms. The first is short because the common case is a remote that has already
+ * settled by the time the action returns, and that attempt sets the latency the user actually perceives; the rest grow
+ * to cover a slow remote without hammering it. The tail (~15s total) is deliberately shorter than a poll interval —
+ * past that, the periodic poll is the backstop and a background loop adds nothing.
+ */
+const RECHECK_DELAYS_MS = [400, 1_200, 3_500, 10_000] as const;
+
+/**
+ * Confirmation loops already running, keyed by `<what>:<localId>`, so repeated clicks don't stack duplicate loops.
+ * Keyed by kind as well as PR: approving and then merging the same PR are two independent settlements, and a merge
+ * confirmation must not be dropped just because the verdict's loop is still winding down.
+ */
+const inFlight = new Set<string>();
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Re-fetch one PR from the remote and persist it, returning the updated record (null when the PR is gone locally).
+ *
+ * Shared by the `prs:refreshOne` handler and the confirmation loops below. `invalidateComments` is what separates the
+ * two callers: a user-driven refresh wants comments re-fetched as well, while a background confirmation only cares
+ * about PR metadata — invalidating on every attempt would make the open comment / diff panes re-fetch several times
+ * over for a state the user never asked about.
+ */
+export async function refreshSinglePr(
+  ctx: ServiceContext,
+  localId: string,
+  opts: { invalidateComments: boolean },
+): Promise<StoredPullRequest> {
+  const existing = await ctx.pr.findPrOrThrow(localId);
+  const adapter = ctx.pr.adapterForOrThrow(existing);
+  // Remote fetch of just this PR. 403/404 normalize to error codes (matching openPrByUrl); other errors bubble up.
+  let fresh;
+  try {
+    fresh = await adapter.prs.getSinglePullRequest(
+      { projectKey: existing.repo.projectKey, repoSlug: existing.repo.repoSlug },
+      existing.remoteId,
+    );
+  } catch (err) {
+    const status = (err as { status?: number } | null)?.status;
+    if (status === 403) throw new AppError(ERROR_CODES.PR_FORBIDDEN, undefined, 'forbidden');
+    if (status === 404) throw new AppError(ERROR_CODES.PR_NOT_FOUND, undefined, 'not found');
+    throw err;
+  }
+  // localStatus mirrors the remote current user's reviewer status (remote authoritative, same mapping as the poll);
+  // when the current user is unknown (ping incomplete) keep the recorded status rather than downgrading to pending.
+  const me = adapter.connection.getCurrentUser();
+  const mineStatus = me ? fresh.reviewers.find((r) => r.name === me.name)?.status : undefined;
+  const localStatus = !me
+    ? existing.localStatus
+    : mineStatus === 'approved'
+      ? 'approved'
+      : mineStatus === 'needsWork'
+        ? 'needs_work'
+        : 'pending';
+  const stored: StoredPullRequest = {
+    ...fresh,
+    localId: existing.localId,
+    platform: existing.platform,
+    connectionId: existing.connectionId,
+    localStatus,
+    // Preserve local-only bookkeeping (a single-PR refresh isn't a discovery pass).
+    discoveryFilters: existing.discoveryFilters,
+    discoveredAt: existing.discoveredAt,
+    lastSeenAt: new Date().toISOString(),
+  };
+  await writePrMeta(await ctx.pr.storeForPr(localId), localId, stored);
+  if (opts.invalidateComments) await ctx.pr.invalidateCommentsCache(localId);
+  if (fresh.sourceRef.sha !== existing.sourceRef.sha) {
+    try {
+      await ctx.pr.ensureMirrorReadyForPr(stored);
+    } catch {
+      /* non-fatal: the diff view self-heals / surfaces a readable error if the mirror still lacks the sha */
+    }
+  }
+  return stored;
+}
+
+/**
+ * Run the backoff re-check loop for one PR: refresh, hand the result to `settled`, and stop as soon as it reports the
+ * expected change (or the attempts run out). Errors on an individual attempt are swallowed and retried — a transient
+ * remote hiccup shouldn't abort the confirmation, and a PR that vanished locally (archived by a concurrent poll) ends
+ * the loop, since there is nothing left to confirm.
+ */
+async function recheckUntilSettled(
+  ctx: ServiceContext,
+  localId: string,
+  what: 'merge' | 'review-verdict',
+  settled: (pr: StoredPullRequest) => boolean,
+): Promise<void> {
+  const key = `${what}:${localId}`;
+  if (inFlight.has(key)) return;
+  inFlight.add(key);
+  try {
+    for (const delay of RECHECK_DELAYS_MS) {
+      await sleep(delay);
+      let pr: StoredPullRequest;
+      try {
+        pr = await refreshSinglePr(ctx, localId, { invalidateComments: false });
+      } catch (err) {
+        if (err instanceof AppError && err.code === ERROR_CODES.PR_NOT_FOUND) return;
+        ctx.logger.debug({ err, localId, what }, 'post-action recheck attempt failed; retrying');
+        continue;
+      }
+      if (!settled(pr)) {
+        // Not the change we're waiting for, but the attempt has still persisted fresh remote state (reviewer verdicts,
+        // vetoes, head sha); leaving that on disk unannounced would show a list disagreeing with what was just stored.
+        // Reloading is a local read, so the extra broadcast costs nothing.
+        ctx.broadcast('prs:changed', { localId });
+        continue;
+      }
+      // The remote has settled. The list filters on archivedAt, not on PR state, so a merged PR only disappears once it
+      // is archived — archive this one directly rather than running a full poll tick for it: a tick would fetch every
+      // connection's discovery lists before the PR the user just merged could leave, and all of that is latency the user
+      // watches. The departure a poll infers from absence is already established here by the confirmed remote state.
+      if (what === 'merge') {
+        try {
+          await ctx.poller.archivePullRequest(localId);
+        } catch (err) {
+          ctx.logger.warn({ err, localId }, 'archiving the merged PR failed; the periodic poll will catch up');
+        }
+      }
+      ctx.logger.info({ localId, what }, 'post-action remote state settled');
+      ctx.broadcast('prs:changed', { localId });
+      return;
+    }
+    ctx.logger.debug(
+      { localId, what },
+      'post-action remote state did not settle within the recheck window; leaving it to the periodic poll',
+    );
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+/**
+ * After a merge is accepted: confirm the PR actually left the open state, then archive it through a poll tick so it
+ * disappears from the list. Fire-and-forget — the merge IPC returns immediately and the button must not stay busy for
+ * the length of the confirmation.
+ */
+export function confirmMergeSettled(ctx: ServiceContext, localId: string): void {
+  void recheckUntilSettled(ctx, localId, 'merge', (pr) => pr.state !== 'open');
+}
+
+/**
+ * After a review verdict is written: confirm whether it changed the remote's mergeability verdict, so the merge button
+ * appears (or disappears) without waiting for the periodic poll. `before` is the canMerge value observed at the moment
+ * the verdict was written; any move away from it is the settlement we're waiting for.
+ */
+export function confirmMergeabilityAfterReview(
+  ctx: ServiceContext,
+  localId: string,
+  before: boolean,
+): void {
+  void recheckUntilSettled(
+    ctx,
+    localId,
+    'review-verdict',
+    (pr) => pr.mergeStatus.canMerge !== before,
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
index 4a5ee78e..34a90ef2 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
+++ b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
@@ -114,10 +114,16 @@ export function usePullRequests({ notifyError }: { notifyError: (msg: string) =>
     } finally {
       setMerging(false);
     }
-    // Merge succeeded: the PR has transitioned to MERGED and will leave the pending list. Deselect + refresh to make it disappear
+    // Merge accepted: deselect, since the PR is on its way out of the pending list.
+    //
+    // Deliberately NOT a remote refresh here: the remote takes a moment to actually mark the PR merged and drop it from
+    // the discovery list, so a poll fired now reads pre-merge state — it would cost a full round-trip across every
+    // connection only to redraw the same list, with the PR still in it. Main confirms the merge landed and archives the
+    // PR (see services/pr-post-action.ts), then broadcasts prs:changed; the local reload below just reflects whatever is
+    // already on disk in the meantime.
     if (selectedId === mergedId) setSelectedId(null);
-    await triggerRefresh();
-  }, [selected, selectedId, triggerRefresh, notifyError, merging, t]);
+    await reloadPrs();
+  }, [selected, selectedId, reloadPrs, triggerRefresh, notifyError, merging, t]);
 
   return {
     prs,
diff --git a/apps/desktop/src/renderer/src/hooks/useBootstrap.ts b/apps/desktop/src/renderer/src/hooks/useBootstrap.ts
index 9dabd248..31918e8d 100644
--- a/apps/desktop/src/renderer/src/hooks/useBootstrap.ts
+++ b/apps/desktop/src/renderer/src/hooks/useBootstrap.ts
@@ -121,6 +121,16 @@ export function useBootstrap({ setPrs, reloadPrs }: UseBootstrapParams): {
     });
   }, [reloadPrs]);
 
+  // A PR settled after a write action (merge landed / a review verdict changed mergeability): main has already
+  // persisted the new state, so reload the list locally — no remote call. Separate from poll:tick because these land
+  // between ticks, on the user's own action, and are exactly the moments where waiting a whole interval is felt.
+  useEffect(() => {
+    if (!window.api) return;
+    return subscribe('prs:changed', () => {
+      void reloadPrs();
+    });
+  }, [reloadPrs]);
+
   // Proactively refresh the remote when the window regains focus: fetch PR meta; on Bitbucket, after adding a comment /
   // changing status, PR.updatedAt jumps → PrPanel's prUpdatedAt dep fires → force listComments to fetch new comments.
   useEffect(() => {
diff --git a/docs/arch/01-platform/03-review-workflow.md b/docs/arch/01-platform/03-review-workflow.md
index 9b0e90b4..603c45ec 100644
--- a/docs/arch/01-platform/03-review-workflow.md
+++ b/docs/arch/01-platform/03-review-workflow.md
@@ -18,6 +18,7 @@ Responsible for: review-command orchestration, output parsing, the draft state m
 - **finding state machine**: `pending → accepted/edited/rejected/posted`; on successful publish, `posted_remote_id` is recorded as the idempotency key to prevent re-sending.
 - **Publishing goes through platform inline comments**: batch `publishInlineComment`, internally mapping the finding anchor to the platform anchor (see [Platform adaptation](01-adapter.md)).
 - **Secondary comment operations**: reply / edit / delete (with can-edit/can-delete pre-checks: only your own authored comments may be operated on, re-validated on the remote); PR merge's entry is controlled by `mergeStatus.canMerge`, merge is irreversible and re-validated on the remote.
+- **Post-action reconciliation (write actions don't settle synchronously)**: a merge / review verdict returns as soon as the remote *accepts* it, while the state the UI reads is recomputed asynchronously and lands seconds later — a merged PR keeps reporting `open` and keeps appearing in the discovery list, and `mergeStatus.canMerge` (a server-side verdict over approvals / builds / branch protection) still holds its pre-verdict value. A refresh fired the instant the action returns therefore reads pre-action state and looks like nothing happened, while leaving it to the periodic poll costs a whole interval. Both actions consequently start a **backoff re-check** in main (`services/pr-post-action.ts`): refresh that one PR on a growing delay until the expected change appears, then broadcast `prs:changed` for the renderer to reload. A confirmed merge additionally **archives that one PR** (`Poller.archivePullRequest`) — the list filters on `archivedAt`, not on PR state, so a merged PR disappears only once archived, and running a whole poll tick for it would put every connection's discovery fetch in front of the departure the user is waiting on. The departure a poll infers from absence is already established here by the confirmed remote state, so it is asserted directly. The loop is fire-and-forget (the action's IPC never waits on the remote settling) and bounded (past its window the periodic poll is the backstop). It lives in main so every entry point is covered by one implementation — the buttons, the chat commands, and the CLI's review write actions all route through the same controllers.
 - **Token usage lands on the run**: the main process captures the subprocess stderr's `@@MEEBOX_USAGE@@` sentinel line by line and accumulates it (see [pr-agent runtime](../02-agent/05-pragent-runtime.md)), writing to `ReviewRun.tokenUsage`; the UI run meta shows ↑input / ↓output.
 - **LLM-failure detection**: pr-agent may exit 0 while stdout is actually a full LLM failure (auth error / no available model) → the parse layer marks llmFailure and lands failed rather than "completed".
 
diff --git a/packages/ipc/src/events.ts b/packages/ipc/src/events.ts
index b7ad9ada..c4c63947 100644
--- a/packages/ipc/src/events.ts
+++ b/packages/ipc/src/events.ts
@@ -39,6 +39,13 @@ export interface IpcEvents {
   'findingClosures:changed': { localId: string };
   /** Broadcast after a comment reply / status change; renderer components (CommentsPanel / DiffView inline) refetch */
   'comments:changed': { localId: string };
+  /**
+   * A PR's stored state changed outside a poll tick, and the renderer should reload the list. Emitted when a
+   * post-action re-check observes the remote settling after a write action — a merge actually landing (the PR has by
+   * then been archived out of the list), or a review verdict flipping the remote's mergeable verdict (the merge button
+   * appears / disappears). Without it those changes would surface only on the next periodic poll.
+   */
+  'prs:changed': { localId: string };
   /**
    * Queue change broadcast: triggered by active add/remove or waiting add/remove. Renderer syncs the
    * chat-pane running UI + StatusBar queue chip. `active` is the list of currently concurrent running runs
diff --git a/packages/poller/src/poller.ts b/packages/poller/src/poller.ts
index dc582bd7..48358509 100644
--- a/packages/poller/src/poller.ts
+++ b/packages/poller/src/poller.ts
@@ -146,6 +146,32 @@ export class Poller {
     }
   }
 
+  /**
+   * Archive one PR by localId (same soft-delete move as a poll round's departure path: relocate the tree into cold
+   * storage, then mark archivedAt), returning whether anything changed. A no-op when the PR is unknown or already archived.
+   *
+   * Exists so a **confirmed departure** can take effect immediately instead of riding on a full poll round. The
+   * departure a poll infers from absence — "not seen this round" — is the same conclusion a caller can reach directly by
+   * observing the remote state (a merge that has landed), and there the whole-round cost is pure latency: a tick fetches
+   * every connection's discovery lists before the one PR the user just acted on can leave the list.
+   *
+   * Like archiveConnectionsExcept, this is driven by an explicit fact rather than by a failure to see the PR, so it does
+   * not weaken the "one network blip must not wrongly delete the store" invariant.
+   */
+  async archivePullRequest(localId: string): Promise<boolean> {
+    const indexFile = await readPrIndex(this.opts.stateStore);
+    const entry = indexFile?.prs[localId];
+    if (!indexFile || !entry || entry.archivedAt) return false;
+    const now = (this.opts.now?.() ?? new Date()).toISOString();
+    // Move the whole tree into archive cold storage, then mark archivedAt (migration precedes index persistence; a crash can idempotently retry).
+    await relocateTree(this.opts.stateStore, this.opts.archiveStore, prDirKey(localId));
+    await writePrIndex(this.opts.stateStore, {
+      schema_version: 1,
+      prs: { ...indexFile.prs, [localId]: { ...entry, archivedAt: now } },
+    });
+    return true;
+  }
+
   /**
    * Hot-swap the poll interval (seconds). While running, rebuild the timer on the new period (does not tick immediately);
    * the new interval takes effect from the next trigger. Called after the settings page changes the poll interval, no restart needed.
diff --git a/packages/poller/tests/poller.test.ts b/packages/poller/tests/poller.test.ts
index 0856aa05..02eaeeb9 100644
--- a/packages/poller/tests/poller.test.ts
+++ b/packages/poller/tests/poller.test.ts
@@ -404,6 +404,33 @@ describe('Poller.tick', () => {
     expect(stored[0]!.remoteId).toBe('1');
   });
 
+  it('archivePullRequest: departs one PR immediately, without a poll round', async () => {
+    const adapter = new FakeAdapter([
+      makePr('1', '2026-05-28T01:00:00.000Z'),
+      makePr('2', '2026-05-28T02:00:00.000Z'),
+    ]);
+    const poller = new Poller({
+      connections: [{ connectionId: 'bb1', adapter }],
+      stateStore: store,
+      archiveStore,
+      intervalSeconds: 60,
+      logger: noopLogger,
+    });
+    await poller.tick();
+    const merged = (await listStoredPullRequests(store)).find((p) => p.remoteId === '2')!;
+
+    // The remote still lists both (a just-merged PR lingers in the discovery list), so a tick would not drop it —
+    // archiving by localId is what makes it leave now.
+    expect(await poller.archivePullRequest(merged.localId)).toBe(true);
+    const stored = await listStoredPullRequests(store);
+    expect(stored).toHaveLength(1);
+    expect(stored[0]!.remoteId).toBe('1');
+
+    // Idempotent: already archived, and an unknown localId is a no-op rather than an error.
+    expect(await poller.archivePullRequest(merged.localId)).toBe(false);
+    expect(await poller.archivePullRequest('no-such-pr')).toBe(false);
+  });
+
   it('all connections fail in one tick: index file mtime untouched + state intact', async () => {
     // first a successful poll to lay down the baseline
     const ok1 = makePr('1', '2026-05-28T01:00:00.000Z');

From 45ca431680b1f5156282c87bb469a83879d343e7 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Mon, 7 Sep 2026 21:21:29 +0800
Subject: [PATCH 05/17] fix(gui): never leave the window blank on a renderer
 failure

A renderer failure could leave the window on its bare background permanently,
indistinguishable from a hung app and unrecoverable short of a restart, because
nothing was watching at any level: main.tsx rendered <App/> with no boundary
above it, so any error thrown while rendering unmounted the whole tree and
emptied #root; main registered no webContents listeners, so a dead renderer
process went unnoticed; and no crash of either kind reached meebox.log, which is
why such a report leaves nothing behind to diagnose.

Three layers, each covering what the others structurally cannot see:

- render-phase errors -> a root ErrorBoundary with a full-window AppCrashScreen
  (retry / reload), and the boundary now relays the stack via log:write, since
  the renderer console is not written to file and a caught render error is not
  an uncaught window error either;
- failures before React mounts -> boot-guard.ts, imported first so it is armed
  before any other module can throw. A module failing while it initializes takes
  down the entry before render() runs, leaving no React and thus no boundary; the
  guard paints a plain-DOM recovery screen, depending on no React, i18n or
  stylesheet, since each is a candidate cause;
- renderer process death -> render-process-gone / did-fail-load in main, logged
  and reloaded with a bounded retry budget so a page that dies on load cannot
  spin in a reload loop. 'unresponsive' is logged but not recovered: it usually
  resolves on its own and reloading would discard in-flight state.

Also fixes a race in the same family: mergeSelectedPr compared the selection
against the selectedId its callback had closed over, so selecting another PR
while the merge round-trip was in flight cleared the PR the user had just opened.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +
 CHANGELOG.zh-CN.md                            |  2 +
 .../src/main/bootstrap/window-manager.ts      | 61 ++++++++++++++
 apps/desktop/src/renderer/src/App.scss        |  1 +
 apps/desktop/src/renderer/src/boot-guard.ts   | 84 +++++++++++++++++++
 .../src/components/common/AppCrashScreen.tsx  | 32 +++++++
 .../src/components/common/ErrorBoundary.tsx   | 18 ++--
 .../renderer/src/components/common/index.ts   |  1 +
 .../features/pr/hooks/usePullRequests.ts      |  8 +-
 .../src/renderer/src/i18n/locales/de-DE.json  | 12 ++-
 .../src/renderer/src/i18n/locales/en-US.json  | 12 ++-
 .../src/renderer/src/i18n/locales/ja-JP.json  | 12 ++-
 .../src/renderer/src/i18n/locales/zh-CN.json  | 12 ++-
 apps/desktop/src/renderer/src/main.tsx        | 15 +++-
 .../src/renderer/src/styles/common/crash.scss | 58 +++++++++++++
 docs/arch/03-gui/01-ui-interaction.md         |  4 +
 16 files changed, 318 insertions(+), 16 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/boot-guard.ts
 create mode 100644 apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
 create mode 100644 apps/desktop/src/renderer/src/styles/common/crash.scss

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e5798ef1..1fcfc80a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,8 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 - A local CLI provider that exits successfully but returns an empty reply is now reported as a failure naming that cause, rather than as an unexplained LLM failure.
 - A merged PR now leaves the list on its own shortly after you merge it, instead of lingering until the next periodic sync — the remote takes a few seconds to actually mark it merged, and the app now waits for that rather than refreshing too early and finding nothing changed.
 - Approving a PR now updates whether it can be merged, so the merge button appears as soon as your approval satisfies the last requirement — previously it stayed hidden until the next periodic sync, because the remote recomputes mergeability only after the approval returns.
+- The window no longer goes permanently black when the interface fails: a crash now shows what went wrong with a retry / reload, a failure during startup shows a recovery screen, and a renderer that dies outright is reloaded automatically. Crash details are also written to the application log, which they previously never were.
+- Switching to another PR while a merge is still in flight no longer clears the PR you just opened.
 
 ## [0.11.2] - 2026-07-28
 
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index d41aafa9..cba14dd4 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -17,6 +17,8 @@
 - 本地 CLI 供应商正常退出却返回空回复时，现在会作为失败上报并指明该原因，而不再表现为一次无从解释的 LLM 调用失败。
 - 合并 PR 后，该 PR 会在稍后自动从列表中消失，而不再滞留到下一次周期同步——远端需要几秒才真正标记为已合并，应用现在会等待这一刻，而不是过早刷新、结果什么都没变。
 - 批准 PR 后会重新判断其是否可合并，当你的批准满足最后一项要求时合并按钮即刻出现——此前它会一直隐藏到下一次周期同步，因为远端要在批准返回之后才重新计算可合并性。
+- 界面出错时窗口不再永久黑屏：渲染崩溃会显示出错内容并提供重试／重新加载，启动阶段失败会显示恢复界面，渲染进程整个崩溃则自动重新加载。崩溃详情同时写入应用日志——此前从不记录。
+- 合并请求仍在进行时切换到其他 PR，不再清空你刚打开的那个 PR。
 
 ## [0.11.2] - 2026-07-28
 
diff --git a/apps/desktop/src/main/bootstrap/window-manager.ts b/apps/desktop/src/main/bootstrap/window-manager.ts
index 3cbb56da..f1d94c6c 100644
--- a/apps/desktop/src/main/bootstrap/window-manager.ts
+++ b/apps/desktop/src/main/bootstrap/window-manager.ts
@@ -18,6 +18,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_SIZE = { width: 1280, height: 800 };
 const MIN_SIZE = { width: 960, height: 600 };
 
+/**
+ * How many times a window may auto-reload after a renderer crash / load failure before giving up. Bounded so a page
+ * that dies on load can't spin in a reload loop; the counter resets on any successful load (see installCrashRecovery).
+ */
+const MAX_CRASH_RELOADS = 3;
+
 // Colors of the system window-control buttons on the right of the self-drawn title bar (Windows
 // titleBarOverlay): same color as the .app-titlebar background (--bg-app), so the seam is invisible;
 // the symbol takes the primary text color. Dark/light sets, following the effective theme
@@ -204,12 +210,67 @@ export class WindowManager {
       return { action: 'deny' };
     });
 
+    this.installCrashRecovery(win);
+
     if (process.env.ELECTRON_RENDERER_URL) {
       void win.loadURL(process.env.ELECTRON_RENDERER_URL);
     } else {
       void win.loadFile(path.join(__dirname, '../renderer/index.html'));
     }
   }
+
+  /**
+   * Recover the window from renderer-level failures that the React error boundary cannot see.
+   *
+   * A boundary only catches errors thrown while rendering; if the renderer **process** dies (OOM, GPU fault, a native
+   * crash inside Monaco) or the document fails to load, no JavaScript survives to report it — the window is simply left
+   * showing its background colour, permanently, since nothing was watching. These listeners are that watcher: log what
+   * happened (the only record there would otherwise be) and reload the window so the user gets a working UI back
+   * instead of a dead frame.
+   *
+   * Reloads are capped: a page that crashes on load would otherwise reload forever, burning CPU and hiding the fault.
+   * After the cap the window is left as-is with an error in the log, and the user can restart the app.
+   */
+  private installCrashRecovery(win: BrowserWindow): void {
+    let reloads = 0;
+    const reload = (reason: string): void => {
+      if (win.isDestroyed()) return;
+      if (reloads >= MAX_CRASH_RELOADS) {
+        this.logger.error(
+          { reason, reloads },
+          'renderer failed repeatedly; not reloading again (restart the app)',
+        );
+        return;
+      }
+      reloads += 1;
+      this.logger.warn({ reason, attempt: reloads }, 'reloading the renderer to recover');
+      win.webContents.reload();
+    };
+    // A successful load means the previous failure (if any) is behind us; reset the budget so an unrelated crash
+    // hours later still gets its full set of retries.
+    win.webContents.on('did-finish-load', () => {
+      reloads = 0;
+    });
+    win.webContents.on('render-process-gone', (_evt, details) => {
+      this.logger.error({ details }, 'renderer process gone');
+      // 'clean-exit' is a normal teardown (window closing), not a crash to recover from.
+      if (details.reason !== 'clean-exit') reload(`render-process-gone:${details.reason}`);
+    });
+    win.webContents.on('did-fail-load', (_evt, errorCode, errorDescription, validatedURL) => {
+      // -3 is ERR_ABORTED, which a superseded navigation raises normally; nothing failed for the user.
+      if (errorCode === -3) return;
+      this.logger.error({ errorCode, errorDescription, validatedURL }, 'renderer failed to load');
+      reload(`did-fail-load:${errorCode}`);
+    });
+    // Not recovered automatically: an unresponsive renderer is usually a long synchronous task that finishes on its
+    // own, and reloading would throw away the user's in-flight state. Logged so a hang leaves a trace.
+    win.webContents.on('unresponsive', () => {
+      this.logger.warn('renderer became unresponsive');
+    });
+    win.webContents.on('responsive', () => {
+      this.logger.info('renderer became responsive again');
+    });
+  }
 }
 
 /** Loads the window state (missing/corrupt → empty object, falling back to default size) and constructs the WindowManager. */
diff --git a/apps/desktop/src/renderer/src/App.scss b/apps/desktop/src/renderer/src/App.scss
index 801115a7..b8dc3f11 100644
--- a/apps/desktop/src/renderer/src/App.scss
+++ b/apps/desktop/src/renderer/src/App.scss
@@ -29,6 +29,7 @@
 @use './styles/features/pr-info';
 @use './styles/features/chat';
 @use './styles/features/drafts-panel';
+@use './styles/common/crash';
 @use './styles/common/modal';
 @use './styles/features/pr'; // pr 簇（含 publish-review，须在 common/modal 之后）
 @use './styles/features/settings/forms';
diff --git a/apps/desktop/src/renderer/src/boot-guard.ts b/apps/desktop/src/renderer/src/boot-guard.ts
new file mode 100644
index 00000000..26c3d435
--- /dev/null
+++ b/apps/desktop/src/renderer/src/boot-guard.ts
@@ -0,0 +1,84 @@
+/**
+ * Last-resort guard against a blank window, sitting below React entirely.
+ *
+ * The root ErrorBoundary covers errors thrown *while rendering*, and main covers the renderer process dying. Between
+ * those two lies a gap neither can see: a module that throws while it initializes — i18n, theme, the app bundle itself
+ * — takes down the entry module before `createRoot().render()` ever runs. No React means no boundary; the window just
+ * stays on its background colour forever, which is the black screen users report and cannot recover from.
+ *
+ * So this module (imported first, so its side effect is armed before anything else can throw) watches for `#root`
+ * staying empty and paints a plain-DOM recovery screen if it does. No React, no i18n, no stylesheet — every one of
+ * those is a thing that could be the failure being reported, so the screen depends on none of them.
+ */
+
+/** How long to wait for React's first commit before assuming boot failed. Generous: a cold start on a slow machine
+ * pulls a sizable bundle, and a false positive would replace a working (if slow) boot with an error screen. */
+const BOOT_TIMEOUT_MS = 15_000;
+
+/** Fixed English copy: i18n may itself be the module that failed, and English is the app's fallback language anyway. */
+const COPY = {
+  title: 'Code Meeseeks failed to start',
+  hint: 'The interface could not be loaded. Reloading usually resolves it; if it keeps happening, the details below and the application log (meebox.log) identify the cause.',
+  reload: 'Reload',
+};
+
+function rootIsEmpty(): boolean {
+  const root = document.getElementById('root');
+  return !root || root.childElementCount === 0;
+}
+
+/** Paint the recovery screen, once — later failures must not stack copies of it on top of each other. */
+function showRecovery(detail: string): void {
+  if (document.getElementById('boot-guard-screen')) return;
+  if (!rootIsEmpty()) return; // The app did render after all; leave the working UI alone.
+  const host = document.createElement('div');
+  host.id = 'boot-guard-screen';
+  // Inline styles on purpose: the stylesheet is part of the app bundle that may have failed to load.
+  host.setAttribute(
+    'style',
+    'position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;justify-content:center;' +
+      'padding:16px;background:#1e1e1e;color:#ccc;font:13px/1.5 system-ui,sans-serif;',
+  );
+  const card = document.createElement('div');
+  card.setAttribute('style', 'max-width:560px;width:100%');
+  const title = document.createElement('h1');
+  title.setAttribute('style', 'margin:0 0 8px;font-size:15px;font-weight:600;color:#eee');
+  title.textContent = COPY.title;
+  const hint = document.createElement('p');
+  hint.setAttribute('style', 'margin:0 0 12px;color:#999');
+  hint.textContent = COPY.hint;
+  const pre = document.createElement('pre');
+  pre.setAttribute(
+    'style',
+    'margin:0 0 16px;padding:8px;max-height:220px;overflow:auto;background:#181818;' +
+      'border:1px solid #333;border-radius:4px;white-space:pre-wrap;word-break:break-word;font-size:12px;color:#999',
+  );
+  pre.textContent = detail;
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.setAttribute(
+    'style',
+    'padding:4px 12px;background:#0e639c;color:#fff;border:none;border-radius:3px;cursor:pointer;font:inherit',
+  );
+  button.textContent = COPY.reload;
+  button.addEventListener('click', () => window.location.reload());
+  card.append(title, hint, pre, button);
+  host.append(card);
+  document.body.append(host);
+}
+
+// An uncaught error while the app is still blank means boot failed — no need to wait out the timeout. Once the app has
+// rendered, the same errors are the app's own business (the root boundary and the log relay handle them), so
+// rootIsEmpty() inside showRecovery keeps this from hijacking a working window.
+window.addEventListener('error', (e: ErrorEvent) => {
+  showRecovery(e.error instanceof Error ? (e.error.stack ?? e.error.message) : e.message);
+});
+window.addEventListener('unhandledrejection', (e: PromiseRejectionEvent) => {
+  const reason: unknown = e.reason;
+  showRecovery(reason instanceof Error ? (reason.stack ?? reason.message) : String(reason));
+});
+
+// Backstop for a silent failure — a module that never resolves, an import that hangs — where nothing throws at all.
+setTimeout(() => {
+  showRecovery(`The interface did not render within ${BOOT_TIMEOUT_MS / 1000}s of startup.`);
+}, BOOT_TIMEOUT_MS);
diff --git a/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx b/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
new file mode 100644
index 00000000..087edb2d
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
@@ -0,0 +1,32 @@
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Full-window fallback for a crash in the app's root subtree.
+ *
+ * Without a boundary at the root, any error thrown while rendering unmounts the whole tree and leaves an empty `#root`
+ * — which reads as a permanently black window, with no way back short of restarting the app. This screen is what the
+ * user gets instead: what broke, and two ways out.
+ *
+ * `onRetry` re-renders the subtree, which is enough when the crash came from transient state (a stale record read
+ * during an in-flight update); reloading rebuilds the renderer from scratch and is the way out when it did not.
+ */
+export function AppCrashScreen({ err, onRetry }: { err: Error; onRetry: () => void }) {
+  const { t } = useTranslation();
+  return (
+    <div className="app-crash" role="alert">
+      <div className="app-crash-card">
+        <h1 className="app-crash-title">{t('crash.title')}</h1>
+        <p className="app-crash-hint">{t('crash.hint')}</p>
+        <pre className="app-crash-detail">{err.message || String(err)}</pre>
+        <div className="app-crash-actions">
+          <button type="button" className="btn btn-primary" onClick={onRetry}>
+            {t('crash.retry')}
+          </button>
+          <button type="button" className="btn" onClick={() => window.location.reload()}>
+            {t('crash.reload')}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/common/ErrorBoundary.tsx b/apps/desktop/src/renderer/src/components/common/ErrorBoundary.tsx
index 9488882e..956756ce 100644
--- a/apps/desktop/src/renderer/src/components/common/ErrorBoundary.tsx
+++ b/apps/desktop/src/renderer/src/components/common/ErrorBoundary.tsx
@@ -1,4 +1,5 @@
 import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { invoke } from '../../api';
 
 interface ErrorBoundaryProps {
   children: ReactNode;
@@ -27,11 +28,18 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
   }
 
   override componentDidCatch(err: Error, info: ErrorInfo): void {
-    console.error(
-      `[ErrorBoundary${this.props.label ? `:${this.props.label}` : ''}] caught:`,
-      err,
-      info.componentStack,
-    );
+    const label = this.props.label ? `:${this.props.label}` : '';
+    console.error(`[ErrorBoundary${label}] caught:`, err, info.componentStack);
+    // Also relay to main so the crash lands in meebox.log: the renderer console is not written to file, and a render
+    // error is not an uncaught window error either, so without this a caught crash leaves no trace on disk — which is
+    // exactly what makes such a report impossible to diagnose after the fact.
+    void invoke('log:write', {
+      level: 'error',
+      msg: `renderer render error${label}: ${err.message}`,
+      meta: { stack: err.stack, componentStack: info.componentStack ?? undefined },
+    }).catch(() => {
+      /* the log relay must never be the thing that breaks the fallback UI */
+    });
   }
 
   reset = (): void => {
diff --git a/apps/desktop/src/renderer/src/components/common/index.ts b/apps/desktop/src/renderer/src/components/common/index.ts
index d49478f4..781175ee 100644
--- a/apps/desktop/src/renderer/src/components/common/index.ts
+++ b/apps/desktop/src/renderer/src/components/common/index.ts
@@ -2,6 +2,7 @@
 // Cross-domain consumers (features/* · layout/* · App etc.) import via this barrel; common's internal modules reference each other
 // (markdownMermaid → MermaidDiagram, Modal → icons, ConfirmModal → Modal) via relative paths,
 // not through this barrel, to avoid circular dependencies.
+export * from './AppCrashScreen';
 export * from './Avatar';
 export * from './BitbucketImage';
 export * from './ConfirmModal';
diff --git a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
index 34a90ef2..1cde9875 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
+++ b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
@@ -121,9 +121,13 @@ export function usePullRequests({ notifyError }: { notifyError: (msg: string) =>
     // connection only to redraw the same list, with the PR still in it. Main confirms the merge landed and archives the
     // PR (see services/pr-post-action.ts), then broadcasts prs:changed; the local reload below just reflects whatever is
     // already on disk in the meantime.
-    if (selectedId === mergedId) setSelectedId(null);
+    //
+    // Compare against the **current** selection, not the `selectedId` this callback closed over: a merge is a remote
+    // round-trip, and clicking another PR while it is in flight leaves the closure holding the pre-merge id. Testing
+    // that stale value would clear a selection the user has since made, blanking the PR they just opened.
+    setSelectedId((cur) => (cur === mergedId ? null : cur));
     await reloadPrs();
-  }, [selected, selectedId, reloadPrs, triggerRefresh, notifyError, merging, t]);
+  }, [selected, reloadPrs, setSelectedId, triggerRefresh, notifyError, merging, t]);
 
   return {
     prs,
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index 47f5e205..b0cf0dcc 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -325,6 +325,12 @@
     "testing": "Teste…",
     "tokenLabel": "Zugriffstoken (PAT)"
   },
+  "crash": {
+    "hint": "Ein Neuladen behebt das in der Regel. Tritt es wiederholt auf, benennen die Details unten und das Anwendungsprotokoll (meebox.log) die Ursache.",
+    "reload": "Neu laden",
+    "retry": "Erneut versuchen",
+    "title": "Beim Rendern der Oberfläche ist ein Fehler aufgetreten"
+  },
   "diffSearchPanel": {
     "caseSensitiveOff": "Groß-/Kleinschreibung beachten (aus)",
     "caseSensitiveOn": "Groß-/Kleinschreibung beachten (ein)",
@@ -344,9 +350,11 @@
     "binaryNotRendered": "⚠️ Binärdatei, Diff wird nicht dargestellt",
     "blameChangeRangeTitle": "Dieser Bereich wurde durch diesen PR geändert",
     "blameFailed": "blame fehlgeschlagen",
-    "blameFailedNamed": "blame für {{path}} fehlgeschlagen",    "diffRenderFailed": "Diff-Darstellung fehlgeschlagen: {{message}}",
+    "blameFailedNamed": "blame für {{path}} fehlgeschlagen",
+    "diffRenderFailed": "Diff-Darstellung fehlgeschlagen: {{message}}",
     "diffRenderFailedHint": "Ein Dateiwechsel oder erneuter Versuch behebt das Problem meist. Der zugrunde liegende Fehler wurde in der console protokolliert.",
-    "dismissNotificationTitle": "Diese Benachrichtigung schließen",    "fileCount_one": "{{count}} Datei",
+    "dismissNotificationTitle": "Diese Benachrichtigung schließen",
+    "fileCount_one": "{{count}} Datei",
     "fileCount_other": "{{count}} Dateien",
     "lfsManagedTitle": "Von Git LFS verwaltet",
     "loadChangedFilesFailed": "Geänderte Dateien konnten nicht geladen werden",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index 45fbae10..de7892f1 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -325,6 +325,12 @@
     "testing": "Testing…",
     "tokenLabel": "Access Token (PAT)"
   },
+  "crash": {
+    "hint": "Reloading usually resolves it. If it keeps happening, the details below and the application log (meebox.log) identify the cause.",
+    "reload": "Reload",
+    "retry": "Retry",
+    "title": "Something went wrong rendering the interface"
+  },
   "diffSearchPanel": {
     "caseSensitiveOff": "Case sensitive (off)",
     "caseSensitiveOn": "Case sensitive (on)",
@@ -344,9 +350,11 @@
     "binaryNotRendered": "⚠️ Binary file, diff not rendered",
     "blameChangeRangeTitle": "This range was changed by this PR",
     "blameFailed": "Blame failed",
-    "blameFailedNamed": "Blame failed for {{path}}",    "diffRenderFailed": "Diff render failed: {{message}}",
+    "blameFailedNamed": "Blame failed for {{path}}",
+    "diffRenderFailed": "Diff render failed: {{message}}",
     "diffRenderFailedHint": "Switching files or retrying usually recovers. The underlying error has been logged to the console.",
-    "dismissNotificationTitle": "Dismiss this notification",    "fileCount_one": "{{count}} file",
+    "dismissNotificationTitle": "Dismiss this notification",
+    "fileCount_one": "{{count}} file",
     "fileCount_other": "{{count}} files",
     "lfsManagedTitle": "Managed by Git LFS",
     "loadChangedFilesFailed": "Failed to load changed files",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index 2929031a..a333b9a8 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -319,6 +319,12 @@
     "testing": "テスト中…",
     "tokenLabel": "アクセストークン (PAT)"
   },
+  "crash": {
+    "hint": "再読み込みで通常は復旧します。繰り返し発生する場合は、以下の詳細とアプリケーションログ（meebox.log）で原因を特定できます。",
+    "reload": "再読み込み",
+    "retry": "再試行",
+    "title": "画面の描画中にエラーが発生しました"
+  },
   "diffSearchPanel": {
     "caseSensitiveOff": "大文字小文字を区別 (オフ)",
     "caseSensitiveOn": "大文字小文字を区別 (オン)",
@@ -337,10 +343,12 @@
     "binaryNotRendered": "⚠️ バイナリファイル、差分は表示されません",
     "blameChangeRangeTitle": "この範囲はこの PR で変更されました",
     "blameFailed": "blame に失敗しました",
-    "blameFailedNamed": "{{path}} の blame に失敗しました",    "diffRenderFailed": "差分の表示に失敗しました: {{message}}",
+    "blameFailedNamed": "{{path}} の blame に失敗しました",
+    "diffRenderFailed": "差分の表示に失敗しました: {{message}}",
     "diffRenderFailedHint": "ファイルを切り替えるか再試行すると通常は復旧します。元のエラーは console に記録されています。",
     "dismissNotificationTitle": "この通知を閉じる",
-    "fileCount_other": "{{count}} ファイル",    "lfsManagedTitle": "Git LFS で管理",
+    "fileCount_other": "{{count}} ファイル",
+    "lfsManagedTitle": "Git LFS で管理",
     "loadChangedFilesFailed": "変更ファイルの読み込みに失敗しました",
     "loadCommentsFailed": "コメントの読み込みに失敗しました",
     "loadingContentHint": "ローカルミラーから git blob を読み込んでいます。大きいファイルやバイナリファイルは時間がかかる場合があります",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index ad5bec2d..1b2860b6 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -319,6 +319,12 @@
     "testing": "测试中…",
     "tokenLabel": "访问令牌 (PAT)"
   },
+  "crash": {
+    "hint": "重新加载通常即可恢复。若反复出现，下方详情与应用日志（meebox.log）可定位原因。",
+    "reload": "重新加载",
+    "retry": "重试",
+    "title": "界面渲染出错"
+  },
   "diffSearchPanel": {
     "caseSensitiveOff": "区分大小写 (已关闭)",
     "caseSensitiveOn": "区分大小写 (已开启)",
@@ -337,10 +343,12 @@
     "binaryNotRendered": "⚠️ 二进制文件，不渲染 diff",
     "blameChangeRangeTitle": "此区段为本 PR 引入的改动",
     "blameFailed": "blame 失败",
-    "blameFailedNamed": "{{path}} blame 失败",    "diffRenderFailed": "diff 渲染失败：{{message}}",
+    "blameFailedNamed": "{{path}} blame 失败",
+    "diffRenderFailed": "diff 渲染失败：{{message}}",
     "diffRenderFailedHint": "切换文件 / 重试通常能恢复。底层异常已记录到 console。",
     "dismissNotificationTitle": "收起此通知",
-    "fileCount_other": "{{count}} 个文件",    "lfsManagedTitle": "由 Git LFS 管理",
+    "fileCount_other": "{{count}} 个文件",
+    "lfsManagedTitle": "由 Git LFS 管理",
     "loadChangedFilesFailed": "拉取变更文件列表失败",
     "loadCommentsFailed": "拉取评论失败",
     "loadingContentHint": "从本地镜像读 git blob，大文件 / 二进制判定时可能略慢",
diff --git a/apps/desktop/src/renderer/src/main.tsx b/apps/desktop/src/renderer/src/main.tsx
index 7b00c3ca..b7dc08d5 100644
--- a/apps/desktop/src/renderer/src/main.tsx
+++ b/apps/desktop/src/renderer/src/main.tsx
@@ -1,3 +1,7 @@
+// boot-guard must be the FIRST import: its side effect arms the last-resort watchdog before any other module runs, so a
+// module that throws while initializing (i18n / theme / App below) still ends with a readable screen instead of a
+// permanently blank window. Anything imported above it would be outside the guard.
+import './boot-guard';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { addCollection } from '@iconify/react';
@@ -10,6 +14,7 @@ import './i18n';
 // avoiding a light-mode user flashing a frame of dark on startup.
 import './theme';
 import App from './App';
+import { AppCrashScreen, ErrorBoundary } from './components/common';
 import './App.scss';
 
 // Preload the PKief Material Icon Theme so that <Icon icon="material-icon-theme:..." />
@@ -21,6 +26,14 @@ if (!container) throw new Error('#root not found');
 
 createRoot(container).render(
   <StrictMode>
-    <App />
+    {/* Root boundary: without one, any error thrown while rendering unmounts the entire tree and leaves an empty
+        #root — an all-black window with no way back short of restarting the app. Here the user gets what broke plus
+        a retry / reload, and the boundary relays the stack to main so the crash is on disk in meebox.log. */}
+    <ErrorBoundary
+      label="App"
+      fallback={(err, reset) => <AppCrashScreen err={err} onRetry={reset} />}
+    >
+      <App />
+    </ErrorBoundary>
   </StrictMode>,
 );
diff --git a/apps/desktop/src/renderer/src/styles/common/crash.scss b/apps/desktop/src/renderer/src/styles/common/crash.scss
new file mode 100644
index 00000000..837dfde4
--- /dev/null
+++ b/apps/desktop/src/renderer/src/styles/common/crash.scss
@@ -0,0 +1,58 @@
+// Full-window crash fallback (AppCrashScreen): what replaces the app when the root subtree fails to render.
+// Deliberately self-contained — it must stay legible even when the failure came from the very UI it is replacing.
+
+@use '../tokens' as *;
+
+.app-crash {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: $space-8;
+  background: $bg-app;
+  color: $text-body;
+  // Above everything, including a modal backdrop left behind by the tree that just crashed.
+  z-index: $z-modal + 10;
+}
+
+.app-crash-card {
+  max-width: 560px;
+  width: 100%;
+  background: $bg-elev;
+  border: 1px solid $border-default;
+  border-radius: 6px;
+  padding: $space-8;
+}
+
+.app-crash-title {
+  margin: 0 0 $space-2;
+  font-size: $fs-lg;
+  font-weight: 600;
+}
+
+.app-crash-hint {
+  margin: 0 0 $space-3;
+  color: $text-muted;
+  line-height: 1.5;
+}
+
+.app-crash-detail {
+  margin: 0 0 $space-8;
+  padding: $space-3;
+  max-height: 220px;
+  overflow: auto;
+  background: $bg-app;
+  border: 1px solid $border-default;
+  border-radius: 4px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: $font-mono;
+  font-size: $fs-xs;
+  color: $text-muted;
+}
+
+.app-crash-actions {
+  display: flex;
+  gap: $space-2;
+}
diff --git a/docs/arch/03-gui/01-ui-interaction.md b/docs/arch/03-gui/01-ui-interaction.md
index b5cb6926..ffb36453 100644
--- a/docs/arch/03-gui/01-ui-interaction.md
+++ b/docs/arch/03-gui/01-ui-interaction.md
@@ -90,6 +90,10 @@ Platform differences are decided via `AppInfo.platform` (delivered by the main p
 - **Second-level modal backdrop click only closes its own layer**: for nested modals (connection/LLM/proxy editing, confirm dialogs) the backdrop click calls `stopPropagation`,
   so it does not bubble up to close the outer settings modal (including createPortal confirm dialogs — React synthetic events still bubble along the component tree).
 - **Action-level toast vs. full-screen error**: a failed remote action (review decision/merge/publish) raises a toast, distinct from the full-screen error of a fatal bootstrap failure.
+- **Never a blank window (three layers of failure containment)**: a renderer failure must always land on a readable screen, never on the window's bare background — which is indistinguishable from a hung app and has no way back short of a restart. Each layer covers what the one below it structurally cannot see:
+  1. **Render-phase errors** → the root `ErrorBoundary` in `main.tsx` (fallback `AppCrashScreen`, offering retry / reload). Without one, any error thrown while rendering unmounts the whole tree and empties `#root`. The boundary also relays the stack through `log:write`, since the renderer console is never written to file and a caught render error is not an uncaught window error either — so a crash would otherwise leave nothing on disk to diagnose.
+  2. **Failures before React mounts** → `boot-guard.ts`, imported **first** in `main.tsx` so it is armed before any other module can throw. A module that fails while initializing (i18n / theme / the app bundle) takes down the entry before `render()` runs, leaving no React and therefore no boundary. The guard paints a plain-DOM recovery screen — no React, no i18n, no stylesheet, since each of those is a candidate cause — on an uncaught error or when `#root` is still empty after a timeout.
+  3. **Renderer process death** → `WindowManager.installCrashRecovery` in main (`render-process-gone` / `did-fail-load`), which logs and reloads the window with a bounded retry budget. When the process itself dies (OOM, GPU fault, a native crash), no in-page JavaScript survives to report it; only main is left watching. `unresponsive` is logged but deliberately not recovered — it usually resolves on its own, and reloading would discard the user's in-flight state.
 - **Auto-refresh on window focus**: when the window regains focus, proactively fetch PR meta once (to follow the "switch to the platform, make edits, then switch back" scenario).
 - **Layout preferences persisted**: sidebar/chat width and collapse state, diff view mode, etc. are stored in localStorage.
 

From 1facdc88f9ce958e2e4b682864bad015e391ede8 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 11:15:46 +0800
Subject: [PATCH 06/17] feat(proxy): let hosts bypass the proxy via a
 configurable no_proxy list

The proxy is a single global egress, but part of what the app reaches commonly
lives inside the network the proxy leads out of -- a self-hosted code platform,
its git remote, an internal model server. Routing those through the proxy wastes
a hop at best and makes them unreachable at worst, and turning the proxy off is
not a fix, since the LLM egress still needs it. Only loopback was bypassed, and
only as built-in behaviour, so there was no way to express any of this.

Settings now take a bypass list, applying to every outbound path at once: the
platform REST fetch, git over HTTPS, pr-agent and the local CLIs.

The syntax mirrors the conventional NO_PROXY on purpose. The subprocess egresses
are handed these rules as the environment variable and interpret them with their
own libraries -- the app does not get to decide how git matches a host -- so any
richer syntax would apply in-process and not in the subprocess, making the same
config bypass on one egress while proxying on the other. Hence the portable
subset (domain plus subdomains, IP literal, `*`, case-insensitive, port ignored)
and the deliberate exclusion of CIDR ranges, which only some implementations
honour. Matching lives in shared/no-proxy.ts, used by both paths so they cannot
drift apart, and loopback is prepended to whatever the user configured: a local
service must never be proxied, and that guarantee should not depend on the user
having typed it.

Normalization happens in the setProxy controller rather than the form, so the
value stored is canonical however the config arrived, and what the user reads
back is what is actually matched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   1 +
 CHANGELOG.zh-CN.md                            |   1 +
 apps/desktop/src/main/controllers/config.ts   |  12 ++-
 apps/desktop/src/main/utils/proxy.ts          |  44 +++++---
 .../settings/editors/ProxyEditorModal.tsx     |  18 ++++
 .../settings/sections/ProxySection.tsx        |  10 +-
 .../src/renderer/src/i18n/locales/de-DE.json  |   6 ++
 .../src/renderer/src/i18n/locales/en-US.json  |   6 ++
 .../src/renderer/src/i18n/locales/ja-JP.json  |   5 +
 .../src/renderer/src/i18n/locales/zh-CN.json  |   5 +
 docs/arch/99-core/03-networking-proxy.md      |  19 ++--
 docs/guide/03-proxy.md                        |  20 +++-
 docs/guide/04-config-reference.md             |   4 +-
 docs/guide/zh-CN/03-proxy.md                  |  20 +++-
 docs/guide/zh-CN/04-config-reference.md       |   4 +-
 packages/shared/src/config.ts                 |   7 +-
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/no-proxy.ts               |  67 ++++++++++++
 packages/shared/tests/no-proxy.test.ts        | 101 ++++++++++++++++++
 19 files changed, 321 insertions(+), 30 deletions(-)
 create mode 100644 packages/shared/src/no-proxy.ts
 create mode 100644 packages/shared/tests/no-proxy.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fcfc80a..b0c47941 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
+- Proxy settings now take a list of **direct connections**: hosts that bypass the proxy and connect straight out, so an internal code platform, its git remote, or a self-hosted model stays reachable while everything else still goes through the proxy. Uses the familiar `NO_PROXY` syntax (a domain covers its subdomains), and applies to every outbound path at once — REST, git and the LLM call.
 - A review that fails because the model is unavailable now says so and tells you what to do — with a local CLI provider (claude / codex) the model comes from that CLI's own configuration, so it has to be changed there.
 
 ### 🔧 Fixed
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index cba14dd4..22781768 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,6 +9,7 @@
 
 ### ✨ 新增
 
+- 代理设置新增**直连地址**列表：列出的地址跳过代理直接连接，内网代码平台、它的 git 远端或自建模型服务因此保持可达，其余流量照常走代理。沿用通行的 `NO_PROXY` 写法（填域名同时覆盖子域），并对所有出站路径一并生效——REST、git 与 LLM 调用。
 - 因模型不可用而失败的评审现在会明确说明，并给出处理方式——使用本地 CLI 供应商（claude / codex）时，模型来自该 CLI 自身的配置，需要在那里更换。
 
 ### 🔧 修复
diff --git a/apps/desktop/src/main/controllers/config.ts b/apps/desktop/src/main/controllers/config.ts
index 54f9da13..9e9fc30c 100644
--- a/apps/desktop/src/main/controllers/config.ts
+++ b/apps/desktop/src/main/controllers/config.ts
@@ -1,6 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import { nativeTheme } from 'electron';
-import { editorThemeNativeSource } from '@meebox/shared';
+import { editorThemeNativeSource, normalizeNoProxy } from '@meebox/shared';
 import { writeConfig } from '@meebox/config';
 import { buildDraftAdapter } from '../adapters.js';
 import { setMainLanguage } from '../i18n/index.js';
@@ -156,12 +156,16 @@ export const setConnections: IpcController<'config:setConnections'> = async (_ev
  */
 export const setProxy: IpcController<'config:setProxy'> = async (_event, req) => {
   const { bootstrap, logger, reconfigureConnections } = getContext();
-  const next = { ...bootstrap.config, proxy: req.proxy };
+  // Normalize the bypass list on the way in, not in the form: whichever way the config arrives — this IPC, or a
+  // hand-edited config.yaml — what lands on disk is one canonical comma-separated line, so the value the user reads
+  // back is the value actually matched against.
+  const proxy = { ...req.proxy, no_proxy: normalizeNoProxy(req.proxy.no_proxy) };
+  const next = { ...bootstrap.config, proxy };
   await writeConfig(bootstrap.paths.configFile, next);
-  bootstrap.config.proxy = req.proxy;
+  bootstrap.config.proxy = proxy;
   await reconfigureConnections();
   logger.info(
-    { enabled: req.proxy.enabled, host: req.proxy.host, port: req.proxy.port },
+    { enabled: proxy.enabled, host: proxy.host, port: proxy.port, noProxy: proxy.no_proxy },
     'proxy config updated (hot-reloaded)',
   );
 };
diff --git a/apps/desktop/src/main/utils/proxy.ts b/apps/desktop/src/main/utils/proxy.ts
index d28e8c69..194298dd 100644
--- a/apps/desktop/src/main/utils/proxy.ts
+++ b/apps/desktop/src/main/utils/proxy.ts
@@ -4,15 +4,33 @@
 //   - shouldBypass: whether loopback/local goes direct (② decides at the call site whether to attach a dispatcher)
 // Phase one is HTTP proxy only; when enabled=false all forms yield "empty/direct connection", so call sites need not each check the switch.
 import { ProxyAgent, type Dispatcher } from 'undici';
-import { ERROR_CODES, errorCodeMessage, type ProxyConfig } from '@meebox/shared';
+import {
+  ERROR_CODES,
+  LOOPBACK_NO_PROXY,
+  errorCodeMessage,
+  matchesNoProxy,
+  normalizeNoProxy,
+  type ProxyConfig,
+} from '@meebox/shared';
 
-// loopback / local: always direct connection, never through the proxy. The env path relies on NO_PROXY, the dispatcher path on shouldBypass.
-const NO_PROXY = 'localhost,127.0.0.1,::1';
+/**
+ * Effective bypass rules = the built-in loopback set + whatever the user configured. Loopback is prepended rather than
+ * left to the user: a local model or local service must never be sent through a proxy, and that guarantee should not
+ * depend on the user having typed it.
+ */
+function effectiveNoProxy(proxy: ProxyConfig): string {
+  return normalizeNoProxy(`${LOOPBACK_NO_PROXY},${proxy.no_proxy ?? ''}`);
+}
 
-/** loopback / local host → true (should go direct connection, not through the proxy). */
-export function shouldBypass(host: string): boolean {
-  const h = host.toLowerCase().replace(/^\[|\]$/g, ''); // strip IPv6 literal brackets
-  return h === 'localhost' || h.endsWith('.localhost') || h === '127.0.0.1' || h === '::1';
+/**
+ * Host should egress directly (loopback, or covered by the user's `no_proxy`) rather than through the proxy.
+ *
+ * The env path hands the same rules to subprocesses via `NO_PROXY` and lets their libraries apply them; this is the
+ * in-process equivalent for the dispatcher path, which is why both derive from `effectiveNoProxy` — the two egress
+ * classes must not disagree about the same config.
+ */
+export function shouldBypass(proxy: ProxyConfig, host: string): boolean {
+  return matchesNoProxy(host, effectiveNoProxy(proxy));
 }
 
 /** Build a standard proxy URL: `<protocol>://[user:pass@]host:port`. undefined when disabled / no host. */
@@ -32,6 +50,7 @@ export function proxyUrl(proxy: ProxyConfig): string | undefined {
 export function buildProxyEnv(proxy: ProxyConfig): Record<string, string> {
   const url = proxyUrl(proxy);
   if (!url) return {};
+  const bypass = effectiveNoProxy(proxy);
   return {
     HTTP_PROXY: url,
     http_proxy: url,
@@ -39,8 +58,8 @@ export function buildProxyEnv(proxy: ProxyConfig): Record<string, string> {
     https_proxy: url,
     ALL_PROXY: url,
     all_proxy: url,
-    NO_PROXY,
-    no_proxy: NO_PROXY,
+    NO_PROXY: bypass,
+    no_proxy: bypass,
   };
 }
 
@@ -85,14 +104,15 @@ export async function testProxyConnectivity(
 
 /**
  * Build a "proxy-aware" fetch for a target host, to inject into BitbucketClient's opts.fetch.
- * host hits loopback/local → returns undefined (the call site uses the default global fetch for a direct connection).
- * Otherwise returns a fetch wrapper carrying the dispatcher. Also returns undefined when the proxy is disabled.
+ * host hits loopback/local or the configured bypass list → returns undefined (the call site uses the default global
+ * fetch for a direct connection). Otherwise returns a fetch wrapper carrying the dispatcher. Also returns undefined
+ * when the proxy is disabled.
  */
 export function proxyFetchForHost(
   proxy: ProxyConfig,
   host: string,
 ): ((input: string, init?: RequestInit) => Promise<Response>) | undefined {
-  if (shouldBypass(host)) return undefined;
+  if (shouldBypass(proxy, host)) return undefined;
   const dispatcher = buildProxyDispatcher(proxy);
   if (!dispatcher) return undefined;
   return (input, init) =>
diff --git a/apps/desktop/src/renderer/src/components/features/settings/editors/ProxyEditorModal.tsx b/apps/desktop/src/renderer/src/components/features/settings/editors/ProxyEditorModal.tsx
index d32a5b04..1cda4ea2 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/editors/ProxyEditorModal.tsx
+++ b/apps/desktop/src/renderer/src/components/features/settings/editors/ProxyEditorModal.tsx
@@ -109,7 +109,25 @@ export function ProxyEditorModal({
                 </button>
               </div>
             </div>
+            <div className="modal-kv-key">{t('settings.proxyNoProxy')}</div>
+            <div className="modal-kv-val">
+              {/* Multi-line on purpose: a bypass list is usually several hosts, and one per line stays readable where a
+                  single comma-separated line does not. Stored normalized to one line (see normalizeNoProxy), and the
+                  parser accepts commas / whitespace / newlines alike, so a value pasted from NO_PROXY also works. */}
+              <textarea
+                className="settings-input"
+                rows={3}
+                value={draft.no_proxy}
+                onChange={(e) => patch({ no_proxy: e.target.value })}
+                placeholder={t('settings.proxyNoProxyPlaceholder')}
+                aria-label={t('settings.proxyNoProxyAria')}
+                spellCheck={false}
+              />
+            </div>
           </div>
+          <p className="muted" style={{ margin: '6px 0 0' }}>
+            {t('settings.proxyNoProxyHint')}
+          </p>
           <div
             className="settings-edit-row"
             style={{ marginTop: 10, alignItems: 'center', gap: 10 }}
diff --git a/apps/desktop/src/renderer/src/components/features/settings/sections/ProxySection.tsx b/apps/desktop/src/renderer/src/components/features/settings/sections/ProxySection.tsx
index 734ab1be..6f05bed1 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/sections/ProxySection.tsx
+++ b/apps/desktop/src/renderer/src/components/features/settings/sections/ProxySection.tsx
@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import type { Config } from '@meebox/shared';
+import { parseNoProxy, type Config } from '@meebox/shared';
 
 export function ProxySection({
   proxy,
@@ -10,6 +10,7 @@ export function ProxySection({
 }) {
   const { t } = useTranslation();
   const on = proxy.enabled && !!proxy.host;
+  const bypassCount = parseNoProxy(proxy.no_proxy).length;
   return (
     <section className="modal-section">
       <div className="modal-section-head">
@@ -28,6 +29,13 @@ export function ProxySection({
       <p className="muted" style={{ margin: 0 }}>
         {t('settings.proxyStatusHint')}
       </p>
+      {/* Surface that bypass rules are in force: when a host unexpectedly does (or does not) go through the proxy, the
+          rule list is the first thing to check, and it would otherwise be hidden inside the dialog. */}
+      {on && bypassCount > 0 && (
+        <p className="muted" style={{ margin: '4px 0 0' }}>
+          {t('settings.proxyNoProxySummary', { count: bypassCount })}
+        </p>
+      )}
     </section>
   );
 }
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index b0cf0dcc..e4da190c 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -848,6 +848,12 @@
     "proxyHostPlaceholder": "z. B. 127.0.0.1",
     "proxyHostRequired": "Bitte den Proxy-Host eingeben",
     "proxyModalHint": "HTTP-Proxy (ausgehend). Wenn aktiviert, laufen LLM-Aufrufe, Code-Plattformen und git (HTTPS) alle über den Proxy; lokale Adressen verbinden sich direkt.",
+    "proxyNoProxy": "Direktverbindungen",
+    "proxyNoProxyAria": "Hosts, die den Proxy umgehen",
+    "proxyNoProxyHint": "Hier aufgeführte Hosts verbinden sich direkt statt über den Proxy — nützlich für eine interne Code-Plattform oder ein Modell, das der Proxy nicht erreicht. Einer pro Zeile oder durch Kommas getrennt; eine Domain umfasst auch ihre Subdomains. Lokale Adressen verbinden sich immer direkt.",
+    "proxyNoProxyPlaceholder": "corp.example.com\n10.0.0.5",
+    "proxyNoProxySummary_one": "{{count}} Host umgeht den Proxy",
+    "proxyNoProxySummary_other": "{{count}} Hosts umgehen den Proxy",
     "proxyOk": "✓ Proxy ist erreichbar",
     "proxyPassword": "Passwort",
     "proxyPasswordAria": "Proxy-Passwort",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index de7892f1..3f981bd5 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -848,6 +848,12 @@
     "proxyHostPlaceholder": "e.g. 127.0.0.1",
     "proxyHostRequired": "Please enter the proxy host",
     "proxyModalHint": "HTTP proxy (outbound). When enabled, LLM calls, code platforms, and git (HTTPS) all go through the proxy; local addresses connect directly.",
+    "proxyNoProxy": "Direct connections",
+    "proxyNoProxyAria": "Hosts that bypass the proxy",
+    "proxyNoProxyHint": "Hosts listed here connect directly instead of through the proxy — useful for an internal code platform or model that the proxy cannot reach. One per line or comma-separated; a domain also covers its subdomains. Local addresses always connect directly.",
+    "proxyNoProxyPlaceholder": "corp.example.com\n10.0.0.5",
+    "proxyNoProxySummary_one": "{{count}} host bypasses the proxy",
+    "proxyNoProxySummary_other": "{{count}} hosts bypass the proxy",
     "proxyOk": "✓ Proxy is reachable",
     "proxyPassword": "Password",
     "proxyPasswordAria": "Proxy password",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index a333b9a8..71f160b1 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -831,6 +831,11 @@
     "proxyHostPlaceholder": "例：127.0.0.1",
     "proxyHostRequired": "プロキシホストを入力してください",
     "proxyModalHint": "HTTP プロキシ（送信）。有効にすると、LLM 呼び出し・コードプラットフォーム・git（HTTPS）はすべてプロキシ経由になります。ローカルアドレスは直接接続します。",
+    "proxyNoProxy": "直接接続するホスト",
+    "proxyNoProxyAria": "プロキシを経由しないホスト",
+    "proxyNoProxyHint": "ここに指定したホストはプロキシを経由せず直接接続します。プロキシから到達できない社内のコードプラットフォームやモデルに利用します。1 行に 1 つ、またはカンマ区切り。ドメインを指定するとそのサブドメインも対象になります。ローカルアドレスは常に直接接続します。",
+    "proxyNoProxyPlaceholder": "corp.example.com\n10.0.0.5",
+    "proxyNoProxySummary_other": "{{count}} 件のホストがプロキシを経由しません",
     "proxyOk": "✓ プロキシに到達可能です",
     "proxyPassword": "パスワード",
     "proxyPasswordAria": "プロキシパスワード",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index 1b2860b6..48503162 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -831,6 +831,11 @@
     "proxyHostPlaceholder": "如 127.0.0.1",
     "proxyHostRequired": "请填代理地址",
     "proxyModalHint": "HTTP 代理（出站）。开启后 LLM 调用、代码平台、git(HTTPS) 统一经代理，本地地址直连。",
+    "proxyNoProxy": "直连地址",
+    "proxyNoProxyAria": "跳过代理的地址",
+    "proxyNoProxyHint": "此处列出的地址将直连而不走代理，适用于代理无法访问的内网代码平台或模型服务。每行一条或以逗号分隔；填写域名同时覆盖其子域。本机地址始终直连。",
+    "proxyNoProxyPlaceholder": "corp.example.com\n10.0.0.5",
+    "proxyNoProxySummary_other": "{{count}} 个地址跳过代理",
     "proxyOk": "✓ 代理可用",
     "proxyPassword": "密码",
     "proxyPasswordAria": "代理密码",
diff --git a/docs/arch/99-core/03-networking-proxy.md b/docs/arch/99-core/03-networking-proxy.md
index 6bef953d..315e5bed 100644
--- a/docs/arch/99-core/03-networking-proxy.md
+++ b/docs/arch/99-core/03-networking-proxy.md
@@ -2,7 +2,7 @@
 
 ## Responsibilities & boundaries
 
-Make all **outbound network** controllable in enterprise-intranet / restricted networks: once the switch is on, everything egresses uniformly through one **HTTP proxy**; local addresses (loopback) connect directly. It covers three egress classes:
+Make all **outbound network** controllable in enterprise-intranet / restricted networks: once the switch is on, everything egresses uniformly through one **HTTP proxy**, except local addresses (loopback) and the hosts the user lists as bypassed, which connect directly. It covers three egress classes:
 
 - **LLM calls** (the LLM client embedded in pr-agent) — the primary target; without it, the whole review is unusable on an intranet.
 - **Code-platform REST** (polling / comments / avatars / attachments / merge / connection probing).
@@ -14,15 +14,17 @@ Phase one supports only an **HTTP proxy** (including Basic Auth); socks5 is not
 
 ## Core design
 
-- **A single global proxy + loopback direct connection**: switch on → all three egresses (LLM, code platform, git(HTTPS)) go through the proxy; only `localhost / 127.0.0.1 / ::1` (including a local Ollama and other local services) auto-connect directly. There is no complex "selectively proxy per host" policy — in the user's environment the proxy is the uniform egress channel, simple and consistent.
-- **Minimal config surface**: it exposes only switch / host / port / Basic Auth (username, password). The loopback bypass is built-in behavior, not exposed. The protocol field goes into config but the UI doesn't render it (currently http only), leaving room to add socks5 later — a new protocol value is non-breaking to existing configs.
+- **A single global proxy + a bypass list**: switch on → all three egresses (LLM, code platform, git(HTTPS)) go through the proxy; `localhost / 127.0.0.1 / ::1` (including a local Ollama and other local services) auto-connect directly, as does anything the user lists in `no_proxy`. Routing is still a single global decision per host — there is no per-egress or per-request policy.
+- **Why a bypass list is not optional**: the proxy is the way *out* of a network, but part of what the app reaches commonly lives *inside* it — a self-hosted code platform, its git remote, an internal model server. Sending those through the proxy wastes a hop at best and makes them unreachable at worst, and the user cannot fix that by turning the proxy off, since the LLM egress still needs it. So the bypass has to be per-host and user-controlled. Loopback stays built in and is prepended to whatever the user configured: a local service must never be proxied, and that guarantee should not depend on the user having typed it.
+- **The bypass syntax mirrors `NO_PROXY`, deliberately**: the subprocess egresses (git, pr-agent, local CLIs) are handed the rules as the `NO_PROXY` environment variable and interpret them with **their own** libraries — the app does not get to decide how git matches a host. Any syntax richer than what those libraries share would therefore apply in-process and not in the subprocess, so the same config would bypass on one egress and proxy on the other: a divergence nearly impossible to diagnose from the UI. Hence the supported subset (domain + subdomains, IP literal, `*`, case-insensitive, port ignored) and the deliberate exclusion of **CIDR ranges**, which only some implementations honour. Matching lives in `shared/no-proxy.ts`, shared by both paths so they cannot drift apart.
+- **Minimal config surface**: it exposes switch / host / port / Basic Auth (username, password) / bypass list. The loopback part of the bypass is built-in behavior, not exposed. The protocol field goes into config but the UI doesn't render it (currently http only), leaving room to add socks5 later — a new protocol value is non-breaking to existing configs.
 - **Three injection forms, consumed per egress** (this is the core of this module):
-  - **Subprocess egress** (pr-agent, git) recognizes the `HTTP(S)_PROXY` / `NO_PROXY` environment variables → inject this set of env into the subprocess (`NO_PROXY` always includes loopback).
-  - **In-process fetch egress** (code-platform REST goes through Node's undici fetch) **does not recognize** proxy env vars by default and must be handed an explicit dispatcher (proxy Agent) → when constructing the platform client, wrap a fetch with a proxy dispatcher around **non-loopback** targets and inject it; loopback / off cases inject nothing (using the default direct connection).
+  - **Subprocess egress** (pr-agent, git) recognizes the `HTTP(S)_PROXY` / `NO_PROXY` environment variables → inject this set of env into the subprocess (`NO_PROXY` = built-in loopback + the user's bypass list; the subprocess's own library applies it).
+  - **In-process fetch egress** (code-platform REST goes through Node's undici fetch) **does not recognize** proxy env vars by default and must be handed an explicit dispatcher (proxy Agent) → when constructing the platform client, wrap a fetch with a proxy dispatcher around targets that are **not bypassed** and inject it; a bypassed target / the switch being off injects nothing (using the default direct connection). Bypass is evaluated in-process here, against the same rules the env path hands out.
   - This unifies into one central component that, per the proxy config, produces the following items, each egress only consuming rather than implementing its own:
     - subprocess env;
     - undici proxy dispatcher / fetch;
-    - loopback determination;
+    - bypass determination (loopback + configured rules);
     - connectivity self-check.
 - **No cost fetching, no network price-table pulls**: token usage is taken solely from the API return value, so the underlying LLM library's remote price table is useless and would time out on a weak network — force using only the local price table, with no network at all (see [pr-agent runtime](../02-agent/05-pragent-runtime.md)).
 - **Takes effect immediately**: change the proxy config → write to disk + update in-memory config + rebuild the platform adapter (REST takes effect immediately); the pr-agent / git egresses read the latest config on their next operation, with no restart.
@@ -39,11 +41,12 @@ proxy:
   port: 8080
   username: ''         # Basic Auth, may be empty
   password: ''         # may be empty (stored in plaintext, same as config's existing policy)
+  no_proxy: ''         # bypass list in NO_PROXY syntax; normalized to one comma-separated line on write
 ```
 
 IPC channels:
 
-- `config:setProxy`: input `{ proxy }` → write to disk + in-memory sync + rebuild adapter (REST takes effect immediately).
+- `config:setProxy`: input `{ proxy }` → normalize `no_proxy` + write to disk + in-memory sync + rebuild adapter (REST takes effect immediately). Normalization happens here rather than in the form, so the value stored is canonical regardless of how the config arrived (IPC or a hand-edited `config.yaml`) — what the user reads back is what is actually matched.
 - `config:testProxy`: input `{ proxy }` → returns `{ ok, reason? }`, verifying connectivity by trying to reach an external address through that proxy; proxy auth failure (407) is classified as a failure with a reason.
 
 Proxy URL form: `http://[username:password@]host:port` (credentials URL-encoded).
@@ -53,5 +56,5 @@ Proxy URL form: `http://[username:password@]host:port` (credentials URL-encoded)
 - **Adding socks5**: append `socks5` to the protocol enum; the undici proxy Agent doesn't support socks, so the REST egress needs to switch to a socks-based dispatcher; the subprocess egress (pr-agent / git) supports socks natively via its underlying library. At that point the UI reveals the protocol choice.
 - **The type of proxy-aware fetch**: Node `fetch`'s `dispatcher` is not in the standard `RequestInit` type, so the injection point needs a type assertion.
 - **Must merge the existing env when replacing subprocess env**: the git wrapper library sets env by wholesale replacement, so missing the merge would lose `PATH`/`HOME`.
-- **Code platform defaults to following the global proxy**: if an intranet platform is collaterally harmed by the proxy (unreachable), that is an edge case — add a "platform direct connection" switch as needed later; not done for now.
+- **Code platform defaults to following the global proxy**: an intranet platform that the proxy cannot reach is resolved by adding its host to `no_proxy`, which covers both its REST egress and its git remote in one rule. A dedicated "platform direct connection" switch is therefore not needed — it would be a second, narrower way to express what the bypass list already expresses.
 - **Plaintext credentials**: the proxy password, like the existing config, is stored in plaintext with no extra encryption; for a developer audience, with a documented risk warning.
diff --git a/docs/guide/03-proxy.md b/docs/guide/03-proxy.md
index 6ba4c004..00a695b0 100644
--- a/docs/guide/03-proxy.md
+++ b/docs/guide/03-proxy.md
@@ -14,6 +14,8 @@ Once the toggle is on, these three egress paths all go through the proxy:
 
 **Local addresses connect directly, automatically**: `localhost / 127.0.0.1 / ::1` (including a local Ollama and other local services) bypass the proxy.
 
+**Anything else you want to keep off the proxy** goes in the **Direct connections** field — see below.
+
 ## Settings
 
 | Field | Description |
@@ -21,6 +23,22 @@ Once the toggle is on, these three egress paths all go through the proxy:
 | Toggle | Master switch; off = everything connects directly (default) |
 | Host / Port | Proxy host and port |
 | Username / Password | Basic Auth, may be left empty |
+| Direct connections | Hosts that bypass the proxy and connect directly; empty by default |
+
+### Direct connections (bypass list)
+
+The proxy is a single global egress, which is a problem when part of what you reach is *inside* the network the proxy leads out of. A self-hosted code platform, its git remote, or an internal model server typically is: routing them through the proxy wastes a hop at best, and makes them unreachable at worst. List those hosts here and they connect directly while everything else still goes through the proxy.
+
+The syntax is the conventional `NO_PROXY` one, so a value copied from an existing environment variable works as-is:
+
+| You write | It matches |
+| --- | --- |
+| `corp.example.com` | that host **and its subdomains** (`git.corp.example.com`, `ci.corp.example.com`, …) |
+| `.corp.example.com` | the same thing — a leading dot is accepted and means no more and no less |
+| `10.0.0.5` | that address exactly (`10.0.0.50` does **not** match) |
+| `*` | every host — the proxy is effectively bypassed entirely |
+
+Write one per line, or separate with commas. Matching ignores case, and any `:port` you include is ignored — a host is either bypassed or not, regardless of port. **CIDR ranges (`10.0.0.0/8`) are not supported**: only some of the underlying tools honour them, so accepting one here would produce a rule that applies to some traffic and not the rest.
 
 > Saving takes effect immediately: the platform client is rebuilt right away and REST goes through the new proxy at once; the LLM / git egress paths read the latest config on their next operation.
 > After configuring, click "Test" and the client will try to reach an external address through the proxy to verify connectivity (a proxy auth failure, 407, reports the reason).
@@ -30,4 +48,4 @@ Once the toggle is on, these three egress paths all go through the proxy:
 - **SSH clone does not use the proxy**: an HTTP proxy does not apply directly to SSH, and there is no uniform cross-platform mechanism for it. If your clone protocol is SSH, configure `ProxyCommand` yourself in `~/.ssh/config`.
 - **Local CLI mode also uses the proxy**: when reviewing with [local CLI mode](02-llm.md#local-cli-mode), the CLI subprocess inherits the proxy environment variables, so its outbound traffic goes through the proxy automatically.
 - **socks5 is not yet supported**: this first phase supports HTTP proxies only (including Basic Auth).
-- **Platform caught in the crossfire**: if an intranet code platform becomes unreachable precisely because it is routed through the proxy, that is an edge case; there is currently no separate "platform direct connection" toggle.
+- **Platform caught in the crossfire**: if an intranet code platform becomes unreachable precisely because it is routed through the proxy, add its host to **Direct connections** — that covers both its REST API and its git remote.
diff --git a/docs/guide/04-config-reference.md b/docs/guide/04-config-reference.md
index cecfa06e..b03fc63b 100644
--- a/docs/guide/04-config-reference.md
+++ b/docs/guide/04-config-reference.md
@@ -46,6 +46,7 @@ proxy:
   port: 8080
   username: ''
   password: ''
+  no_proxy: ''         # hosts that bypass the proxy, comma-separated; loopback is always bypassed
 
 pr_agent:
   strategy: auto
@@ -214,7 +215,7 @@ If the layout contains `<SUGGESTIONS>` it is used as the full comment body; othe
 
 ## `proxy` — outbound network proxy
 
-When enabled, LLM calls, code platform REST, and git HTTPS all go through the proxy; loopback / local addresses (including a local Ollama) connect directly. git fetch over SSH does not use this config — configure it yourself in `~/.ssh/config`.
+When enabled, LLM calls, code platform REST, and git HTTPS all go through the proxy; loopback / local addresses (including a local Ollama) connect directly, as do any hosts listed in `no_proxy`. git fetch over SSH does not use this config — configure it yourself in `~/.ssh/config`.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -224,6 +225,7 @@ When enabled, LLM calls, code platform REST, and git HTTPS all go through the pr
 | `port` | integer | `8080` | Proxy port, `1`–`65535`. |
 | `username` | string | `''` | Basic Auth username, empty if no auth. |
 | `password` | string | `''` | Basic Auth password, empty if no auth. |
+| `no_proxy` | string | `''` | Hosts that connect directly instead of through the proxy, in the conventional `NO_PROXY` syntax (comma-separated; a domain also covers its subdomains; `*` bypasses everything; CIDR ranges are not supported). Loopback is always bypassed and need not be listed. See [Network proxy setup](03-proxy.md#direct-connections-bypass-list). |
 
 ## `pr_agent` — runtime
 
diff --git a/docs/guide/zh-CN/03-proxy.md b/docs/guide/zh-CN/03-proxy.md
index 48ef6dde..7931101a 100644
--- a/docs/guide/zh-CN/03-proxy.md
+++ b/docs/guide/zh-CN/03-proxy.md
@@ -14,6 +14,8 @@
 
 **本地地址自动直连**：`localhost / 127.0.0.1 / ::1`（含本地 Ollama 等本地服务）不经代理。
 
+**其他希望绕开代理的地址**填入「直连地址」——见下。
+
 ## 配置项
 
 | 字段 | 说明 |
@@ -21,6 +23,22 @@
 | 开关 | 总开关；关 = 全部直连（默认） |
 | 地址 / 端口 | 代理 host 与 port |
 | 用户名 / 密码 | Basic Auth，可留空 |
+| 直连地址 | 跳过代理、直接连接的地址；默认为空 |
+
+### 直连地址（跳过代理）
+
+代理是全局唯一出口，而你要访问的一部分服务往往就在代理所通向的那道边界**之内**：自建代码平台、它的 git 远端、内网模型服务通常都是如此。让它们走代理，轻则多绕一跳，重则根本连不上。把这些地址填在这里，它们就直连，其余流量照常走代理。
+
+语法沿用通行的 `NO_PROXY` 写法，从既有环境变量里复制过来即可直接使用：
+
+| 填写 | 匹配 |
+| --- | --- |
+| `corp.example.com` | 该地址**及其子域**（`git.corp.example.com`、`ci.corp.example.com` 等） |
+| `.corp.example.com` | 同上——前导点会被接受，含义完全一致 |
+| `10.0.0.5` | 精确匹配该地址（`10.0.0.50` **不**匹配） |
+| `*` | 所有地址——等同于整体绕开代理 |
+
+每行一条，或以逗号分隔。匹配不区分大小写；写上 `:端口` 会被忽略——一个地址要么绕过代理、要么不绕，与端口无关。**不支持 CIDR 网段（`10.0.0.0/8`）**：底层各工具只有一部分认这种写法，若在此接受，会出现同一条规则对部分流量生效、对其余流量失效的情况。
 
 > 保存即热生效：修改后立即重建平台客户端，REST 立即走新代理；LLM / git 出口在下次操作时读最新配置。
 > 配好后可点「测试」，客户端会经该代理试连一个外部地址验证连通（代理认证失败 407 会报原因）。
@@ -30,4 +48,4 @@
 - **SSH 克隆不走代理**：HTTP 代理对 SSH 不直接适用，跨平台也无统一手段。若 Clone 协议选 SSH，请自行在 `~/.ssh/config` 配 `ProxyCommand`。
 - **本地 CLI 模式同样走代理**：用[本地 CLI 模式](02-llm.md#本地-cli-模式)评审时，CLI 子进程继承代理环境变量，出站自动走代理。
 - **socks5 暂不支持**：一期仅 HTTP 代理（含 Basic Auth）。
-- **平台被代理误伤**：内网代码平台若因走代理反而连不上，属边缘场景，当前未提供「平台直连」单独开关。
+- **平台被代理误伤**：内网代码平台若因走代理反而连不上，把它的地址加入「直连地址」即可——REST 接口与 git 远端会一并生效。
diff --git a/docs/guide/zh-CN/04-config-reference.md b/docs/guide/zh-CN/04-config-reference.md
index 46df9eee..40380c06 100644
--- a/docs/guide/zh-CN/04-config-reference.md
+++ b/docs/guide/zh-CN/04-config-reference.md
@@ -46,6 +46,7 @@ proxy:
   port: 8080
   username: ''
   password: ''
+  no_proxy: ''         # 跳过代理的地址，逗号分隔；本机地址始终直连
 
 pr_agent:
   strategy: auto
@@ -214,7 +215,7 @@ Agent **无独立启用开关**——配置了 LLM 且 pr-agent 就绪即可用
 
 ## `proxy` — 出站网络代理
 
-开启后 LLM 调用、代码平台 REST、git HTTPS 统一经代理；loopback / 本地地址（含本地 Ollama）自动直连。SSH 方式的 git 拉取不走此配置，需在 `~/.ssh/config` 自配。
+开启后 LLM 调用、代码平台 REST、git HTTPS 统一经代理；loopback / 本地地址（含本地 Ollama）自动直连，`no_proxy` 中列出的地址同样直连。SSH 方式的 git 拉取不走此配置，需在 `~/.ssh/config` 自配。
 
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
@@ -224,6 +225,7 @@ Agent **无独立启用开关**——配置了 LLM 且 pr-agent 就绪即可用
 | `port` | integer | `8080` | 代理端口，`1`–`65535`。 |
 | `username` | string | `''` | Basic Auth 用户名，无鉴权留空。 |
 | `password` | string | `''` | Basic Auth 密码，无鉴权留空。 |
+| `no_proxy` | string | `''` | 直连而不走代理的地址，沿用通行的 `NO_PROXY` 写法（逗号分隔；填域名同时覆盖其子域；`*` 表示全部绕过；不支持 CIDR 网段）。本机地址始终直连，无需填写。参见[网络代理配置](03-proxy.md#直连地址跳过代理)。 |
 
 ## `pr_agent` — 运行时
 
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
index 0b665f27..5e504033 100644
--- a/packages/shared/src/config.ts
+++ b/packages/shared/src/config.ts
@@ -144,8 +144,12 @@ export type LlmProfile = z.infer<typeof LlmProfileSchema>;
 /**
  * Outbound network proxy. Phase 1 supports HTTP proxy only: once enabled, LLM / Bitbucket Server
  * REST / git HTTPS all go through the proxy, only loopback/local (including local Ollama) connect directly automatically; SSH goes through the user's
- * own ~/.ssh/config. The config surface only exposes host/port/Basic Auth.
+ * own ~/.ssh/config. The config surface exposes host/port/Basic Auth plus the bypass list.
  * `protocol` is an enum reserved as an extension point (phase 1 only 'http'; adding socks5 etc. is non-breaking for existing configs).
+ *
+ * `no_proxy`: hosts that egress directly despite the proxy being on, in the conventional `NO_PROXY` syntax (see
+ * no-proxy.ts for the supported subset and why it mirrors the environment variable). Loopback is always bypassed and
+ * is not part of this value. Empty (the default) preserves the historical behaviour of proxying everything non-local.
  */
 export const ProxySchema = z.object({
   enabled: z.boolean().default(false),
@@ -154,6 +158,7 @@ export const ProxySchema = z.object({
   port: z.number().int().min(1).max(65535).default(8080),
   username: z.string().default(''),
   password: z.string().default(''),
+  no_proxy: z.string().default(''),
 });
 export type ProxyConfig = z.infer<typeof ProxySchema>;
 
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index c86c2539..b312445b 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -5,6 +5,7 @@ export * from './error-code.js';
 export * from './inline-comment-policy.js';
 export * from './language.js';
 export * from './mention.js';
+export * from './no-proxy.js';
 export * from './platform.js';
 export * from './poller-contract.js';
 export * from './pr-agent-status.js';
diff --git a/packages/shared/src/no-proxy.ts b/packages/shared/src/no-proxy.ts
new file mode 100644
index 00000000..7398454c
--- /dev/null
+++ b/packages/shared/src/no-proxy.ts
@@ -0,0 +1,67 @@
+/**
+ * Proxy bypass rules (`proxy.no_proxy`): which hosts egress **directly** even while the global proxy is on.
+ *
+ * Needed because the proxy is a single global egress: on a corporate network the proxy is the way out to the internet,
+ * but the code platform, its git remote and a self-hosted model often live *inside* that network, where routing them
+ * through the proxy at best wastes a hop and at worst makes them unreachable. Loopback is bypassed unconditionally;
+ * everything else the user has to name, which is what these rules are.
+ *
+ * The syntax deliberately mirrors the conventional `NO_PROXY` environment variable, because that is exactly where these
+ * rules end up for the subprocess egresses (git, pr-agent, local CLIs) — they are handed the variable and interpret it
+ * with their own library. Keeping one syntax means the in-process matching here and those libraries agree; inventing a
+ * richer one would make the two egress paths disagree for the same config, which is a class of bug nearly impossible to
+ * diagnose from the UI. For the same reason the supported subset is kept to what is portable across implementations:
+ *
+ * - `*` on its own bypasses every host;
+ * - a domain (`corp.example.com`) matches that host **and its subdomains**; a leading dot (`.corp.example.com`) is
+ *   accepted and means the same thing, since implementations disagree on whether it also covers the bare domain and
+ *   users expect it to;
+ * - an IP literal matches exactly (IPv6 may be written with or without brackets);
+ * - matching is case-insensitive, and a `:port` suffix on a rule is ignored (accepted so a value pasted from an
+ *   existing `NO_PROXY` still works, but the port plays no part — bypass is decided per host).
+ *
+ * **CIDR ranges are not supported** (`10.0.0.0/8`): only some implementations honour them, so accepting one here would
+ * bypass in-process while the subprocess egresses still proxied — the disagreement this file exists to avoid.
+ */
+
+/** Hosts that always bypass the proxy regardless of configuration, in `NO_PROXY` syntax. */
+export const LOOPBACK_NO_PROXY = 'localhost,127.0.0.1,::1';
+
+/** Strip an IPv6 literal's brackets and any `:port` suffix, and lowercase — the form both rules and hosts compare in. */
+function normalizeHost(value: string): string {
+  const v = value.trim().toLowerCase();
+  if (!v) return '';
+  // Bracketed IPv6, optionally with a port: [::1] / [::1]:8080
+  const bracketed = /^\[(.+)\]/.exec(v);
+  if (bracketed) return bracketed[1]!;
+  // A bare IPv6 literal contains several colons, so a colon is only a port separator when there is exactly one.
+  const colons = v.split(':').length - 1;
+  if (colons === 1) return v.slice(0, v.indexOf(':'));
+  return v;
+}
+
+/**
+ * Split a raw `no_proxy` value into normalized rules. Accepts commas, whitespace and newlines as separators, so a value
+ * pasted from an environment variable and one typed as a list both work; empty entries are dropped.
+ */
+export function parseNoProxy(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(/[\s,]+/)
+    .map((r) => (r.trim() === '*' ? '*' : normalizeHost(r.replace(/^\./, ''))))
+    .filter((r) => r.length > 0);
+}
+
+/** Normalize a raw `no_proxy` value for storage: one comma-separated line, deduplicated, in the order given. */
+export function normalizeNoProxy(raw: string | undefined): string {
+  return [...new Set(parseNoProxy(raw))].join(',');
+}
+
+/** Whether `host` is covered by the given `no_proxy` rules, i.e. it should egress directly. */
+export function matchesNoProxy(host: string, raw: string | undefined): boolean {
+  const target = normalizeHost(host);
+  if (!target) return false;
+  return parseNoProxy(raw).some(
+    (rule) => rule === '*' || target === rule || target.endsWith(`.${rule}`),
+  );
+}
diff --git a/packages/shared/tests/no-proxy.test.ts b/packages/shared/tests/no-proxy.test.ts
new file mode 100644
index 00000000..2421e69a
--- /dev/null
+++ b/packages/shared/tests/no-proxy.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  LOOPBACK_NO_PROXY,
+  matchesNoProxy,
+  normalizeNoProxy,
+  parseNoProxy,
+} from '../src/no-proxy.js';
+
+describe('parseNoProxy', () => {
+  it('accepts commas, whitespace and newlines as separators', () => {
+    expect(parseNoProxy('a.com, b.com\nc.com  d.com')).toEqual([
+      'a.com',
+      'b.com',
+      'c.com',
+      'd.com',
+    ]);
+  });
+
+  it('normalizes case, leading dots and port suffixes', () => {
+    expect(parseNoProxy('.Corp.EXAMPLE.com, git.corp.com:7999')).toEqual([
+      'corp.example.com',
+      'git.corp.com',
+    ]);
+  });
+
+  it('drops empty entries, and treats an absent value as no rules', () => {
+    expect(parseNoProxy(' , ,\n')).toEqual([]);
+    expect(parseNoProxy(undefined)).toEqual([]);
+    expect(parseNoProxy('')).toEqual([]);
+  });
+
+  it('keeps IPv6 literals, with or without brackets', () => {
+    expect(parseNoProxy('[fe80::1], ::1')).toEqual(['fe80::1', '::1']);
+  });
+});
+
+describe('normalizeNoProxy', () => {
+  it('collapses to one comma-separated line and deduplicates', () => {
+    expect(normalizeNoProxy('a.com\n.a.com\nb.com, a.com')).toBe('a.com,b.com');
+  });
+});
+
+describe('matchesNoProxy', () => {
+  it('matches the domain itself and its subdomains', () => {
+    expect(matchesNoProxy('corp.example.com', 'corp.example.com')).toBe(true);
+    expect(matchesNoProxy('git.corp.example.com', 'corp.example.com')).toBe(true);
+    // A leading dot means the same thing: users expect it to cover the bare domain too.
+    expect(matchesNoProxy('corp.example.com', '.corp.example.com')).toBe(true);
+  });
+
+  it('does not match a host that merely ends with the rule text', () => {
+    // The suffix must fall on a label boundary, or "evil-example.com" would bypass a rule for "example.com".
+    expect(matchesNoProxy('evil-example.com', 'example.com')).toBe(false);
+    expect(matchesNoProxy('notexample.com', 'example.com')).toBe(false);
+  });
+
+  it('is case-insensitive and ignores ports on either side', () => {
+    expect(matchesNoProxy('GIT.Corp.COM', 'corp.com')).toBe(true);
+    expect(matchesNoProxy('git.corp.com:7999', 'corp.com')).toBe(true);
+    expect(matchesNoProxy('git.corp.com', 'corp.com:7999')).toBe(true);
+  });
+
+  it('matches IP literals exactly, not as a suffix', () => {
+    expect(matchesNoProxy('10.0.0.5', '10.0.0.5')).toBe(true);
+    expect(matchesNoProxy('10.0.0.50', '10.0.0.5')).toBe(false);
+    expect(matchesNoProxy('[fe80::1]', 'fe80::1')).toBe(true);
+  });
+
+  it('supports the wildcard, and treats no rules as no bypass', () => {
+    expect(matchesNoProxy('anything.com', '*')).toBe(true);
+    expect(matchesNoProxy('anything.com', '')).toBe(false);
+    expect(matchesNoProxy('anything.com', undefined)).toBe(false);
+  });
+
+  // How both egress paths compose the effective rules: the built-in loopback set prepended to the user's (see the
+  // desktop proxy plumbing). Asserted here so the guarantee holds no matter what the user typed.
+  describe('composed with the built-in loopback set', () => {
+    const effective = (userRules: string): string =>
+      normalizeNoProxy(`${LOOPBACK_NO_PROXY},${userRules}`);
+
+    it('keeps local addresses direct even when the user configured nothing', () => {
+      expect(matchesNoProxy('localhost', effective(''))).toBe(true);
+      expect(matchesNoProxy('127.0.0.1', effective(''))).toBe(true);
+      expect(matchesNoProxy('[::1]', effective(''))).toBe(true);
+      expect(matchesNoProxy('api.openai.com', effective(''))).toBe(false);
+    });
+
+    it('bypasses the user rules alongside loopback, leaving everything else proxied', () => {
+      const rules = effective('corp.example.com\n10.0.0.5');
+      expect(matchesNoProxy('git.corp.example.com', rules)).toBe(true);
+      expect(matchesNoProxy('10.0.0.5', rules)).toBe(true);
+      expect(matchesNoProxy('localhost', rules)).toBe(true);
+      expect(matchesNoProxy('api.openai.com', rules)).toBe(false);
+    });
+  });
+
+  it('does not support CIDR: a range is not silently treated as a match', () => {
+    // Documented limitation — honouring it here while the subprocess egresses did not would make the two disagree.
+    expect(matchesNoProxy('10.0.0.5', '10.0.0.0/8')).toBe(false);
+  });
+});

From defb4a0ee6f200bdfbe5cb3b9320b50d2d560ce3 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 14:01:14 +0800
Subject: [PATCH 07/17] feat(comments): render @mentions as pills instead of
 running text

A mention is a reference to a person, but as plain text it disappears into the
sentence -- exactly when the reader is scanning a thread for whether it concerns
them. A remark plugin now renders each mention as a pill, wherever author-written
prose that can name someone is rendered: the activity page, the inline comment
zone, both draft surfaces and the PR description. Drafts are included because a
draft is a comment about to be posted, and the same body must not read
differently before and after publishing. Agent-facing markdown (chat, finding
cards, rule previews) is not: nothing there addresses a person.

Parsing lives beside writing. findMentions sits next to formatMention in
shared/mention.ts, so the syntax -- notably Bitbucket's quoted @"first.last",
required for a username containing a dot -- is defined once rather than once per
direction. The pill accordingly shows @first.last: the quotes are platform
syntax, not part of anyone's name, and this is the one place the rendered text
intentionally differs from the source.

Matching is syntactic, not resolved: there is no authoritative local list of who
exists on the remote, so anything shaped like a mention is styled. That trade
holds only because a false positive costs a tinted background and nothing else --
the text is unaltered and nothing becomes clickable. Boundary rules still exclude
the common ones (email addresses, scoped package names, trailing punctuation),
and code spans and fences are excluded for free, since only mdast text nodes are
rewritten.

The pill class had to be allowlisted for rehype-sanitize, which strips class from
a span by default. It is allowed as a value-restricted attribute rather than as
free-form className, so a comment cannot borrow arbitrary app styles by writing
raw HTML.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 CHANGELOG.zh-CN.md                            |  1 +
 .../features/pr/tabs/PrInfoView.tsx           |  3 +-
 .../features/pr/tabs/drafts/DraftZone.tsx     | 11 ++-
 .../features/pr/tabs/drafts/DraftsPanel.tsx   |  7 +-
 .../pr/tabs/shared/CommentMarkdown.tsx        |  5 +-
 apps/desktop/src/renderer/src/lib/markdown.ts |  6 ++
 .../src/renderer/src/lib/remark-mention.ts    | 70 +++++++++++++++++++
 .../renderer/src/styles/common/markdown.scss  | 17 +++++
 .../01-platform/04-comment-interactions.md    | 12 ++++
 packages/shared/src/mention.ts                | 50 +++++++++++++
 packages/shared/tests/mention.test.ts         | 70 +++++++++++++++++++
 12 files changed, 248 insertions(+), 5 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/lib/remark-mention.ts
 create mode 100644 packages/shared/tests/mention.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0c47941..248103c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
+- Mentions now render as a pill instead of blending into the surrounding text, so it is obvious at a glance when someone is named — on the activity page, in the inline diff comments, in drafts, and in the PR description alike.
 - Proxy settings now take a list of **direct connections**: hosts that bypass the proxy and connect straight out, so an internal code platform, its git remote, or a self-hosted model stays reachable while everything else still goes through the proxy. Uses the familiar `NO_PROXY` syntax (a domain covers its subdomains), and applies to every outbound path at once — REST, git and the LLM call.
 - A review that fails because the model is unavailable now says so and tells you what to do — with a local CLI provider (claude / codex) the model comes from that CLI's own configuration, so it has to be changed there.
 
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 22781768..55e47be0 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,6 +9,7 @@
 
 ### ✨ 新增
 
+- @提及 改为胶囊标签展示，不再淹没在正文里，一眼即可看出点到了谁——活动页、内联 diff 评论、草稿与 PR 描述一致生效。
 - 代理设置新增**直连地址**列表：列出的地址跳过代理直接连接，内网代码平台、它的 git 远端或自建模型服务因此保持可达，其余流量照常走代理。沿用通行的 `NO_PROXY` 写法（填域名同时覆盖子域），并对所有出站路径一并生效——REST、git 与 LLM 调用。
 - 因模型不可用而失败的评审现在会明确说明，并给出处理方式——使用本地 CLI 供应商（claude / codex）时，模型来自该 CLI 自身的配置，需要在那里更换。
 
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/PrInfoView.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/PrInfoView.tsx
index b14e6ae7..14ad6074 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/PrInfoView.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/PrInfoView.tsx
@@ -4,6 +4,7 @@ import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import type { StoredPullRequest } from '@meebox/shared';
 import { REMOTE_REHYPE_PLUGINS } from '../../../../lib/markdown';
+import { remarkMentions } from '../../../../lib/remark-mention';
 import { formatTimestamp } from '../../../../utils/time';
 import {
   Avatar,
@@ -48,7 +49,7 @@ export function PrInfoView({ pr }: PrInfoViewProps) {
                 {/* Bitbucket remote uses \r\n line endings; when remark parses, CR and LF each count as a line break → a single
                     newline gets treated as a paragraph separator, adding blank space between each list item. Normalize to \n */}
                 <ReactMarkdown
-                  remarkPlugins={[remarkGfm]}
+                  remarkPlugins={[remarkGfm, remarkMentions]}
                   rehypePlugins={REMOTE_REHYPE_PLUGINS}
                   components={mdComponents}
                   urlTransform={transformBitbucketUrl}
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftZone.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftZone.tsx
index 80a02754..067826cf 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftZone.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftZone.tsx
@@ -4,6 +4,7 @@ import remarkBreaks from 'remark-breaks';
 import remarkGfm from 'remark-gfm';
 import type { PlatformKind, PlatformUser, ReviewDraft } from '@meebox/shared';
 import { ConfirmModal, TrashIcon } from '../../../../common';
+import { remarkMentions } from '../../../../../lib/remark-mention';
 import { MentionTextarea } from '../shared/MentionTextarea';
 import { searchMentionUsers } from '../shared/mentionSearch';
 import { uploadCommentImage } from '../shared/uploadCommentImage';
@@ -227,9 +228,17 @@ export function DraftZone({
           </div>
         </div>
       ) : (
+        // Mentions render as pills here too: a draft is a comment the user is about to post, and the same body must
+        // not read differently before and after publishing (see docs/arch/01-platform/04-comment-interactions.md).
         <div className="draft-zone-body markdown">
           {draft.body.trim() ? (
-            <ReactMarkdown remarkPlugins={hardBreaks ? [remarkGfm, remarkBreaks] : [remarkGfm]}>
+            <ReactMarkdown
+              remarkPlugins={
+                hardBreaks
+                  ? [remarkGfm, remarkBreaks, remarkMentions]
+                  : [remarkGfm, remarkMentions]
+              }
+            >
               {draft.body}
             </ReactMarkdown>
           ) : (
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftsPanel.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftsPanel.tsx
index a80ba10e..9d82a861 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftsPanel.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/drafts/DraftsPanel.tsx
@@ -8,6 +8,7 @@ import { invoke } from '../../../../../api';
 import { formatBackendError } from '../../../../../errors';
 import { useDraftsForPr } from '../../../../../stores/drafts-store';
 import { ConfirmModal } from '../../../../common';
+import { remarkMentions } from '../../../../../lib/remark-mention';
 
 // posted no longer exists (successful publish deletes the local draft), filters keep only publishable / all / rejected
 type Filter = 'all' | 'publishable' | 'rejected';
@@ -250,7 +251,11 @@ export function DraftsPanel({ pr, onJumpToAnchor, capabilities, readOnly = false
                 <div className="drafts-panel-item-body markdown">
                   {d.body.trim() ? (
                     <ReactMarkdown
-                      remarkPlugins={hardBreaks ? [remarkGfm, remarkBreaks] : [remarkGfm]}
+                      remarkPlugins={
+                        hardBreaks
+                          ? [remarkGfm, remarkBreaks, remarkMentions]
+                          : [remarkGfm, remarkMentions]
+                      }
                     >
                       {d.body}
                     </ReactMarkdown>
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/shared/CommentMarkdown.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/shared/CommentMarkdown.tsx
index 2d6d279b..db12b8ed 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/shared/CommentMarkdown.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/shared/CommentMarkdown.tsx
@@ -3,6 +3,7 @@ import remarkBreaks from 'remark-breaks';
 import remarkGfm from 'remark-gfm';
 import { REMOTE_REHYPE_PLUGINS } from '../../../../../lib/markdown';
 import { remarkEmojiShortcodes } from '../../../../../lib/remark-emoji';
+import { remarkMentions } from '../../../../../lib/remark-mention';
 import { transformBitbucketUrl } from '../../../../common';
 
 /**
@@ -29,8 +30,8 @@ export function CommentMarkdown({
       <ReactMarkdown
         remarkPlugins={
           hardBreaks
-            ? [remarkGfm, remarkBreaks, remarkEmojiShortcodes]
-            : [remarkGfm, remarkEmojiShortcodes]
+            ? [remarkGfm, remarkBreaks, remarkEmojiShortcodes, remarkMentions]
+            : [remarkGfm, remarkEmojiShortcodes, remarkMentions]
         }
         rehypePlugins={REMOTE_REHYPE_PLUGINS}
         components={components}
diff --git a/apps/desktop/src/renderer/src/lib/markdown.ts b/apps/desktop/src/renderer/src/lib/markdown.ts
index db9afb94..12241905 100644
--- a/apps/desktop/src/renderer/src/lib/markdown.ts
+++ b/apps/desktop/src/renderer/src/lib/markdown.ts
@@ -8,6 +8,7 @@
 import type { Options } from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
 import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import { MENTION_CLASS } from './remark-mention';
 
 function extend<T>(list: readonly T[] | null | undefined, extra: readonly T[]): T[] {
   return Array.from(new Set<T>([...(list ?? []), ...extra]));
@@ -44,6 +45,11 @@ const schema = {
     td: extend(defaultSchema.attributes?.td, ['align']),
     th: extend(defaultSchema.attributes?.th, ['align']),
     a: extend(defaultSchema.attributes?.a, ['rel', 'target']),
+    // The @mention pill (remark-mention) renders as <span class="comment-mention">, and sanitize would otherwise strip
+    // the class, leaving the mention indistinguishable from prose. Allowed as a **value-restricted** attribute
+    // (`[name, ...allowed values]`), not as free-form className: the body is user-generated, so permitting arbitrary
+    // classes on a span would let a comment borrow any style in the app.
+    span: extend(defaultSchema.attributes?.span, [['className', MENTION_CLASS]]),
     '*': extend(defaultSchema.attributes?.['*'], ['align']),
   },
 };
diff --git a/apps/desktop/src/renderer/src/lib/remark-mention.ts b/apps/desktop/src/renderer/src/lib/remark-mention.ts
new file mode 100644
index 00000000..fc6b15f8
--- /dev/null
+++ b/apps/desktop/src/renderer/src/lib/remark-mention.ts
@@ -0,0 +1,70 @@
+import { findMentions } from '@meebox/shared';
+
+/** Minimal shape of an mdast node (only the fields this plugin uses, avoiding an mdast type dependency). */
+interface MdNode {
+  type: string;
+  value?: string;
+  children?: MdNode[];
+  data?: { hName?: string; hProperties?: Record<string, unknown> };
+}
+
+/** The class the rendered pill carries; must stay in sync with the sanitize allowlist in lib/markdown.ts. */
+export const MENTION_CLASS = 'comment-mention';
+
+/** Split one text value into text / mention nodes, or null when it holds no mention (the common case — keep the node). */
+function splitMentions(text: string): MdNode[] | null {
+  const found = findMentions(text);
+  if (found.length === 0) return null;
+  const out: MdNode[] = [];
+  let last = 0;
+  for (const { start, end, name } of found) {
+    if (start > last) out.push({ type: 'text', value: text.slice(last, start) });
+    out.push({
+      type: 'mention',
+      // A node type mdast does not know: mdast-util-to-hast's unknown handler builds an element from the children and
+      // applies hName / hProperties, which is the documented way to emit custom markup from a remark plugin.
+      data: { hName: 'span', hProperties: { className: MENTION_CLASS } },
+      // The pill shows `@name`, not the raw token: Bitbucket's quoted form (`@"first.last"`) carries quotes that are
+      // platform syntax, not part of anyone's name, and showing them inside the pill is noise. This is the one place
+      // the rendered text intentionally differs from the source — everything else is styling only.
+      children: [{ type: 'text', value: `@${name}` }],
+    });
+    last = end;
+  }
+  if (last < text.length) out.push({ type: 'text', value: text.slice(last) });
+  return out;
+}
+
+/**
+ * remark plugin: render `@mention` tokens in a comment body as a pill instead of leaving them as running text, so a
+ * mention reads as "a person" at a glance rather than as prose that happens to start with `@`.
+ *
+ * Only mdast `text` nodes are rewritten, so code spans and code blocks are untouched for free — their content never
+ * lives in text nodes, meaning an `@Override` in a snippet or an email in a fenced block stays literal. Which runs
+ * count as mentions is decided by `findMentions` in shared, the reading counterpart of the `formatMention` used by the
+ * editors, so the two directions cannot disagree about the syntax (notably Bitbucket's quoted `@"first.last"`).
+ */
+export function remarkMentions() {
+  return (tree: MdNode): void => {
+    const walk = (node: MdNode): void => {
+      if (!node.children) return;
+      const out: MdNode[] = [];
+      let changed = false;
+      for (const child of node.children) {
+        if (child.type === 'text' && child.value?.includes('@')) {
+          const parts = splitMentions(child.value);
+          if (parts) {
+            out.push(...parts);
+            changed = true;
+            continue;
+          }
+        } else {
+          walk(child);
+        }
+        out.push(child);
+      }
+      if (changed) node.children = out;
+    };
+    walk(tree);
+  };
+}
diff --git a/apps/desktop/src/renderer/src/styles/common/markdown.scss b/apps/desktop/src/renderer/src/styles/common/markdown.scss
index 0a9e705b..65232abe 100644
--- a/apps/desktop/src/renderer/src/styles/common/markdown.scss
+++ b/apps/desktop/src/renderer/src/styles/common/markdown.scss
@@ -148,3 +148,20 @@
     margin-right: $space-2;
   }
 }
+
+// @mention pill (remark-mention → span.comment-mention). Rendered as one unit so a mention reads as "a person" rather
+// than as prose that happens to start with `@`. Scoped to the whole file rather than nested inside `.markdown`,
+// because the class is emitted by the markdown pipeline wherever a comment body is rendered — including the draft
+// preview, whose container carries `.markdown`, and any future surface that may not.
+.comment-mention {
+  display: inline-block;
+  padding: 0 5px;
+  border-radius: $radius-pill;
+  background: $color-accent-bg-fade;
+  color: $color-accent;
+  font-weight: 500;
+  // Keep line height from growing where a mention sits in a dense comment: the pill borrows the line box it is in.
+  line-height: 1.4;
+  // A long username must wrap with the text rather than force the comment to scroll sideways.
+  word-break: break-word;
+}
diff --git a/docs/arch/01-platform/04-comment-interactions.md b/docs/arch/01-platform/04-comment-interactions.md
index 89ee0131..5c956a90 100644
--- a/docs/arch/01-platform/04-comment-interactions.md
+++ b/docs/arch/01-platform/04-comment-interactions.md
@@ -72,6 +72,18 @@ Both layers are a **pure convenience**: the user can still freely type any `@nam
 
 **Consistency across surfaces (design philosophy)**: every comment-interaction behavior — reactions, `@mention` (local + remote), attachments, reply / edit / delete — must be **identical on all comment surfaces**: the comments/activity page (`CommentItem`), the inline diff comment zone (`InlineCommentZone`), and the inline draft editor (`DraftZone`). This is enforced by **sharing the leaf components / hooks** (`CommentReplyEditor`, `MentionTextarea`, `useReactions`, `useCommentThread`) rather than reimplementing per surface, so a surface can only differ in layout, never in interaction behavior. When adding or changing an interaction, wire it into **all** surfaces (thread the same props down each path) — a capability reaching only one surface is a bug, not a scope choice.
 
+### @mention rendering: a pill, not running text
+
+A mention is a reference to a person, and left as plain text it disappears into the sentence — exactly when the reader is scanning a thread for whether it concerns them. So a mention renders as a **pill** (`remark-mention` → `span.comment-mention`), applied wherever author-written prose that can name someone is rendered: the activity page, the inline comment zone, both draft surfaces, and the PR description. Drafts are included because a draft is a comment about to be posted, and the same body must not read differently before and after publishing; the PR description is included because it is the same kind of authored text, and a mention that is a pill in one place and plain text in another reads as a bug. Agent-facing markdown (chat, finding cards, rule previews) is **not** included — nothing there addresses a person.
+
+Three things worth knowing about the implementation:
+
+- **Parsing is the counterpart of writing, and lives beside it.** `findMentions` sits next to `formatMention` in `shared/mention.ts`, so the syntax — notably Bitbucket's quoted `@"first.last"`, which the server requires for a username containing a dot — is defined once instead of once per direction.
+- **It is syntactic, not resolved.** There is no authoritative local list of who exists on the remote (a mention may name someone outside this PR's participants), so anything shaped like a mention is styled. That is the right side of the trade only because a false positive costs a tinted background and nothing else: the text is not altered and nothing becomes clickable. Boundary rules exclude the common false positives — an email address (no leading boundary before `@`), a scoped package (`@scope/pkg`), and trailing sentence punctuation. Code spans and fences are excluded for free, since only mdast `text` nodes are rewritten.
+- **The class has to be allowlisted for sanitize, by value.** Comment bodies pass through `rehype-sanitize`, which strips `class` from a `span` by default; the pill class is allowed as a **value-restricted** attribute rather than as free-form `className`, so a comment cannot borrow arbitrary app styles by writing raw HTML.
+
+The pill is also the one place the rendered text intentionally differs from the source: it shows `@first.last`, dropping Bitbucket's quotes, which are platform syntax rather than part of anyone's name.
+
 ### File-level comments: whole-file anchor + capability degradation
 
 A comment can anchor to a **whole file** (not a specific line) where the platform supports it (`fileLevelComments`). This is modeled by a `PrCommentAnchor` **without a `line`** (path + side only): `anchor == null` → PR summary; `anchor` with a line → inline; `anchor` without a line → file-level. The comment `kind` (`'summary' | 'inline' | 'file'`) mirrors this.
diff --git a/packages/shared/src/mention.ts b/packages/shared/src/mention.ts
index 2d521dc5..a0218407 100644
--- a/packages/shared/src/mention.ts
+++ b/packages/shared/src/mention.ts
@@ -26,3 +26,53 @@ export function formatMention(platform: PlatformKind, user: Pick<PlatformUser, '
   }
   return `@${id}`;
 }
+
+/** One mention found in a body: `[start, end)` are indices into the input, `name` excludes the `@` and any quotes. */
+export interface FoundMention {
+  start: number;
+  end: number;
+  name: string;
+}
+
+/**
+ * Mention token, the reading counterpart of {@link formatMention} — both forms it can write must parse back here, which
+ * is why the two live together: the quoted Bitbucket form is defined once, not once per direction.
+ *
+ * The leading boundary is deliberately narrow (start of input, whitespace, or an opening bracket) because `@` is common
+ * in prose that is not a mention; requiring the boundary is what keeps `user@example.com` from matching its domain.
+ */
+const MENTION = /(^|[\s([{])@(?:"([^"\n]{1,64})"|([A-Za-z0-9_][A-Za-z0-9_.-]{0,63}))/g;
+
+/**
+ * Locate `@mention` tokens in a plain-text run, for rendering them distinctly from surrounding prose.
+ *
+ * **Syntactic, not resolved**: there is no authoritative local list of who exists on the remote (a mention may name
+ * someone outside this PR's participants), so anything shaped like a mention is reported. Callers should therefore use
+ * this for presentation only — a false positive that merely restyles a word is cheap, one that turned text into a link
+ * or a notification would not be. The boundary rules exclude the common false positives anyway:
+ *
+ * - an email address (`user@example.com`) — the `@` has no leading boundary;
+ * - a scoped package (`@scope/pkg`) — a `/` immediately after the name disqualifies it;
+ * - a trailing `.` or `-` is treated as punctuation and left out of the name, so a mention ending a sentence is clean.
+ *
+ * Code spans are not a concern here: callers run this over text runs, and markdown code never reaches them.
+ */
+export function findMentions(text: string): FoundMention[] {
+  const out: FoundMention[] = [];
+  MENTION.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = MENTION.exec(text)) !== null) {
+    const lead = m[1] ?? '';
+    const quoted = m[2];
+    // A trailing `.` / `-` belongs to the surrounding prose, not to the username.
+    const name = quoted ?? (m[3] ?? '').replace(/[.-]+$/, '');
+    if (!name) continue;
+    const start = m.index + lead.length;
+    // `@` + name, plus the two quotes when quoted.
+    const end = start + name.length + (quoted ? 3 : 1);
+    MENTION.lastIndex = end;
+    if (text[end] === '/') continue; // scoped package, not a mention
+    out.push({ start, end, name });
+  }
+  return out;
+}
diff --git a/packages/shared/tests/mention.test.ts b/packages/shared/tests/mention.test.ts
new file mode 100644
index 00000000..5a2fc7d0
--- /dev/null
+++ b/packages/shared/tests/mention.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { findMentions, formatMention } from '../src/mention.js';
+
+/** Just the matched text of each hit, which is what a renderer turns into a pill. */
+const tokens = (text: string): string[] =>
+  findMentions(text).map((m) => text.slice(m.start, m.end));
+
+describe('formatMention', () => {
+  it('quotes a Bitbucket username that needs it, and leaves a simple one bare', () => {
+    expect(formatMention('bitbucket-server', { name: 'first.last' })).toBe('@"first.last"');
+    expect(formatMention('bitbucket-server', { name: 'jdoe' })).toBe('@jdoe');
+  });
+
+  it('uses the bare form on GitHub / GitLab', () => {
+    expect(formatMention('github', { name: 'jdoe' })).toBe('@jdoe');
+    expect(formatMention('gitlab', { name: 'jdoe' })).toBe('@jdoe');
+  });
+});
+
+describe('findMentions', () => {
+  it('reads back both forms formatMention can write', () => {
+    const quoted = formatMention('bitbucket-server', { name: 'first.last' });
+    const bare = formatMention('github', { name: 'jdoe' });
+    expect(findMentions(`ping ${quoted} and ${bare}`).map((m) => m.name)).toEqual([
+      'first.last',
+      'jdoe',
+    ]);
+  });
+
+  it('finds a mention at the start of the body and after an opening bracket', () => {
+    expect(tokens('@jdoe please look')).toEqual(['@jdoe']);
+    expect(tokens('(@jdoe) and [@ada]')).toEqual(['@jdoe', '@ada']);
+  });
+
+  it('ignores an email address', () => {
+    // The `@` has no leading boundary, so neither the local part nor the domain is a mention.
+    expect(tokens('mail me at user@example.com please')).toEqual([]);
+  });
+
+  it('ignores a scoped package name', () => {
+    expect(tokens('install @meebox/shared first')).toEqual([]);
+    // ...but a mention immediately before a slash-free word is still found.
+    expect(tokens('ask @meebox about it')).toEqual(['@meebox']);
+  });
+
+  it('leaves sentence punctuation out of the name', () => {
+    expect(findMentions('thanks @jdoe.')[0]?.name).toBe('jdoe');
+    expect(findMentions('cc @jdoe, @ada').map((m) => m.name)).toEqual(['jdoe', 'ada']);
+  });
+
+  it('reports offsets that exactly span the token', () => {
+    const text = 'hi @jdoe there';
+    const [m] = findMentions(text);
+    expect(text.slice(m!.start, m!.end)).toBe('@jdoe');
+  });
+
+  it('handles several mentions in one run, including adjacent ones', () => {
+    expect(tokens('@a @b @c')).toEqual(['@a', '@b', '@c']);
+  });
+
+  it('finds nothing in text without a mention', () => {
+    expect(findMentions('no mentions here')).toEqual([]);
+    expect(findMentions('')).toEqual([]);
+  });
+
+  it('is not confused by a stray @ or an empty quoted token', () => {
+    expect(findMentions('a @ b')).toEqual([]);
+    expect(findMentions('a @"" b')).toEqual([]);
+  });
+});

From 69b62a83d241405d8d9be5e418bbb45faa51a3fd Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 14:23:49 +0800
Subject: [PATCH 08/17] fix(gui): contain a failed lazy chunk instead of taking
 down the app

Suspense covers only the pending half of a dynamic import. When the chunk fails
to load the promise rejects and the error propagates to the nearest boundary --
and neither lazy() site had one: the diff editor in PrPanel and a comment''s
inline code context in CommentItem. DiffView carries an internal boundary around
DiffPane, but that cannot see its own chunk failing to arrive. So a Monaco
snippet that could not be fetched cost the user the entire application.

Each lazy subtree now owns a LazyBoundary (Suspense plus a boundary) and the
failure stays inside the pane that could not load.

A stale chunk is singled out. The window holds a hashed module URL the app no
longer has -- it was rebuilt or updated while the window stayed open -- so
re-rendering re-requests the same dead URL and fails identically; only a reload
recovers. Offering "retry" there is offering a button that cannot work, so
isChunkLoadError detects the case and both the pane fallback and the root crash
screen lead with reload and say why. Other errors keep retry.

Observed via the root crash screen added earlier, which reported the failing
module by name -- the diagnosis this containment work was meant to make possible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 CHANGELOG.zh-CN.md                            |  1 +
 .../src/components/common/AppCrashScreen.tsx  | 29 ++++---
 .../src/components/common/LazyBoundary.tsx    | 75 +++++++++++++++++++
 .../renderer/src/components/common/index.ts   |  1 +
 .../src/components/features/pr/PrPanel.tsx    | 11 ++-
 .../features/pr/tabs/comments/CommentItem.tsx | 10 ++-
 .../src/renderer/src/i18n/locales/de-DE.json  |  7 ++
 .../src/renderer/src/i18n/locales/en-US.json  |  7 ++
 .../src/renderer/src/i18n/locales/ja-JP.json  |  7 ++
 .../src/renderer/src/i18n/locales/zh-CN.json  |  7 ++
 .../src/renderer/src/styles/common/crash.scss | 19 +++++
 docs/arch/03-gui/01-ui-interaction.md         |  5 +-
 13 files changed, 161 insertions(+), 19 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/components/common/LazyBoundary.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 248103c2..afa860cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### 🔧 Fixed
 
+- A part of the interface that loads on demand — the diff editor, a comment's inline code context — no longer takes the whole app down with it when it fails to load; the failure now stays inside that pane. If it failed because the app was updated or rebuilt while the window was open, it says so and offers to reload, which is the only thing that actually helps in that case.
 - A failed review now shows the provider's actual error instead of only "all fallback models failed" — the real cause (an unavailable model, an expired login, an exhausted quota) was previously swallowed and never reached the run card.
 - A local CLI provider that exits successfully but returns an empty reply is now reported as a failure naming that cause, rather than as an unexplained LLM failure.
 - A merged PR now leaves the list on its own shortly after you merge it, instead of lingering until the next periodic sync — the remote takes a few seconds to actually mark it merged, and the app now waits for that rather than refreshing too early and finding nothing changed.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 55e47be0..a0091c78 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -15,6 +15,7 @@
 
 ### 🔧 修复
 
+- 按需加载的界面部分——diff 编辑器、评论中的内联代码上下文——加载失败时不再拖垮整个应用，失败被限制在该区域内。若失败原因是窗口开着时应用被更新或重新构建，会明确说明并提供重新加载，那也是这种情况下唯一有效的操作。
 - 评审失败时现在会展示供应商返回的真实错误，而不再只有一句「所有备选模型均调用失败」——真正的原因（模型不可用、登录过期、额度耗尽）此前被吞掉，从未出现在运行卡片上。
 - 本地 CLI 供应商正常退出却返回空回复时，现在会作为失败上报并指明该原因，而不再表现为一次无从解释的 LLM 调用失败。
 - 合并 PR 后，该 PR 会在稍后自动从列表中消失，而不再滞留到下一次周期同步——远端需要几秒才真正标记为已合并，应用现在会等待这一刻，而不是过早刷新、结果什么都没变。
diff --git a/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx b/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
index 087edb2d..401ce60f 100644
--- a/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
+++ b/apps/desktop/src/renderer/src/components/common/AppCrashScreen.tsx
@@ -1,30 +1,41 @@
 import { useTranslation } from 'react-i18next';
+import { isChunkLoadError } from './LazyBoundary';
 
 /**
  * Full-window fallback for a crash in the app's root subtree.
  *
  * Without a boundary at the root, any error thrown while rendering unmounts the whole tree and leaves an empty `#root`
  * — which reads as a permanently black window, with no way back short of restarting the app. This screen is what the
- * user gets instead: what broke, and two ways out.
+ * user gets instead: what broke, and a way out.
  *
- * `onRetry` re-renders the subtree, which is enough when the crash came from transient state (a stale record read
- * during an in-flight update); reloading rebuilds the renderer from scratch and is the way out when it did not.
+ * The way out depends on the failure. `onRetry` re-renders the subtree, which is enough when the crash came from
+ * transient state (a stale record read during an in-flight update). A **stale chunk** is the exception: the page holds
+ * a hashed module URL that no longer exists (the app was rebuilt or updated while this window stayed open), so
+ * re-rendering re-requests the same dead URL and fails identically — only a reload recovers. Offering "retry" there
+ * would be offering a button that cannot work, so that case leads with reload and explains why.
  */
 export function AppCrashScreen({ err, onRetry }: { err: Error; onRetry: () => void }) {
   const { t } = useTranslation();
+  const stale = isChunkLoadError(err);
   return (
     <div className="app-crash" role="alert">
       <div className="app-crash-card">
-        <h1 className="app-crash-title">{t('crash.title')}</h1>
-        <p className="app-crash-hint">{t('crash.hint')}</p>
+        <h1 className="app-crash-title">{stale ? t('crash.staleTitle') : t('crash.title')}</h1>
+        <p className="app-crash-hint">{stale ? t('crash.staleHint') : t('crash.hint')}</p>
         <pre className="app-crash-detail">{err.message || String(err)}</pre>
         <div className="app-crash-actions">
-          <button type="button" className="btn btn-primary" onClick={onRetry}>
-            {t('crash.retry')}
-          </button>
-          <button type="button" className="btn" onClick={() => window.location.reload()}>
+          <button
+            type="button"
+            className="btn btn-primary"
+            onClick={() => window.location.reload()}
+          >
             {t('crash.reload')}
           </button>
+          {!stale && (
+            <button type="button" className="btn" onClick={onRetry}>
+              {t('crash.retry')}
+            </button>
+          )}
         </div>
       </div>
     </div>
diff --git a/apps/desktop/src/renderer/src/components/common/LazyBoundary.tsx b/apps/desktop/src/renderer/src/components/common/LazyBoundary.tsx
new file mode 100644
index 00000000..29d6c104
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/common/LazyBoundary.tsx
@@ -0,0 +1,75 @@
+import { Suspense, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ErrorBoundary } from './ErrorBoundary';
+
+/**
+ * Whether an error is a dynamic-import failure — the chunk behind a `lazy()` could not be fetched.
+ *
+ * Worth distinguishing because the remedy is the opposite of the usual one: the page is holding a hashed chunk URL that
+ * no longer exists on disk (the app was rebuilt or updated while this window stayed open), so **retrying re-requests the
+ * same dead URL and fails again**. Only a reload — which re-reads the entry and picks up current hashes — recovers.
+ *
+ * The message differs per engine, hence matching several forms rather than one.
+ */
+export function isChunkLoadError(err: Error): boolean {
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch dynamically imported module') || // Chromium (Electron)
+    msg.includes('error loading dynamically imported module') || // Firefox
+    msg.includes('importing a module script failed') || // Safari
+    msg.includes('unable to preload') // Vite's preload helper
+  );
+}
+
+/**
+ * Suspense + an error boundary around a `lazy()` subtree.
+ *
+ * `Suspense` alone only covers the *pending* half of a lazy import: if the chunk fails to load, the promise rejects and
+ * the error propagates to the nearest boundary. With no boundary in between it reaches the root one and takes the whole
+ * app down — a Monaco snippet failing to load should not cost the user the comment thread around it. So each lazy
+ * subtree gets its own boundary, and the failure stays inside the pane that could not load.
+ */
+export function LazyBoundary({
+  label,
+  loading,
+  children,
+}: {
+  /** Names the failing region in logs (see ErrorBoundary). */
+  label: string;
+  /** Rendered while the chunk is in flight. */
+  loading: ReactNode;
+  children: ReactNode;
+}) {
+  const { t } = useTranslation();
+  return (
+    <ErrorBoundary
+      label={label}
+      fallback={(err, reset) => (
+        <div className="lazy-boundary-error">
+          <p>{t('lazyLoad.failed')}</p>
+          <p className="muted">
+            {isChunkLoadError(err) ? t('lazyLoad.staleHint') : t('lazyLoad.genericHint')}
+          </p>
+          <div className="lazy-boundary-actions">
+            {/* Retry is offered only when it can actually work: for a stale chunk it would re-request the same dead
+                URL, so that case leads with reload instead. */}
+            {!isChunkLoadError(err) && (
+              <button type="button" className="btn btn-sm" onClick={reset}>
+                {t('crash.retry')}
+              </button>
+            )}
+            <button
+              type="button"
+              className="btn btn-sm btn-primary"
+              onClick={() => window.location.reload()}
+            >
+              {t('crash.reload')}
+            </button>
+          </div>
+        </div>
+      )}
+    >
+      <Suspense fallback={loading}>{children}</Suspense>
+    </ErrorBoundary>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/common/index.ts b/apps/desktop/src/renderer/src/components/common/index.ts
index 781175ee..f9ab8137 100644
--- a/apps/desktop/src/renderer/src/components/common/index.ts
+++ b/apps/desktop/src/renderer/src/components/common/index.ts
@@ -7,6 +7,7 @@ export * from './Avatar';
 export * from './BitbucketImage';
 export * from './ConfirmModal';
 export * from './ErrorBoundary';
+export * from './LazyBoundary';
 export * from './LlmProviderIcon';
 export * from './Loading';
 export * from './MermaidDiagram';
diff --git a/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx b/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
index 04155f61..343acb81 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { lazy, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import type {
   LocalPrStatus,
@@ -10,7 +10,7 @@ import type {
 } from '@meebox/shared';
 import { invoke } from '../../../api';
 import { useDraftsForPr } from '../../../stores/drafts-store';
-import { PaneLoading } from '../../common';
+import { LazyBoundary, PaneLoading } from '../../common';
 import { ActivityPanel } from './tabs/activity/ActivityPanel';
 import { CommitsPanel } from './tabs/CommitsPanel';
 // Monaco editor (~10MB) lazy-loaded: the DiffView chunk is fetched only when actually switching to the Diff tab,
@@ -211,7 +211,10 @@ export function PrPanel({
         {/* keep-alive: each tab mounts only on first visit, then stays alive with only CSS show/hide (see KeepAliveTab).
             Switching away and back is instant, no refetch, embedded Monaco / scroll position / expanded state all preserved, eliminating switch jitter. */}
         <KeepAliveTab active={tab === 'diff'}>
-          <Suspense fallback={<PaneLoading label={t('mainPane.loadingEditor')} />}>
+          <LazyBoundary
+            label="DiffView"
+            loading={<PaneLoading label={t('mainPane.loadingEditor')} />}
+          >
             <DiffView
               pr={pr}
               renderSideBySide={renderSideBySide}
@@ -225,7 +228,7 @@ export function PrPanel({
               onCommitViewConsumed={() => setPendingCommitView(null)}
               onViewCommitScopeChange={onViewCommitScopeChange}
             />
-          </Suspense>
+          </LazyBoundary>
         </KeepAliveTab>
         <KeepAliveTab active={tab === 'activity'}>
           <ActivityPanel
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
index 7251b145..1662690d 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useMemo } from 'react';
+import { lazy, useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 import type { PlatformUser, PrComment, PrCommentAnchor, StoredPullRequest } from '@meebox/shared';
 import i18n from '../../../../../i18n';
@@ -8,6 +8,7 @@ import {
   makeBitbucketImageFor,
   ChatIcon,
   ConfirmModal,
+  LazyBoundary,
   mermaidComponents,
 } from '../../../../common';
 import { CommentEditEditor } from './CommentEditEditor';
@@ -146,11 +147,12 @@ export function CommentItem({
   // File-level comments (no line) have no single line to show → skip the code context.
   const inlineCode =
     comment.anchor && comment.anchor.line != null && depth === 0 ? (
-      <Suspense
-        fallback={<div className="pane-loading muted">{t('commentsPanel.loadingCodeContext')}</div>}
+      <LazyBoundary
+        label="InlineCodeContext"
+        loading={<div className="pane-loading muted">{t('commentsPanel.loadingCodeContext')}</div>}
       >
         <InlineCodeContext pr={pr} anchor={comment.anchor} autoExpand={autoExpandCode} />
-      </Suspense>
+      </LazyBoundary>
     ) : null;
 
   // Edit mode: textarea replaces the markdown body in place; non-edit mode: render markdown
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index e4da190c..8a4be21d 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -329,6 +329,8 @@
     "hint": "Ein Neuladen behebt das in der Regel. Tritt es wiederholt auf, benennen die Details unten und das Anwendungsprotokoll (meebox.log) die Ursache.",
     "reload": "Neu laden",
     "retry": "Erneut versuchen",
+    "staleHint": "Ein Teil der Oberfläche konnte nicht mehr geladen werden — das passiert, wenn die Anwendung bei geöffnetem Fenster aktualisiert oder neu gebaut wird. Ein Neuladen übernimmt die aktuelle Version.",
+    "staleTitle": "Die Anwendungsdateien haben sich geändert, seit dieses Fenster geöffnet wurde",
     "title": "Beim Rendern der Oberfläche ist ein Fehler aufgetreten"
   },
   "diffSearchPanel": {
@@ -502,6 +504,11 @@
     "expandTitle": "Code um die verankerte Zeile erweitern",
     "loading": "Code-Kontext wird geladen…"
   },
+  "lazyLoad": {
+    "failed": "Dieser Teil der Oberfläche konnte nicht geladen werden.",
+    "genericHint": "Ein erneuter Versuch hilft meistens; schlägt es weiterhin fehl, laden Sie das Fenster neu.",
+    "staleHint": "Die Anwendungsdateien haben sich seit dem Öffnen dieses Fensters geändert — meist durch ein Update oder einen Neubau. Ein Neuladen übernimmt die aktuelle Version."
+  },
   "llmProfileForm": {
     "apiKeyOptionalPlaceholder": "Dieser Provider benötigt keinen Schlüssel (leer lassen)",
     "cliCommandFallback": "Kommandozeilen-Tool",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index 3f981bd5..ddff7557 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -329,6 +329,8 @@
     "hint": "Reloading usually resolves it. If it keeps happening, the details below and the application log (meebox.log) identify the cause.",
     "reload": "Reload",
     "retry": "Retry",
+    "staleHint": "Part of the interface could no longer be loaded, which happens when the app is updated or rebuilt while a window stays open. Reloading picks up the current version.",
+    "staleTitle": "The app files changed since this window opened",
     "title": "Something went wrong rendering the interface"
   },
   "diffSearchPanel": {
@@ -502,6 +504,11 @@
     "expandTitle": "Expand code around the anchored line",
     "loading": "Loading code context…"
   },
+  "lazyLoad": {
+    "failed": "This part of the interface could not be loaded.",
+    "genericHint": "Retrying often works; if it keeps failing, reload the window.",
+    "staleHint": "The app files changed since this window opened — usually an update or a rebuild. Reloading picks up the current version."
+  },
   "llmProfileForm": {
     "apiKeyOptionalPlaceholder": "This provider needs no key (leave empty)",
     "cliCommandFallback": "command-line tool",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index 71f160b1..1b440396 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -323,6 +323,8 @@
     "hint": "再読み込みで通常は復旧します。繰り返し発生する場合は、以下の詳細とアプリケーションログ（meebox.log）で原因を特定できます。",
     "reload": "再読み込み",
     "retry": "再試行",
+    "staleHint": "画面の一部を読み込めなくなりました。ウィンドウを開いたままアプリが更新または再ビルドされた場合に発生します。再読み込みすると最新版が読み込まれます。",
+    "staleTitle": "ウィンドウを開いた後にアプリのファイルが変更されました",
     "title": "画面の描画中にエラーが発生しました"
   },
   "diffSearchPanel": {
@@ -491,6 +493,11 @@
     "expandTitle": "アンカー行の前後のコードを展開",
     "loading": "コードコンテキストを読み込み中…"
   },
+  "lazyLoad": {
+    "failed": "この部分の画面を読み込めませんでした。",
+    "genericHint": "再試行で復旧することが多く、繰り返し失敗する場合はウィンドウを再読み込みしてください。",
+    "staleHint": "ウィンドウを開いた後にアプリのファイルが変更されました（通常は更新または再ビルド）。再読み込みすると最新版が読み込まれます。"
+  },
   "llmProfileForm": {
     "apiKeyOptionalPlaceholder": "このプロバイダーはキー不要です（空のままに）",
     "cliCommandFallback": "コマンドラインツール",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index 48503162..daf19ceb 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -323,6 +323,8 @@
     "hint": "重新加载通常即可恢复。若反复出现，下方详情与应用日志（meebox.log）可定位原因。",
     "reload": "重新加载",
     "retry": "重试",
+    "staleHint": "部分界面已无法加载——通常是窗口开着时应用被更新或重新构建所致。重新加载即可载入当前版本。",
+    "staleTitle": "应用文件在窗口打开后发生了变化",
     "title": "界面渲染出错"
   },
   "diffSearchPanel": {
@@ -491,6 +493,11 @@
     "expandTitle": "展开锚定行前后代码",
     "loading": "加载代码上下文…"
   },
+  "lazyLoad": {
+    "failed": "这部分界面加载失败。",
+    "genericHint": "重试通常可以恢复；若持续失败，请重新加载窗口。",
+    "staleHint": "应用文件在窗口打开后发生了变化——通常是更新或重新构建所致。重新加载即可载入当前版本。"
+  },
   "llmProfileForm": {
     "apiKeyOptionalPlaceholder": "该 provider 无需密钥（留空）",
     "cliCommandFallback": "命令行",
diff --git a/apps/desktop/src/renderer/src/styles/common/crash.scss b/apps/desktop/src/renderer/src/styles/common/crash.scss
index 837dfde4..5546af5f 100644
--- a/apps/desktop/src/renderer/src/styles/common/crash.scss
+++ b/apps/desktop/src/renderer/src/styles/common/crash.scss
@@ -56,3 +56,22 @@
   display: flex;
   gap: $space-2;
 }
+
+// Failure of one lazily-loaded pane (LazyBoundary). Sized to sit inside whatever region failed — a comment's code
+// context, the diff pane — rather than taking over the window like .app-crash does.
+.lazy-boundary-error {
+  padding: $space-8;
+  color: $text-muted;
+  font-size: $fs-xs;
+  line-height: 1.5;
+
+  p {
+    margin: 0 0 $space-2;
+  }
+}
+
+.lazy-boundary-actions {
+  display: flex;
+  gap: $space-2;
+  margin-top: $space-3;
+}
diff --git a/docs/arch/03-gui/01-ui-interaction.md b/docs/arch/03-gui/01-ui-interaction.md
index ffb36453..e89b6ab7 100644
--- a/docs/arch/03-gui/01-ui-interaction.md
+++ b/docs/arch/03-gui/01-ui-interaction.md
@@ -90,10 +90,11 @@ Platform differences are decided via `AppInfo.platform` (delivered by the main p
 - **Second-level modal backdrop click only closes its own layer**: for nested modals (connection/LLM/proxy editing, confirm dialogs) the backdrop click calls `stopPropagation`,
   so it does not bubble up to close the outer settings modal (including createPortal confirm dialogs — React synthetic events still bubble along the component tree).
 - **Action-level toast vs. full-screen error**: a failed remote action (review decision/merge/publish) raises a toast, distinct from the full-screen error of a fatal bootstrap failure.
-- **Never a blank window (three layers of failure containment)**: a renderer failure must always land on a readable screen, never on the window's bare background — which is indistinguishable from a hung app and has no way back short of a restart. Each layer covers what the one below it structurally cannot see:
+- **Never a blank window (four layers of failure containment)**: a renderer failure must always land on a readable screen, never on the window's bare background — which is indistinguishable from a hung app and has no way back short of a restart. Each layer covers what the one below it structurally cannot see:
   1. **Render-phase errors** → the root `ErrorBoundary` in `main.tsx` (fallback `AppCrashScreen`, offering retry / reload). Without one, any error thrown while rendering unmounts the whole tree and empties `#root`. The boundary also relays the stack through `log:write`, since the renderer console is never written to file and a caught render error is not an uncaught window error either — so a crash would otherwise leave nothing on disk to diagnose.
   2. **Failures before React mounts** → `boot-guard.ts`, imported **first** in `main.tsx` so it is armed before any other module can throw. A module that fails while initializing (i18n / theme / the app bundle) takes down the entry before `render()` runs, leaving no React and therefore no boundary. The guard paints a plain-DOM recovery screen — no React, no i18n, no stylesheet, since each of those is a candidate cause — on an uncaught error or when `#root` is still empty after a timeout.
-  3. **Renderer process death** → `WindowManager.installCrashRecovery` in main (`render-process-gone` / `did-fail-load`), which logs and reloads the window with a bounded retry budget. When the process itself dies (OOM, GPU fault, a native crash), no in-page JavaScript survives to report it; only main is left watching. `unresponsive` is logged but deliberately not recovered — it usually resolves on its own, and reloading would discard the user's in-flight state.
+  3. **A lazily-loaded subtree failing to load** → `LazyBoundary` (Suspense + a boundary) around each `lazy()` site. `Suspense` alone covers only the *pending* half of a dynamic import; a rejected chunk propagates to the nearest boundary, and with none in between it reaches the root one — so a Monaco snippet that fails to fetch costs the user the entire app. Each lazy subtree therefore owns a boundary and the failure stays inside the pane that could not load. A **stale chunk** (the window holds a hashed module URL the rebuilt/updated app no longer has) is called out separately by `isChunkLoadError`, because there retrying re-requests the same dead URL and only a reload recovers — the fallback and the root crash screen both lead with reload in that case rather than offering a button that cannot work.
+  4. **Renderer process death** → `WindowManager.installCrashRecovery` in main (`render-process-gone` / `did-fail-load`), which logs and reloads the window with a bounded retry budget. When the process itself dies (OOM, GPU fault, a native crash), no in-page JavaScript survives to report it; only main is left watching. `unresponsive` is logged but deliberately not recovered — it usually resolves on its own, and reloading would discard the user's in-flight state.
 - **Auto-refresh on window focus**: when the window regains focus, proactively fetch PR meta once (to follow the "switch to the platform, make edits, then switch back" scenario).
 - **Layout preferences persisted**: sidebar/chat width and collapse state, diff view mode, etc. are stored in localStorage.
 

From 3ead85aefb8b63c8ea0019bb7c6d6527049e68a2 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 15:34:59 +0800
Subject: [PATCH 09/17] chore(pragent): upgrade the embedded runtime to
 pr-agent 0.45.0

Assessed by diffing the 0.45.0 wheel against the vendored 0.39.0 rather than
reading release notes: 82 of 123 files changed, including all eight we patch.

Two patches are retired because upstream fixed the bugs. extract_hunk_headers
now defaults an omitted hunk size to 1 instead of 0, so a single-line change no
longer renders its old value as a still-present context line; get_diff_files now
skips a file that fails to decode instead of crashing the review on a binary.
Both were confirmed against the installed runtime, not assumed. The four
remaining patches were probed under 0.45.0 and all apply -- none silently
skipped by the version guard -- and get_line_link's call sites are unchanged, so
the structured /review anchor still works.

Three upstream features now default to on and append to the very output this app
parses, which would have surfaced as bogus findings rather than as an obvious
break: persistent_finding_state (upstream cross-run state the app already owns
through drafts, finding closures and re-review verdicts) and two coverage
footers. They are pinned off in buildPragentEnv, verified to be true by default
and false under the override.

Telemetry is new in 0.45.0 but ships disabled with no built-in endpoint, so it
needs no handling.

Also bumps the development version to 0.12.0-dev.

Not exercised end to end: 0.45.0 revises six prompt files, and whether the
rendered markdown still matches the parser needs a real /describe /review /ask
against a live PR.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 CHANGELOG.zh-CN.md                            |  1 +
 apps/desktop/package.json                     |  2 +-
 apps/desktop/scripts/pragent-runtime.json     |  2 +-
 .../meebox_pragent_shim/__init__.py           | 13 +--
 .../patches/git_patch_processing.py           | 88 -------------------
 .../patches/local_git_provider.py             | 67 ++------------
 .../meebox_pragent_shim/runtime.py            |  2 +-
 docs/arch/02-agent/05-pragent-runtime.md      |  9 +-
 package-lock.json                             |  2 +-
 packages/pr-agent-bridge/src/env.ts           | 15 ++++
 11 files changed, 38 insertions(+), 164 deletions(-)
 delete mode 100644 apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/git_patch_processing.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index afa860cd..4f18dd6b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
+- The bundled review engine is now pr-agent 0.45.0 (from 0.39.0). Two long-standing local fixes are no longer needed — a single-line file change is rendered correctly upstream now, and a binary file no longer has to be worked around — and its YAML handling is more tolerant of imperfect model output.
 - Mentions now render as a pill instead of blending into the surrounding text, so it is obvious at a glance when someone is named — on the activity page, in the inline diff comments, in drafts, and in the PR description alike.
 - Proxy settings now take a list of **direct connections**: hosts that bypass the proxy and connect straight out, so an internal code platform, its git remote, or a self-hosted model stays reachable while everything else still goes through the proxy. Uses the familiar `NO_PROXY` syntax (a domain covers its subdomains), and applies to every outbound path at once — REST, git and the LLM call.
 - A review that fails because the model is unavailable now says so and tells you what to do — with a local CLI provider (claude / codex) the model comes from that CLI's own configuration, so it has to be changed there.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index a0091c78..fa17c636 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,6 +9,7 @@
 
 ### ✨ 新增
 
+- 内置评审引擎升级至 pr-agent 0.45.0（原 0.39.0）。两处长期存在的本地修补不再需要——单行文件变更在上游已渲染正确，二进制文件也无需再绕开——其 YAML 解析对不规范的模型输出也更宽容。
 - @提及 改为胶囊标签展示，不再淹没在正文里，一眼即可看出点到了谁——活动页、内联 diff 评论、草稿与 PR 描述一致生效。
 - 代理设置新增**直连地址**列表：列出的地址跳过代理直接连接，内网代码平台、它的 git 远端或自建模型服务因此保持可达，其余流量照常走代理。沿用通行的 `NO_PROXY` 写法（填域名同时覆盖子域），并对所有出站路径一并生效——REST、git 与 LLM 调用。
 - 因模型不可用而失败的评审现在会明确说明，并给出处理方式——使用本地 CLI 供应商（claude / codex）时，模型来自该 CLI 自身的配置，需要在那里更换。
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 6f6f0220..b5ea2309 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@meebox/desktop",
-  "version": "0.11.3-dev",
+  "version": "0.12.0-dev",
   "private": true,
   "description": "meebox Electron desktop app",
   "author": {
diff --git a/apps/desktop/scripts/pragent-runtime.json b/apps/desktop/scripts/pragent-runtime.json
index 0216b6ef..99f495d7 100644
--- a/apps/desktop/scripts/pragent-runtime.json
+++ b/apps/desktop/scripts/pragent-runtime.json
@@ -8,6 +8,6 @@
   },
   "prAgent": {
     "_comment": "嵌入式运行时安装的 pr-agent 版本（pinned）；须与 sitecustomize.py 的 _EXPECTED_PRAGENT_VERSION 对齐，升级时两处同步",
-    "version": "0.39.0"
+    "version": "0.45.0"
   }
 }
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/__init__.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/__init__.py
index 9a57b442..061d8203 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/__init__.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/__init__.py
@@ -10,7 +10,6 @@
 applied it silently degrades, never letting a shim exception block the flow.
 """
 from .patches.describe_assessment import patch as _patch_describe_assessment
-from .patches.git_patch_processing import patch as _patch_git_patch_processing
 from .patches.litellm_handler import patch as _patch_litellm_handler
 from .patches.load_yaml import patch as _patch_load_yaml
 from .patches.local_git_provider import patch as _patch_local_git_provider
@@ -18,9 +17,8 @@
 
 
 def apply() -> None:
-    # local_git_provider two patches merged into one patch_fn (registering multiple finders for the
-    # same module shadows each other; only the meta_path[0] one takes effect): binary-safe
-    # get_diff_files + get_line_link anchor.
+    # local_git_provider: inject get_line_link (the structured /review anchor) + get_repo_file_content. Registered as a
+    # single patch_fn because multiple finders on one module shadow each other (only meta_path[0] takes effect).
     _register_post_import(
         "pr_agent.git_providers.local_git_provider",
         _patch_local_git_provider,
@@ -40,11 +38,4 @@ def apply() -> None:
         "pr_agent.tools.pr_description",
         _patch_describe_assessment,
     )
-    # git patch processing: fix the phantom "unchanged" line on single-line hunks (omitted hunk size defaulted to 0
-    # instead of 1), which made single-line file changes look like they contained both the old and new value. Self-
-    # disabling once upstream fixes it — see patches/git_patch_processing.py.
-    _register_post_import(
-        "pr_agent.algo.git_patch_processing",
-        _patch_git_patch_processing,
-    )
     _debug("meebox shim loaded")
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/git_patch_processing.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/git_patch_processing.py
deleted file mode 100644
index cfe29630..00000000
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/git_patch_processing.py
+++ /dev/null
@@ -1,88 +0,0 @@
-"""git_patch_processing patch (version-guarded, self-disabling): fix phantom "unchanged" line on single-line hunks.
-
-===============================================================================================================
-MAINTENANCE NOTE — remove this shim once pr-agent fixes the bug upstream.
----------------------------------------------------------------------------------------------------------------
-Bug: pr-agent renders a single-line file change (e.g. VERSION `1.5.2` -> `1.5.3`, a hash/checksum file, any
-hunk whose OLD side is exactly one line) so the model sees the OLD value as a still-present, unchanged line —
-it then wrongly reports "the file now contains both the old and new value".
-
-Root cause (in pr_agent/algo/git_patch_processing.py):
-  1. git omits the hunk line-count when it is 1, so a single-line change emits `@@ -1 +1 @@`
-     (which per the unified-diff spec means `@@ -1,1 +1,1 @@`).
-  2. `extract_hunk_headers` coerces every missing regex group to 0, so the omitted size becomes size1=0
-     (it should be 1).
-  3. `process_patch_lines`' trailing-context slice `file_original_lines[start1 + size1 - 1 : ...]` then reads
-     from `1 + 0 - 1 = 0` — i.e. re-reads the CHANGED line itself — and appends it as a phantom unchanged
-     context line, which `decouple_and_convert_to_hunks_with_lines_numbers` places into `__new hunk__`.
-
-Fix: default an OMITTED hunk size to 1 (spec-correct) instead of 0, keeping an EXPLICIT 0 (e.g. `@@ -0,0 +1 @@`
-new-file case) as 0. This makes the trailing-context slice start after the hunk, so no phantom line is emitted.
-
-Upstream status (re-checked at pr-agent 0.39.0): still present — `extract_hunk_headers` is byte-identical to
-0.36.0 and still coerces the omitted size to 0; no upstream issue/PR addresses it (PRs #2322 / #2330 guard a
-DIFFERENT None — a fully malformed `@@` line where `match` itself is None — not the size default).
-
-Removal / upgrade checklist:
-  * This patch is BOTH version-guarded (only applies to the pinned _EXPECTED_PRAGENT_VERSION) AND self-disabling
-    (it probes the live `extract_hunk_headers`; if upstream already returns size1=1 for `@@ -1 +1 @@`, it does
-    nothing). So on a pr-agent bump, re-verify: if the probe reports the bug is gone, DELETE this file and its
-    registration in `../__init__` apply(); if it persists, bump _EXPECTED_PRAGENT_VERSION and keep it.
-  * Reproduce quickly against the vendored runtime with `MEEBOX_SHIM_DEBUG=1` (the probe logs which branch it took).
-===============================================================================================================
-"""
-from ..runtime import _EXPECTED_PRAGENT_VERSION, _debug, _pragent_version, _warn
-
-
-def patch(module) -> None:
-    # Version guard: this reimplementation mirrors the pinned pr-agent's extract_hunk_headers structure; on a
-    # version mismatch skip rather than risk a wrong reimplementation (safe degradation, consistent with the
-    # other shim patches). The warning is the "pay attention on upgrade" signal.
-    installed = _pragent_version()
-    if installed != _EXPECTED_PRAGENT_VERSION:
-        _warn(
-            f"pr-agent {installed} does not match the {_EXPECTED_PRAGENT_VERSION} that the meebox patch is "
-            "adapted for; git_patch_processing patch skipped (single-line-hunk phantom-line fix disabled). If "
-            "this is an intentional upgrade, sync runtime.py's _EXPECTED_PRAGENT_VERSION + pragent-runtime.json, "
-            "re-verify whether upstream has fixed the omitted-hunk-size bug, and remove this shim if so."
-        )
-        return
-
-    orig_extract = module.extract_hunk_headers
-    re_hunk_header = module.RE_HUNK_HEADER
-
-    # Self-disable if upstream already fixed it: git omits the size for `@@ -1 +1 @@`, so a correct implementation
-    # yields size1 == 1. If the live function already returns a non-zero size here, the bug is gone — do nothing.
-    probe = re_hunk_header.match("@@ -1 +1 @@")
-    try:
-        _, probe_size1, _, _, _ = orig_extract(probe)
-    except Exception as exc:  # noqa: BLE001 - unexpected upstream signature change → skip, don't crash the run
-        _debug(f"git_patch_processing: extract_hunk_headers probe failed ({exc}); patch skipped")
-        return
-    if probe_size1 != 0:
-        _debug(
-            "git_patch_processing: upstream already defaults an omitted hunk size correctly "
-            "(probe size1=%r); phantom-line shim skipped — safe to delete this file" % probe_size1
-        )
-        return
-
-    def extract_hunk_headers(match):
-        # Faithful mirror of upstream extract_hunk_headers, with ONE correction: an omitted hunk line-count
-        # (regex group is None) defaults to 1 per the unified-diff spec — git drops ",N" only when N == 1 —
-        # instead of upstream's blanket 0. An EXPLICIT 0 (present in the text, e.g. the `@@ -0,0 +1 @@` new-file
-        # case) is untouched because its group is "0", not None. Only the two size groups (indices 1 and 3) get
-        # the size default; any other missing group keeps the original 0 fallback.
-        res = list(match.groups())
-        for i in range(len(res)):
-            if res[i] is None:
-                res[i] = 1 if i in (1, 3) else 0
-        try:
-            start1, size1, start2, size2 = map(int, res[:4])
-        except (ValueError, TypeError):  # '@@ -0,0 +1 @@' case (mirrors upstream's bare except)
-            start1, size1, size2 = map(int, res[:3])
-            start2 = 0
-        section_header = res[4]
-        return section_header, size1, size2, start1, start2
-
-    module.extract_hunk_headers = extract_hunk_headers
-    _debug("git_patch_processing: applied single-line-hunk phantom-line fix (omitted hunk size -> 1)")
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
index 62d153ac..a3cd8b5d 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
@@ -1,72 +1,23 @@
-"""LocalGitProvider patch (version-guarded): binary-safe get_diff_files + get_line_link anchor + repo-context file fetch."""
+"""LocalGitProvider patch (version-guarded): get_line_link anchor + dirty-tolerant repo prep + repo-context file fetch."""
 from ..runtime import _EXPECTED_PRAGENT_VERSION, _pragent_version, _warn
 
 
 def patch(module) -> None:
-    """LocalGitProvider.get_diff_files blindly .decode('utf-8') on every diff file, and on a binary
-    file (images / build artifacts / UTF-16 etc., e.g. starting with 0xff) throws UnicodeDecodeError, crashing the whole review.
-    Replace with a binary-safe version: files that fail to decode are skipped (review doesn't handle binaries), the rest of the logic identical to upstream."""
-    # version guard: only patch the pinned pr-agent version; on mismatch skip the whole group (including get_line_link).
+    """Inject the methods LocalGitProvider does not implement: the structured /review anchor (get_line_link),
+    a dirty-tolerant _prepare_repo, labels, and repo-context file reads.
+
+    Binary-safe get_diff_files used to live here too; pr-agent 0.45.0 fixed it upstream (it now skips a file that
+    fails to decode, with a warning), so that override is gone — one less thing to keep in step with upstream.
+    """
+    # version guard: only patch the pinned pr-agent version; on mismatch skip the whole group.
     installed = _pragent_version()
     if installed != _EXPECTED_PRAGENT_VERSION:
         _warn(
             f"pr-agent {installed} does not match the {_EXPECTED_PRAGENT_VERSION} that the meebox patch is adapted for; "
-            "patches skipped (/review line-number anchoring and binary-safe diff disabled). If this is an intentional upgrade, sync "
+            "patches skipped (/review line-number anchoring disabled). If this is an intentional upgrade, sync "
             "runtime.py's _EXPECTED_PRAGENT_VERSION + pragent-runtime.json and re-verify."
         )
         return
-    from pr_agent.algo.types import EDIT_TYPE, FilePatchInfo
-
-    def get_diff_files(self):
-        diffs = self.repo.head.commit.diff(
-            self.repo.merge_base(self.repo.head, self.repo.branches[self.target_branch_name]),
-            create_patch=True,
-            R=True,
-        )
-        diff_files = []
-        for diff_item in diffs:
-            try:
-                original_file_content_str = (
-                    diff_item.a_blob.data_stream.read().decode("utf-8")
-                    if diff_item.a_blob is not None
-                    else ""
-                )
-                new_file_content_str = (
-                    diff_item.b_blob.data_stream.read().decode("utf-8")
-                    if diff_item.b_blob is not None
-                    else ""
-                )
-                patch_str = diff_item.diff.decode("utf-8")
-            except (UnicodeDecodeError, ValueError):
-                # binary file can't be utf-8 decoded → skip this file
-                continue
-            edit_type = EDIT_TYPE.MODIFIED
-            if diff_item.new_file:
-                edit_type = EDIT_TYPE.ADDED
-            elif diff_item.deleted_file:
-                edit_type = EDIT_TYPE.DELETED
-            elif diff_item.renamed_file:
-                edit_type = EDIT_TYPE.RENAMED
-            diff_files.append(
-                FilePatchInfo(
-                    original_file_content_str,
-                    new_file_content_str,
-                    patch_str,
-                    # a deleted file's b_path is None → FilePatchInfo.filename=None, and downstream
-                    # set_file_languages / extract_relevant_lines_str's filename.rsplit/strip
-                    # would crash, and one crash interrupts the whole review's line-snippet extraction (even findings for non-deleted files lose
-                    # code snippets). Fall back to a_path to guarantee filename is never None.
-                    diff_item.b_path or diff_item.a_path,
-                    edit_type=edit_type,
-                    old_filename=None
-                    if diff_item.a_path == diff_item.b_path
-                    else diff_item.a_path,
-                )
-            )
-        self.diff_files = diff_files
-        return diff_files
-
-    module.LocalGitProvider.get_diff_files = get_diff_files
 
     # _prepare_repo: upstream throws "repository is not in a clean state" when repo.is_dirty(). For CLI-mode
     # /ask worktrees we sanitize as needed — truncating the repo's own agent instruction files (CLAUDE.md / AGENTS.md / .cursor rules
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/runtime.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/runtime.py
index 5e5ea899..998e4ccb 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/runtime.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/runtime.py
@@ -15,7 +15,7 @@
 # skipped (safe degradation, preferring to apply fewer patches over applying wrong ones).
 # When upgrading pr-agent: sync this constant + prAgent.version in scripts/pragent-runtime.json
 # (the assemble script verifies the two match and extracts this constant from this file), and re-verify patch behavior.
-_EXPECTED_PRAGENT_VERSION = "0.39.0"
+_EXPECTED_PRAGENT_VERSION = "0.45.0"
 
 # System context "cache break" marker: assembleSystemContext (TS, packages/agent/src/assemble.ts) inserts this string
 # (along with the --- separators on both sides) between the **globally stable prefix** (SOUL/AGENTS/tool directory/memory/user
diff --git a/docs/arch/02-agent/05-pragent-runtime.md b/docs/arch/02-agent/05-pragent-runtime.md
index f253597a..27260a6a 100644
--- a/docs/arch/02-agent/05-pragent-runtime.md
+++ b/docs/arch/02-agent/05-pragent-runtime.md
@@ -56,16 +56,19 @@ Design principles:
 - **Version guard**: patches depend on a specific pr-agent version's internal implementation → if `_EXPECTED_PRAGENT_VERSION` ≠ the actually installed version at runtime,
   **skip all patches and emit a stderr WARNING** (safe degradation); at build time it hard-checks the shim constant == the manifest version, failing outright on mismatch.
 
-Current patches:
-- **Binary-safe diff**: the original `get_diff_files` blindly utf-8-decodes every file and crashes on binary → changed to skip on decode failure.
+Current patches (pinned pr-agent **0.45.0**):
 - **anchor line numbers** (details in [Review workflow](../01-platform/03-review-workflow.md)): patch `get_line_link` to return `meebox:///<file>#L<s>-L<e>`,
   letting `/review`'s key_issues render with a structured file:line.
 - **Anthropic drops temperature**: new Claude models deprecate temperature, so all `anthropic/*` are put into the "don't send temperature" set.
 - **load_yaml tolerance**: an anchor marker taking a whole line breaks YAML → on parse failure, strip the marker and retry, avoiding a whole review crash.
-- **repo-context file fetch**: pr-agent 0.39.0 defaults `repo_context_files = ["AGENTS.md"]`, but `LocalGitProvider` inherits the base no-op `get_repo_file_content` → the feature is skipped with a per-run WARNING. Implement it by reading the blob from the base branch's tree (`git show <target_branch>:<path>`, never the working tree), so `/review /describe /improve` inject the reviewed repo's `AGENTS.md`/etc. as `<instruction_files>`; a missing file degrades to `""`.
+- **repo-context file fetch**: pr-agent defaults `repo_context_files = ["AGENTS.md"]`, but `LocalGitProvider` inherits the base no-op `get_repo_file_content` → the feature is skipped with a per-run WARNING. Implement it by reading the blob from the base branch's tree (`git show <target_branch>:<path>`, never the working tree), so `/review /describe /improve` inject the reviewed repo's `AGENTS.md`/etc. as `<instruction_files>`; a missing file degrades to `""`.
 - **Local CLI provider**: when `MEEBOX_CLI_MODE` is set, replace `chat_completion` wholesale with the "call the local CLI" version (see below).
 - **token usage collection**: see below.
 
+**Retired patches** (kept as a record, because "why is this no longer patched" is the question an upgrade raises): *binary-safe diff* and the *single-line-hunk phantom line* were both **fixed upstream in 0.45.0** — `get_diff_files` now skips a file that fails to decode, and `extract_hunk_headers` defaults an omitted hunk size to 1 rather than 0. Both were verified against the installed runtime before deletion, not assumed from release notes.
+
+**Upstream defaults that must stay pinned**: 0.45.0 turned on three features that append to the output this app *parses* — `pr_reviewer.persistent_finding_state` (a "resolved findings" section carrying upstream's own cross-run state, which the app already owns via drafts / finding closures / re-review verdicts), and two coverage footers. They are forced off in `buildPragentEnv` rather than left at their defaults. **Re-check this list on every upgrade**: a new default that adds a section is not a free improvement here — it lands as a bogus finding.
+
 ### Real token usage
 
 Inline-wrap pr-agent's `_get_completion`, take `prompt/completion/total_tokens` from the returned `response.usage`,
diff --git a/package-lock.json b/package-lock.json
index 7cf37584..71027e61 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -32,7 +32,7 @@
     },
     "apps/desktop": {
       "name": "@meebox/desktop",
-      "version": "0.11.3-dev",
+      "version": "0.12.0-dev",
       "dependencies": {
         "@iconify-json/material-icon-theme": "^1.2.66",
         "@iconify/react": "^5.2.1",
diff --git a/packages/pr-agent-bridge/src/env.ts b/packages/pr-agent-bridge/src/env.ts
index ed637cbf..78caec30 100644
--- a/packages/pr-agent-bridge/src/env.ts
+++ b/packages/pr-agent-bridge/src/env.ts
@@ -78,6 +78,16 @@ function normalizeModel(provider: LlmProfile['provider'], model: string): string
  * - `CONFIG__FALLBACK_MODELS=[]`: pr-agent configures a fallback by default (usually pointing at the OpenAI family),
  *   and after the main model fails it automatically tries OpenAI with a dummy key, polluting the log and easily misread as "OpenAI misconfigured".
  *   We already specify the provider explicitly, so a fallback is unnecessary
+ *
+ * Plus a group that pins **upstream features whose defaults changed under us**. The app parses `/review` and
+ * `/describe` output as structured markdown (see poller/parse-output), so anything upstream appends to that output is
+ * not a free improvement — it lands as a bogus finding or a stray section. These are therefore turned off explicitly
+ * rather than left at whatever the pinned pr-agent version happens to default to (re-check on every upgrade):
+ * - `PR_REVIEWER__PERSISTENT_FINDING_STATE=false` (new in 0.45, defaults **true**): would append a "resolved findings"
+ *   section carrying cross-run state. The app already owns that concept — drafts, finding closures, re-review verdicts
+ *   — so upstream's version would both duplicate it and parse as extra findings.
+ * - `PR_REVIEWER__ENABLE_REVIEW_COVERAGE_FOOTER=false` / `PR_CODE_SUGGESTIONS__ENABLE_SUGGESTIONS_COVERAGE_FOOTER=false`
+ *   (new in 0.45, both default **true**): a footer appended to the body, which the parser would read as content.
  */
 export function buildPragentEnv(profile: LlmProfile, maxModelTokens?: number): Record<string, string> {
   const env: Record<string, string> = {};
@@ -88,6 +98,11 @@ export function buildPragentEnv(profile: LlmProfile, maxModelTokens?: number): R
   env['CONFIG__MAX_MODEL_TOKENS'] = String(contextTokens);
   env['CONFIG__CUSTOM_MODEL_MAX_TOKENS'] = String(contextTokens);
   env['CONFIG__FALLBACK_MODELS'] = '[]';
+  // Pin upstream output-shaping features that default on (see the doc comment above): the app parses this output, so
+  // extra sections/footers are corruption rather than enrichment.
+  env['PR_REVIEWER__PERSISTENT_FINDING_STATE'] = 'false';
+  env['PR_REVIEWER__ENABLE_REVIEW_COVERAGE_FOOTER'] = 'false';
+  env['PR_CODE_SUGGESTIONS__ENABLE_SUGGESTIONS_COVERAGE_FOOTER'] = 'false';
   // On import litellm fetches the remote model price table over the network (raw.githubusercontent.com); on an intranet/weak network
   // the SSL timeout slows startup and floods warnings. We only take the real token count (from API response.usage),
   // don't need the price table → force using only the in-package local backup, no network at all. See sitecustomize's usage callback.

From 91702d0c24a01406e96a4853ca37bc72eca621db Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 15:54:16 +0800
Subject: [PATCH 10/17] fix(pragent): correct the describe file walkthrough and
 stop quoted headings splitting it

Three defects surfaced by a real /describe run. None was introduced by the
0.45.0 upgrade -- the relevant upstream code is identical in 0.39.0 -- they had
simply never been noticed.

Line counts rendered as "+-1/--1". FilePatchInfo defaults num_plus_lines and
num_minus_lines to -1 and only the real platform providers fill them in;
LocalGitProvider does not. get_diff_files is wrapped rather than reimplemented
to backfill both from the patch text, counted by the same rule the platform
providers use, so upstream keeps owning how the diff is produced.

Every walkthrough link pointed at "#L-1". Upstream passes relevant_line_start=-1
to mean "the whole file", and -1 is truthy, so a plain falsiness check let it
through. The resulting fragment was then rejected by the anchor parser entirely
(its line group accepts only digits), so the link yielded no anchor at all --
the fix therefore also recovers a path-level anchor for these rows.

A merge tail in the PR description tore the result apart. `# Conflicts:` and the
`#<tab>path` lines beneath it are markdown H1s, and /describe frames its own
structure at H3, so the author's prose outranked the tool's structure and
produced sections named after conflicted files. Section splitting now takes a
minimum heading level, and describe splits only at H3 or deeper: quoted content
stays inside the section that quotes it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  3 ++
 CHANGELOG.zh-CN.md                            |  3 ++
 .../patches/local_git_provider.py             | 41 ++++++++++++++--
 docs/arch/02-agent/05-pragent-runtime.md      |  3 +-
 packages/poller/src/parse-output.ts           | 20 ++++++--
 packages/poller/tests/parse-output.test.ts    | 49 +++++++++++++++++--
 6 files changed, 107 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f18dd6b..d623b4c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,9 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### 🔧 Fixed
 
+- The file list in a generated PR description now shows the real number of added and removed lines per file, instead of `+-1/--1`.
+- Links in that file list now open the file instead of pointing at a non-existent line, so clicking through works.
+- A PR description ending in a git merge tail (`# Conflicts:` and the file lines under it) no longer breaks up the generated description — those lines are part of the quoted description, not headings of their own.
 - A part of the interface that loads on demand — the diff editor, a comment's inline code context — no longer takes the whole app down with it when it fails to load; the failure now stays inside that pane. If it failed because the app was updated or rebuilt while the window was open, it says so and offers to reload, which is the only thing that actually helps in that case.
 - A failed review now shows the provider's actual error instead of only "all fallback models failed" — the real cause (an unavailable model, an expired login, an exhausted quota) was previously swallowed and never reached the run card.
 - A local CLI provider that exits successfully but returns an empty reply is now reported as a failure naming that cause, rather than as an unexplained LLM failure.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index fa17c636..d3c62396 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -16,6 +16,9 @@
 
 ### 🔧 修复
 
+- 生成的 PR 描述中，文件清单现在显示每个文件真实的增删行数，不再是 `+-1/--1`。
+- 该清单中的链接现在指向文件本身，而非一个不存在的行号，点击可正常跳转。
+- PR 描述末尾带有 git 合并残留（`# Conflicts:` 及其下的文件行）时，生成的描述不再被切碎——那些行属于被引用的描述正文，而不是标题。
 - 按需加载的界面部分——diff 编辑器、评论中的内联代码上下文——加载失败时不再拖垮整个应用，失败被限制在该区域内。若失败原因是窗口开着时应用被更新或重新构建，会明确说明并提供重新加载，那也是这种情况下唯一有效的操作。
 - 评审失败时现在会展示供应商返回的真实错误，而不再只有一句「所有备选模型均调用失败」——真正的原因（模型不可用、登录过期、额度耗尽）此前被吞掉，从未出现在运行卡片上。
 - 本地 CLI 供应商正常退出却返回空回复时，现在会作为失败上报并指明该原因，而不再表现为一次无从解释的 LLM 调用失败。
diff --git a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
index a3cd8b5d..9c88511f 100644
--- a/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
+++ b/apps/desktop/scripts/pragent-shim/meebox_pragent_shim/patches/local_git_provider.py
@@ -38,18 +38,51 @@ def _prepare_repo(self):
     # and parse-output derives the structured anchor from the link (same source as real providers, not dependent on the model self-reporting a marker).
     from urllib.parse import quote
 
+    def _line_no(value):
+        """A usable 1-based line number, or 0 for "no specific line"."""
+        try:
+            n = int(value)
+        except (TypeError, ValueError):
+            return 0
+        return n if n > 0 else 0
+
     def get_line_link(self, relevant_file, relevant_line_start, relevant_line_end=None):
         f = quote((relevant_file or "").lstrip("/"), safe="/")
         if not f:
             return ""
-        if not relevant_line_start:
+        # `-1` is upstream's "whole file, no particular line" (pr_description passes it for every File Walkthrough
+        # row). It is truthy, so a plain falsiness check let it through and produced `#L-1` — a fragment the app then
+        # parsed into a bogus anchor at line -1. Anything that is not a positive line number yields a file-level link.
+        start = _line_no(relevant_line_start)
+        if not start:
             return f"meebox:///{f}"
-        if relevant_line_end and relevant_line_end != relevant_line_start:
-            return f"meebox:///{f}#L{relevant_line_start}-L{relevant_line_end}"
-        return f"meebox:///{f}#L{relevant_line_start}"
+        end = _line_no(relevant_line_end)
+        if end and end != start:
+            return f"meebox:///{f}#L{start}-L{end}"
+        return f"meebox:///{f}#L{start}"
 
     module.LocalGitProvider.get_line_link = get_line_link
 
+    # num_plus_lines / num_minus_lines: FilePatchInfo defaults both to -1, and only the real platform providers fill
+    # them in — LocalGitProvider does not, so /describe's File Walkthrough rendered every row as "+-1/--1". Wrap
+    # rather than reimplement get_diff_files: upstream owns how the diff is produced (0.45.0 also made it binary-safe),
+    # and this only backfills two derived counters, computed the same way the platform providers do.
+    _orig_get_diff_files = module.LocalGitProvider.get_diff_files
+
+    def get_diff_files(self):
+        files = _orig_get_diff_files(self)
+        for f in files or []:
+            if getattr(f, "num_plus_lines", -1) >= 0:
+                continue  # already counted (a future upstream that fills them in wins)
+            lines = (getattr(f, "patch", None) or "").splitlines()
+            # Count the same way the platform providers do: any line starting with +/-, which includes the
+            # `+++`/`---` file headers. Kept identical rather than "corrected" so the numbers agree across providers.
+            f.num_plus_lines = len([ln for ln in lines if ln.startswith("+")])
+            f.num_minus_lines = len([ln for ln in lines if ln.startswith("-")])
+        return files
+
+    module.LocalGitProvider.get_diff_files = get_diff_files
+
     # uniformly enable GFM: LocalGitProvider defaults to False for 'gfm_markdown', causing /describe's
     # enable_pr_diagram (on by default in configuration.toml) to be gated off by `enable and is_supported(gfm_markdown)`,
     # not producing the mermaid architecture diagram; /review etc. also take the non-GFM simplified branch. Here we make gfm_markdown
diff --git a/docs/arch/02-agent/05-pragent-runtime.md b/docs/arch/02-agent/05-pragent-runtime.md
index 27260a6a..e81a2ca7 100644
--- a/docs/arch/02-agent/05-pragent-runtime.md
+++ b/docs/arch/02-agent/05-pragent-runtime.md
@@ -58,7 +58,8 @@ Design principles:
 
 Current patches (pinned pr-agent **0.45.0**):
 - **anchor line numbers** (details in [Review workflow](../01-platform/03-review-workflow.md)): patch `get_line_link` to return `meebox:///<file>#L<s>-L<e>`,
-  letting `/review`'s key_issues render with a structured file:line.
+  letting `/review`'s key_issues render with a structured file:line. **`-1` means "the whole file"** upstream — `/describe` passes it for every File Walkthrough row — and it is truthy, so it must be screened out explicitly or the link becomes `#L-1`, which the anchor parser then rejects outright (its line group only accepts digits), losing even the path. Anything that is not a positive line number yields a file-level link.
+- **diff line counts**: `FilePatchInfo.num_plus_lines` / `num_minus_lines` default to `-1` and only the real platform providers fill them in, so `/describe`'s File Walkthrough rendered every row as `+-1/--1`. `get_diff_files` is **wrapped** (not reimplemented) to backfill the two counters from the patch text, counted by the same rule the platform providers use — upstream keeps owning how the diff is produced.
 - **Anthropic drops temperature**: new Claude models deprecate temperature, so all `anthropic/*` are put into the "don't send temperature" set.
 - **load_yaml tolerance**: an anchor marker taking a whole line breaks YAML → on parse failure, strip the marker and retry, avoiding a whole review crash.
 - **repo-context file fetch**: pr-agent defaults `repo_context_files = ["AGENTS.md"]`, but `LocalGitProvider` inherits the base no-op `get_repo_file_content` → the feature is skipped with a per-run WARNING. Implement it by reading the blob from the base branch's tree (`git show <target_branch>:<path>`, never the working tree), so `/review /describe /improve` inject the reviewed repo's `AGENTS.md`/etc. as `<instruction_files>`; a missing file degrades to `""`.
diff --git a/packages/poller/src/parse-output.ts b/packages/poller/src/parse-output.ts
index 265119ea..e54cc75b 100644
--- a/packages/poller/src/parse-output.ts
+++ b/packages/poller/src/parse-output.ts
@@ -107,19 +107,25 @@ interface Section {
 }
 
 /**
- * Slice pr-agent 0.36.0's markdown output into sections by H1-H6.
+ * Slice pr-agent's markdown output into sections by heading.
  * Each section has level / title / body (body has leading/trailing whitespace stripped).
  * Leading content at the top with no header is also synthesized into a level=0 / title='' section, so /describe
  * can be pulled out as a whole segment.
+ *
+ * `minLevel` is the shallowest heading allowed to start a section; anything shallower stays as body text. The tool's
+ * own structure sits at a known depth, while the text it quotes is arbitrary user prose — so without this, a heading
+ * the user happened to write outranks the structure and tears it apart. The case that forced it: a PR description
+ * ending in a git merge tail, where `# Conflicts:` and the `#\tpath` lines under it are markdown H1s, split a
+ * `/describe` result into sections named after conflicted files.
  */
-export function splitMarkdownSections(md: string): Section[] {
+export function splitMarkdownSections(md: string, minLevel = 1): Section[] {
   const lines = md.replace(/\r\n/g, '\n').split('\n');
   const sections: Section[] = [];
   let cur: Section | null = { level: 0, title: '', body: '' };
   const HEADER_RE = /^(#{1,6})\s+(.+?)\s*$/;
   for (const line of lines) {
     const m = HEADER_RE.exec(line);
-    if (m) {
+    if (m && m[1]!.length >= minLevel) {
       // First finalize the prev section (drop empty segments)
       if (cur && (cur.title || cur.body.trim())) {
         sections.push({ ...cur, body: cur.body.trim() });
@@ -889,7 +895,13 @@ export function parseReviewOutput(stdout: string, tool: ReviewRunTool): ParsedRe
   // The GFM path is only for /review (under gfm_markdown the whole thing is a <table>); describe/ask still go through markdown
   // slicing (their HTML/table/mermaid is rendered downstream by react-markdown, the section structure is unaffected).
   const gfm = tool === 'review' && isGfmReviewOutput(baseMd);
-  const allSections = gfm ? splitGfmTableSections(baseMd) : splitMarkdownSections(baseMd);
+  // /describe frames its whole structure at `###` (User description / PR Type / Description / Diagram Walkthrough /
+  // Assessment), and one of those sections quotes the PR description verbatim. Splitting at H1/H2 there would let the
+  // author's own prose define sections — a merge-conflict tail (`# Conflicts:`) being the case that surfaced it. Other
+  // tools keep the default, since their bodies are model output shaped by our prompts, not quoted user text.
+  const allSections = gfm
+    ? splitGfmTableSections(baseMd)
+    : splitMarkdownSections(baseMd, tool === 'describe' ? 3 : 1);
   const sections = allSections.filter((s) => !shouldSkipSection(s, tool));
   if (sections.length === 0) {
     const fs = walkthroughFinding ? [walkthroughFinding] : [];
diff --git a/packages/poller/tests/parse-output.test.ts b/packages/poller/tests/parse-output.test.ts
index 0de269ab..fcf52e8c 100644
--- a/packages/poller/tests/parse-output.test.ts
+++ b/packages/poller/tests/parse-output.test.ts
@@ -666,9 +666,11 @@ describe('parseStructuredAsk', () => {
   });
 
   it('suggestions section with no marker → the whole section as one ask-suggestions (same as old behavior)', () => {
-    const md = ['<suggestions>', 'General advice with no specific code location.', '</suggestions>'].join(
-      '\n',
-    );
+    const md = [
+      '<suggestions>',
+      'General advice with no specific code location.',
+      '</suggestions>',
+    ].join('\n');
     const { findings } = parseReviewOutput(md, 'ask');
     expect(findings[0]!.sectionKey).toBe('ask-suggestions');
     expect(findings[0]!.body).toBe('General advice with no specific code location.');
@@ -729,3 +731,44 @@ describe('classifyLlmFailure', () => {
     expect(classifyLlmFailure("CLI 'codex' returned an empty reply")).toBeUndefined();
   });
 });
+
+describe('splitMarkdownSections minLevel', () => {
+  // Regression: a PR description ending in a git merge tail. `# Conflicts:` and the `#\tpath` lines under it are
+  // markdown H1s, so before minLevel they outranked /describe's own `###` structure and split the result into
+  // sections named after conflicted files — with the real description scattered across them.
+  const describeOut = [
+    '### **User description**',
+    'fix: isolate internal and external roles',
+    'Merge remote-tracking branch',
+    '',
+    '# Conflicts:',
+    '#\tpackage-lock.json',
+    '#\tpackage.json',
+    '',
+    '___',
+    '',
+    '### **PR Type**',
+    'Enhancement, Bug fix',
+  ].join('\n');
+
+  it('keeps a quoted merge tail inside the section that quotes it', () => {
+    const titles = splitMarkdownSections(describeOut, 3).map((s) => s.title);
+    expect(titles).toEqual(['**User description**', '**PR Type**']);
+    const userDesc = splitMarkdownSections(describeOut, 3)[0]!;
+    // The conflict tail stays put as body text rather than becoming structure.
+    expect(userDesc.body).toContain('# Conflicts:');
+    expect(userDesc.body).toContain('package-lock.json');
+  });
+
+  it('default level 1 still splits on every heading (unchanged for other tools)', () => {
+    const titles = splitMarkdownSections(describeOut).map((s) => s.title);
+    expect(titles).toContain('Conflicts:');
+  });
+
+  it('describe output routes through the shallower minimum', () => {
+    const { findings } = parseReviewOutput(describeOut, 'describe');
+    // No finding is named after a conflicted file.
+    expect(findings.some((f) => /conflicts/i.test(f.title ?? ''))).toBe(false);
+    expect(findings.some((f) => /package-lock/i.test(f.title ?? ''))).toBe(false);
+  });
+});

From 49dd71396504ca43ad77a7579d9aadc484df8d11 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 17:26:28 +0800
Subject: [PATCH 11/17] chore(deps): upgrade monaco-editor to 0.56.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

0.56.0 replaces the identity `exports` map (`"./*": "./*"`) with
`"./*": "./esm/vs/*.js"`, so every deep import that still spelled the prefix
resolved to `esm/vs/esm/vs/…` and broke the build. It also moved the
worker-backed language services from `vs/language/<x>/monaco.contribution.js`
to typed namespaces on the package entry.

That second change lets the code get simpler rather than merely adapt: the four
`*Defaults` we disable are now read straight off `monaco` with real types, so
the hand-written LangServiceDefaults shape, the cast through unknown (the old
.d.ts was an empty `export {}`) and the by-name lookup are all gone.

Re-checked both suppressed Monaco errors against 0.56.0: still present, so the
suppression stays. `Missing requestHandler` is still a plain Promise.reject from
editorWebWorker.$fmr, and `TextModel got disposed` still goes through
onUnexpectedError in diffEditorWidget -- an unhandledrejection and a window
error respectively, which is what the two listeners catch. Recorded in the
comment so the next upgrade re-checks instead of assuming.

Security: monaco's pinned dompurify moves 3.2.7 -> 3.4.8, dropping the copy
behind 16 open advisories down to 4. Not enough to close the tracking issue
(#208) -- newer advisories widened the range past 3.4.11, and one has no fix in
any published version -- but its premise changed, so the issue is updated with
the revised bar rather than left stale.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 CHANGELOG.zh-CN.md                            |  1 +
 apps/desktop/package.json                     |  2 +-
 .../src/renderer/src/lib/monaco-setup.ts      | 44 +++++++++----------
 package-lock.json                             | 16 +++----
 5 files changed, 31 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d623b4c0..2f23fa34 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
+- The code editor is now Monaco 0.56.0 (from 0.55.1), which also drops the outdated sanitizer copy behind most of the open dependency advisories.
 - The bundled review engine is now pr-agent 0.45.0 (from 0.39.0). Two long-standing local fixes are no longer needed — a single-line file change is rendered correctly upstream now, and a binary file no longer has to be worked around — and its YAML handling is more tolerant of imperfect model output.
 - Mentions now render as a pill instead of blending into the surrounding text, so it is obvious at a glance when someone is named — on the activity page, in the inline diff comments, in drafts, and in the PR description alike.
 - Proxy settings now take a list of **direct connections**: hosts that bypass the proxy and connect straight out, so an internal code platform, its git remote, or a self-hosted model stays reachable while everything else still goes through the proxy. Uses the familiar `NO_PROXY` syntax (a domain covers its subdomains), and applies to every outbound path at once — REST, git and the LLM call.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index d3c62396..008f7183 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,6 +9,7 @@
 
 ### ✨ 新增
 
+- 代码编辑器升级至 Monaco 0.56.0（原 0.55.1），同时替换掉了此前多数依赖安全告警所指向的过时清理库副本。
 - 内置评审引擎升级至 pr-agent 0.45.0（原 0.39.0）。两处长期存在的本地修补不再需要——单行文件变更在上游已渲染正确，二进制文件也无需再绕开——其 YAML 解析对不规范的模型输出也更宽容。
 - @提及 改为胶囊标签展示，不再淹没在正文里，一眼即可看出点到了谁——活动页、内联 diff 评论、草稿与 PR 描述一致生效。
 - 代理设置新增**直连地址**列表：列出的地址跳过代理直接连接，内网代码平台、它的 git 远端或自建模型服务因此保持可达，其余流量照常走代理。沿用通行的 `NO_PROXY` 写法（填域名同时覆盖子域），并对所有出站路径一并生效——REST、git 与 LLM 调用。
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index b5ea2309..843b87c3 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -81,7 +81,7 @@
     "i18next": "^26.3.1",
     "i18next-resources-to-backend": "^1.2.1",
     "mermaid": "^11.4.0",
-    "monaco-editor": "^0.55.0",
+    "monaco-editor": "^0.56.0",
     "pino": "^9.5.0",
     "pino-roll": "^3.0.0",
     "react": "^19.2.0",
diff --git a/apps/desktop/src/renderer/src/lib/monaco-setup.ts b/apps/desktop/src/renderer/src/lib/monaco-setup.ts
index 811209ff..a06d081f 100644
--- a/apps/desktop/src/renderer/src/lib/monaco-setup.ts
+++ b/apps/desktop/src/renderer/src/lib/monaco-setup.ts
@@ -5,16 +5,8 @@
 // When M1+ actually needs syntax highlighting, import the corresponding language worker on demand.
 
 import * as monaco from 'monaco-editor';
-import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
+import editorWorker from 'monaco-editor/editor/editor.worker.js?worker';
 import { loader } from '@monaco-editor/react';
-// The 4 contribution submodules for "worker-backed language services" (editor.main already loaded them; importing
-// again here is only to grab their named-exported *Defaults; ES module singletons won't re-execute). Their runtime
-// JS named-exports typescriptDefaults / jsonDefaults / cssDefaults … but the .d.ts is wrongly `export {}` (monaco
-// 0.55 ESM bundling defect), so import as namespace and cast via unknown below into the known shapes, without any.
-import * as tsLang from 'monaco-editor/esm/vs/language/typescript/monaco.contribution.js';
-import * as jsonLang from 'monaco-editor/esm/vs/language/json/monaco.contribution.js';
-import * as cssLang from 'monaco-editor/esm/vs/language/css/monaco.contribution.js';
-import * as htmlLang from 'monaco-editor/esm/vs/language/html/monaco.contribution.js';
 // Third-party editor themes (IStandaloneThemeData shape, vendored from monaco-themes, see editor-themes/NOTICE.md),
 // registered via defineTheme below for selection. ids align with @meebox/shared EDITOR_THEME_OPTIONS; vs / vs-dark /
 // hc-* are Monaco built-ins, no registration needed. Vendored in place rather than an npm dependency: monaco-themes'
@@ -135,22 +127,19 @@ export function getEditorThemeColors(id: string): EditorThemeColorData | null {
  * (the window fallback below degrades to pure insurance). The other 80+ languages are pure monarch tokenizer
  * coloring with no worker backend, unaffected and needing no handling.
  */
-interface LangServiceDefaults {
-  // Passing an empty ModeConfiguration (each field is optional, absent = don't register that provider) = turn off all features
-  setModeConfiguration(modeConfiguration: object): void;
-}
-// The runtime named exports exist (see each contribution.js's export), but their .d.ts is wrongly `export {}`, so
-// cast via unknown into the known *Defaults shape (without any); filter as fallback when a name is missing, so a future monaco rename won't crash.
-const defaultsOf = (mod: unknown, names: readonly string[]): LangServiceDefaults[] =>
-  names
-    .map((n) => (mod as Record<string, LangServiceDefaults | undefined>)[n])
-    .filter((d): d is LangServiceDefaults => typeof d?.setModeConfiguration === 'function');
-
+// monaco 0.56.0 moved these language services from `vs/language/<x>/monaco.contribution.js` (whose .d.ts was an
+// empty `export {}`, forcing a cast through unknown) to typed namespaces on the package entry. Reading them from
+// `monaco` is both the supported path and fully typed, so the previous hand-written shape + name lookup is gone.
 for (const d of [
-  ...defaultsOf(tsLang, ['typescriptDefaults', 'javascriptDefaults']),
-  ...defaultsOf(jsonLang, ['jsonDefaults']),
-  ...defaultsOf(cssLang, ['cssDefaults', 'scssDefaults', 'lessDefaults']),
-  ...defaultsOf(htmlLang, ['htmlDefaults', 'handlebarDefaults', 'razorDefaults']),
+  monaco.typescript.typescriptDefaults,
+  monaco.typescript.javascriptDefaults,
+  monaco.json.jsonDefaults,
+  monaco.css.cssDefaults,
+  monaco.css.scssDefaults,
+  monaco.css.lessDefaults,
+  monaco.html.htmlDefaults,
+  monaco.html.handlebarDefaults,
+  monaco.html.razorDefaults,
 ]) {
   d.setModeConfiguration({});
 }
@@ -169,6 +158,13 @@ for (const d of [
  * don't affect rendering, and can't be eradicated on the app side → **silently ignored by default** (as known
  * issues). To diagnose, run `localStorage.setItem('meebox.monacoDebug','1')` in devtools and refresh to see the
  * details of the swallowed errors.
+ *
+ * **Re-checked at monaco 0.56.0: both still present, so this stays.** `Missing requestHandler` is still a plain
+ * `Promise.reject` from `editorWebWorker.$fmr`, and `TextModel got disposed` still goes through
+ * `onUnexpectedError(new BugIndicatingError(...))` in `diffEditorWidget` — i.e. they still surface as an
+ * unhandledrejection and a window error respectively, which is what the two listeners below catch. Re-check on the
+ * next upgrade rather than assuming: this suppression is deliberately narrow, and outliving its cause would mean
+ * silently swallowing a message that had become meaningful again.
  */
 const MONACO_DEBUG = (() => {
   try {
diff --git a/package-lock.json b/package-lock.json
index 71027e61..f3f5c9ca 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -55,7 +55,7 @@
         "i18next": "^26.3.1",
         "i18next-resources-to-backend": "^1.2.1",
         "mermaid": "^11.4.0",
-        "monaco-editor": "^0.55.0",
+        "monaco-editor": "^0.56.0",
         "pino": "^9.5.0",
         "pino-roll": "^3.0.0",
         "react": "^19.2.0",
@@ -5852,9 +5852,9 @@
       }
     },
     "node_modules/dompurify": {
-      "version": "3.2.7",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.2.7.tgz",
-      "integrity": "sha512-WhL/YuveyGXJaerVlMYGWhvQswa7myDG17P7Vu65EWC05o8vfeNbvNf4d/BOvH99+ZW+LlQsc1GDKMa1vNK6dw==",
+      "version": "3.4.8",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.8.tgz",
+      "integrity": "sha512-yb1cEmaOum7wFvOCSQxyfgVlv5D47Rc30iZWoMpbDIWTnJ6grDDQyu2KFJzB2k7u0pMuJcQ1zphH//fFnw2tjQ==",
       "license": "(MPL-2.0 OR Apache-2.0)",
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
@@ -9920,12 +9920,12 @@
       }
     },
     "node_modules/monaco-editor": {
-      "version": "0.55.1",
-      "resolved": "https://registry.npmjs.org/monaco-editor/-/monaco-editor-0.55.1.tgz",
-      "integrity": "sha512-jz4x+TJNFHwHtwuV9vA9rMujcZRb0CEilTEwG2rRSpe/A7Jdkuj8xPKttCgOh+v/lkHy7HsZ64oj+q3xoAFl9A==",
+      "version": "0.56.0",
+      "resolved": "https://registry.npmjs.org/monaco-editor/-/monaco-editor-0.56.0.tgz",
+      "integrity": "sha512-sXboRm3BeBeLm938eaiyLMe0OxzfXIlZvbv4ir/jVgQy1zDhWjgmny0WoN45fuDKhCCQsYMbBJrv/A6jd8aCUg==",
       "license": "MIT",
       "dependencies": {
-        "dompurify": "3.2.7",
+        "dompurify": "3.4.8",
         "marked": "14.0.0"
       }
     },

From e8732e234d4b717e1308d75639cc1cf0ca0a5c7c Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 19:21:25 +0800
Subject: [PATCH 12/17] fix(chat): anchor the commit divider to the boundary,
 not to the end of the pane

The trailing commit divider rendered after everything in the timeline, so it was
not marking a position -- it was tracking the bottom. Every message, thinking
step or queued run that arrived pushed it further down, and a boundary that
moves is worse than no boundary: it reads as if the commit itself keeps
happening later.

The boundary belongs immediately after the last run that reviewed the previous
commit. Everything that arrives afterwards belongs below it, which is also what
the divider means. So it now anchors before whatever first followed that run,
and only falls back to the end in the one case where nothing follows it yet --
where the two positions coincide anyway.

Placement moves into computeCommitDividers, a pure function: it is the part with
the actual reasoning, and it was previously inlined in a component with no way
to exercise it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 CHANGELOG.zh-CN.md                            |  1 +
 .../src/components/features/chat/ChatPane.tsx | 34 +++++--------
 .../features/chat/utils/commit-dividers.ts    | 49 +++++++++++++++++++
 4 files changed, 62 insertions(+), 23 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/components/features/chat/utils/commit-dividers.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2f23fa34..7642b774 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### 🔧 Fixed
 
+- The commit divider in the review timeline now stays where the commit boundary actually is, instead of sliding further down every time a new message appears below it.
 - The file list in a generated PR description now shows the real number of added and removed lines per file, instead of `+-1/--1`.
 - Links in that file list now open the file instead of pointing at a non-existent line, so clicking through works.
 - A PR description ending in a git merge tail (`# Conflicts:` and the file lines under it) no longer breaks up the generated description — those lines are part of the quoted description, not headings of their own.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 008f7183..8f0c9dc8 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -17,6 +17,7 @@
 
 ### 🔧 修复
 
+- 评审时间线中的提交分割线现在固定在提交边界的真实位置，不再因为下方出现新消息而一路下移。
 - 生成的 PR 描述中，文件清单现在显示每个文件真实的增删行数，不再是 `+-1/--1`。
 - 该清单中的链接现在指向文件本身，而非一个不存在的行号，点击可正常跳转。
 - PR 描述末尾带有 git 合并残留（`# Conflicts:` 及其下的文件行）时，生成的描述不再被切碎——那些行属于被引用的描述正文，而不是标题。
diff --git a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
index 8fcd5b69..df25119c 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
@@ -27,6 +27,7 @@ import { useChatTimeline } from './hooks/useChatTimeline';
 import { AgentStepRow, ThinkingLive } from './components/AgentStep';
 import { ChatEmpty } from './components/ChatEmpty';
 import { CommitDivider } from './components/CommitDivider';
+import { computeCommitDividers } from './utils/commit-dividers';
 import { ChatInputBar } from './components/ChatInputBar';
 import { ConversationMessage } from './components/ConversationMessage';
 import { PlanPanel } from './components/PlanPanel';
@@ -244,26 +245,12 @@ export function ChatPane({
     prLocalId,
   });
 
-  // Commit dividers: mark every point in the run timeline where the reviewed commit changes, so the boundary persists
-  // rather than vanishing once the new code is reviewed. Two cases:
-  //  - between two consecutive runs whose headSha differs → a divider *before* the newer run (a durable boundary
-  //    between the old-commit runs above and the new-commit runs below);
-  //  - a trailing divider at the bottom when the current PR head has advanced past the last run's commit (covers a new
-  //    commit that hasn't been reviewed yet — including while a run against it is still in flight).
-  // The timeline is ascending by start time; only runs that recorded a headSha participate (pre-feature runs are skipped).
-  const commitDividers = useMemo(() => {
-    const before = new Map<string, string>(); // timeline entry.key → the newer headSha to render a divider before it
-    let prevSha: string | undefined;
-    for (const entry of timeline) {
-      const sha = entry.run?.headSha;
-      if (!sha) continue;
-      if (prevSha && sha !== prevSha) before.set(entry.key, sha);
-      prevSha = sha;
-    }
-    const head = pr?.sourceRef.sha;
-    const bottom = head && prevSha && head !== prevSha ? head : null;
-    return { before, bottom };
-  }, [timeline, pr?.sourceRef.sha]);
+  // Commit dividers: every point in the timeline where the reviewed commit changes (see computeCommitDividers, which
+  // also explains why the trailing boundary anchors after the last run rather than at the end of the pane).
+  const commitDividers = useMemo(
+    () => computeCommitDividers(timeline, pr?.sourceRef.sha),
+    [timeline, pr?.sourceRef.sha],
+  );
 
   // Commit messages for divider tooltips: fetch the PR's commits (main-cached; keyed on head sha so it refreshes when
   // the head advances) into a sha → message map. Empty until loaded / on failure (the tooltip falls back to the short sha).
@@ -451,9 +438,10 @@ export function ChatPane({
             <ConversationMessage key={entry.key} message={entry.message} />
           ) : null,
         )}
-        {/* Bottom commit divider: the PR head advanced past the last run's commit and no run against it exists yet
-            (a new commit not reviewed yet, including while a run against it is still in flight). Once such a run
-            completes, the boundary instead renders between the old and new runs above (see commitDividers.before). */}
+        {/* Trailing commit divider, for the one case with no entry to precede: the head advanced past the last run's
+            commit and nothing has landed after that run yet. As soon as anything does — a message, a step, a queued
+            run — the boundary moves into `before` and anchors there, so it stays put instead of being pushed down by
+            each new bubble (see computeCommitDividers). */}
         {commitDividers.bottom && (
           <CommitDivider
             sha={commitDividers.bottom}
diff --git a/apps/desktop/src/renderer/src/components/features/chat/utils/commit-dividers.ts b/apps/desktop/src/renderer/src/components/features/chat/utils/commit-dividers.ts
new file mode 100644
index 00000000..4cca80a0
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/features/chat/utils/commit-dividers.ts
@@ -0,0 +1,49 @@
+import type { TimelineEntry } from '../hooks/useChatTimeline';
+
+export interface CommitDividers {
+  /** timeline entry.key → the headSha whose boundary is drawn immediately *before* that entry. */
+  before: Map<string, string>;
+  /** headSha for a divider after everything, used only when the boundary has no entry to precede. */
+  bottom: string | null;
+}
+
+/**
+ * Place the commit boundaries in the chat timeline: every point where the reviewed commit changes, so the boundary
+ * persists rather than vanishing once the new code has been reviewed.
+ *
+ * - **Between runs**: two consecutive runs with different `headSha` → a boundary before the newer one, separating the
+ *   old-commit runs above from the new-commit ones below.
+ * - **After the newest run**: the PR head has advanced past the last run's commit and nothing has reviewed it yet.
+ *   The boundary belongs immediately after that last run — **not at the end of the timeline**. Those differ as soon as
+ *   anything else lands (a message, a thinking step, a queued run), and anchoring to the end made the divider drift
+ *   down the pane on every new bubble, as if the boundary itself kept moving. A boundary marks a point in history; it
+ *   has to stay where that point is, with everything that came after it below.
+ *
+ * The timeline is ascending by start time; only runs that recorded a `headSha` participate (runs from before that field
+ * existed are skipped, which is why the last *run* and the last *sha-bearing run* are tracked as the same cursor).
+ */
+export function computeCommitDividers(
+  timeline: readonly TimelineEntry[],
+  headSha: string | undefined,
+): CommitDividers {
+  const before = new Map<string, string>();
+  let prevSha: string | undefined;
+  let lastShaIdx = -1;
+  timeline.forEach((entry, i) => {
+    const sha = entry.run?.headSha;
+    if (!sha) return;
+    if (prevSha && sha !== prevSha) before.set(entry.key, sha);
+    prevSha = sha;
+    lastShaIdx = i;
+  });
+  // No run has recorded a sha, or the head is the one already reviewed → no trailing boundary.
+  if (!headSha || !prevSha || headSha === prevSha) return { before, bottom: null };
+  // Anchor the boundary before whatever first followed that last run. Nothing follows it yet → fall back to the end,
+  // which is then the same position (and stops being a moving target as soon as an entry appears there).
+  const next = timeline[lastShaIdx + 1];
+  if (next) {
+    before.set(next.key, headSha);
+    return { before, bottom: null };
+  }
+  return { before, bottom: headSha };
+}

From 154bd44d97c46d0c1f7950b0609cd65ac1ce686e Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 21:43:26 +0800
Subject: [PATCH 13/17] feat(comments): reference a comment into the agent
 conversation

A reviewer''s comment is usually a claim -- is this actually a problem, does this
path really run, was it handled elsewhere -- and settling it means reading the
code the comment points at. That is what the agent is for, but the only way to
hand it one was to paste the text into the chat box, dropping the anchor and the
authorship on the way.

The reference button attaches the comment as implicit context for the next
question, so "is this right?" is a complete question. No IPC change was needed:
agent:ask already carries referencedContext for the diff selection, and the two
compose, since asking whether a comment is right about a selected region needs
both.

Cross-pane state goes in a store for the same reason the diff selection does:
the comment surfaces and ChatPane are siblings with no common owner below App.

Both comment surfaces get it, identically -- toggle to release, a chip with a
clear button, released on send, cleared on PR switch. DraftZone does not: a
draft is a comment not yet written by anyone else, so there is no claim to
investigate.

The glyph is the existing ShareIcon rather than something agent-flavoured,
because that is already what "reference" looks like in this app (the finding
reference button); one gesture should not have two icons.

The prompt says what to do with the comment, not just what it says. Without
that instruction a model tends to paraphrase the comment back instead of
checking it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   1 +
 CHANGELOG.zh-CN.md                            |   1 +
 .../src/components/features/chat/ChatPane.tsx |  38 ++++++-
 .../features/chat/components/ChatInputBar.tsx |  25 +++++
 .../features/pr/tabs/comments/CommentItem.tsx |  38 +++++++
 .../inline-comments/InlineCommentZone.tsx     |  41 ++++++-
 .../src/renderer/src/i18n/locales/de-DE.json  |   5 +
 .../src/renderer/src/i18n/locales/en-US.json  |   5 +
 .../src/renderer/src/i18n/locales/ja-JP.json  |   5 +
 .../src/renderer/src/i18n/locales/zh-CN.json  |   5 +
 .../src/stores/comment-reference-store.ts     | 105 ++++++++++++++++++
 .../styles/features/diff/comment-zone.scss    |  33 ++++--
 .../src/styles/features/pr/comments.scss      |  19 ++++
 13 files changed, 310 insertions(+), 11 deletions(-)
 create mode 100644 apps/desktop/src/renderer/src/stores/comment-reference-store.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7642b774..7d650d87 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
+- A comment can now be handed to the agent to investigate: click the reference button on any comment and ask about it, and the agent gets the comment, its author and the code it points at, then checks the claim against the actual code.
 - The code editor is now Monaco 0.56.0 (from 0.55.1), which also drops the outdated sanitizer copy behind most of the open dependency advisories.
 - The bundled review engine is now pr-agent 0.45.0 (from 0.39.0). Two long-standing local fixes are no longer needed — a single-line file change is rendered correctly upstream now, and a binary file no longer has to be worked around — and its YAML handling is more tolerant of imperfect model output.
 - Mentions now render as a pill instead of blending into the surrounding text, so it is obvious at a glance when someone is named — on the activity page, in the inline diff comments, in drafts, and in the PR description alike.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 8f0c9dc8..8faa77f9 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,6 +9,7 @@
 
 ### ✨ 新增
 
+- 现在可以把评论交给 Agent 调查：在任意评论上点击引用按钮再提问，Agent 会拿到评论原文、作者及其指向的代码，对照真实代码核查该说法是否成立。
 - 代码编辑器升级至 Monaco 0.56.0（原 0.55.1），同时替换掉了此前多数依赖安全告警所指向的过时清理库副本。
 - 内置评审引擎升级至 pr-agent 0.45.0（原 0.39.0）。两处长期存在的本地修补不再需要——单行文件变更在上游已渲染正确，二进制文件也无需再绕开——其 YAML 解析对不规范的模型输出也更宽容。
 - @提及 改为胶囊标签展示，不再淹没在正文里，一眼即可看出点到了谁——活动页、内联 diff 评论、草稿与 PR 描述一致生效。
diff --git a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
index df25119c..4c85572a 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
@@ -14,6 +14,12 @@ import { ChatIcon, TrashIcon, ConfirmModal, PaneLoading } from '../../common';
 import { useChatRunStore } from '../../../stores/chat-run-store';
 import { useDraftsForPr } from '../../../stores/drafts-store';
 import { useFindingClosuresForPr } from '../../../stores/finding-closures-store';
+import {
+  commentReferenceStore,
+  commentReferenceLabel,
+  formatCommentReference,
+  useCommentReference,
+} from '../../../stores/comment-reference-store';
 import {
   formatReferencedContext,
   selectionStore,
@@ -160,6 +166,7 @@ export function ChatPane({
   // On PR switch, clear the reference state and reset the detached state to avoid cross-PR residue.
   useEffect(() => {
     setRefFinding(null);
+    commentReferenceStore.clear();
     setScopeDetached(false);
   }, [prLocalId]);
   // On switching to another commit (or clearing the view scope), reset the detached state: the newly selected commit becomes the implicit scope again.
@@ -172,9 +179,19 @@ export function ChatPane({
 
   // Diff selection (belonging to the current PR): used for the input bar's "N lines selected" badge + carrying the selected code as implicit context into a question.
   const { selection: diffSelection, ignored: selectionIgnored } = useDiffSelection(prLocalId);
-  // When not ignored, format the selection into a reference string; shared by /ask and natural-language questions. Ignored / no selection → undefined (this message carries no reference).
+  // Comment referenced from a comment surface (activity panel / inline diff zone), carried as implicit context so the
+  // question can be about the comment without restating it.
+  const commentRef = useCommentReference(prLocalId);
+  // Implicit context for this message: the diff selection and the referenced comment are independent sources and
+  // compose — asking "is this comment right about the code I selected?" needs both. Each block is self-describing, so
+  // concatenating them needs no framing. Undefined when neither is present (the message carries no reference).
   const referencedContext =
-    diffSelection && !selectionIgnored ? formatReferencedContext(diffSelection) : undefined;
+    [
+      diffSelection && !selectionIgnored ? formatReferencedContext(diffSelection) : null,
+      commentRef ? formatCommentReference(commentRef) : null,
+    ]
+      .filter(Boolean)
+      .join('\n\n') || undefined;
 
   // The effective scope for this PR's chat commands: follows the commit selected in the Diff view, unless the user has detached (scopeDetached).
   // Only one scope may be in effect at a time — when a Diff selection exists it takes precedence (finer-grained), the commit scope is suspended and its chip
@@ -500,6 +517,10 @@ export function ChatPane({
             undefined,
             tool === 'ask' ? undefined : (effectiveScope ?? undefined),
           );
+          // Release the referenced comment once carried: a reference is per-question, so leaving it attached would
+          // silently prepend the same comment to every later message. The diff selection is deliberately *not*
+          // released here — it stays visible in the editor, so keeping it is what the user sees and expects.
+          if (tool === 'ask') commentReferenceStore.clear();
         }}
         onAgentAsk={(q) => {
           if (refFinding) {
@@ -512,6 +533,7 @@ export function ChatPane({
             return;
           }
           void actions.handleAgentAsk(q, referencedContext);
+          commentReferenceStore.clear();
         }}
         onCancel={hasMyActive || agentRunningHere ? actions.handleStopAll : undefined}
         onSetReviewStatus={onSetReviewStatus}
@@ -537,6 +559,18 @@ export function ChatPane({
               }
             : null
         }
+        // Referenced comment: chip showing "<author>: <excerpt>" + clear. Attached from a comment's reference button;
+        // carried as implicit context with the next question, and released on send (see onSend).
+        commentChip={
+          commentRef
+            ? {
+                label: commentReferenceLabel(commentRef),
+                onClear: () => {
+                  commentReferenceStore.clear();
+                },
+              }
+            : null
+        }
         // Single-commit scope chip: shown when a commit is selected in the view (the selected state comes from the view); click to toggle enabled/disabled —
         // when disabled (scopeDetached) commands revert to the full PR and the chip greys out; switching to another commit or switching PR resets it to enabled.
         // Only one scope at a time: when a Diff selection exists it yields to the selection chip (hides this chip), auto-restored after the selection is cleared.
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
index 06d5979a..839296bb 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
@@ -12,6 +12,7 @@ import {
   FileTreeIcon,
   SendIcon,
   StopIcon,
+  ShareIcon,
 } from '../../../common';
 import { useChatInput } from '../hooks/useChatInput';
 import { useTextareaAutosizeDrag } from '../hooks/useTextareaAutosizeDrag';
@@ -55,6 +56,8 @@ interface ChatInputBarProps {
   onToggleSelection: () => void;
   /** Re-review reference chip: shows "re-review <file:line>" + clear when a finding is referenced; null = not rendered. */
   referenceChip?: { label: string; onClear: () => void } | null;
+  /** Referenced-comment chip: shows "<author>: <excerpt>" + clear when a comment is referenced; null = not rendered. */
+  commentChip?: { label: string; onClear: () => void } | null;
   /**
    * Single-commit scope chip: follows the commit selected in the Diff view, showing "short SHA · subject". Shown whenever there is
    * a selection, click to **toggle enable/disable** (disabling does not remove the chip, this session's commands revert to the whole
@@ -89,6 +92,7 @@ export function ChatInputBar({
   selectionIgnored,
   onToggleSelection,
   referenceChip,
+  commentChip,
   commitScopeChip,
 }: ChatInputBarProps) {
   const { t } = useTranslation();
@@ -287,6 +291,27 @@ export function ChatInputBar({
               </span>
             </>
           )}
+          {/* Referenced comment chip: the comment is carried as implicit context for this question. Its own chip rather
+              than sharing the re-review one — that reference changes what the run *does* (produces a verdict), while
+              this only adds context, and the two can be attached at once. */}
+          {commentChip && (
+            <>
+              <span className="chat-cmd-divider" aria-hidden="true" />
+              <span className="chat-selection-chip chat-reference-chip" title={commentChip.label}>
+                <ShareIcon size={12} />
+                <span>{commentChip.label}</span>
+                <button
+                  type="button"
+                  className="chat-reference-chip-clear"
+                  onClick={commentChip.onClear}
+                  title={t('chatPane.commentReference.clearTitle')}
+                  aria-label={t('chatPane.commentReference.clearTitle')}
+                >
+                  ✕
+                </button>
+              </span>
+            </>
+          )}
           {/* Single-commit scope chip: follows the commit selected in the view, showing "short SHA · subject". Click to toggle enable/disable (without removing) —
               when enabled the commands are scoped to that commit (parent..sha), when disabled they revert to the whole PR, greyed out + eye-slash. */}
           {commitScopeChip && (
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
index 1662690d..53ad580f 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/comments/CommentItem.tsx
@@ -10,7 +10,12 @@ import {
   ConfirmModal,
   LazyBoundary,
   mermaidComponents,
+  ShareIcon,
 } from '../../../../common';
+import {
+  commentReferenceStore,
+  useCommentReference,
+} from '../../../../../stores/comment-reference-store';
 import { CommentEditEditor } from './CommentEditEditor';
 import { CommentReplyEditor } from './CommentReplyEditor';
 import { ReplyDraftList } from './ReplyDraftList';
@@ -107,6 +112,10 @@ export function CommentItem({
     readOnly,
   );
 
+  // Whether this comment is the one currently referenced into the Agent conversation (drives the toggle + active styling).
+  const activeRef = useCommentReference(pr.localId);
+  const referenced = activeRef?.commentId === comment.remoteId;
+
   // inline comment anchor chip: path:line + side (old=base / new=head), letting the user locate the code position from the comment.
   // When onJumpToAnchor is provided (activity view) the chip becomes clickable → jump to the corresponding file/line in the Diff.
   const anchor = comment.anchor;
@@ -205,6 +214,35 @@ export function CommentItem({
           {deleting ? t('commentsPanel.deleting') : t('common.delete')}
         </button>
       )}
+      {/* Reference this comment into the Agent conversation: attaches it as implicit context, so the question can be
+          "is this right?" without the user restating the comment or its location. Uses the same ShareIcon as the
+          finding reference button — one action, one glyph, rather than teaching the same gesture twice. A toggle
+          rather than a one-way action: clicking the referenced comment again releases it (the input-bar chip can
+          also clear it). */}
+      {!replyOpen && (
+        <button
+          type="button"
+          className={`pr-comment-reference-btn${referenced ? ' is-active' : ''}`}
+          onClick={() =>
+            referenced
+              ? commentReferenceStore.clear()
+              : commentReferenceStore.set({
+                  prLocalId: pr.localId,
+                  commentId: comment.remoteId,
+                  author: comment.author.displayName || comment.author.name,
+                  body: comment.body,
+                  ...(comment.anchor
+                    ? { anchor: { path: comment.anchor.path, line: comment.anchor.line } }
+                    : {}),
+                })
+          }
+          title={referenced ? t('commentsPanel.referenceClearTitle') : t('commentsPanel.referenceTitle')}
+          aria-label={referenced ? t('commentsPanel.referenceClearTitle') : t('commentsPanel.referenceTitle')}
+          aria-pressed={referenced}
+        >
+          <ShareIcon size={13} />
+        </button>
+      )}
       {/* The "add reaction" button goes after the action buttons; hidden in reply edit mode to avoid crowding */}
       {reactionsMode && !replyOpen && (
         <ReactionAddButton
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/inline-comments/InlineCommentZone.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/inline-comments/InlineCommentZone.tsx
index a7ede0c5..84a07541 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/inline-comments/InlineCommentZone.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/inline-comments/InlineCommentZone.tsx
@@ -2,7 +2,7 @@ import { useMemo } from 'react';
 import { useTranslation } from 'react-i18next';
 import type ReactMarkdown from 'react-markdown';
 import type { PlatformKind, PlatformUser, PrComment } from '@meebox/shared';
-import { Avatar, makeBitbucketImageFor, ConfirmModal } from '../../../../../common';
+import { Avatar, makeBitbucketImageFor, ConfirmModal, ShareIcon } from '../../../../../common';
 import { formatTimestamp } from '../../../../../../utils/time';
 import { CommentEditEditor } from '../../comments/CommentEditEditor';
 import { CommentReplyEditor } from '../../comments/CommentReplyEditor';
@@ -11,6 +11,10 @@ import { CommentMarkdown } from '../../shared/CommentMarkdown';
 import { toReplyDraftAnchor } from '../../shared/replyDraftAnchor';
 import { ReactionAddButton, ReactionChips, useReactions } from '../../shared/ReactionBar';
 import { useCommentThread } from '../../shared/useCommentThread';
+import {
+  commentReferenceStore,
+  useCommentReference,
+} from '../../../../../../stores/comment-reference-store';
 
 /**
  * Estimate view zone height (in lines). Each comment = header(avatar+name+date, 1.3 lines) + body
@@ -199,6 +203,9 @@ function CommentNode({
     canDelete,
     handleDelete,
   } = useCommentThread(prLocalId, comment);
+  // Whether this comment is the one currently referenced into the Agent conversation.
+  const activeRef = useCommentReference(prLocalId);
+  const referenced = activeRef?.commentId === comment.remoteId;
 
   // body wraps only author + content + reply button / editor; replies live outside as siblings —
   // so hovering inner replies doesn't bubble up to trigger the outer :hover and reveal all ancestor reply buttons at once
@@ -261,6 +268,38 @@ function CommentNode({
                 {deleting ? t('commentsPanel.deleting') : t('common.delete')}
               </button>
             )}
+            {/* Reference into the Agent conversation — same action, same glyph and same toggle behaviour as the
+                comments tab, since a comment surface may differ in layout but never in what its actions do. */}
+            <button
+              type="button"
+              className={`comment-zone-reference-btn${referenced ? ' is-active' : ''}`}
+              onClick={() =>
+                referenced
+                  ? commentReferenceStore.clear()
+                  : commentReferenceStore.set({
+                      prLocalId,
+                      commentId: comment.remoteId,
+                      author: comment.author.displayName || comment.author.name,
+                      body: comment.body,
+                      ...(comment.anchor
+                        ? { anchor: { path: comment.anchor.path, line: comment.anchor.line } }
+                        : {}),
+                    })
+              }
+              title={
+                referenced
+                  ? t('commentsPanel.referenceClearTitle')
+                  : t('commentsPanel.referenceTitle')
+              }
+              aria-label={
+                referenced
+                  ? t('commentsPanel.referenceClearTitle')
+                  : t('commentsPanel.referenceTitle')
+              }
+              aria-pressed={referenced}
+            >
+              <ShareIcon size={13} />
+            </button>
             {/* The "add reaction" button goes after the action buttons (consistent with the comments tab); the whole foot group is already hidden in reply / edit mode. */}
             {reactionsMode && (
               <ReactionAddButton
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index 8a4be21d..d5524619 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -71,6 +71,9 @@
     "codeExistingAria": "Originalcode",
     "codeImprovedAria": "Verbesserter Code",
     "commandNoArgs": "{{cmd}} akzeptiert keine Argumente",
+    "commentReference": {
+      "clearTitle": "Referenzierten Kommentar entfernen"
+    },
     "deleteRunAria": "Löschen",
     "deleteRunTitle": "Diesen Lauf löschen",
     "draftJumpEditTitle": "Im Code bearbeiten",
@@ -272,6 +275,8 @@
     "loadingCodeContext": "Code-Kontext wird geladen…",
     "minutesAgo_one": "vor {{count}} Minute",
     "minutesAgo_other": "vor {{count}} Minuten",
+    "referenceClearTitle": "Verweis auf diesen Kommentar aufheben",
+    "referenceTitle": "Den Agenten zu diesem Kommentar befragen",
     "reply": "Antworten"
   },
   "commitsPanel": {
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index ddff7557..84551f8b 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -71,6 +71,9 @@
     "codeExistingAria": "Original code",
     "codeImprovedAria": "Improved code",
     "commandNoArgs": "{{cmd}} does not accept arguments",
+    "commentReference": {
+      "clearTitle": "Remove the referenced comment"
+    },
     "deleteRunAria": "Delete",
     "deleteRunTitle": "Delete this run",
     "draftJumpEditTitle": "Edit in code",
@@ -272,6 +275,8 @@
     "loadingCodeContext": "Loading code context…",
     "minutesAgo_one": "{{count}} minute ago",
     "minutesAgo_other": "{{count}} minutes ago",
+    "referenceClearTitle": "Stop referencing this comment",
+    "referenceTitle": "Ask the agent about this comment",
     "reply": "Reply"
   },
   "commitsPanel": {
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index 1b440396..c1ba8ec6 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -71,6 +71,9 @@
     "codeExistingAria": "元のコード",
     "codeImprovedAria": "改善後のコード",
     "commandNoArgs": "{{cmd}} は引数を受け付けません",
+    "commentReference": {
+      "clearTitle": "参照中のコメントを外す"
+    },
     "deleteRunAria": "削除",
     "deleteRunTitle": "この記録を削除",
     "draftJumpEditTitle": "コード内で編集",
@@ -269,6 +272,8 @@
     "loading": "コメントを読み込み中…",
     "loadingCodeContext": "コードコンテキストを読み込み中…",
     "minutesAgo_other": "{{count}} 分前",
+    "referenceClearTitle": "このコメントの参照を解除",
+    "referenceTitle": "このコメントについてエージェントに調べてもらう",
     "reply": "返信"
   },
   "commitsPanel": {
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index daf19ceb..5d42c4a0 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -71,6 +71,9 @@
     "codeExistingAria": "原代码",
     "codeImprovedAria": "改进代码",
     "commandNoArgs": "{{cmd}} 不接受参数",
+    "commentReference": {
+      "clearTitle": "移除引用的评论"
+    },
     "deleteRunAria": "删除",
     "deleteRunTitle": "删除此记录",
     "draftJumpEditTitle": "在代码中编辑",
@@ -269,6 +272,8 @@
     "loading": "加载评论中…",
     "loadingCodeContext": "加载代码上下文…",
     "minutesAgo_other": "{{count}} 分钟前",
+    "referenceClearTitle": "取消引用这条评论",
+    "referenceTitle": "让 Agent 调查这条评论",
     "reply": "回复"
   },
   "commitsPanel": {
diff --git a/apps/desktop/src/renderer/src/stores/comment-reference-store.ts b/apps/desktop/src/renderer/src/stores/comment-reference-store.ts
new file mode 100644
index 00000000..a2bf4a95
--- /dev/null
+++ b/apps/desktop/src/renderer/src/stores/comment-reference-store.ts
@@ -0,0 +1,105 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * The comment currently referenced into the Agent conversation ("ask the agent about this comment").
+ *
+ * A reviewer's comment is often a question — is this actually a problem, does this path really run, was this handled
+ * elsewhere — and answering it means reading the code the comment is attached to. That is what the Agent is for, but
+ * until now the only way to hand it a comment was to copy the text into the chat box, losing the anchor and the thread
+ * along with it.
+ *
+ * Lives in a module-level store for the same reason the diff selection does: the comment surfaces (activity panel,
+ * inline diff zone) and ChatPane are sibling panes with no common owner below App, and the reference has to survive
+ * the panes re-rendering independently. Same shape as selection-store (module state + subscriber set +
+ * useSyncExternalStore), purely renderer-local, no IPC and nothing persisted — a reference is a transient intent.
+ */
+export interface CommentReference {
+  /** PR the reference belongs to; a reference from another PR is never presented (see useCommentReference). */
+  prLocalId: string;
+  /** Remote comment id, so the prompt can name the comment the answer is about. */
+  commentId: string;
+  /** Display name of the comment's author. */
+  author: string;
+  /** Comment body as written (markdown, unrendered). */
+  body: string;
+  /** Inline comments carry their code location; a summary comment has none. */
+  anchor?: { path: string; line?: number | null };
+}
+
+interface CommentReferenceState {
+  reference: CommentReference | null;
+}
+
+let state: CommentReferenceState = { reference: null };
+const subscribers = new Set<() => void>();
+
+function notify(): void {
+  for (const cb of subscribers) cb();
+}
+
+export const commentReferenceStore = {
+  getSnapshot: (): CommentReferenceState => state,
+  subscribe: (cb: () => void): (() => void) => {
+    subscribers.add(cb);
+    return () => {
+      subscribers.delete(cb);
+    };
+  },
+  /** Reference a comment (replaces any current one — the input bar carries at most one comment reference). */
+  set: (reference: CommentReference): void => {
+    state = { reference };
+    notify();
+  },
+  clear: (): void => {
+    if (!state.reference) return;
+    state = { reference: null };
+    notify();
+  },
+};
+
+/** The reference for this PR, or null (including when the stored one belongs to another PR). */
+export function useCommentReference(prLocalId: string | undefined): CommentReference | null {
+  const snap = useSyncExternalStore(
+    commentReferenceStore.subscribe,
+    commentReferenceStore.getSnapshot,
+  );
+  const ref = snap.reference;
+  return ref && ref.prLocalId === prLocalId ? ref : null;
+}
+
+/** Trim a body for chip / prompt display, on a word boundary where there is one nearby. */
+function excerpt(body: string, max: number): string {
+  const flat = body.replace(/\s+/g, ' ').trim();
+  if (flat.length <= max) return flat;
+  const cut = flat.slice(0, max);
+  const lastSpace = cut.lastIndexOf(' ');
+  return `${lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut}…`;
+}
+
+/** Short label for the input-bar chip: the author plus enough of the comment to tell which one it is. */
+export function commentReferenceLabel(ref: CommentReference): string {
+  return `${ref.author}: ${excerpt(ref.body, 40)}`;
+}
+
+/**
+ * Assemble the referenced comment into a self-describing block, sent as implicit context alongside the question (the
+ * same channel the diff selection uses, so the two compose when both are present).
+ *
+ * States what the agent is being asked to do, because a comment alone is ambiguous input: without it a model tends to
+ * summarize the comment back rather than investigate the claim. Four-backtick fences, since a comment body can easily
+ * contain triple backticks of its own.
+ */
+export function formatCommentReference(ref: CommentReference): string {
+  const where = ref.anchor
+    ? ` on \`${ref.anchor.path}\`${ref.anchor.line ? `:${String(ref.anchor.line)}` : ''}`
+    : '';
+  return [
+    `The user is asking about this review comment${where}, written by ${ref.author}:`,
+    '',
+    '````',
+    ref.body,
+    '````',
+    '',
+    'Investigate what it claims against the actual code and say whether it holds, with the evidence you found.',
+  ].join('\n');
+}
diff --git a/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss b/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
index d5ac3c89..deb5d04b 100644
--- a/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
+++ b/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
@@ -55,6 +55,7 @@
 }
 .comment-zone-reply-btn,
 .comment-zone-edit-btn,
+.comment-zone-reference-btn,
 .comment-zone-delete-btn {
   padding: 2px $space-3;
   font-size: $fs-sm;
@@ -64,7 +65,10 @@
   color: $text-muted;
   cursor: pointer !important;
   opacity: 0;
-  transition: opacity 0.12s, border-color 0.12s, color 0.12s;
+  transition:
+    opacity 0.12s,
+    border-color 0.12s,
+    color 0.12s;
 }
 .comment-zone-reply-btn:hover {
   border-color: $color-accent;
@@ -76,6 +80,22 @@
   color: $color-info;
   background: rgb(var(--rgb-accent) / 0.08);
 }
+// Reference button: icon-only, so it sizes to the glyph rather than to a label; while the comment is referenced it
+// stays lit (is-active) and visible regardless of hover, since an attached reference must be discoverable at a glance.
+.comment-zone-reference-btn {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px $space-2;
+  line-height: 1;
+}
+.comment-zone-reference-btn:hover,
+.comment-zone-reference-btn.is-active {
+  border-color: $color-accent;
+  color: $color-info;
+}
+.comment-zone-item-body .comment-zone-foot .comment-zone-reference-btn.is-active {
+  opacity: 1;
+}
 // delete button uses danger as its main color to differentiate its semantics from other buttons; semi-transparent when disabled
 .comment-zone-delete-btn:hover:not(:disabled) {
   border-color: $color-danger-strong;
@@ -94,10 +114,12 @@
 // on hovering the comment body area, show all buttons in foot (including add reaction); focus-within covers keyboard / reaction popover open states
 .comment-zone-item-body:hover > .comment-zone-foot .comment-zone-reply-btn,
 .comment-zone-item-body:hover > .comment-zone-foot .comment-zone-edit-btn,
+.comment-zone-item-body:hover > .comment-zone-foot .comment-zone-reference-btn,
 .comment-zone-item-body:hover > .comment-zone-foot .comment-zone-delete-btn,
 .comment-zone-item-body:hover > .comment-zone-foot .pr-reaction-add-wrap,
 .comment-zone-foot:focus-within .comment-zone-reply-btn,
 .comment-zone-foot:focus-within .comment-zone-edit-btn,
+.comment-zone-foot:focus-within .comment-zone-reference-btn,
 .comment-zone-foot:focus-within .comment-zone-delete-btn,
 .comment-zone-foot:focus-within .pr-reaction-add-wrap,
 .comment-zone-reply-btn:focus,
@@ -115,7 +137,7 @@
   padding: $space-3 $space-4;
   font-size: $fs-sm;
   color: $color-danger;
-  background: rgb(var(--rgb-danger) / 0.10);
+  background: rgb(var(--rgb-danger) / 0.1);
   border-left: 3px solid $color-danger;
   border-radius: $radius-sm;
   word-break: break-word;
@@ -142,12 +164,7 @@
   font-size: $fs-lg;
   color: $text-primary;
   font-family:
-    -apple-system,
-    BlinkMacSystemFont,
-    'Segoe UI',
-    'PingFang SC',
-    'Microsoft YaHei',
-    sans-serif;
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif;
   line-height: $lh-loose;
   box-sizing: border-box;
 }
diff --git a/apps/desktop/src/renderer/src/styles/features/pr/comments.scss b/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
index ed21a3ff..cc7befe6 100644
--- a/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
+++ b/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
@@ -307,6 +307,25 @@
     background: rgb(var(--rgb-accent) / 0.08);
   }
 }
+// Reference button: icon-only, so it sizes to the glyph instead of a label. While the comment is referenced it stays
+// lit (is-active), because an attached reference has to be visible without hovering to find it again.
+.pr-comment-reference-btn {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px $space-3;
+  line-height: 1;
+  background: transparent;
+  border: 1px solid $border-default;
+  border-radius: $radius-sm;
+  color: $text-muted;
+  cursor: pointer;
+  &:hover,
+  &.is-active {
+    border-color: $color-accent;
+    color: $color-info;
+    background: rgb(var(--rgb-accent) / 0.08);
+  }
+}
 // Delete button: same size as the reply button, uses danger as the main color so users recognize it at a glance as a destructive action.
 // Secondary confirmation goes through ConfirmModal; no more hover-only hiding on the button (to avoid making users think the feature is missing)
 .pr-comment-delete-btn {

From 006f5e1fe5031d21fabb8937cddec0abe826bedf Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Tue, 8 Sep 2026 22:51:14 +0800
Subject: [PATCH 14/17] feat(comments): turn the agent answer into a draft
 reply to the comment

Investigating a comment usually ends in replying to it, and retyping the
conclusion by hand was the remaining manual step.

This needs the answer to know which comment it answers, so a referenced comment
now hands off on send rather than being discarded: it detaches from the input
bar but stays associated with the round it was asked in. The hand-off runs on
every send, including unreferenced ones -- that is what ends a previous
association, so an unrelated later answer never offers itself as a reply to an
old comment. Memory only, one round: an association that outlived its round
would attach an answer to the wrong comment, and that is worse than not offering
the action at all.

It produces a draft, not a posted reply. The words are the agent''s and
publishing under the user''s name is the user''s call, so it lands in the same
draft pool as every other pending reply -- editable, rejectable, published with
the review batch. No IPC change: drafts:create already models a reply through
replyTo, and the comment''s anchor carries over so an inline reply keeps its
position in the diff.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +-
 CHANGELOG.zh-CN.md                            |  2 +-
 .../src/components/features/chat/ChatPane.tsx | 75 +++++++++++++++++--
 .../chat/components/ConversationMessage.tsx   | 24 +++++-
 .../src/renderer/src/i18n/locales/de-DE.json  |  3 +-
 .../src/renderer/src/i18n/locales/en-US.json  |  3 +-
 .../src/renderer/src/i18n/locales/ja-JP.json  |  3 +-
 .../src/renderer/src/i18n/locales/zh-CN.json  |  3 +-
 .../src/stores/comment-reference-store.ts     | 44 ++++++++++-
 .../src/styles/features/chat/agent.scss       | 13 ++++
 10 files changed, 153 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7d650d87..f3d04a17 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### ✨ Added
 
-- A comment can now be handed to the agent to investigate: click the reference button on any comment and ask about it, and the agent gets the comment, its author and the code it points at, then checks the claim against the actual code.
+- A comment can now be handed to the agent to investigate: click the reference button on any comment and ask about it, and the agent gets the comment, its author and the code it points at, then checks the claim against the actual code. Its answer can be turned into a draft reply to that comment in one click, editable before it goes out.
 - The code editor is now Monaco 0.56.0 (from 0.55.1), which also drops the outdated sanitizer copy behind most of the open dependency advisories.
 - The bundled review engine is now pr-agent 0.45.0 (from 0.39.0). Two long-standing local fixes are no longer needed — a single-line file change is rendered correctly upstream now, and a binary file no longer has to be worked around — and its YAML handling is more tolerant of imperfect model output.
 - Mentions now render as a pill instead of blending into the surrounding text, so it is obvious at a glance when someone is named — on the activity page, in the inline diff comments, in drafts, and in the PR description alike.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 8faa77f9..efc42003 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -9,7 +9,7 @@
 
 ### ✨ 新增
 
-- 现在可以把评论交给 Agent 调查：在任意评论上点击引用按钮再提问，Agent 会拿到评论原文、作者及其指向的代码，对照真实代码核查该说法是否成立。
+- 现在可以把评论交给 Agent 调查：在任意评论上点击引用按钮再提问，Agent 会拿到评论原文、作者及其指向的代码，对照真实代码核查该说法是否成立。得到的结论可一键转成针对该评论的回复草稿，发出前仍可编辑。
 - 代码编辑器升级至 Monaco 0.56.0（原 0.55.1），同时替换掉了此前多数依赖安全告警所指向的过时清理库副本。
 - 内置评审引擎升级至 pr-agent 0.45.0（原 0.39.0）。两处长期存在的本地修补不再需要——单行文件变更在上游已渲染正确，二进制文件也无需再绕开——其 YAML 解析对不规范的模型输出也更宽容。
 - @提及 改为胶囊标签展示，不再淹没在正文里，一眼即可看出点到了谁——活动页、内联 diff 评论、草稿与 PR 描述一致生效。
diff --git a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
index 4c85572a..725ae07e 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
@@ -12,12 +12,13 @@ import type {
 import { invoke } from '../../../api';
 import { ChatIcon, TrashIcon, ConfirmModal, PaneLoading } from '../../common';
 import { useChatRunStore } from '../../../stores/chat-run-store';
-import { useDraftsForPr } from '../../../stores/drafts-store';
+import { draftsStore, useDraftsForPr } from '../../../stores/drafts-store';
 import { useFindingClosuresForPr } from '../../../stores/finding-closures-store';
 import {
   commentReferenceStore,
   commentReferenceLabel,
   formatCommentReference,
+  useAnsweringComment,
   useCommentReference,
 } from '../../../stores/comment-reference-store';
 import {
@@ -166,7 +167,7 @@ export function ChatPane({
   // On PR switch, clear the reference state and reset the detached state to avoid cross-PR residue.
   useEffect(() => {
     setRefFinding(null);
-    commentReferenceStore.clear();
+    commentReferenceStore.reset();
     setScopeDetached(false);
   }, [prLocalId]);
   // On switching to another commit (or clearing the view scope), reset the detached state: the newly selected commit becomes the implicit scope again.
@@ -193,6 +194,9 @@ export function ChatPane({
       .filter(Boolean)
       .join('\n\n') || undefined;
 
+  // The comment this round is answering (set when the question carried a reference). Its presence is what puts the
+  // "use as reply" action on the answer.
+  const answeringComment = useAnsweringComment(prLocalId);
   // The effective scope for this PR's chat commands: follows the commit selected in the Diff view, unless the user has detached (scopeDetached).
   // Only one scope may be in effect at a time — when a Diff selection exists it takes precedence (finer-grained), the commit scope is suspended and its chip
   // is hidden too (see commitScopeChip), auto-restored after the selection is cleared.
@@ -269,6 +273,45 @@ export function ChatPane({
     [timeline, pr?.sourceRef.sha],
   );
 
+  // Key of the last assistant message in the timeline: the answer the action belongs on. Anchored to the last one
+  // rather than to a message id because a conversation message has no stable id of its own here.
+  const lastAnswerKey = useMemo(() => {
+    for (let i = timeline.length - 1; i >= 0; i -= 1) {
+      const m = timeline[i]?.message;
+      if (m && m.role !== 'user') return timeline[i]!.key;
+    }
+    return null;
+  }, [timeline]);
+  /** Turn the agent's answer into a draft reply to the comment that was asked about, then release the association. */
+  const createReplyDraftFromAnswer = (body: string): void => {
+    if (!answeringComment || !prLocalId) return;
+    void invoke('drafts:create', {
+      localId: prLocalId,
+      draft: {
+        body,
+        status: 'pending',
+        replyTo: { parentCommentId: answeringComment.commentId },
+        ...(answeringComment.anchor?.line != null
+          ? {
+              anchor: {
+                path: answeringComment.anchor.path,
+                startLine: answeringComment.anchor.line,
+                endLine: answeringComment.anchor.line,
+              },
+            }
+          : {}),
+      } as Parameters<typeof invoke<'drafts:create'>>[1]['draft'],
+    })
+      .then(() => {
+        void draftsStore.refresh(prLocalId);
+        commentReferenceStore.clearAnswering();
+      })
+      .catch((e: unknown) => {
+        console.error('create reply draft from answer failed', e);
+      });
+  };
+
+
   // Commit messages for divider tooltips: fetch the PR's commits (main-cached; keyed on head sha so it refreshes when
   // the head advances) into a sha → message map. Empty until loaded / on failure (the tooltip falls back to the short sha).
   const [commitMsgBySha, setCommitMsgBySha] = useState<Map<string, string>>(() => new Map());
@@ -452,7 +495,20 @@ export function ChatPane({
           ) : entry.step ? (
             <AgentStepRow key={entry.key} step={entry.step} />
           ) : entry.message ? (
-            <ConversationMessage key={entry.key} message={entry.message} />
+            <ConversationMessage
+              key={entry.key}
+              message={entry.message}
+              useAsReply={
+                answeringComment && entry.key === lastAnswerKey
+                  ? {
+                      label: t('chatPane.commentReference.useAsReply'),
+                      onUse: () => {
+                        createReplyDraftFromAnswer(entry.message!.content);
+                      },
+                    }
+                  : null
+              }
+            />
           ) : null,
         )}
         {/* Trailing commit divider, for the one case with no entry to precede: the head advanced past the last run's
@@ -517,10 +573,13 @@ export function ChatPane({
             undefined,
             tool === 'ask' ? undefined : (effectiveScope ?? undefined),
           );
-          // Release the referenced comment once carried: a reference is per-question, so leaving it attached would
-          // silently prepend the same comment to every later message. The diff selection is deliberately *not*
-          // released here — it stays visible in the editor, so keeping it is what the user sees and expects.
-          if (tool === 'ask') commentReferenceStore.clear();
+          // Hand the referenced comment off to the round being answered: it detaches from the input bar (a reference
+          // is per-question — leaving it attached would silently prepend the same comment to every later message)
+          // while staying associated with this answer, so the answer can be turned into a reply to it. Called on
+          // every send, including unreferenced ones, which is what clears a previous round's association.
+          // The diff selection is deliberately *not* released — it stays visible in the editor, so keeping it is
+          // what the user sees and expects.
+          if (tool === 'ask') commentReferenceStore.handOff();
         }}
         onAgentAsk={(q) => {
           if (refFinding) {
@@ -533,7 +592,7 @@ export function ChatPane({
             return;
           }
           void actions.handleAgentAsk(q, referencedContext);
-          commentReferenceStore.clear();
+          commentReferenceStore.handOff();
         }}
         onCancel={hasMyActive || agentRunningHere ? actions.handleStopAll : undefined}
         onSetReviewStatus={onSetReviewStatus}
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/ConversationMessage.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/ConversationMessage.tsx
index 10eb2c7f..5d8fe3cd 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/ConversationMessage.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/ConversationMessage.tsx
@@ -1,6 +1,6 @@
 import { useTranslation } from 'react-i18next';
 import type { AgentMessage } from '@meebox/shared';
-import { ChatIcon } from '../../../common';
+import { ChatIcon, ShareIcon } from '../../../common';
 import { VERDICT_LABEL_KEY } from '../constants';
 import { Md } from './shared';
 
@@ -8,8 +8,17 @@ import { Md } from './shared';
  * Display of a single multi-turn conversation message: user → right-aligned bubble; assistant review type
  * (with recommendation) → "review summary" card + verdict badge; assistant conversation type (no
  * recommendation) → left-aligned dedicated conversation reply wrapper.
+ *
+ * `useAsReply` turns the answer into a draft reply to the comment the question referenced. Offered only on the answer
+ * to such a question (the caller decides), because the action needs to know which comment it is replying to.
  */
-export function ConversationMessage({ message }: { message: AgentMessage }) {
+export function ConversationMessage({
+  message,
+  useAsReply,
+}: {
+  message: AgentMessage;
+  useAsReply?: { label: string; onUse: () => void } | null;
+}) {
   const { t } = useTranslation();
   if (message.role === 'user') {
     return (
@@ -53,6 +62,17 @@ export function ConversationMessage({ message }: { message: AgentMessage }) {
       <ChatIcon size={16} />
       <div className="markdown chat-agent-reply-body">
         <Md>{message.content}</Md>
+        {/* Turn the answer into a draft reply to the comment that was asked about. A draft rather than a posted
+            reply: the answer is the agent's, and publishing in the user's name is theirs to decide — the draft lands
+            in the same pool as every other pending reply, editable and published with the review batch. */}
+        {useAsReply && (
+          <div className="chat-agent-reply-actions">
+            <button type="button" className="btn btn-sm" onClick={useAsReply.onUse}>
+              <ShareIcon size={12} />
+              <span>{useAsReply.label}</span>
+            </button>
+          </div>
+        )}
       </div>
     </div>
   );
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index d5524619..bf7b7758 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -72,7 +72,8 @@
     "codeImprovedAria": "Verbesserter Code",
     "commandNoArgs": "{{cmd}} akzeptiert keine Argumente",
     "commentReference": {
-      "clearTitle": "Referenzierten Kommentar entfernen"
+      "clearTitle": "Referenzierten Kommentar entfernen",
+      "useAsReply": "Als Antwort übernehmen"
     },
     "deleteRunAria": "Löschen",
     "deleteRunTitle": "Diesen Lauf löschen",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index 84551f8b..b06b10d3 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -72,7 +72,8 @@
     "codeImprovedAria": "Improved code",
     "commandNoArgs": "{{cmd}} does not accept arguments",
     "commentReference": {
-      "clearTitle": "Remove the referenced comment"
+      "clearTitle": "Remove the referenced comment",
+      "useAsReply": "Use as reply"
     },
     "deleteRunAria": "Delete",
     "deleteRunTitle": "Delete this run",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index c1ba8ec6..ee0760e7 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -72,7 +72,8 @@
     "codeImprovedAria": "改善後のコード",
     "commandNoArgs": "{{cmd}} は引数を受け付けません",
     "commentReference": {
-      "clearTitle": "参照中のコメントを外す"
+      "clearTitle": "参照中のコメントを外す",
+      "useAsReply": "返信として使う"
     },
     "deleteRunAria": "削除",
     "deleteRunTitle": "この記録を削除",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index 5d42c4a0..88f49baa 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -72,7 +72,8 @@
     "codeImprovedAria": "改进代码",
     "commandNoArgs": "{{cmd}} 不接受参数",
     "commentReference": {
-      "clearTitle": "移除引用的评论"
+      "clearTitle": "移除引用的评论",
+      "useAsReply": "用作回复"
     },
     "deleteRunAria": "删除",
     "deleteRunTitle": "删除此记录",
diff --git a/apps/desktop/src/renderer/src/stores/comment-reference-store.ts b/apps/desktop/src/renderer/src/stores/comment-reference-store.ts
index a2bf4a95..3f643e3a 100644
--- a/apps/desktop/src/renderer/src/stores/comment-reference-store.ts
+++ b/apps/desktop/src/renderer/src/stores/comment-reference-store.ts
@@ -27,10 +27,17 @@ export interface CommentReference {
 }
 
 interface CommentReferenceState {
+  /** Attached to the input bar, to be carried with the next question. */
   reference: CommentReference | null;
+  /**
+   * The comment the **most recent** question referenced, kept after sending so the answer can be turned into a reply
+   * to that comment. Held only in memory and only for that one round: the association is what makes "use as reply"
+   * meaningful, and an association that outlived its round would attach the answer to the wrong comment.
+   */
+  answering: CommentReference | null;
 }
 
-let state: CommentReferenceState = { reference: null };
+let state: CommentReferenceState = { reference: null, answering: null };
 const subscribers = new Set<() => void>();
 
 function notify(): void {
@@ -47,12 +54,33 @@ export const commentReferenceStore = {
   },
   /** Reference a comment (replaces any current one — the input bar carries at most one comment reference). */
   set: (reference: CommentReference): void => {
-    state = { reference };
+    state = { ...state, reference };
     notify();
   },
   clear: (): void => {
     if (!state.reference) return;
-    state = { reference: null };
+    state = { ...state, reference: null };
+    notify();
+  },
+  /**
+   * Called when a question is sent: the attached reference (if any) detaches from the input bar and becomes the one
+   * this round is answering. Called on **every** send, including unreferenced ones — that is what clears a previous
+   * round's association, so a later unrelated answer never offers to be posted as a reply to an old comment.
+   */
+  handOff: (): void => {
+    state = { reference: null, answering: state.reference };
+    notify();
+  },
+  /** Drop the association (the answer was used, dismissed, or the PR changed). */
+  clearAnswering: (): void => {
+    if (!state.answering) return;
+    state = { ...state, answering: null };
+    notify();
+  },
+  /** Drop both, e.g. on PR switch. */
+  reset: (): void => {
+    if (!state.reference && !state.answering) return;
+    state = { reference: null, answering: null };
     notify();
   },
 };
@@ -67,6 +95,16 @@ export function useCommentReference(prLocalId: string | undefined): CommentRefer
   return ref && ref.prLocalId === prLocalId ? ref : null;
 }
 
+/** The comment the current round is answering, for this PR, or null. */
+export function useAnsweringComment(prLocalId: string | undefined): CommentReference | null {
+  const snap = useSyncExternalStore(
+    commentReferenceStore.subscribe,
+    commentReferenceStore.getSnapshot,
+  );
+  const ref = snap.answering;
+  return ref && ref.prLocalId === prLocalId ? ref : null;
+}
+
 /** Trim a body for chip / prompt display, on a word boundary where there is one nearby. */
 function excerpt(body: string, max: number): string {
   const flat = body.replace(/\s+/g, ' ').trim();
diff --git a/apps/desktop/src/renderer/src/styles/features/chat/agent.scss b/apps/desktop/src/renderer/src/styles/features/chat/agent.scss
index 3666b5db..7bfb674e 100644
--- a/apps/desktop/src/renderer/src/styles/features/chat/agent.scss
+++ b/apps/desktop/src/renderer/src/styles/features/chat/agent.scss
@@ -272,3 +272,16 @@
   font-size: $fs-sm;
   line-height: $lh-loose;
 }
+
+// "Use as reply" action under an agent answer that was asked about a comment. Sits inside the reply body so it
+// aligns with the text rather than the icon gutter, and stays quiet — it is an offer, not the main content.
+.chat-agent-reply-actions {
+  display: flex;
+  margin-top: $space-3;
+
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: $space-2;
+  }
+}

From 3a9e1ef28db6dec39d054c0cecb66a6d918a7648 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Wed, 9 Sep 2026 14:10:04 +0800
Subject: [PATCH 15/17] fix(comments): align the reference button height with
 its sibling actions

The icon button sized itself to its glyph (line-height:1, its own padding) while
the text buttons beside it size to a font-size line box, so it stood taller than
the row it sits in.

Both surfaces now take the same padding and font-size as the text buttons, so
the line box -- and therefore the height -- is theirs; the inline zone simply
stops overriding the shared rule it already belongs to. The svg is display:block
so it does not sit on the text baseline and add descender space underneath.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/styles/features/diff/comment-zone.scss       |  8 ++++++--
 .../renderer/src/styles/features/pr/comments.scss    | 12 ++++++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss b/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
index deb5d04b..6b820783 100644
--- a/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
+++ b/apps/desktop/src/renderer/src/styles/features/diff/comment-zone.scss
@@ -83,10 +83,14 @@
 // Reference button: icon-only, so it sizes to the glyph rather than to a label; while the comment is referenced it
 // stays lit (is-active) and visible regardless of hover, since an attached reference must be discoverable at a glance.
 .comment-zone-reference-btn {
+  // Padding and font-size come from the shared rule above, so this only has to centre the glyph within that box —
+  // overriding them here is what made the button a different height from the text buttons beside it.
   display: inline-flex;
   align-items: center;
-  padding: 2px $space-2;
-  line-height: 1;
+
+  svg {
+    display: block;
+  }
 }
 .comment-zone-reference-btn:hover,
 .comment-zone-reference-btn.is-active {
diff --git a/apps/desktop/src/renderer/src/styles/features/pr/comments.scss b/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
index cc7befe6..664f23c2 100644
--- a/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
+++ b/apps/desktop/src/renderer/src/styles/features/pr/comments.scss
@@ -312,8 +312,10 @@
 .pr-comment-reference-btn {
   display: inline-flex;
   align-items: center;
-  padding: 2px $space-3;
-  line-height: 1;
+  // Same padding and font-size as the text buttons beside it, so the line box — and therefore the button height —
+  // matches theirs. An icon button that sizes to its glyph instead ends up a different height from its row.
+  padding: 2px $space-4;
+  font-size: $fs-sm;
   background: transparent;
   border: 1px solid $border-default;
   border-radius: $radius-sm;
@@ -325,6 +327,12 @@
     color: $color-info;
     background: rgb(var(--rgb-accent) / 0.08);
   }
+
+  // Block-level svg: as an inline element it would sit on the text baseline and add descender space below it,
+  // making the button taller than its siblings even with the line box matched.
+  svg {
+    display: block;
+  }
 }
 // Delete button: same size as the reply button, uses danger as the main color so users recognize it at a glance as a destructive action.
 // Secondary confirmation goes through ConfirmModal; no more hover-only hiding on the button (to avoid making users think the feature is missing)

From c0450638d5858e713965085911dc196f28806a73 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Wed, 9 Sep 2026 16:24:48 +0800
Subject: [PATCH 16/17] fix(describe): drop the blank card and keep diagrams
 left-to-right

Two regressions from the pr-agent 0.45.0 upgrade, both from new upstream
defaults I did not pin, and neither reported as an error by anything.

0.45.0 stamps `<!-- pr-agent-generated -->` at the top of its output. That landed
in the leading title-less section, whose body therefore counted as non-empty --
but an HTML comment renders to nothing, so every /describe result grew a card
that looked blank. trimNoise already discarded blank lines, horizontal rules and
the internal branch-name leak; it now also discards a line that is only an HTML
comment, which makes the existing "no title and no content" rule cover this.

0.45.0 also added pr_diagram_direction='adaptive', which draws any chain past a
few nodes top-down. Pinned to LR: upstream tunes that heuristic for a full-width
page, while the diagram is read here in a narrow chat column, where a tall
diagram pushes the rest of the result off screen and a wide one scrolls sideways
and can be opened in the preview view.

The pinning list in the design doc now separates the two ways an upstream default
can be wrong here -- one adds output that parses as a bogus finding, the other
changes presentation for a surface upstream cannot know about. The upgrade
review only applied the first test, which is why the diagram default slipped
through.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                               |  2 ++
 CHANGELOG.zh-CN.md                         |  2 ++
 docs/arch/02-agent/05-pragent-runtime.md   |  2 +-
 packages/poller/src/parse-output.ts        |  4 ++++
 packages/poller/tests/parse-output.test.ts | 27 ++++++++++++++++++++++
 packages/pr-agent-bridge/src/env.ts        |  5 ++++
 6 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f3d04a17..83c0258a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 
 ### 🔧 Fixed
 
+- A generated PR description no longer ends with a blank card — an invisible marker the review engine now stamps into its output was being treated as a section of its own.
+- Diagrams in a generated PR description are laid out left-to-right again, instead of turning tall and top-down once they get past a few steps and pushing the rest of the result off screen.
 - The commit divider in the review timeline now stays where the commit boundary actually is, instead of sliding further down every time a new message appears below it.
 - The file list in a generated PR description now shows the real number of added and removed lines per file, instead of `+-1/--1`.
 - Links in that file list now open the file instead of pointing at a non-existent line, so clicking through works.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index efc42003..bdb06b80 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -18,6 +18,8 @@
 
 ### 🔧 修复
 
+- 生成的 PR 描述末尾不再出现空白卡片——评审引擎新加入输出的一个不可见标记此前被当成了独立分块。
+- 生成的 PR 描述中的图表恢复为从左至右布局，不再在步骤稍多时变成纵向长图、把其余内容挤出屏幕。
 - 评审时间线中的提交分割线现在固定在提交边界的真实位置，不再因为下方出现新消息而一路下移。
 - 生成的 PR 描述中，文件清单现在显示每个文件真实的增删行数，不再是 `+-1/--1`。
 - 该清单中的链接现在指向文件本身，而非一个不存在的行号，点击可正常跳转。
diff --git a/docs/arch/02-agent/05-pragent-runtime.md b/docs/arch/02-agent/05-pragent-runtime.md
index e81a2ca7..21b067fa 100644
--- a/docs/arch/02-agent/05-pragent-runtime.md
+++ b/docs/arch/02-agent/05-pragent-runtime.md
@@ -68,7 +68,7 @@ Current patches (pinned pr-agent **0.45.0**):
 
 **Retired patches** (kept as a record, because "why is this no longer patched" is the question an upgrade raises): *binary-safe diff* and the *single-line-hunk phantom line* were both **fixed upstream in 0.45.0** — `get_diff_files` now skips a file that fails to decode, and `extract_hunk_headers` defaults an omitted hunk size to 1 rather than 0. Both were verified against the installed runtime before deletion, not assumed from release notes.
 
-**Upstream defaults that must stay pinned**: 0.45.0 turned on three features that append to the output this app *parses* — `pr_reviewer.persistent_finding_state` (a "resolved findings" section carrying upstream's own cross-run state, which the app already owns via drafts / finding closures / re-review verdicts), and two coverage footers. They are forced off in `buildPragentEnv` rather than left at their defaults. **Re-check this list on every upgrade**: a new default that adds a section is not a free improvement here — it lands as a bogus finding.
+**Upstream defaults that must stay pinned** (in `buildPragentEnv`): 0.45.0 turned on three features that append to the output this app *parses* — `pr_reviewer.persistent_finding_state` (a "resolved findings" section carrying upstream's own cross-run state, which the app already owns via drafts / finding closures / re-review verdicts) and two coverage footers — plus `pr_description.pr_diagram_direction='adaptive'`, which turns a longer diagram top-down. **Re-check this list on every upgrade**, and note the two distinct ways a default can be wrong here: one *adds output* (landing as a bogus finding), the other *changes presentation* for a surface upstream does not know about — pr-agent assumes a full-width page, while this diagram is read in a narrow chat column. Neither shows up as an error.
 
 ### Real token usage
 
diff --git a/packages/poller/src/parse-output.ts b/packages/poller/src/parse-output.ts
index e54cc75b..7faae594 100644
--- a/packages/poller/src/parse-output.ts
+++ b/packages/poller/src/parse-output.ts
@@ -161,6 +161,10 @@ function trimNoise(body: string): string {
     const trimmed = l.trim();
     if (trimmed === '') return true;
     if (/^(?:[-*_]\s*){3,}$/.test(trimmed)) return true; // markdown HR
+    // A line that is nothing but an HTML comment: invisible once rendered, so it is not content. pr-agent 0.45.0
+    // stamps `<!-- pr-agent-generated -->` at the top of its output, and counting that as content produced a section
+    // with a body that renders to nothing — an empty card in the run result.
+    if (/^<!--[\s\S]*-->$/.test(trimmed)) return true;
     if (INTERNAL_BRANCH_RE.test(trimmed) && trimmed.length < 40) return true; // short line + contains branch name
     return false;
   };
diff --git a/packages/poller/tests/parse-output.test.ts b/packages/poller/tests/parse-output.test.ts
index fcf52e8c..541580d5 100644
--- a/packages/poller/tests/parse-output.test.ts
+++ b/packages/poller/tests/parse-output.test.ts
@@ -772,3 +772,30 @@ describe('splitMarkdownSections minLevel', () => {
     expect(findings.some((f) => /package-lock/i.test(f.title ?? ''))).toBe(false);
   });
 });
+
+describe('invisible-only sections', () => {
+  // Regression: pr-agent 0.45.0 stamps `<!-- pr-agent-generated -->` at the top of its output. That landed in the
+  // leading (title-less) section, whose body was therefore "not empty" — but an HTML comment renders to nothing, so
+  // the run result grew a card that looked blank.
+  it('drops a section whose body is only an HTML comment', () => {
+    const md = [
+      'pr-7c82edaec417/head',
+      '<!-- pr-agent-generated -->',
+      '### **PR Type**',
+      'Enhancement',
+    ].join('\n');
+    const { findings } = parseReviewOutput(md, 'describe');
+    expect(findings.map((f) => f.title)).toEqual(['PR Type']);
+  });
+
+  it('keeps a section that has real content alongside the comment', () => {
+    const md = [
+      '<!-- pr-agent-generated -->',
+      'actual prose',
+      '### **PR Type**',
+      'Enhancement',
+    ].join('\n');
+    const { findings } = parseReviewOutput(md, 'describe');
+    expect(findings.some((f) => (f.body ?? '').includes('actual prose'))).toBe(true);
+  });
+});
diff --git a/packages/pr-agent-bridge/src/env.ts b/packages/pr-agent-bridge/src/env.ts
index 78caec30..b93bbe1e 100644
--- a/packages/pr-agent-bridge/src/env.ts
+++ b/packages/pr-agent-bridge/src/env.ts
@@ -88,6 +88,10 @@ function normalizeModel(provider: LlmProfile['provider'], model: string): string
  *   — so upstream's version would both duplicate it and parse as extra findings.
  * - `PR_REVIEWER__ENABLE_REVIEW_COVERAGE_FOOTER=false` / `PR_CODE_SUGGESTIONS__ENABLE_SUGGESTIONS_COVERAGE_FOOTER=false`
  *   (new in 0.45, both default **true**): a footer appended to the body, which the parser would read as content.
+ * - `PR_DESCRIPTION__PR_DIAGRAM_DIRECTION=LR` (new in 0.45, defaults `adaptive`): `adaptive` turns any chain longer
+ *   than a few nodes top-down, which is the wrong trade for where this diagram is read — a narrow chat column, where
+ *   a tall diagram pushes everything else off screen while a wide one scrolls sideways and can be opened in the
+ *   preview view. Pinned left-to-right rather than left to a heuristic tuned for a full-width page.
  */
 export function buildPragentEnv(profile: LlmProfile, maxModelTokens?: number): Record<string, string> {
   const env: Record<string, string> = {};
@@ -103,6 +107,7 @@ export function buildPragentEnv(profile: LlmProfile, maxModelTokens?: number): R
   env['PR_REVIEWER__PERSISTENT_FINDING_STATE'] = 'false';
   env['PR_REVIEWER__ENABLE_REVIEW_COVERAGE_FOOTER'] = 'false';
   env['PR_CODE_SUGGESTIONS__ENABLE_SUGGESTIONS_COVERAGE_FOOTER'] = 'false';
+  env['PR_DESCRIPTION__PR_DIAGRAM_DIRECTION'] = 'LR';
   // On import litellm fetches the remote model price table over the network (raw.githubusercontent.com); on an intranet/weak network
   // the SSL timeout slows startup and floods warnings. We only take the real token count (from API response.usage),
   // don't need the price table → force using only the in-package local backup, no network at all. See sitecustomize's usage callback.

From 674b58585161b37b8f35d5d0f812d05fee1cee87 Mon Sep 17 00:00:00 2001
From: Hamhire Hu <me@huhamhire.com>
Date: Wed, 9 Sep 2026 17:46:04 +0800
Subject: [PATCH 17/17] chore(release): 0.12.0

Version, changelog and lockfile for the 0.12.0 release: Unreleased renamed to
the version section in both locales with their compare links, and the app
version dropped from -dev.

Proofread against v0.11.2..dev: 19 entries covering all ten merged PRs, the two
locales matching in count and structure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md              | 3 ++-
 CHANGELOG.zh-CN.md        | 3 ++-
 apps/desktop/package.json | 2 +-
 package-lock.json         | 2 +-
 4 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83c0258a..13338a97 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@
 All notable changes to this project are recorded here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the versioning follows [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.12.0] - 2026-09-09
 
 ### ✨ Added
 
@@ -541,6 +541,7 @@ and the versioning follows [Semantic Versioning](https://semver.org/).
 License: [Apache-2.0](LICENSE). The package bundles third-party components (pr-agent, Electron, etc.), each distributed under its own license, see [NOTICE](NOTICE).
 
 [Unreleased]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.1...HEAD
+[0.12.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.2...v0.12.0
 [0.11.2]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.1...v0.11.2
 [0.11.1]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.10.0...v0.11.0
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index bdb06b80..63fdb30c 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -5,7 +5,7 @@
 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [Unreleased]
+## [0.12.0] - 2026-09-09
 
 ### ✨ 新增
 
@@ -541,6 +541,7 @@
 许可证：[Apache-2.0](LICENSE)。打包内含第三方组件（pr-agent、Electron 等），各按其许可证分发，见 [NOTICE](NOTICE)。
 
 [Unreleased]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.1...HEAD
+[0.12.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.2...v0.12.0
 [0.11.2]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.1...v0.11.2
 [0.11.1]: https://github.com/huhamhire/code-meeseeks/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.10.0...v0.11.0
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 843b87c3..74370c9c 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@meebox/desktop",
-  "version": "0.12.0-dev",
+  "version": "0.12.0",
   "private": true,
   "description": "meebox Electron desktop app",
   "author": {
diff --git a/package-lock.json b/package-lock.json
index f3f5c9ca..e7f52868 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -32,7 +32,7 @@
     },
     "apps/desktop": {
       "name": "@meebox/desktop",
-      "version": "0.12.0-dev",
+      "version": "0.12.0",
       "dependencies": {
         "@iconify-json/material-icon-theme": "^1.2.66",
         "@iconify/react": "^5.2.1",