/instances returns unbounded list of historical known instances

[NorveraFlorent]

~/.forge-hub/state/_hub/instance-identities.json 持久化所有曾连 Hub 的 instance，每个新 forked PID 都是新 ID 写一条（instance-manager.ts:194 register、:219 ready、:242 ws-close、setTag/setDescription/setChannels 等共 8 个 saveIdentity callsite），永不剔除。

routes/instances.ts:9 handleInstances → routes/health.ts:35 buildInstanceList → instance-manager.ts:117 listKnownInstances 把保存的 identities 全量 union 当前 in-memory instances 返回，无 filter，无 query 参数支持。

实测累积

时间	条目	响应大小
2026-05-12	258	15 KB
2026-05-27	645	67 KB

单用户机器累积速度 ~26 entries/day。

影响

1. 响应跨过下游消费者 pipe buffer 阈值会触发死锁（见 forge-launcher 配套 issue）
2. 即使消费者没 bug，每次 enrichScanResults 都全量 fetch 也是 IO + JSON 解析的线性浪费
3. 历史 stale 条目里 ~85% 没 description/tag（645 → 99 有标识 = 546 是纯噪声）

建议修法

默认行为不要改（避免破坏现有客户端契约），走 query 参数：

GET /instances              → 现有行为（all known，含 stale）
GET /instances?include=live → 只返当前在线
GET /instances?include=tagged → 在线 + 有 description/tag 的离线（供 menubar 之类的回放）

配套：长期可在 hub 启动时 GC instance-identities.json——剔除 >30 天 lastSeenAt 且无 description/tag 的条目。

临时绕过

python3 -c "
import json
p='$HOME/.forge-hub/state/_hub/instance-identities.json'
d=json.load(open(p))
kept={k:v for k,v in d.items() if v.get('description') or v.get('tag')}
json.dump(kept, open(p,'w'), indent=2, ensure_ascii=False)
print(f'{len(d)} -> {len(kept)}')
"
launchctl kickstart -k gui/$(id -u)/com.forge-hub

listKnownInstances 只读不写，trim 不会被自动回填。

环境

• forge-hub: HEAD-19628bb
• Bun 1.3.14
• macOS 25.5.0

[NorveraFlorent]

复核（claude v2.1.154 · forge-hub HEAD ba6c6d2）

本 issue 的核心前提「instance-identities 永不剔除、无限累积」在当前 HEAD 已不成立：hub-server/instance-manager.ts:24 现有 KNOWN_IDENTITY_TTL_MS = 24h + pruneSavedIdentities()，每次 getSavedIdentities() 读时剔除 lastSeenAt > 24h 的条目。

本机运行时实测：instance-identities.json 61 条，全部 <24h（最老 22.7h），0 条超 24h——不再是 645 条无限增长。

一个未解时序褶皱：该 prune 所在 commit (0058b64) 日期 05-11，但本 issue 累积表 05-27 仍测 645 条。最可能是生产 Hub 直到之后才重启加载新码（热重载仅开发模式）。能否确认部署历史？

据此，建议收窄本 issue 的修复范围：

• 「≤30 天 GC」不要做——现有 24h TTL 比它更紧，实现会是 regression。
• 仍成立的残留只剩两条观感级：(a) routes/instances.ts:9 handleInstances() 无 ?include= 解析；(b) fh hub peers/status 把所有 <24h 纯噪声 tool-only ghost（~40 条，无 tag/desc）全打出来。
• 若要收口：服务端 ?include=live|tagged（默认 all 不破现有客户端契约）+ fh peers/status 默认走 ?include=tagged。这是有界观感优化，非 pipe 死锁级。

[LinekForge]

暂不修。

经核实，instance-identities.json 已有 24 小时 TTL 自动清理（pruneSavedIdentities，每次读写时触发）。单用户场景下文件不会无限增长。

存在一个边界情况：channel-mode 实例缺 lastSeenAt 时每次 Hub 重启会续命（重新赋值当前时间），延迟清理。但不影响正常使用。

后续安排：

• 加 /instances?include=live query 参数支持只返回在线实例（减少响应体积）
• 修 channel-mode 缺 lastSeenAt 的续命问题
• 长期考虑 30 天以上无标识的条目自动 GC

优先级 P2，排在当前 bug 修复之后。