Read the analysis cache before refusing a pass, and own the cache root

Opening a recording while the session that recorded it was still live never reached
``stored_result()``, so the panel reported no result over a recording whose result was on
disk. The guard now follows the cache read, results move to the app's derived-data root
(swept at startup, the old in-recording root ignored), and the panel states which of the
four no-result states it is in, with the pass's own reason.
Verified: apps/studio 462/0/18, shared 431/0/1, autocal 358, ui_check 628/0, both gates
clean, real-GL snapshots per state.

apps/studio/docs/replay-analysis-part-b.md

@@ -24,26 +24,31 @@
 
 **应用里的时间轴永远是录像的。** 引擎留在 `recording`：游标、帧 id 与时长都是录像自己的，
 结果挂在游标后面当缓存（`available_result()`），`_adopt_session()` 调用 `use_recording()` 保证
-这一点。缓存有三个触点，不必先打开「从视频重算」：复用已有结果、pass 完成、选择器选中派生模式
-（时间轴不动）。
+这一点。缓存有三个触点，都不必先打开「从视频重算」：复用结果、pass 完成、选中派生模式。
 
 **帧身份只来自录像自己的计数器。** 证据录像 id 是 20…52 而非 0…32，所以
-`AnalysisSession.frame(frame_id)` 对结果里没有的 id 报 `AnalysisNotFoundError`：把索引当 id
-传进去不会被"顺手改成能读的那一帧"，那会返回一张看起来完全正确的图。按时间取帧走
-`frame_id_at(t)`，取**该时刻或之前**的那一帧 —— 与顺序播放经过的是同一帧。
+`AnalysisSession.frame(frame_id)` 对结果里没有的 id 报 `AnalysisNotFoundError`：把索引当 id 传
+进去不会被"顺手改成能读的那一帧"。按时间取帧走 `frame_id_at(t)`，取**该时刻或之前**的那一帧
+—— 与顺序播放经过的是同一帧。
 
 ## 10. 打开即分析
 
-打开录像后固定做一件事：**有兼容结果就用，没有就跑**。`stored_result()` 命中是一次文件读，
-面板显示"已有结果，无需重算"；没有命中就在**工作线程**上跑 pass，`Progress` 按 0.1 s 合流后
-经 Qt 信号回到 GUI 线程，面板显示 `已写/预计`、分段号与已用时间。pass 期间时间轴留在
-`recording` 模式，完成后才切到 `analysis` —— 半截结果永远不上屏。面板的取消按钮置一次取消
-事件，服务在检查点停下，目录带 `INCOMPLETE` 标记留下，**不提供回放**（第 13 节）。「从视频
-重算」语义不变，与打开路径走同一个 `on_analysis_requested()`，因此不可能出现两条并行模式。
+打开录像后固定做一件事：**有兼容结果就用，没有就跑**，而且**顺序是硬性的**：读结果是一次
+文件读（不开链路、不碰设备、不改工作目录），「一次只跑一条链」管不到它，所以
+`on_analysis_requested()` 先问缓存、再问会话。反过来时，只要采集会话还在（暂停也算：设备还在
+手里）或预览开着，整个调用就被拒、缓存根本没读 —— 面板对着一份就在磁盘上的结果说"这个录像还
+没有分析结果"，操作员得停掉会话再重新打开才看得到箭头。
 
-分析的四条终态消息**都不写状态栏**，只更新进度面板：pass 是异步的，可能在操作员做了别的事
-几秒后才结束，一条活得比原因久的状态栏消息会把无关操作说成失败。原因留在面板上，也由
-`analysis_error()` 提供。
+**拒跑是状态，不是过期就消失的状态栏文字。** 真没有结果时才轮到会话判断：此时不跑 pass（开
+链路要独占工作目录），`analysis.blocked` 作为原因记下来，2D 面板据此把话说明白（第 11 节）。
+`stored_result()` 命中就是一次文件读（"已有结果，无需重算"）；没命中才在工作线程上跑 pass，
+`Progress` 按 0.1 s 合流后经 Qt 信号回到 GUI 线程。pass 期间时间轴留在 `recording`，完成后才切
+到 `analysis` —— 半截结果永远不上屏；取消按钮置一次取消事件，目录带 `INCOMPLETE` 标记留下，
+**不提供回放**（第 13 节）。「从视频重算」与打开路径走同一个 `on_analysis_requested()`。
+
+分析的四条终态消息**都不写状态栏**，只更新进度面板：pass 是异步的，可能在操作员做了别的事几秒
+后才结束，一条活得比原因久的状态栏消息会把无关操作说成失败。原因留在面板上，也由
+`analysis_error()` 与 `result_state()` 提供：**面板那一行和进度条说的是同一件事**。
 
 **并发与工作目录。** 开链路会往当前目录写 2 MB 预览图（Part A 第 6 节），所以 pass 跑在**本
 进程**的一个线程里，启动前要求没有采集会话、没有预览、也没有第二遍分析，并且**本模块从不改
