fix(renderer): restore session proposal backfill

- synced proposal rail and lineage IPC specs
- archived fix-session-proposal-backfill

Author: Fioooooooo

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-06-25T00:00:00.000Z
+status: applying

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/design.md

@@ -0,0 +1,43 @@
+## Context
+
+`ChatSessionEventRail` 通过 `useSessionStore.sessionProposals` 展示当前 chat session 关联的 proposal。运行中创建 proposal 时，MCP server 写出 create-proposal 事件，主进程 lineage consumer 将 `sessionId -> changeId` 写入 lineage，并启动 `ProposalStatusService.watchProposal`。重启后 renderer 的内存态 `sessionProposals` 丢失，需要在进入 session 时通过 lineage 与 proposal 列表恢复。
+
+现有 `useSessionStore.backfillSessionProposals(sessionId)` 已调用 `lineageApi.getBySession(projectId, sessionId)`，再用 lineage 中的 `LineageProposalLink.changeId` 去匹配 `useProposalStore.proposals`。问题在于 archived proposal 的 `ProposalMeta.id` 当前可能是 archive 目录名 `YYYY-MM-DD-<changeId>`，而 lineage 保存的是原始 `changeId`。主进程已有 `stripArchivePrefix` / `resolveChangeDirAnywhere` 等路径定位统一化，但 `proposal:list` 仍保留 archive 目录名作为 `ProposalMeta.id`，现有测试也覆盖了该行为。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 进入 session 时恢复展示 lineage 已记录的所有 proposal，包括 archived proposal。
+- 保持 archived proposal 为终态展示，不为它重新开启 `proposal:watch`。
+- 保持非 archived proposal 在回填后继续启动 watch，以便后续状态变化能推送到 renderer。
+- 补齐 `lineage:getBySession` 的 IPC 规格，使 renderer 的恢复路径有明确契约。
+
+**Non-Goals:**
+
+- 不统一修改 `ProposalMeta.id` 的主进程返回格式；archive proposal 可继续以 `YYYY-MM-DD-<changeId>` 作为 id。
+- 不新增 IPC channel，不改变 lineage 持久化结构。
+- 不重构 `ProposalStatusService` 的 watcher key 策略。
+- 不改变 `ChatProposalPanel` 的按钮、badge 或详情页导航语义。
+
+## Decisions
+
+1. 在 renderer 回填层做 `changeId` 等价匹配，而不是修改 `proposal:list`。
+   - 选择：在 `src/renderer/src/stores/session.ts` 中新增局部 helper，将 proposal id 与 lineage changeId 视为等价，当 `proposal.id === changeId` 或 `proposal.id` 去掉 `YYYY-MM-DD-` 前缀后等于 `changeId`。
+   - 理由：主进程列表行为已有测试断言保留 archive 前缀；直接改变 `ProposalMeta.id` 会影响 proposal 列表、详情路由、archive 后查找和 overview 等多个调用方，超出本次 bug fix 范围。
+   - 替代方案：修改 `readProposalFiles()` 让 archived `ProposalMeta.id` 始终无前缀。拒绝，因为这是更大的行为变更，且现有测试明确覆盖了前缀保留。
+
+2. watch 启动由匹配到的 `ProposalMeta.status` 决定。
+   - 选择：`backfillSessionProposals` 回填 `matched` 后，只对 `proposal.status !== "archived"` 的项目调用 `ensureProposalWatched(proposal, sessionId)`。
+   - 理由：archived proposal 已是终态，重新 watch 只会增加主进程 watcher 资源，不提供状态同步价值；active proposal 仍需要 watch 以接收 draft/applying/archived 变化。
+   - 替代方案：对所有回填 proposal 都 watch。拒绝，因为它会对 archived 终态产生不必要监听，且与本次确认的产品边界冲突。
+
+3. 保持 statusChanged 推送路径的防御性 watch 行为，但避免对 archived payload 重启 watch。
+   - 选择：`handleProposalStatusChanged` 中如果收到未知 proposal 的 status push，可继续刷新 proposal store 并 upsert；但仅当 payload/status 对应 proposal 非 archived 时才需要补 watch。
+   - 理由：status push 本身说明主进程已有 watcher 或刚处理事件。对 archived 继续 watch 没必要；对非 archived 保持既有防御逻辑。
+
+## Risks / Trade-offs
+
+- [Risk] Renderer 本地实现 archive 前缀剥离规则可能与主进程 `stripArchivePrefix` 未来变化不一致。→ Mitigation：使用同一正则语义 `^\d{4}-\d{2}-\d{2}-`，并通过 store 单测固定行为；若未来主进程规则变化，再同步调整 renderer helper。
+- [Risk] 一个项目同时存在 active `foo` 和 archived `YYYY-MM-DD-foo` 时，回填可能匹配两个 proposal。→ Mitigation：这是现有 `readProposalFiles` 可返回的状态；回填展示 session lineage 关联的所有匹配项时应排序并保持去重，watch 只作用于非 archived 项。
+- [Risk] `lineage:getBySession` 已在代码中存在但 spec 描述缺失，Apply 阶段可能只改 renderer。→ Mitigation：本 change 增加 `lineage-ipc` delta，明确该 channel 是恢复路径的依赖。

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+重启 FylloCode 后，已经产生 proposal 的 chat session 重新打开时可能不再展示 `ChatProposalPanel`，尤其是已归档 proposal 因 archive 目录名带日期前缀而无法用 lineage 中的原始 `changeId` 精确匹配。现有规格已经要求 EventRail 展示当前 session 关联的所有 proposal，因此这是恢复路径没有履行既有契约的 bug。
+
+## What Changes
+
+- 修复 `useSessionStore` 在进入 session 时从 `lineage:getBySession` 回填 proposal 的匹配逻辑，使 lineage 中的原始 `changeId` 能匹配 active proposal，也能匹配 archive 目录名形如 `YYYY-MM-DD-<changeId>` 的 archived proposal。
+- 回填后继续展示 archived proposal，但不再为 archived proposal 调用 `proposal:watch`；只有 `creating`、`draft`、`applying` 等非终态 proposal 需要启动主进程状态监听。
+- 补齐 `lineage:getBySession` 的 IPC 规格描述，明确 renderer 可用它读取 session 所属 lineage 及该 session 的 proposal 产出列表。
+- 增加 renderer store 测试，覆盖 session 重开/切换后的 proposal 回填、archive id 匹配和 archived 不 watch 的行为。
+
+## Capabilities
+
+### New Capabilities
+
+- 无。
+
+### Modified Capabilities
+
+- `chat-event-rail-proposal-status`: 明确 Chat EventRail 在进入 session 时必须从 lineage 回填历史 proposal，并只对非 archived proposal 启动状态监听。
+- `lineage-ipc`: 补齐 `lineage:getBySession` channel 的渲染进程 IPC 契约，用于按 session 查询 lineage 投影。
+
+## Impact
+
+- 影响 `src/renderer/src/stores/session.ts` 的 `backfillSessionProposals` / watch 启动边界。
+- 影响 `test/renderer/src/stores/session.spec.ts` 的 lineage/proposal API mock 与新增恢复场景。
+- 不新增 IPC channel，不改变持久化 schema，不改变 `ProposalMeta.id` 的主进程返回格式。

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/specs/chat-event-rail-proposal-status/spec.md

