feat(core): bind PRs created via gh pr create in the session shell

docs/design/2026-08-20-webshell-session-pr-binding.md

@@ -20,10 +20,11 @@ Web Shell 同时运行 20+ 会话时，侧栏信息不足以回答"哪个会话
 `DaemonSessionSummary` 与 `BridgeSessionSummary`（镜像，需同步）增加：
 
 ```json
-"prs": [{ "number": 9517, "url": "https://github.com/owner/repo/pull/9517" }]
+"prs": [{ "number": 9517, "url": "https://github.com/owner/repo/pull/9517", "state": "open" }]
 ```
 
 - 一个会话可能创建多个 PR（stacked PR、连续修复），`prs` 按绑定时间排序（最后一个 = 最新），上限 10 个（超出丢弃最旧）。同号重复绑定刷新 url 并移到最新位。
+- `state`：可选快照，取值 `open` / `merged` / `closed`；写入端（GitDialog）记 `open`，回填记 gh 查询时刻的值，刷新定时器负责 open→merged/closed 迁移。badge 对 merged 弱化显示。
 - `number`：正整数；`url`：http(s) URL（badge/tooltip 直接作为链接目标渲染，拒绝 `javascript:` 等 scheme——route、bridge、SDK 校验器、sidecar 校验四层统一要求）。
 - 字段可选、可缺省；不提供"清除"语义。
 - 写入 API 保持单条：`updateSessionMetadata(sessionId, { pr: {number, url} })` 每次绑定一个，daemon 负责 upsert 进列表；读取/事件/响应均为完整 `prs` 数组。
@@ -35,14 +36,15 @@ Web Shell 同时运行 20+ 会话时，侧栏信息不足以回答"哪个会话
 - bridge `updateSessionMetadata`（`packages/acp-bridge/src/bridge.ts`）先做全部校验再变更（组合请求不允许部分生效）；upsert 进 live entry.prs（去重按 number，上限 10），`session_metadata_updated` SSE 事件 data 带完整 `prs`。
 - ACP `session/update_metadata`（`acp-http/dispatch.ts`）同样把最新绑定 upsert 进 sidecar。
 - `GitDialog.doCreatePr` 成功后：仅用 dialog 已有的 `sessionId`（`sessionIdRef.current`，即连接会话或 dialog 已为提交信息生成等操作解析出的会话）调用 `updateSessionMetadata(sessionId, { pr })`。**不调 `resolveSessionForWorkspace`**——它可能创建幽灵会话或误绑"最近会话"。写入失败仅降级为 console 警告，不影响 PR 创建成功的状态展示。
+- **shell 工具 post-hook**：`run_shell_command` 完成、未中止且退出码为 0 时，`detectGhPrCreateBinding(command, output, repoKey)`（core `session-pr-service.ts`）识别 `gh pr create`（排除 `--dry-run`）并绑定 stdout 里**最后一个** `/pull/<N>` URL——gh 成功时把新建 PR 的 URL 打在输出末尾，而复合命令里被 echo 的文本通常出现在它之前；该 URL 还必须与 workspace 自身仓库一致（`host/owner/repo` 比对 git origin remote），跨仓库/伪造 URL 一律不绑。命中则直接 `upsertSessionPr(..., state:'open')` 直写 sidecar（复刻 worktree sidecar 的"工具进程直写"模式，CLI/daemon 双模生效，daemon 列表 ~2s 内展示）。best-effort，失败不影响工具结果。
 
 ### 持久化
 
 新增 sidecar `<chatsDir>/<sessionId>.pr.json`，复刻 worktree sidecar 模式：
 
 - 新 core 服务 `packages/core/src/services/session-pr-service.ts`：`SessionPr` 接口、数组 schema 校验（`{prs: [...]}`，容忍 ENOENT/JSON 损坏）、`readSessionPrs` / `writeSessionPrs` / `upsertSessionPr`（按 number 去重、移到最新、cap 10）。
 - `SessionService` 增加 `getPrSessionPathForArchiveState` 路径助手；归档/取消归档移动 sidecar、删除会话时清理（与 worktree sidecar 一一对应）。