@@ -57,21 +62,29 @@
 | 二维画布 | 结果的 `flow`、`depth` 与 `valid_mask` | `ImageFrame` 走窗口唯一的 2D 出口 `_show_image_frame`（录像时间轴上的派生视图带 `source="replay"` 与 `result_available=True`，因此"原始图像"仍在选择器里），箭头、暗点、配色、域边界与深度视图与实时/重算**同一套代码** |
 | 三维面板 | 同一帧的 `SdkPacket` | `session.packet(frame)` → `Scene3DView.submit_packet`，走同一个 adapter、域掩码 latch 与有效性求交 |
 
-**深度视图也由结果喂。** `AnalysedFrame.depth` 就是第 1 节那幅量化平面重建出来的
-`float32` 图（空帧是形状正确的全零），`depth_valid` 因此是 `True` 而不像以前那样恒为
-`False`；深度着色、色标锁定、空/缺数据的区分全在窗口既有的那条路径上，回放没有第二条绘制
-代码。"这一帧深度是精确的零"由面板说出来（`panels.depth_empty`，带 `{pixels}`），与
-"这一帧根本没有深度通道"（`panels.depth_unavailable`）是两句不同的话，因为它们是两个不同的
-事实。
+**没有结果时那一行必须说清是四种里的哪一种。** `plan_image()` 只拿到 `ImageFrame`，四种状态
+因此由生产者写进帧里（`result_state`/`result_reason`），`ReplayController.result_state()` 是唯一
+的判断处；有结果时这一行根本不出现：
 
-**画面是重建的，并且是精确重建。** 二维需要的 `[H,W,2]` 流场是把存下来的 `dx`/`dy` 写回
-**记录下来的候选位置**、其余格子填 `NaN`（选区器把非有限值当作非法，邻居格子因此不可能贡献
-出 pass 没记录过的样本）。写回要除以
-`DISPLACEMENT_PX_PER_FLOW × flow_arrow_scale × flow_length_margin`。
+| 状态 | 何时 | 那一行 |
+|---|---|---|
+| `none` | 还没问过缓存（打开录像时 `recording_changed` 的重画） | 点名产生结果的动作（`panels.replay_raw_note`） |
+| `running` | pass 在跑 | 正在分析、进度与取消在分析面板上 |
+| `failed` | 跑完没留下结果，**或**被拒启动（会话/预览开着） | 带上**自己的原因**（`analysis_error()`）：`chain_failed:<frame>`、`FileNotFoundError: …` 或 `analysis.blocked` |
+| `impossible` | 没有 `session.json` / 没有 `raw_*.mp4` 分段 | 这里没有能跑的分析，数字只能靠「从视频重算」 |
 
-`dx`/`dy` 是**画出来的**位移，已经带上长度余量那一步的缩放：只用前两个因子会让每根箭头短
-20%（finger 余量 0.8），330 个样本里 319 个不同、活动集也不同 —— 实测的，不是推导的。余量补
-上后，重建流场重新过一遍共享选区器，样本集与存下来的**逐元素相等**（33 帧全覆盖）。
+**深度视图也由结果喂。** `AnalysedFrame.depth` 就是第 1 节那幅量化平面重建出来的 `float32` 图
+（空帧是形状正确的全零），`depth_valid` 因此是 `True` 而不像以前恒为 `False`；着色、色标锁定、
+空/缺数据的区分全在窗口既有的那条路径上，回放没有第二条绘制代码。"这一帧深度是精确的零"
+（`panels.depth_empty`，带 `{pixels}`）与"这一帧根本没有深度通道"（`panels.depth_unavailable`）
+是两句不同的话，因为它们是两个不同的事实。
+
+**画面是重建的，并且是精确重建。** 二维要的 `[H,W,2]` 流场是把存下来的 `dx`/`dy` 写回**记录
+下来的候选位置**、其余格子填 `NaN`（选区器把非有限值当作非法，邻居格子因此贡献不出 pass 没记
+录过的样本），除以 `DISPLACEMENT_PX_PER_FLOW × flow_arrow_scale × flow_length_margin`：
+`dx`/`dy` 是**画出来的**位移，已带上长度余量那一步的缩放，只用前两个因子会让每根箭头短 20%
+（finger 余量 0.8，330 个样本里 319 个不同）。余量补上后，重建流场重过一遍共享选区器，样本集
+与存下来的**逐元素相等**（33 帧全覆盖）。
 
 ## 12. 显示设置是读
 