@@ -0,0 +1,80 @@
+## MODIFIED Requirements
+
+### Requirement: Chat EventRail 展示当前 session 的 proposal 列表
+
+`ChatSessionEventRail` SHALL 展示与当前活跃 session 关联的所有 proposal，按创建时间倒序排列，并实时反映非终态 proposal 的状态变化。进入或切换到一个已存在的 session 时，renderer SHALL 通过 `lineage:getBySession` 读取该 session 的 proposal 产出列表，并用 `useProposalStore.proposals` 中的完整 `ProposalMeta` 回填 `useSessionStore.sessionProposals`。回填匹配 SHALL 使用 lineage 中的原始 `changeId`，并且 SHALL 同时匹配 `ProposalMeta.id === changeId` 与 archived proposal 的 `ProposalMeta.id === YYYY-MM-DD-<changeId>` 形式。
+
+回填完成后，renderer SHALL 仅对 `status !== "archived"` 的 proposal 调用 `proposal:watch` 启动主进程状态监听；`archived` proposal SHALL 作为终态展示，不启动新的状态监听。
+
+`ChatProposalPanel` SHALL 从 `ProposalMeta.status` 与当前匹配的 `ApplyRunMeta.status` 派生卡片展示态：
+
+- `creating`：显示 badge “创建中”
+- `draft`：显示 badge “草稿”
+- `applying` 且没有匹配的 done apply run：显示 badge “实施中”
+- `applying` 且 `proposalRunStore.runMeta.changeId === proposal.id` 且 `proposalRunStore.runMeta.status === "done"`：显示 badge “可归档”
+- `applying` 且 `proposalRunStore.isArchiving === true` 且 `proposalRunStore.runMeta.changeId === proposal.id`：显示 badge “归档中”
+- `archived`：显示 badge “已归档”
+
+#### Scenario: 当前 session 有一个 draft proposal
+
+- **GIVEN** 用户处于 `session-1`，该 session 已关联一个 `draft` proposal
+- **WHEN** `ChatSessionEventRail` 渲染
+- **THEN** rail SHALL 展示该 proposal 的标题、状态 badge 为“草稿”，并提供“开始实现”按钮
+
+#### Scenario: proposal 状态实时更新
+
+- **GIVEN** `ChatSessionEventRail` 已展示一个 `draft` proposal
+- **WHEN** renderer 收到 `proposal:statusChanged` 事件，payload 中 `status` 变为 `applying`
+- **THEN** rail 中对应 proposal 的状态 badge SHALL 立即更新为“实施中”，且“开始实现”按钮消失
+
+#### Scenario: apply run 完成后显示可归档
+
+- **GIVEN** `ChatSessionEventRail` 已展示一个 `applying` proposal
+- **AND** `proposalRunStore.runMeta.changeId` 等于该 proposal id
+- **AND** `proposalRunStore.runMeta.status === "done"`
+- **WHEN** `ChatProposalPanel` 渲染该 proposal
+- **THEN** 该 proposal 的状态 badge SHALL 显示“可归档”
+- **AND** 该 proposal SHALL 显示“归档”按钮
+
+#### Scenario: 点击归档后显示归档中
+
+- **GIVEN** `ChatSessionEventRail` 已展示一个“可归档” proposal
+- **WHEN** 用户点击“归档”按钮
+- **AND** `proposalRunStore.isArchiving === true`
+- **AND** `proposalRunStore.runMeta.changeId` 等于该 proposal id
+- **THEN** 该 proposal 的状态 badge SHALL 显示“归档中”
+- **AND** 该 proposal SHALL 不显示“归档”按钮
+- **AND** 该 proposal SHALL 显示“查看详情”按钮
+
+#### Scenario: 切换 session 后展示不同 proposal 列表
+
+- **GIVEN** `session-1` 关联 proposal A，`session-2` 关联 proposal B
+- **WHEN** 用户从 `session-1` 切换到 `session-2`
+- **THEN** `ChatSessionEventRail` SHALL 隐藏 proposal A，展示 proposal B
+
+#### Scenario: 重启后进入 session 恢复 active proposal 并启动 watch
+
+- **GIVEN** FylloCode 重启后 renderer 内存中的 `sessionProposals` 为空
+- **AND** lineage 中 `session-1` 的 proposal 列表包含 `changeId: "fix-login"`
+- **AND** `useProposalStore.proposals` 包含 `{ id: "fix-login", status: "draft" }`
+- **WHEN** 用户进入 `session-1`
+- **THEN** `useSessionStore.sessionProposals["session-1"]` SHALL 包含该完整 `ProposalMeta`
+- **AND** renderer SHALL 调用 `proposal:watch`，入参包含 `changeId: "fix-login"` 与 `sessionId: "session-1"`
+
+#### Scenario: 重启后进入 session 恢复 archived proposal 且不启动 watch
+
+- **GIVEN** FylloCode 重启后 renderer 内存中的 `sessionProposals` 为空
+- **AND** lineage 中 `session-1` 的 proposal 列表包含 `changeId: "fix-login"`
+- **AND** `useProposalStore.proposals` 包含 `{ id: "2026-06-25-fix-login", status: "archived" }`
+- **WHEN** 用户进入 `session-1`
+- **THEN** `useSessionStore.sessionProposals["session-1"]` SHALL 包含该 archived `ProposalMeta`
+- **AND** renderer SHALL NOT 为 `2026-06-25-fix-login` 调用 `proposal:watch`
+
+#### Scenario: 回填失败不阻断 session 切换
+
+- **GIVEN** 用户进入 `session-1`
+- **AND** `lineage:getBySession` 返回 `null`、错误响应或抛出异常
+- **WHEN** `useSessionStore` 执行 proposal 回填
+- **THEN** 当前 session SHALL 保持选中
+- **AND** `sessionProposals["session-1"]` SHALL 保持为空
+- **AND** renderer SHALL NOT 调用 `proposal:watch`

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/specs/lineage-ipc/spec.md

