feat: desktop single-instance lock and port fallback

WORKMEMORY/PROJECT_OVERVIEW.md

@@ -30,13 +30,17 @@
 - **未发版（已进 master，2026-10-20）：前端单体继续解耦 + 分层闸纳管面扩展**（PR **#161** / **#164** / **#165** / **#166**，计划 `docs/plans/2026-10-19-reader-js-layer-split.md` · `2026-10-19-reader-api-layer-split.md` · `2026-10-20-cards-state-container.md`，设计稿 `docs/specs/2026-10-20-cards-state-view-decoupling-design.md`）。`reader.js` 抽出 `rd-syntax.js`（纯语法层）与 `rd-api.js`（L2 持久化层，14 个端点函数）；`cards.js` 的 **15 个模块级可变状态**收进 `cd-state.js` 纯状态容器，视图层顶层 `let` **15 → 0**（首次把视图层纳入机械约束，闸规则 ⑦）。导出面全程冻结（`reader.js` 40 个具名、`cards.js` 36 个 + 1 条 barrel 逐字不变），错误轨守恒（`reader.js` 10/10、`cards.js` 12/12）。
   ⚠️ **本批真正的产出不是解耦，是挖出两条与重构无关的既有静默失效**：① `ia_dom_mount_probe.mjs` 有 **4 条守卫一直是死的**（切片锚点只到函数名 ⇒ 切片里没有函数体 ⇒ 断言恒真），② 探针静态层已红时仍照样跑 `node:vm`，空源撞出的 `ReferenceError` 排在真实具名问题**后面**、把诊断引向渲染链（#166 修）。两者形态相同：**判据看着在跑，实际恒真**。纪律已写进 `docs/agents/architecture.md`「前端模块分层契约」节，动探针/守卫前必读。
   ⚠️ **计划写法教训（已在计划里更正）**：变异用例的注入锚点必须按**最终状态树**普查 —— Task 1 新造的锚点钉在 `let cardSegment = "due";` 上，而那正是 Task 3 要删的行，于是两条用例挂在「锚点命中 0 次」而不是挂在闸上。另：同一主机上并行子代理曾三次落在**错误血统**的 worktree 上并据此给出与事实相反的汇报，故后续派单一律要求「先 merge 目标分支并核实 HEAD」。
+- **现测基线（2026-10-22 18:30，分支 `feat/desktop-single-instance` @ `58b8f57`；单实例锁交付实测，**当前值**）**：全量 **2586 收集 = 2584 passed + 2 skipped**（单进程串行 **580s**，前置 `PYTHONIOENCODING=utf-8`）· **156** 个 `tests/test_*.py` · `static/js` **36** · `tools/*.mjs` **31** · `ruff check .` 零告警 · `mypy --strict delector tools`（**119** files）/ `mypy --follow-imports=skip tests`（**160** files）/ 入口面 `--platform win32 --strict --follow-imports=skip`（**4** files）零错误 · 六道机械闸全 exit 0 · PR #172 CI 全绿（含 Windows Portable Smoke）。LOC：后端+入口 `*.py` **40,001** / tests **61,312** / `static/js` **16,801**。
+  - ⚠️ 入口面那档 MUST 带 `--follow-imports=skip`（漏了会本地假绿，见 `docs/agents/ops.md` 第 13 条第四类）。
+- **历史基线（2026-10-21 23:38，master `85fb029`；已被上一行取代）**：全量 **2519 收集 = 2517 passed + 2 skipped**（`python -m pytest tests/ -q`，单进程串行 **513s**，前置 `PYTHONIOENCODING=utf-8`）· 155 个 `tests/test_*.py` · `static/js` **36** · `tools/*.mjs` **31** · `ruff check .` 零告警 · `mypy --strict delector tools`（**118** files）/ `mypy --follow-imports=skip tests`（**159** files）零错误 · `cd agent && go test ./...`（8 包）全绿 · 六道机械闸全 exit 0。**该基线含 dependabot 的 `fastapi 0.144.0` / `starlette 1.8.0` 升级（#168/#170）⇒ 两个 minor bump 在本机无回归**（此前该升级只报过 CI，未见本地全量结论）。LOC：后端+入口 `*.py` **39,577** / tests **59,429** / `static/js` **16,800**。
 - **现测基线（2026-10-21，分支 `fix/master-scope-gate-squash-merge`；本次实测重算）**：全量 155 个文件 · 8 批串行全绿 = 收集 **2519**（**2517 passed + 2 skipped**，净增 6 条 master-scope 健全性与变异自证测试）· `static/js` **36** 个模块 · `tests/test_*.py` **155** 个文件 · `tools/*.mjs` 探针 **31** 个 · `ruff` 零告警 · `mypy --strict delector tools`（**118** files）/ `mypy --follow-imports=skip tests`（**159** files）零错误 · 六道机械闸全 exit 0。
   - 重算：`python3 -m pytest tests/ --collect-only -q | tail -1`；`ls static/js/*.js | wc -l`；`ls tests/test_*.py | wc -l`；`ls tools/*.mjs | wc -l`。
   - ⚠️ 全量 MUST **分批串行**跑（本主机并行 python 会争抢数据目录守卫导致假红）。
 - **现测基线（2026-10-20，master `07139ac`；历史发版前基线）**：全量 155 个文件 · 8 批串行全绿 = 收集 **2513**（**2511 passed + 2 skipped**）· `static/js` **36** 个模块 · `tests/test_*.py` **155** 个文件 · `tools/*.mjs` 探针 **31** 个 · `ruff` 零告警 · `mypy --strict delector tools`（**118** files）/ `mypy --follow-imports=skip tests`（**159** files）零错误 · 六道机械闸全 exit 0。
 - **现测基线（2026-10-19，master `4646a67` 发版基线；由本次发版实测）**：收集 **2441** 用例（**2438 passed + 3 skipped**，全量单条串行分批全绿）·`ruff check .` 零告警 · `mypy --strict delector tools`（**118** files）· `mypy --follow-imports=skip tests`（**157** files）· 入口面 `--platform win32 --strict`（**4** files）零错误 · `tools/*.mjs` 探针 **31** 个 · `static/js` **34** 个模块 · `tests/test_*.py` **153** 个文件。**六道机械闸**：`check_layer_invariants` · `check_mock_drift` · `check_silent_degradation` · `check_frontend_api_contract` · `check_frontend_layers` · `check_index_html_sync` 全 exit 0。
   - 重算：`python3 -m pytest tests/ --collect-only -q | tail -1`；`python3 -m mypy --strict delector tools | tail -1`；`ls tools/*.mjs | wc -l`；`ls static/js/*.js | wc -l`。