-- `session-list.ts` 的 `enrichPrSidecars` 回填 persisted summary 的 `prs`；live 会话的 entry.prs 只含本 daemon 生命周期内的绑定，回填时与 sidecar 历史按 number 合并（live 的 url 优先，live-only 的排最后）。
+- `session-list.ts` 的 `enrichPrSidecars` 回填 persisted summary 的 `prs`；live 会话的 entry.prs 只含本 daemon 生命周期内的绑定，回填时与 sidecar 历史按 number 合并（live 的 url 优先，live-only 的排最后；`state` 以 sidecar 为准——定时器只刷 sidecar，live entry 停在绑定时刻）。
 
 ### 展示与搜索（web-shell 侧栏）
 
@@ -52,9 +54,31 @@ Web Shell 同时运行 20+ 会话时，侧栏信息不足以回答"哪个会话
 - SSE 消费侧：web-shell 不直接消费 `session_metadata_updated` 更新 store；bridge 的 `markSessionCatalogChanged()` 触发 catalog revision bump，侧栏 live-state 轮询（2s 周期）发现后自动 refetch——badge 在绑定后 ~2s 内出现（与改名等其他客户端变更的传播机制一致）。
 - i18n：新增 `sidebar.sessionPr` / `sidebar.sessionPrMultiple` 两个 key（EN/ZH）。
 
+### 存量回填（按需）
+
+新增 daemon 路由 `POST /sessions/backfill-prs`（进程级、按需触发，启动不自动扫描），实现见 `packages/cli/src/serve/routes/session-pr-backfill.ts`：
+
+- 遍历 registry 中所有 trusted workspace runtime；每个 workspace 扫描 persisted 会话（active + archived），候选分支 = worktree sidecar branch ∪ transcript 各记录的 `gitBranch`（正则提取，distinct 上限 64），解析三源：
+  1. **约定**：slug `pr-<N>` / branch `worktree-pr-<N>` 直接给出 PR 号（零网络）；
+  2. **gh 批量**：每 workspace 一次 `fetchGitHubPullRequests({state:'all', limit:500, slim:true})`，把候选分支与 headRefName 交集映射到 number + url。实测存量里 `pr-<N>` slug 与 worktree branch 几乎零命中（PR 基本不从 worktree 分支提交），`gitBranch` 是主力来源（主 workspace 342 会话命中 272）；
+  3. **transcript `gh pr create` 痕迹**：按 part id 配对 `run_shell_command` 的 functionCall/functionResponse，复用 `detectGhPrCreateBinding` 提取创建时打印的 URL（同样要求 URL 属于 workspace 自身仓库）——gh 不可用时也能绑（URL 兜底链：gh 映射 → 创建时打印的 URL → remote 推导仅约定号）。
+- `slim` 只取 number/url/headRefName：带 CI rollup 的全字段查询在 `--state all --limit 500` 下触发 GitHub GraphQL 504；slim 约 4s/60KB。
+- URL 优先取 gh 映射；gh 不可用时由 git remote web URL 推导 `<repo>/pull/<N>`（支持 https / scp 风格 ssh / `ssh://` 与 enterprise host，仅约定号）；解析不到号的会话原样跳过。
+- 已知副作用：曾 checkout/review 他人 PR 分支的会话也会被绑定（多 PR 列表可容纳，搜索语义上属于"相关会话"）。
+- 已绑定同一 number 的会话跳过（不刷新 createdAt），重复调用幂等；写入复用 `upsertSessionPr`。
+- 响应按 workspace 聚合 `scanned/bound/alreadyBound/unresolved`；untrusted workspace 跳过。
+
+### 合入状态快照 + 定时刷新
+
+- **快照来源**：slim 查询增取 gh `state`（OPEN/MERGED/CLOSED → `open`/`merged`/`closed`）；回填写入当时值，GitDialog 新建记 `open`。
+- **定时器**：daemon 启动后挂独立低频任务（不挂列表轮询热路径），默认 **5 分钟**一轮，环境变量 `QWEN_SESSION_PR_REFRESH_MINUTES` 可调（`0` = 关闭）；`unref()` 不阻碍进程退出，首轮延迟启动避开 boot。
+- **每轮**：遍历 trusted workspace → 读 `.pr.json` sidecar 挑出非 merged 绑定 → 无目标直接跳过（零 gh 调用）→ 有目标发一次 slim `gh pr list --state all --limit 500` → `updateSessionPrStates` 原地回写 state（**不重排顺序、不刷新 createdAt**，与 upsert 共享同一路径写入队列避免竞态）→ badge 经现有 2s 轮询自动更新。
+- **成本**：只对含未合入绑定的 workspace 发查询（每 ~4s）；gh 不可用时静默跳过该轮。
+- **明确不做**：定时器不做新 PR 发现（重扫 transcript 全量 6 分钟不适合 5 分钟周期）；发现由 shell post-hook（实时）与 backfill（按需）承担。
+
 ## 关键决策
 