@@ -0,0 +1,53 @@
+## MODIFIED Requirements
+
+### Requirement: lineage 服务向渲染进程暴露 IPC 契约
+
+系统 SHALL 在 `src/main/ipc/lineage.ts` 注册 lineage 的 IPC handler，并在 `src/preload/api/lineage.ts` 与 `src/renderer/src/api/lineage.ts` 暴露对应的请求-响应 api。新增 channel SHALL 定义在 lineage 专属的 channel 常量中（与 `ChatChannels` 同模式），SHALL NOT 复用或污染 `ChatChannels`。所有 handler SHALL 复用 `ipc/_kit` 的 `wrapHandler` 与 `validate`，入参 SHALL 由 `src/shared/schemas/ipc/lineage.ts` 的 zod schema 校验。
+
+本能力 SHALL 暴露以下 channel：
+
+- `lineage:ensureTaskSubject`：入参 `{ projectId: string, snapshot: LineageTaskSnapshot }`，调用 `lineage-service.ensureTaskSubject`，返回创建/复用的 `Subject`。
+- `lineage:linkTaskSession`：入参 `{ projectId: string, taskRef: LineageTaskRef, sessionId: string }`，调用 `lineage-service.linkTaskSession`（见 project-lineage-model delta），返回更新后的 `Subject` 或 `null`。
+- `lineage:getByTask`：入参 `{ projectId: string, ref: LineageTaskRef }`，调用 `lineage-service.getByTask`，返回 `TaskDownstreamProjection | null`。
+- `lineage:getBySession`：入参 `{ projectId: string, sessionId: string }`，调用 `lineage-service.getBySession`，返回 `SessionLineageProjection | null`。renderer 可使用该 channel 在进入 session 时恢复该 session 所属 lineage、任务快照与该 session 产出的 proposal 列表。
+
+#### Scenario: ensureTaskSubject 经 IPC 建/复用 subject
+
+- **WHEN** renderer 调用 `lineageApi.ensureTaskSubject(projectId, snapshot)`
+- **THEN** 主进程 handler 校验入参后调用 `lineage-service.ensureTaskSubject(projectPath, snapshot)`
+- **AND** 返回的 `Subject` 包含与 `snapshot.ref` 对应的 `task` 字段
+- **AND** 对同一 `snapshot.ref` 重复调用返回同一个 subjectId（幂等）
+
+#### Scenario: getByTask 经 IPC 读取 subject 快照
+
+- **WHEN** renderer 调用 `lineageApi.getByTask(projectId, ref)`，且该 ref 已存在 subject
+- **THEN** 返回 `TaskDownstreamProjection`，其 `task.snapshot` 为发起讨论时拍摄的全量 `TaskItem`
+- **AND** 即使该 task 在第三方侧已关闭、本地不可见，仍能从快照读取来源与标题
+
+#### Scenario: getByTask 对未知 ref 返回 null
+
+- **WHEN** renderer 调用 `lineageApi.getByTask(projectId, ref)`，且该 ref 无对应 subject
+- **THEN** 返回 `null`，不抛出异常
+
+#### Scenario: getBySession 经 IPC 读取 session lineage
+
+- **WHEN** renderer 调用 `lineageApi.getBySession(projectId, "session-1")`，且该 session 已存在 lineage subject
+- **THEN** 主进程 handler 校验入参后调用 `lineage-service.getBySession(projectPath, "session-1")`
+- **AND** 返回 `SessionLineageProjection`
+- **AND** 返回值的 `session.proposals` SHALL 包含该 session 已记录的 proposal `changeId` 列表
+
+#### Scenario: getBySession 对未知 session 返回 null
+
+- **WHEN** renderer 调用 `lineageApi.getBySession(projectId, "missing-session")`
+- **AND** lineage index 中不存在该 session
+- **THEN** 返回 `null`，不抛出异常
+
+### Requirement: lineage IPC 入参经 schema 校验且 projectId 解析为 projectPath
+
+系统 SHALL 在 `src/shared/schemas/ipc/lineage.ts` 定义 `ensureTaskSubjectInputSchema`、`linkTaskSessionInputSchema`、`getByTaskInputSchema`、`getBySessionInputSchema`。每个 schema 的 `projectId` SHALL 为非空字符串；`taskRef` / `ref` SHALL 校验为形如 `<source>:<id>` 的字符串；`sessionId` SHALL 为非空字符串；`snapshot` SHALL 校验 `ref` / `snapshot` / `capturedAt` 三字段齐备。handler SHALL 通过 lineage 服务现有的 project 路径解析方式把 `projectId` 解析为 `projectPath` 后再调用服务函数。
+
+#### Scenario: 非法入参被 schema 拒绝
+
+- **WHEN** renderer 以缺失 `projectId`、缺失 `snapshot.ref` 或空 `sessionId` 的入参调用任一 lineage channel
+- **THEN** handler 通过 `validate` 抛出校验错误，返回标准 IPC 错误响应
+- **AND** 不调用任何 lineage 服务函数

