Coverage reports all-stale with staleReason=null for every selector

[catoncat]

Update: 修正诊断 (2026-06-26)

原 issue 说"staleReason=null"是字段不存在导致的误判——CoverageInventoryStatus(数组条目)只有 freshness: "fresh" | "stale",没有 staleReason 字段。但"全部 stale"这个现象本身需要深究。

诊断脚本结果(53 条 coverage,2 fresh / 51 stale):

id=72 kind=all  fpMatch=false fspMatch=true  countMatch=true   → content changed (advisory)
id=80 kind=cwd  fpMatch=false fspMatch=false countMatch=false  → file set grew 508→528 (real stale)
id=113 kind=cwd fpMatch=false fspMatch=true  countMatch=false  → file set grew 43→45 (real stale)
id=112 kind=cwd fpMatch=false fspMatch=true  countMatch=false  → file set grew 8→9 (real stale)
id=81 kind=cwd  fpMatch=false fspMatch=true  countMatch=false  → file set grew 38→50 (real stale)

真正的 bug

"全部 stale"本身是正确行为——codex session 不断新增,coverage 当然 stale。但有两个缺陷:

1. CoverageInventoryStatus 缺少 staleReason 字段:用户/agent 无法区分 "advisory (content changed, 查询仍可用)" 和 "real stale (file set grew, 需要 sync)"。RequestedCoverageStatus 有 staleReason,但数组条目没有。

2. isAdvisorySourceContentStale 只作用于 requestedCoverage:coverage 数组里的条目无法享受 advisory 判定,全部裸露为 "stale",造成"全部 stale"的恐慌性 UX。

Fix

1. 给 CoverageInventoryStatus 加 staleReason: "none" | "source_content_changed" | "source_set_changed" 字段。
2. 在 toCoverageInventoryStatus 里计算 staleReason,逻辑复用 requestedCoverageStaleReason。
3. (可选)给 CoverageInventoryStatus 加 advisory: boolean 字段,对 codex + source_content_changed 标 true。

Impact

• 6 个 agent 在真实数据测试中 3/6 报告 coverage 警告噪音。有了 staleReason 后,agent 可以判断"advisory 的忽略,real stale 的才 sync"。
• 论文 RQ3 (dynamic update robustness):区分 advisory 和 real stale 是 maintenance 模块的基本要求。

原始 issue (保留供参考)

shlog status --source codex --json 显示几乎所有 coverage 都是 freshness=stale。用户/agent 无法判断是否需要 sync。

[catoncat]

Fix Posted

Fixed in commit 9f94e6b on branch fix/issue-84-coverage-stale-reason (sealed as intent int_d9348025).

What changed

CoverageInventoryStatus (the coverage array entries in status --json) now includes:

• staleReason: "none" | "source_content_changed" | "source_set_changed"
• advisory: boolean (true when stale is advisory — query is still safe)

Previously these fields only existed on requestedCoverage (single selector). Now agents can distinguish advisory stale (content changed, keep querying) from real stale (file set grew, needs sync) on every coverage entry.

Verified on real data

total: 53  fresh: 2  stale: 51 (advisory: 1, real: 50)

staleReason distribution:
  source_set_changed: 50
  none: 2
  source_content_changed: 1

The 1 advisory entry (id=72, kind=all) is source_content_changed — existing codex session files were modified, but the file set didn't grow. Querying is still safe. The 50 source_set_changed entries are real stale (new session files added, needs sync).

Tests

• 215/215 tests pass (3 new tests in status.test.ts covering fresh, content-changed, and file-set-changed scenarios)