-- **绑定时机 = GitDialog 创建 PR 成功时**。Agent 在 shell 里自行 `gh pr create` 的路径无法拦截，MVP 不覆盖；用户主力流程是 GitDialog。
+- **绑定时机 = GitDialog 创建 PR 成功时**（用户主力流程）；agent 在 shell 里 `gh pr create` 由 shell 工具 post-hook 实时识别 + backfill 的 transcript 痕迹源回填存量（后续补充，见写入端与回填章节）。
 - **sidecar 而非 transcript 记录**：displayName 走 `custom_title` transcript 记录是因为标题属于会话内容流；PR 绑定是会话外部元数据，worktree sidecar 是同类先例，改动面更小。
 - **多 PR 列表（cap 10）**：一个会话可能创建多个 PR（stacked PR、连续修复），只保留最新一个会让"按 PR 号反查会话"在这些场景失效。绑定按 number 去重、重复绑定移到最新位；badge 显示最新号 + `+N`，tooltip 列全部，搜索匹配任意一个。上限 10 防无界增长。
 - **workspace 级打开 GitDialog（无会话上下文）时不回写**：dialog 没有已解析的会话就跳过，不报错；绝不通过 `resolveSessionForWorkspace` 创建新会话来绑定（会产生幽灵会话/误绑）。
@@ -68,18 +92,17 @@ Web Shell 同时运行 20+ 会话时，侧栏信息不足以回答"哪个会话
 | SDK 客户端  | `packages/sdk-typescript/src/daemon/DaemonClient.ts`（updateSessionMetadata 参数）                                                                        |
 | bridge 类型 | `packages/acp-bridge/src/bridgeTypes.ts`（BridgeSessionSummary.pr、metadata 参数）                                                                        |
 | bridge      | `packages/acp-bridge/src/bridge.ts`（updateSessionMetadata 校验/存储/广播）                                                                               |
-| core        | `packages/core/src/services/session-pr-service.ts`（新增）+ SessionService 路径助手/归档移动/删除清理                                                     |
+| core        | `packages/core/src/services/session-pr-service.ts`（新增）+ SessionService 路径助手/归档移动/删除清理；`tools/shell.ts`（gh pr create post-hook）         |
 | daemon 路由 | `packages/cli/src/serve/routes/session.ts`（两个 PATCH 路由校验 + sidecar 写入）、`acp-http/dispatch.ts`（ACP `session/update_metadata` 的 sidecar 写入） |
 | daemon 列表 | `packages/cli/src/serve/server/session-list.ts`（enrichPrSidecars）                                                                                       |
+| daemon 回填 | `packages/cli/src/serve/routes/session-pr-backfill.ts`（`POST /sessions/backfill-prs`，存量会话按需回填）                                                 |
 | web-shell   | `GitDialog.tsx`（回写）、`WebShellSidebar.tsx`（badge + 搜索）、`SessionDetailsTooltip.tsx`（PR 行）、locale 文件                                         |
 | 测试        | 上述各层的 collocated 单测                                                                                                                                |
 
 ## 范围边界（明确不做）
 
 - 服务端分页过滤（20+ 会话规模客户端搜索足够；`sourceType/sourceId` 过滤管道是将来扩展的样板）。
-- 历史会话迁移；CLI `--worktree=#<pr>` 的 `pr-<n>` slug 由搜索匹配 slug 顺带覆盖。
-- 纯 branch 会话 branch 信息重启丢失的独立 bug，另行处理。
-- Agent shell 内 `gh pr create` 的自动发现。
+- 无 worktree sidecar 且 transcript 无 `gh pr create`/`gitBranch` 痕迹的会话：回填无可靠来源，不覆盖。
 
 ## 开放问题
 