openspec/changes/archive/2026-06-25-fix-session-proposal-backfill/tasks.md

@@ -0,0 +1,24 @@
+## 1. Renderer 回填修复
+
+- [x] 1.1 修改 `src/renderer/src/stores/session.ts`：为 `backfillSessionProposals(sessionId)` 增加 proposal id 与 lineage changeId 的等价匹配 helper，匹配 `proposal.id === changeId` 或 `proposal.id` 去掉 `YYYY-MM-DD-` 前缀后等于 `changeId`；保持 `ProposalMeta.id` 原值不改写。
+- [x] 1.2 修改 `src/renderer/src/stores/session.ts`：回填 `matched` proposal 后，只对 `proposal.status !== "archived"` 的 proposal 调用 `ensureProposalWatched(proposal, sessionId)`；archived proposal 只写入 `sessionProposals` 用于展示。
+- [x] 1.3 检查 `handleProposalStatusChanged(payload)` 的未知 proposal 防御逻辑：保持刷新 `useProposalStore().loadProposals()` 与 `upsertSessionProposal`，但避免为 `status === "archived"` 的 proposal 重新调用 `ensureProposalWatched`。
+
+## 2. 测试
+
+- [x] 2.1 修改 `test/renderer/src/stores/session.spec.ts` 的 `@renderer/api/lineage` mock，补充 `getBySession` mock，并在 `beforeEach` 中提供默认返回值。
+- [x] 2.2 在 `test/renderer/src/stores/session.spec.ts` 新增场景：选择 session 后，`lineageApi.getBySession(projectId, sessionId)` 返回 `changeId: "fix-login"`，`useProposalStore.proposals` 含 `{ id: "fix-login", status: "draft" }` 时，`sessionProposals[sessionId]` 包含该 proposal，且 `proposalApi.watch` 被调用一次。
+- [x] 2.3 在 `test/renderer/src/stores/session.spec.ts` 新增场景：`lineageApi.getBySession` 返回原始 `changeId: "fix-login"`，`useProposalStore.proposals` 含 `{ id: "2026-06-25-fix-login", status: "archived" }` 时，`sessionProposals[sessionId]` 包含该 archived proposal，且 `proposalApi.watch` 不被调用。
+- [x] 2.4 在 `test/renderer/src/stores/session.spec.ts` 新增场景：`lineageApi.getBySession` 返回 `null`、错误响应或抛错时，`selectSession` 不抛错，`sessionProposals[sessionId]` 保持空数组，且不调用 `proposalApi.watch`。
+
+## 3. 规格与文档同步
+
+- [x] 3.1 确认 `openspec/changes/fix-session-proposal-backfill/specs/chat-event-rail-proposal-status/spec.md` 中的回填、archive id 匹配、archived 不 watch 场景与最终实现一致。
+- [x] 3.2 确认 `openspec/changes/fix-session-proposal-backfill/specs/lineage-ipc/spec.md` 中 `lineage:getBySession` 的 channel 描述与 `src/shared/types/channels.ts`、`src/shared/schemas/ipc/lineage.ts`、`src/main/ipc/lineage.ts`、`src/renderer/src/api/lineage.ts` 的现有实现一致。
+- [x] 3.3 无需更新 `guidelines/RendererProcess.md`：其中 “Chat Session Proposals” 已描述从 proposal store 与 lineage 回填历史 proposals；本 change 只是补充 OpenSpec 与测试中的精确场景。
+
+## 4. 验证
+
+- [x] 4.1 运行 `pnpm vitest run test/renderer/src/stores/session.spec.ts`。
+- [x] 4.2 运行 `pnpm vitest run test/renderer/src/components/chat/event/ChatProposalPanel.test.ts test/renderer/src/components/chat-session-event-rail.spec.ts`，确认 proposal rail 展示行为未回退。
+- [x] 4.3 运行 `pnpm typecheck:web`，确认 renderer 类型仍通过。