-  - ⚠️ **本行已不是当前值**（v5.18.0 发版快照，收集 2441）。当前值看**上面那条「现测基线（2026-10-20）」**。v5.17.0 的 1768 passed 同理是历史快照 —— 读到时 MUST 以 2026-10-20 那条为准，MUST NOT 拿旧值做判断。
+  - ⚠️ **本行已不是当前值**（v5.18.0 发版快照，收集 2441）。当前值看**上面那条「现测基线（2026-10-21 23:38，master `85fb029`）」**。v5.17.0 的 1768 passed 同理是历史快照 —— 读到时 MUST 以当前那条为准，MUST NOT 拿旧值做判断。
+- **未发版（分支 `feat/desktop-single-instance`，2026-10-22）**：**桌面单实例锁 + 端口顺延**（计划 `docs/plans/2026-10-21-desktop-single-instance.md`，10 任务）。判据从「端口上有没有东西」换成 OS 文件锁（`%LOCALAPPDATA%\DeLector\instance.lock` + `instance.json` 分离，避免 POSIX `os.replace` 让锁静默失效）；唯一判定点 `start.claim_instance`，`start.main()` 与桌面壳共用；端口候选 `8000, 8002–8010`（8001 留给 Go supervisor），自动顺延 / 显式 `--port` 不顺延；锁降级时以 `/api/health` 身份探测作第二腿（否则会为同一个库起第二个服务）；`/api/wb/lan-info` 改为报真实端口。桌面壳退出码新增 3 = 端口或实例冲突（六种 `reason` 各有获批的人话文案）。细节见 `docs/agents/architecture.md`「桌面单实例与端口顺延」。
 - **未发版（已进 master，2026-10-15）**：**ADR-0023 交互层「验证驱动 agent 循环」Task 0~6**（PR #136，7 个任务单元经 maker-checker 双席位评审）—— Go 门禁三红灯修复并接入 CI（含执行期新发现的「硬编码 8001 且不校验身份 ⇒ 真实风险是假绿」）、LLM 出网收口到 `delector/services/llm_client.py`（5 处裸 HTTP + 补 `max_tokens`）、循环内核 `delector/services/polish_loop.py`（收尾终审 / 不降即停 + argmin 回退 / 循环级 token+deadline 预算 / 零静默失败）、工具白名单 `polish_tools.py`（恰好 3 项只读 + 前置钩子）、`ai-polish` 返回契约新增 `converged`/`unconverged_reason` + SSE 逐轮进度/取消 + 未收敛 toast。**⚠️ 按 ADR-0023 §4.3 不得宣称「已实现」**：裁判集一行未扩，适用性闸门使循环的真实迭代价值目前只覆盖 A1 书信体。剩余活项：① 裁判集扩充（Unknown 1，第一瓶颈）② Android 真机点检（本批动了 `static/`，且 **SSE 的 `fetch`+`ReadableStream` 在 WebView 未验证**）③ 有 Key 后回测真实轮次分布与真 token 计数（折算系数 3.0 是 UNVERIFIED 假设）。
 - **未发版（已进 master，2026-10-15 第二批）**：**ADR-0023 §4.3 第 ④ 步「裁判集扩充」**（计划 `docs/plans/2026-10-15-a1-judge-expansion.md`，8 任务全交付，PR **#137**）。裁判从 6 条书信格式/字数浅规则扩到 A1 语法层：**动词位置**（主句 V2 + 8 豁免）· **格的使用**（冠词-名词一致 / 介词支配格 / 动词支配格，29 条人工登记动词→格表）三条 error 级；**时态一致性**接线为 **advisory**（用户拍板）；**语序（情态框架）经实测评审判定不做**（FP 与 FN 同源）。同时把**闸门按规则族分流** ⇒ 语法族对**任意德语文本**生效（循环价值面不再只覆盖 A1 书信体），并把提示词按文本族参数化。§4.3 判据表 8 条实测后经用户签批：**采用限定表述，无条件「已实现」继续禁用**（第 8 条对照实验缺 Key 未做）。**排障经验已沉淀**：vault `99-Inbox/2026-10-15-规则引擎硬门必须按「类」覆盖正样本…md`（含"三次误报类全被官方样本集放过"与两条既有规则的新实例）。
   ⚠️ 本批最值得复看的产品语义变更：**非书信文本模型修不动语法错 ⇒ `no_improvement` ⇒ 回退原文**（前端给人话原因码；用户签批保持）。