packages/acp-bridge/src/bridge.ts

@@ -9678,7 +9678,11 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
           // The url is interpolated into the stderr audit line — control
           // characters would let a client forge log lines (the displayName
           // branch rejects them for the same reason).
-          hasControlCharacter((pr as SessionPrInfo).url)
+          hasControlCharacter((pr as SessionPrInfo).url) ||
+          ((pr as SessionPrInfo).state !== undefined &&
+            (pr as SessionPrInfo).state !== 'open' &&
+            (pr as SessionPrInfo).state !== 'merged' &&
+            (pr as SessionPrInfo).state !== 'closed')
         ) {
           throw new InvalidSessionMetadataError(
             'pr',
@@ -9760,10 +9764,21 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
         if (latest?.number === bound.number && latest.url === bound.url) {
           // Same binding repeated — no change, no event.
         } else {
-          // Re-binding a number refreshes it and moves it to latest.
+          // Re-binding a number refreshes it and moves it to latest; an
+          // omitted state preserves the known one (mirrors the sidecar).
+          const known = existing.find((p) => p.number === bound.number);
           entry.prs = [
             ...existing.filter((p) => p.number !== bound.number),
-            { number: bound.number, url: bound.url },
+            {
+              number: bound.number,
+              url: bound.url,
+              ...((bound.state ?? known?.state)
+                ? {
+                    state: (bound.state ??
+                      known?.state) as SessionPrInfo['state'],
+                  }
+                : {}),
+            },
           ].slice(-SESSION_PR_LIST_LIMIT);
           markSessionCatalogChanged();
           writeStderrLine(
@@ -9804,7 +9819,11 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge {
       const entry = byId.get(sessionId);
       if (!entry || (entry.prs && entry.prs.length > 0)) return;
       entry.prs = prs
-        .map(({ number, url }) => ({ number, url }))
+        .map(({ number, url, state }) => ({
+          number,
+          url,
+          ...(state ? { state } : {}),
+        }))
         .slice(-SESSION_PR_LIST_LIMIT);
     },
 

packages/acp-bridge/src/bridgeTypes.ts

@@ -725,6 +725,8 @@ export interface BridgeSessionGoal {
 export interface SessionPrInfo {
   number: number;
   url: string;
+  /** Snapshot of the PR's state at last bind/refresh; optional. */
+  state?: 'open' | 'merged' | 'closed';
 }
 
 export interface SessionMetadataUpdate {

packages/cli/src/serve/acp-http/dispatch.ts

@@ -2933,6 +2933,7 @@ export class AcpDispatcher {
                 typeof boundPr['number'] === 'number' &&
                 typeof boundPr['url'] === 'string'
               ) {
+                const boundState = boundPr['state'];
                 const persistedPrs = (
                   await upsertSessionPr(
                     service.getPrSessionPathForArchiveState(
@@ -2942,9 +2943,18 @@ export class AcpDispatcher {
                     {
                       number: boundPr['number'],
                       url: boundPr['url'],
+                      ...(boundState === 'open' ||
+                      boundState === 'merged' ||
+                      boundState === 'closed'
+                        ? { state: boundState }
+                        : {}),
                     },
                   )
-                ).map(({ number, url }) => ({ number, url }));
+                ).map(({ number, url, state }) => ({
+                  number,
+                  url,
+                  ...(state ? { state } : {}),
+                }));
                 // Reply with the authoritative persisted list, mirroring the
                 // REST metadata routes.
                 result = { ...result, prs: persistedPrs };

packages/cli/src/serve/process-env-guard.test.ts

@@ -189,6 +189,16 @@ const allowedProcessEnvAccesses = normalizeAllowances([
       accesses: { whole: 1 },
     },
   ],
+  [
+    'packages/cli/src/serve/server/session-pr-refresh.ts',
+    {
+      reason:
+        'The PR-state refresh interval (QWEN_SESSION_PR_REFRESH_MINUTES) is a ' +
+        'process-scoped operator switch; embedded callers may omit the ' +
+        'environment argument.',
+      accesses: { whole: 1 },
+    },
+  ],
   [
     'packages/cli/src/serve/live/live-host-coordinator.ts',
     {