@@ -100,75 +113,48 @@ on_progress)`（`chain_spec_for` 从录像自己的 `session.json` 取链路，
 
 ## 14. 验收证据
 
-`apps/studio/tests/test_replay_analysis.py`（15 项，真实素材）：
+`apps/studio/tests/test_replay_analysis.py`（18 项）与 `test_replay_wiring.py`（11 项）跑真实素材，
+`shared/tests/*` 覆盖格式、缓存根与清扫。要保住的断言：
 
-* **跳转等于顺序播放**：顺序走过全部 33 帧记下每帧，再按 `time_of(frame_id)` 直接跳到 5 个
-  采样位置，帧 id、`rows/cols/dx/dy/active` 与流场逐项相等（非候选格按构造是 `NaN`）。
-* **取消不被当完整**：pass 在第一帧后取消 → 面板报 `cancelled`、时间轴留在 `recording`、目录里
-  `complete=false` 且默认读端抛 `AnalysisIncompleteError`。
+* **跳转等于顺序播放**：顺序走过全部 33 帧后按 `time_of(frame_id)` 跳到 5 个位置，帧 id、
+  `rows/cols/dx/dy/active` 与流场逐项相等；深度模式同款，往返误差见 Part A 第 1 节。
+* **取消不被当完整**：第一帧后取消 → 面板报 `cancelled`、时间轴留在 `recording`、目录
+  `complete=false`、默认读端抛 `AnalysisIncompleteError`。
+* **模式切换与显示设置都不写结果**：四个模式各画一次、改一次阈值、改一次被拒的栅格，
+  `scan_results(cache)` 的目录集合都不变。
+* **"没什么可画"只在该说的时候说**：无结果时只给 `recorded` 并带一句说明、文案点名产生结果的
+  动作（两种语言）；有结果时该行消失、四个模式都在。
+* **会话开着也照读缓存**：会话/预览三种在场状态下，带结果的录像一打开就是 `reused`、像素等于
+  存下来的深度图（把守卫顺序改回去，控制器与窗口两级都失败）。
+* **四种状态各一句**：`none` → `running`（真跑一遍）→ `failed`（链路配置不存在的真失败，原因
+  来自 pass 自己）→ `impossible`（裸视频）；窗口层再断言三句面板文案本身。
+* **录像目录一字未改**：`_entry_set(recording)`（相对路径 + 大小）在 open+analyze 前后相等、
+  `analysis/` 不存在、结果落在 `paths.analysis_cache_dir()` 下。
 
-**深度那一片加的验收**（同一文件再 +8 项，另加 `shared/tests/test_analysis_depth.py` 10 项；
-往返误差与尺寸见 Part A 第 1 节）：
-
-* **深度往返**：另跑一遍链路逐帧比 `depth_map`，在 box 录像与 264 帧的 `long_8x.mp4` 上都是
-  0 失败；非零计数、min/max 与链路的完全相等。
-* **跳转等于顺序播放（深度模式）**：顺序播放记下每帧渲染出的深度图，再跳到 5 个位置，帧 id、
-  `depth`、统计与渲染出的字节逐项相等。
-* **模式切换不写结果**：四个模式各画一次，`scan_results(cache)` 的目录集合不变。
-* **"没什么可画"只在该说的时候说**：无结果时 `plan_image` 只给 `recorded` 并带
-  `replay_raw_note`；有结果时该行消失、四个模式都在，默认仍是原始图像。两种语言各断言一次，
-  且文案必须点出产生结果的动作。
-* **派生模式走结果**：时间轴在录像上、模式选深度时，送到 2D 出口的是**结果那一帧**（含深度），
-  不是解码出来的视频帧；切回"原始图像"仍是录像自己的画面。
-
-真实 GL 快照（`QT_QPA_PLATFORM=windows` + `QT_OPENGL=desktop`，真实窗口路径、pass 写入
-scratch cache、游标停在存下来的帧 id 上）：
+真实 GL 快照（`QT_QPA_PLATFORM=windows` + `QT_OPENGL=desktop`，真实窗口路径）：
 
 | 文件 | 内容 |
 |---|---|
-| `.scratch/replay-analysis-b/snapshots/analysis-frame-21-2d.png` | 帧 21（t=0.0641 s）二维画布，308×331 |
-| `.scratch/replay-analysis-b/snapshots/analysis-frame-21-3d.png` | 同一帧三维面板，676×610 |
-| `.scratch/replay-analysis-b/snapshots/analysis-frame-36-2d.png` | 帧 36（t=0.9601 s）二维画布，308×331 |
-| `.scratch/replay-analysis-b/snapshots/analysis-frame-36-3d.png` | 同一帧三维面板，676×594 |
-
-二维画面是候选网格上的暗点阵（该帧活动样本很少），三维是手指岛面加同一套样本点；"同一个样本
-集"由上面的逐元素断言保证，快照证明这条链路真的走到了 GL。
-
-**深度那一片的快照**（`.scratch/replay-analysis-a2/snapshots/`，同一个窗口、同一个游标、同一个
-选择器；"原始图像"是真的相机图，两个派生模式读结果）：
-
-| 文件 | 内容 |
-|---|---|
-| `analysis-finger-frame-33-2d-raw.png` / `-arrows.png` / `-depth.png` | finger 链路帧 33，深度非零 76 px（峰值 0.0242） |
-| `analysis-box-frame-27-2d-raw.png` / `-arrows.png` / `-depth.png` | box 链路帧 27，`depth_map` 365×365 全零，面板显示"本帧深度全为 0（133225 px 中 0 个非零）" |
-
-同一帧三张图的大小不同（raw 96.6 kB 是相机图，arrows 4.9 kB，depth 4.2 kB），这本身就是
-"三个模式画的是三样东西"的证据。
-
-**接线那一片的验收**（`apps/studio/tests/test_replay_wiring.py`，7 项，真实录像 + 真实 pass；录像
-先复制到临时目录、结果写进它自己的 cache，窗口因此复用而不开链路）：操作员路径断言引擎仍在
-`recording`、`available_result()` 非空、选择器给出"原始图像"与三个派生模式、屏上是复用的结果而
-「从视频重算」是关的（改前报 `'analysis' == 'recording'`；选择器里当时没有"原始图像"）。
-
-箭头与深度的字节分别与存下来的候选/`active` 集合和 `depth_map_to_bgr(存的 depth, …)` 相等
-（这份 box 结果每帧全零，面板用 `panels.depth_empty` 说明）；跳转、单步、真定时器播放（0.4 s）
-与 pass 完成四条都在录像时间轴上读结果。另两项：改阈值只重画、改栅格被拒但画面照画（改前抛
-`TypeError`）。
-
-**接线那一片的快照**（`.scratch/replay-reachable/snapshots/`，真实 GL、真窗口、没有手工调用
-`use_recording()`）：`wiring-operator-frame-40-2d-{raw,arrows,depth}.png` 是同一帧的三个模式
-（86 个活动样本；深度全零），`-playback-2d-arrows.png` 是播放到该时刻抓的，`-window.png` 为整窗。
+| `.scratch/replay-analysis-b/snapshots/analysis-frame-{21,36}-2d.png` / `-3d.png` | 帧 21/36 的二维画布与三维面板 |
+| `.scratch/replay-analysis-a2/snapshots/analysis-{finger,box}-frame-*-2d-{raw,arrows,depth}.png` | 两条链路的同一帧三种模式（box 深度全零） |
+| `.scratch/replay-reachable/snapshots/wiring-operator-frame-40-2d-*.png`、`-window.png` | 操作员路径：同一帧三个模式、整窗 |
+| `.scratch/result-visible/snapshots/*.png` | 本次：会话开着时的三种模式、四种面板文案、整窗 |
 
 ## 15. 已知限制
 
 * 结果里没有力：力曲线始终读记录的 `forces.csv`。深度有了（第 1、11 节），但**三维面板仍只
   拿光流**：`session.packet()` 的 `depth` 依旧是 `None`、`depth_valid` 依旧是 `False` —— 接进
   三维会改变三维图形的构成，不在这一片里。
+* **box 的箭头画布在回放里是空的**（本片实测，非本次引入）：box 的绘制路径吃不下只有候选格
+  有限的恢复场，同一帧密流场画 24,440 px、恢复场 0 px；见 [replay-panel.md](replay-panel.md) 第 5 节。
 * 结果覆盖的帧是 pass 走过的那些：**结果的第一帧可能晚于录像的起点**（box 链路构造时吃掉前
   7 个解码帧，这份结果从 t=0.4162 s 开始），最后一批帧也可能早于录像的终点。游标落在这两段里
   时，派生视图按 `frame_id_at()` 的"该时刻或之前、越界夹到端点"给帧：起点之前画的是最早那一帧
   测量，终点之后画的是最后一帧。两段没有各自的提示，"不会静默重复最后一帧"在本片没有兑现。
 * 栅格类显示设置不生效（第 12 节）；换栅格就是重跑一遍，那是**另一个键**。
-* 一个进程同时只有一遍分析在跑；采集会话运行期间不启动分析。
+* 一个进程同时只有一遍分析在跑；采集会话运行期间不启动分析 —— 但**读结果不受这条限制**（第 10
+  节）：会话开着时面板照画缓存，只是新的那一遍要等会话停下、「从视频重算」再点一次。
 * "有没有结果"是录像的属性、不是游标的属性：`available_result()` 查的是本录像在
   `ResultLibrary` 里的那一份，第 9 节的接线之后这是常态。
+* 面板的 `failed` 把"跑挂"和"被拒跑"合成一句（原因与动作都不同：一个要修链路，一个要停会话）；
+  分开是更细的一步，本片没有做。