@@ -76,7 +80,7 @@
 3. **README 首屏改造**（宣传线，门槛③剩余部分）：截图/GIF + 一句话价值 + 30 秒上手；当前首屏对非技术用户仍是代码仓库脸（badge 墙 + 版本摘要墙）。
 4. **预置包 LLM gloss 富化**：阻塞于 `DEEPSEEK_API_KEY` 缺失；`import_encounter_pack` 按 `pack_id` 幂等**不更新**既有行。
 5. **C 档 8 项（当前唯一待办入口）**：`docs/reviews/2026-10-16-open-items-backlog.md`。其中 **C1「裁判结论回灌（verifier-in-the-loop）」为无条件下一步**（ADR-0024 四条硬依赖：① ~~裁判 FP 先修完~~ 已确认基线完成 ② 回灌内容 MUST 过同一道适用性闸与双限截断 ③ 定三角一致性（循环裁判带 nlp / `writing_check` **不带** nlp / 回灌源）④ 阴性对照 MUST 在动产品之前先跑成基线）。⚠️ 回灌落地后，§4.3 实验的阈值与结论**只对"准入式裁判"有效** ⇒ 必须重跑或明确分域（ADR-0024 已登记资产折旧，不留给下一任发现）。
-6. **递延项（未立项）**：tests `--strict`；`tools/vault-proactive-scan.py` 三条版本正则无自动化守卫；PWA 安装提示验证 / 192-512 PNG 图标；桌面单实例文件锁（pid+版本+数据目录 + `/api/health` 身份校验 + 顺延 8001–8010）；发布链路 runbook（Publish 被跳过 / 孤儿 tag 的恢复路径：Vault v5.4.0 复盘 + **v5.1.1 孤儿 tag 在案**；`gh workflow run --ref <tag>` 理论可补发但**本仓未实证**，判据只能是 release 资产清单）。
+6. **递延项（未立项）**：tests `--strict`；`tools/vault-proactive-scan.py` 三条版本正则无自动化守卫；PWA 安装提示验证 / 192-512 PNG 图标；**桌面单实例与端口顺延已于 2026-10-22 交付**（见「当前状态」，勿再当待办）；发布链路 runbook（Publish 被跳过 / 孤儿 tag 的恢复路径：Vault v5.4.0 复盘 + **v5.1.1 孤儿 tag 在案**；`gh workflow run --ref <tag>` 理论可补发但**本仓未实证**，判据只能是 release 资产清单）。
 7. **`check_master_commit_scope.py` 把 squash 合并误判成直推【已闭环 (2026-10-21)】**：
    - 根因：`--no-merges --first-parent` 只能识别多父的 merge-commit 型合并；GitHub squash/rebase 合并产出的单父提交被误划入直推审查对象，导致 #165 / #166 在 PR CI 全绿合并后被 master 直推闸拦截（因整个 PR 改动面不在白名单）。
    - 修法（分支 `fix/master-scope-gate-squash-merge`）：以 `committer == "GitHub <noreply@github.com>"` 判定 GitHub 集成合并（merge / squash / rebase 三种合并方式均盖该章，本地 git commit 不会生成）。同时封死原有仅凭 `Merge pull request #...` 标题即可绕过检查的单父伪造路径（要求 `is_merge_commit` 即 ≥2 父）。