specrails-desktop 2.64.2 → 2.65.1

package/docs/guide/zh/settings/1-themes.md

@@ -1,4 +1,4 @@
-# 主题
+# 主题 {#themes}
 
 让 Specrails 看起来更合你的心意。应用内置了五套精心调校的主题，可以随时一键切换——无需重启、无需重新构建，也不用做任何配置。
 

package/docs/guide/zh/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,4 +1,4 @@
-# 流水线遥测与诊断
+# 流水线遥测与诊断 {#telemetry}
 
 遥测在本地记录流水线诊断信息。未保存偏好的项目**默认开启**。可以按项目关闭；明确保存的选择会保留。
 
@@ -20,7 +20,7 @@
 
 ### 覆盖范围
 
-遥测适用于**流水线任务**（即排入队列的 Architect → Developer → Reviewer → Ship rail 运行）。像聊天、安装向导这样的交互式会话被有意排除在外——遥测面向的是可重复、可检查的流水线运行，而非一次性的对话。
+遥测适用于经过项目**任务队列**的任务：CLI 流水线运行（Loops 关闭时的 rail，以及从 `specrails-desktop` CLI 发送的 `implement` 命令）。循环运行（rail 的默认运行方式）以及聊天、Explore、任务会话（mission）这类交互式会话不会被采集。
 
 ## 数据存放在哪里
 

package/docs/guide/zh/settings/5-project-environment.md

@@ -1,4 +1,4 @@
-# 项目环境
+# 项目环境 {#project-environment}
 
 有些项目在运行时需要凭据，例如私有 npm 包所需的 `NODE_AUTH_TOKEN`。在 **项目设置 → 环境** 中，添加你的 rail 和 loop 需要的变量**名称**。Specrails 只保存名称，从不保存值。
 

package/docs/guide/zh/settings/6-updates.md

@@ -0,0 +1,24 @@
+# 更新 {#updates}
+
+Specrails 会保持两样东西为最新：**Specrails Desktop** 应用本身，以及项目使用的 **specrails-core** 框架。两者都在 **设置 ▸ 更新** 中。
+
+## 更新通道
+
+选择接收新版本的节奏：
+
+- **最新**（默认）：每个版本发布后立即获取。最先获得新功能和修复。
+- **稳定**：仅接收在最新通道上至少一周且 CI 通过、随后由维护者提升的版本。适合希望更新更少、更经过验证的团队。
+
+通道同时适用于应用和 specrails-core。如果 specrails-core 尚无稳定版本，Core 暂时跟随最新，Core 卡片会提示这一点。
+
+在稳定通道上，如果还没有任何版本被提升，**检查更新** 会明确告知，而不会提供最新通道的版本。
+
+## 更新如何送达
+
+- **Specrails Desktop** 在启动时和每 6 小时检查一次。有可用更新时会出现一张卡片，可在其中下载、安装并重启。也可以点击 **检查更新**。
+- **specrails-core** 从不自动更新。在 Core 卡片上点击 **检查更新**，然后点击 **更新到（版本）** 进行安装。项目会切换到新框架，无需重启应用。
+
+## 须知
+
+- 从最新切换到稳定不会降级。你会停留在当前版本，直到稳定通道赶上。
+- 两个通道上的每次更新都会在安装前进行签名验证。

package/docs/guide/zh/settings/7-existing-projects.md

@@ -0,0 +1,33 @@
+# 在现有项目中工作 {#existing-projects}
+
+这些功能帮助运行尊重已经存在的项目：规格不涵盖的内容、架构师在规划前的问题、测试真正证明了哪些需求、在修改旧代码前如何描述它，以及团队已经写下的规则。每项功能都需要支持它的 specrails-core 版本；在此之前，其开关显示为灰色，并提示更新 Core。
+
+## 不在范围内
+
+每个规格都可以列出它有意**不**更改的内容。Quick 和 Explore 会为你填写；在规格窗口中，它显示在描述下方的 **不在范围内**，每行一项，可以像其他字段一样编辑。代理在每次启动时都会随规格一起收到它。
+
+## Jira 中的架构师问题
+
+在 **设置 ▸ 在现有项目中落地** 中打开 **将架构师的澄清问题发布到 Jira**。当运行因架构师需要答复而停止，或基于假设继续时，Specrails 会将其作为一条评论发布到关联的 Jira 工单。在 Jira 中回复该评论：回复会作为澄清添加到规格上，规格的下一次运行会读取它。你仍然可以在应用中答复已暂停的运行。
+
+## 已证明的需求
+
+当测试在标题中写明它所证明的需求（`[spec:<能力>/<需求>]`）时，评审页面会显示 **已证明的需求 X/Y**：哪些需求由通过的测试证明、哪些还没有测试、哪些是本次变更涉及的。分析页面按循环显示同样的信息。若要在变更的需求没有测试时让 CI 失败，请在测试之后添加 `specrails-core pipeline trace --check --tests-passed`。
+
+循环库还提供 **偏差巡检**，这是一个只读循环，会比较每个规格的描述与代码的实际行为，并列出每处矛盾。它不做任何更改。
+
+## 触及时建立基线
+
+打开 **触及时建立基线** 后，当变更触及没有任何规格描述的代码时，会先描述这些代码：在未修改的代码上证明的当前行为测试，以及一份简短的现状规格。评审页面会显示 **已为本次工作涉及的代码创建规格**，包括模块、需求和测试，其成本与变更分开显示。如果这些测试在未修改的代码上失败，运行会在编辑模块之前停止并说明原因。
+
+## 项目规则 {#project-rules}
+
+**设置 ▸ 项目规则** 列出项目已经运行的检查（lint、类型、测试、CI），以及写在 `CLAUDE.md` 或 `AGENTS.md` 等文件中的每条规则，并分为：
+
+- **已强制执行**：已有检查保证它。
+- **可自动化**：可以由检查保证。**创建规格** 一键将其变为规格。
+- **仅限人工**：需要有人查看。它们会出现在每个评审页面的 **需要人工检查** 中。
+
+Core 尚未能分类的规则（例如刚添加项目、盘点以离线方式运行时）显示为 **未分类**；配置提供方后点击 **重新盘点** 即可完成分类。
+
+**重新盘点** 会刷新列表。当项目还没有验证命令时，Agent Runtime 设置会优先提供这些检查。

package/docs/guide/zh/settings/8-accessibility.md

@@ -0,0 +1,23 @@
+# 无障碍与个性化 {#accessibility}
+
+Specrails 会适应你的工作方式。所有选项都在**设置 ▸ 外观**中,立即生效,并保存在这台电脑上。
+
+## 密度 {#density}
+
+**舒适**让卡片和行保持宽松。**紧凑**让屏幕容纳更多内容:规格看板默认以紧凑行显示,作业列表使用更紧的行,作业过程也会收紧时间线。已保存的看板视图保留自己的布局,因此以便利贴卡片保存的视图仍以便利贴卡片打开。 如果此项目的看板已有自己的布局,点击选项下方的 **同时用于看板** 即可让它重新遵循密度设置。
+
+## 减少动态效果 {#reduce-motion}
+
+**跟随系统**遵循操作系统的设置。**减少**会在 Specrails 内关闭动画和过渡,无论系统如何设置:Rail 上的小胶囊停在它的位置,实时圆点不再脉动,Builder 光晕和主题特效保持静止。**完整动效**即使系统要求减少也会播放动画。
+
+## 用键盘移动规格 {#keyboard-moves}
+
+在看板上聚焦一张规格卡片(Tab 或方向键),按 **M**。弹出的小选择器列出各个状态和 Rail;用方向键选择并按 **Enter**。效果等同于把卡片拖过去,包括关联 Jira 的规格,它们会通过你的 Jira 工作流移动。如果该卡片属于多选(**X** 选中当前聚焦的卡片),移动会应用到所有选中的规格。命令面板中的**移动聚焦的规格…**提供相同功能。在输入框中打字时,**M** 不起作用。
+
+## 面向读屏软件的运行播报 {#live-status}
+
+Specrails 通过礼貌的实时区域,为你正在查看的项目播报运行变化:运行已开始、已暂停、需要你处理、失败、完成或审阅已就绪。连续的变化会合并,重复的会被丢弃,繁忙的 Rail 不会淹没读屏软件。撤销提示本身已会被播报。
+
+## 键盘焦点 {#focus}
+
+用键盘到达的每个按钮、链接、菜单项、卡片和树节点行,都会显示清晰的焦点环。过去只出现在提示框中的信息,例如 Rail 条上的规格编号,键盘和读屏软件用户现在也能获取。

package/docs/guide/zh/specs/1-specs-and-the-backlog.md

@@ -1,4 +1,4 @@
-# Spec 与 backlog
+# Spec 与 backlog {#specs-backlog}
 
 **spec** 是 AI 流水线要实现的工作单元。你可以把它想象成一张工单：包含标题、一段对需求的描述、优先级，以及可选的标签。当你启动流水线时，AI agent 会读取这份 spec 并据此行动——所以一份清晰的 spec，是决定结果好坏的最重要输入。
 
@@ -13,7 +13,27 @@
 - **便签视图**（默认）——卡片样式的方块，附带简短摘要。
 - **列表视图**——紧凑的单行行式布局。
 
-工具栏上的 **状态选择器** 把每种状态都显示为带实时计数的独立筛选片，另加两个智能分组：**活跃**（默认视图——一切仍在推进中的内容：草稿、待办、进行中和评审中）和 **全部**（所有内容，完成的固定在底部）。你的选择会按项目记住并同步到 URL，刷新或分享链接都能还原完全相同的视图。在连接了 Jira 的项目上还会出现一个 **Jira 状态** 下拉菜单，列出看板*真实*的工作流状态（原始名称，例如 "Code Review"，每个都带实时计数），按其映射到的状态分组——它与状态筛选片叠加生效。你还可以按 **标签** 筛选，并按 **默认**、**工单 #** 或 **优先级** 排序（每一种都带有升序/降序切换）。
+Spec 工具栏分为两行。第一行包含 **搜索** 框（按 `/` 即可跳到这里；可按标题、`#编号`、标签或 Jira 键搜索）、一个统一的 **筛选** 按钮、排序与视图控件，以及 **新建 Spec**。第二行是 **状态选择器**：每种状态都是带实时计数的独立分段，另加两个智能分组：**活跃**（默认视图：一切仍在推进中的内容，即草稿、待办、进行中和评审中）和 **全部**（所有内容，完成的固定在底部）。列较窄时，不常用的状态会收进 **更多** 菜单，而你选中的状态始终可见。你的选择会按项目记住并同步到 URL，刷新或分享链接都能还原完全相同的视图。**筛选** 会打开一个面板，每个维度一节：**标签**（多选），在连接了 Jira 的项目上还有 **史诗**、**冲刺** 和 **Jira 状态**（看板*真实*的工作流状态，例如 "Code Review"，按其映射到的状态分组，并与状态选择器叠加生效）。当搜索或筛选缩小了看板范围时，第三行会把每个条件显示为可移除的标签，显示“x / y”个 Spec，并提供 **全部清除**（保留你选中的状态）。排序可选 **默认**、**工单 #** 或 **优先级**，每一种都带有升序/降序切换。
+
+### 选择多个规格
+
+可以批量整理,而不必一个个处理。在获得焦点的卡片上按 `x`,按住 `Ctrl`/`⌘` 点击卡片,或按住 `Shift` 点击来选择一个范围(范围只在一列之内:进行中的规格或“已完成”分组)。`Ctrl`/`⌘`+`A` 选中你所在的整列,`Esc` 取消选择。鼠标悬停或获得焦点时,每张卡片会显示一个复选框,已选中的卡片边框会高亮。在搜索框中输入时,这些按键不会生效。
+
+只要选中了一个规格,看板底部就会浮出一条操作栏,显示数量和可用操作:
+
+- **移至**:更改状态。本地规格使用本地状态;来自 Jira 的规格使用 Jira 看板真实的工作流状态,并和单个移动一样经由同一个 Jira 队列。
+- **标签**:为所选规格添加标签,或移除规格已有的标签。
+- **优先级**:为全部规格设置同一个优先级。
+- **加入轨道**:把所选规格放到某个轨道上。
+- **全部启动**:为每个所选规格分配各自的空闲轨道并并行启动,事先经过与轨道上*全部启动*相同的确认和每日预算检查。暂时无法启动的规格(例如处于评审中但没有打开的 PR)或找不到空闲轨道的规格会被跳过,并在汇总中计数。
+- **删除**:移入*最近删除*。
+- **取消选择**(或 `Esc`):放弃选择。
+
+删除以及状态、标签、优先级的更改可以一步撤销:一条*撤销*提示(或 `⌘Z`)即可恢复它改动的所有规格。如果部分失败,一条提示会说明成功和失败的数量。选择中只包含你能看到的规格:筛选条件若隐藏了某个已选规格,它就会从选择中移除。
+
+### 已保存的视图
+
+**筛选**旁边的**视图**按钮会保存看板当前的样子:状态选择、筛选、排序和密度(不含搜索文本)。选择**保存当前视图…**,为它命名(如“可以启动”“冲刺 42”“本周失败”),之后在同一个菜单里选用。**管理视图…**可以重命名视图、用当前看板更新它、复制它的链接或删除它。视图属于项目。复制的链接(`?view=…`)在本应用中打开时会应用该视图,命令面板(`⌘K`)也可以保存当前视图或切换到另一个视图。
 
 ## 状态
 
@@ -38,7 +58,7 @@
 
 ## 创建一份 spec
 
-要创建 spec，点击 **添加**（SpecsBoard 工具栏上的加号按钮）。**添加 Spec** 对话框会打开，提供几种工作方式：
+要创建 spec，点击 **新建 Spec**（SpecsBoard 工具栏上的加号按钮）。**添加 Spec** 对话框会打开，提供几种工作方式：
 
 - **Quick 模式**——你描述需求，AI 一次性写出完整的 spec。参见 [添加 Spec — Quick 模式](add-spec-quick-mode.md)。
 - **Explore 模式**——你与 AI 对话，它会一轮一轮地帮你打磨 spec。参见 [添加 Spec — Explore 模式](add-spec-explore-mode.md)。
@@ -50,6 +70,24 @@
 
 当一个规格已经有了成果（评审中的 PR、已合并的功能）而你还想要*更多*时，不要重写它的描述：那会让规格偏离原意（并把偏离同步到 Jira），还会迫使下一次运行重新规划一切。打开规格，改为添加一条**附录**：一条简短说明，带有类型（变更请求、评审反馈、澄清、约束）和你自己的话。待处理的附录会自动随该规格在任何循环上的下一次启动传递（Implement、SDD Quick、Freestyle），运行只改变你要求的内容，评审包会把每条附录报告为已应用、部分应用或受阻。如果运行失败或你丢弃了交付，它们会自动回到**待处理**。当你让任务智能体修改现有规格时，它可以替你添加附录。
 
+## 审查交付：先看哪里
+
+运行结束后，评审包会以 **需要关注的地方** 开头：这是 AI 评审者的简短摘要，先列出风险最高的位置（按高、中、低排序，每项都带文件和行号），然后是会变化的行为、此次改动所依赖的规则、没有任何测试覆盖的代码路径，以及只能由人完成的检查。同样的风险、未测试路径和检查也会以简短区块出现在拉取请求顶部，任务卡片会用一行显示首要风险。该摘要只是审查参考，不是验证结果，永远不会阻止“接受”。使用旧版 Specrails Core 的运行没有摘要，其评审包保持原样。
+
+## 撤销与最近删除 {#recently-deleted}
+
+删除规格、将其移到另一个状态、修改标签或把它从 Rail 上移除，都会立即生效——不会先问“确定吗？”。取而代之的是，一条提示会在大约八秒内提供**撤销**，在你没有在输入框中打字时，也可以按 **⌘Z**（Windows 和 Linux 上为 **Ctrl+Z**）。撤销以项目为单位：切换项目会关闭该时间窗口。
+
+被删除的规格（以及被删除的任务）并没有消失。它会进入项目设置中的**设置 → 最近删除**，你可以在 30 天内**恢复**它，或**永久删除**（这一步会先确认）。30 天后将被彻底移除。放弃未推送的工作、强制关闭拉取请求以及移除项目仍会先确认，因为它们无法撤回。与 Jira 关联的规格仍然通过**移至**处理，而不是直接删除。
+
+## 规格时间线与交接 {#spec-timeline}
+
+打开一个规格并切换到 **时间线** 标签页，即可在一处读完它的全部经过：编辑与补充、接触过它的任务、每次运行及其阶段和智能体操作、拉取请求事件，以及评审者的结论和发现。条目按天分组，筛选标签按类型过滤，每个条目都链接到它来源的任务、运行或评审。较长的分组（阶段、智能体操作、任务交互）会折叠并显示数量，可就地展开。
+
+成本显示在产生它的条目旁边，并把两种成本分开：提供方报告的数字，以及按本地价格表估算的数字（标注“估算”）。如果某个提供方按订阅计划计费，时间线和导出只显示轮数，绝不显示美元；没有报告成本的运行则不显示成本。
+
+**导出交接**（标签页旁的菜单，或 ⌘K → *导出 #N 的交接*）会生成 Markdown 文件或独立的 HTML 页面，包含摘要、决策（补充、澄清、评审结论）、差异统计、成本以及仍未完成的事项（未处理的补充和未解决的评审发现）。**复制为 PR 描述**（同样在 ⌘K 中）会把较短的 Markdown 版本放入剪贴板。标题跟随应用语言。所有内容都经过与智能体操作审计相同的机密信息遮蔽，如有内容被隐去，提示会告诉你。
+
 ## 下一步去哪里
 
 - [添加 Spec — Quick 模式](add-spec-quick-mode.md)——把想法变成 spec 的最快方式。

package/docs/guide/zh/specs/2-add-spec-quick-mode.md

@@ -6,7 +6,7 @@
 
 要快速创建一份 spec：
 
-1. 在 Dashboard 上点击 **添加**（SpecsBoard 工具栏上的加号按钮）。
+1. 在 Dashboard 上点击 **新建 Spec**（SpecsBoard 工具栏上的加号按钮）。
 2. 选择 **Quick** 模式。
 3. 在文本框里输入你的想法——一句话或一段话，能说清楚就行。
 4. 点击生成。

package/docs/guide/zh/specs/3-add-spec-explore-mode.md

@@ -22,7 +22,7 @@ Explore 模式是一场对话。你不必自己动手写 spec，而是和 AI 一
 
 这正是 Explore 模式的精髓：你永远不会对着一张空白表单发呆，而是始终面对一份真实的、不断演进的 spec。
 
-## AI 能看到多少：上下文滑块
+## AI 能看到多少：上下文滑块 {#context-scope}
 
 在 AI 作答之前，由你来决定它能看到你项目里的多少内容。一个上下文预设滑块让你在速度和深度之间做权衡：
 

package/docs/internals/README.md

@@ -17,16 +17,24 @@ Start with [the modular architecture decision](modular-architecture.md),
 | [configuration.md](configuration.md) | Settings, env vars, kill switches, advanced flags |
 | [operations-runbook.md](operations-runbook.md) | Start/stop, port conflicts, recovery procedures, backups |
 | [core-runtime-updates.md](core-runtime-updates.md) | Core runtime discovery, durable package updates, version reporting and recovery after partial workspace refresh |
+| [mission-read-only-policy.md](mission-read-only-policy.md) | Read-only mission agents: per-provider native boundary that keeps MCP tools callable, Core session policy, kill switch, limitations and live evidence |
 | [agent-sessions.md](agent-sessions.md) | Core resident agent sessions in Desktop: host per scope, runner seam, projection, rebuild, sub-agent UI and rollout flag |
+| [companion-inbox-decisions.md](companion-inbox-decisions.md) | Paired companion as a decision remote for the Needs-you inbox: the four safe actions, their MCP permission tiers, what stays desktop-only (and why Discard is excluded), the `inbox.changed` nudge |
+| [flow-mode.md](flow-mode.md) | Flow mode server side: lifecycle and sagas, worktree hand-off to a rail, Flow turns with interrupt delivery, capability gating, routes and events |
+| [spec-triage.md](spec-triage.md) | Spec triage: hashed deterministic inputs, the one cheap structured-output call, triggers, rail preselection and the recommended/chosen loop recorded per delivery |
+| [existing-project-anchoring.md](existing-project-anchoring.md) | Existing-project anchoring (feedback-2026-10 phase 3 + rules inventory): ticket non-goals, architect clarifications on Jira, requirements demonstrated, baseline on touch, project rules; every surface gated on its Core capability |
 | [programmatic-agent-runtime.md](programmatic-agent-runtime.md) | Paired Core build, per-role providers/local models, project settings, saved execution recovery and delivery boundaries |
 | [programmatic-agent-runtime-validation.md](programmatic-agent-runtime-validation.md) | Paired implementation test results, packaging evidence and release limitations |
 | [openspec-workflow.md](openspec-workflow.md) | `opsx:*` change lifecycle — used by the app itself for structured change management |
 | [adding-a-provider.md](adding-a-provider.md) | How to add a new AI CLI: one adapter file plus one entry in the registry |
 | [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/modules/agents/runtime/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |
 | [safe-pr-review-flow.md](safe-pr-review-flow.md) | The ask-first PR delivery: the `rail_pr_deliveries` row, decision state machine, the two synced decision surfaces (rail row + agent-chat card), the `on_review` ticket status and its Jira mapping |
+| [agent-actions-audit.md](agent-actions-audit.md) | The per-project `agent_actions` log: producers (provider streams, Core events, missions, MCP wrapper, provenance), redaction, batched non-blocking writer, JSONL/CSV export, review-packet summary and retention |
 | [interactive-jobs.md](interactive-jobs.md) | Interactive-by-default jobs: the persistent-stdin session model, `finalize` vs `auto` settle modes, loop-step turn routing, accounting reconciliation, kill-switch matrix |
 | [loop-step-log-explorer.md](loop-step-log-explorer.md) | The step-grouped log surface for loop runs: the `loop_graph` / `loop_step` / `loop_step_end` event contract and seq guarantees, grouping + status model (interrupted rule, legacy fallback), follow mode, perf notes |
 | [gemini-mcp-registration.md](gemini-mcp-registration.md) | How MCP servers actually reach gemini-cli (`.gemini/settings.json` + trust env, FQN tool prefix) and the deferred `.mcp.json` gap on non-agent-chat surfaces |
+| [../../DESIGN.md](../../DESIGN.md) | The design system record (Signal box at night): colour, type, radius, elevation, motion and component tokens derived from the shipped code; `visual-design-audit.md` stays the conventions log |
+| [modal-standard.md](modal-standard.md) | The client modal standard: Radix primitive, five sizes, sticky header/body/footer anatomy, button order, named z-index layers (`client/src/lib/layers.ts`), one scrim and entrance animation, workspace-only resizing, 12px type floor |
 | [browser-capture-performance.md](browser-capture-performance.md) | Embedded-browser fluidity: the CDP screencast → WS → canvas pipeline, the latency levers (non-blocking navigation, input coalescing, latest-frame-wins drawing, frame conflation), tuning knobs, and the OAuth popup design |
 
 **See also:** the app registers Claude Code, Codex CLI, Gemini CLI, and Kimi

package/docs/internals/adding-a-provider.md

@@ -93,6 +93,15 @@ it; if your CLI has no persistent-stdin transport, `throw` in that `case`
 (as Gemini does) so a misrouted spawn fails loudly instead of emitting a
 broken argv.
 
+#### Declare `envAllowlist`
+
+List the authentication and configuration variable names your CLI reads
+(`'MYCLI_*'` matches a prefix). Projects in the `minimal` agent environment mode
+forward only these, the shared allowlist and the project's passthrough names to
+your provider; omitting a credential variable makes the CLI fail to sign in
+there. See [agent environment mode](configuration.md#agent-environment-mode) and
+add a case to `server/providers/env-allowlist.test.ts`.
+
 #### (Optional) prepareHeadlessSpawn
 
 `prepareHeadlessSpawn?(projectPath)` is an optional, best-effort filesystem
@@ -286,8 +295,9 @@ Two distinct version concepts — don't conflate them:
   (Claude = `null` / none pinned, Codex = `0.128.0`, Gemini = `0.11.0`,
   Kimi = `0.27.0`). It
   guards stream-format / flag availability for that one CLI.
-- **`specrails-core@^4.12.0`** (`CORE_PACKAGE_SPEC`, `server/core-package.ts`) is
-  the single shared package floor the app installs/probes for **all** providers.
+- **`specrails-core@^6.0.0`** (`CORE_PACKAGE_SPEC`, `server/core-package.ts`) is
+  the single shared package range the app installs/probes for **all** providers
+  (`SUPPORTED_CORE_MAJORS` still reads Core 4 and 5 workspaces).
   It matters when your provider's **rails** rely on core-side scaffolding: core
   must emit the provider's command/agent/skill tree (e.g. Gemini needed core
   `4.8.0` to ship the `.gemini/` commands + `sr-*` agents, while Kimi requires
@@ -296,6 +306,13 @@ Two distinct version concepts — don't conflate them:
 
 ## Known gotchas
 
+- **Read-only missions keep MCP tools.** If the adapter advertises
+  `capabilities.toolPolicies` with `read-only`, mission turns spawn with
+  `toolPolicy: 'read-only'` and `retainMcpTools: true`. The adapter's read-only
+  mode must still let the agent call the MCP servers registered for the turn.
+  Verify this live, because plan-style modes often hide or refuse MCP tools.
+  For Core sessions, declare `capabilities.missionReadOnlySession`. See
+  [read-only missions](mission-read-only-policy.md).
 - **Legacy result path.** `normaliseResultEvent(event, provider)`
   (`server/modules/accounting/runtime/result-event.ts`) is still live for any callsite not yet
   migrated to `finaliseInvocationResult`. It only special-cases

package/docs/internals/agent-actions-audit.md

@@ -0,0 +1,101 @@
+# Agent actions audit
+
+Every project keeps a log of what its agents **read**, **wrote**, **executed**,
+called over **MCP** or fetched from the **network**. It answers "what did the
+agent do?" after a run, without replaying transcripts.
+
+The log is built from streams Desktop already consumes. It is as complete as
+those streams are. In particular, **reads are only as complete as each
+provider's stream reports them**: a provider that does not emit a tool event for
+a read leaves no read row. Writes are additionally cross-checked by the
+post-run diff (`file_provenance`), which is provider-independent.
+
+## Table
+
+Migration 73 adds `agent_actions` to the project database (`jobs.sqlite`):
+
+| Column | Meaning |
+| --- | --- |
+| `id` | Integer key |
+| `run_id` | Run that acted: queue job id, loop run id, or mission conversation id |
+| `job_id` | Backing job row when there is one (`NULL` for missions) |
+| `role` | `architect`, `developer`, `reviewer`, `fixer`, `mission`, `subagent`, `loop`, `run`, `agent`, … |
+| `kind` | `read`, `write`, `exec`, `mcp` or `network` (CHECK constraint) |
+| `target` | Path, redacted command, MCP tool (`mcp__server__tool`, `specrails_jobs:audit`), URL without query, or `search: <query>` |
+| `hash` | sha256 of the written content when the call carried it, or of the recorded diff for provenance rows |
+| `ts` | ISO timestamp |
+| `source` | `claude-stream`, `codex-stream`, `gemini-stream`, `provider-stream`, `core-agent-event`, `core-session`, `file-provenance`, `mcp-wrapper` |
+
+Indexes: `(run_id, ts)` and `(ts)`.
+
+## What is never stored
+
+- File contents, tool outputs, patches and diffs. Only paths. `apply_patch`
+  contributes the file names in its envelope, never its hunks.
+- Environment values. `NAME=value` assignments in commands keep `NAME=***`.
+- Obvious secrets in commands: `--token`, `--password`, `--api-key` style flags,
+  `Authorization:` / `Bearer` headers, `user:pass@` URL credentials and common
+  token shapes (`ghp_…`, `github_pat_…`, `sk-…`, `xox?-…`, `AKIA…`, `glpat-…`,
+  `npm_…`).
+- URL query strings and fragments.
+- MCP arguments. A mission call is recorded as `tool:action` only.
+
+Targets are single-line and capped at 512 characters.
+
+## Producers
+
+| Source | Where | Notes |
+| --- | --- | --- |
+| Legacy queue jobs | `QueueManager` stdout reader | Claude stream-json, Codex `item.*`, Gemini `tool_use`. Claude `Task` sub-agents are followed through `parent_tool_use_id`, so their actions carry the sub-agent type as role |
+| Interactive jobs and interactive loop steps | `InteractiveJobSession.onProviderEvent` | Same classification; observer failures are swallowed |
+| Loop AI steps (one-shot) | `LoopRunManager` raw-line forwarder | Provider JSONL and Core `agent-event` tool-start lines (`role` comes from Core) |
+| Core workflow definitions | `LoopRunManager` runtime-event observer | Core `agent-event` tool-start lines; host-run environment commands (`npm ci`, …) become `exec` rows |
+| Mission Core sessions | `MissionSessionProjector` | `turn.tool` (role `mission`) and sub-agent tool output (role `subagent`), recorded after the projection commit, in the mission's pinned project |
+| Mission native sessions | `AgentChatManager` | Adapter tool-use previews (truncated input; paths are recovered when visible) |
+| Mission MCP calls | `recordMissionMcpAction` in `registerTieredTool` | Only first-party (capability-bearing) calls of a pinned project; external MCP clients leave no rows |
+| Post-run diff | `recordProvenanceForJob` | One `write` row per provenance row (role `run`), hashed patch, same transaction, guarded against a pre-migration database |
+
+Missions without a pinned project, or whose project is not loaded, are not
+recorded.
+
+## Writing never blocks a run
+
+`createAgentAuditRecorder` validates rows synchronously and buffers them. It
+writes from a timer: every 250 ms, or immediately once 200 rows are pending.
+A batch is one SQLite transaction (one WAL commit). `record()` performs no IO
+and never throws. Storage failures are counted (`stats().failed`) and logged
+at most once every 10 seconds. More than 20 000 pending rows are dropped and
+counted. Every stream tap catches its own errors, so a classification bug or a
+broken disk cannot fail, stall or alter the run that produced the action.
+
+The project registry creates one recorder per project connection and flushes it
+before the connection closes (project removal and app shutdown).
+
+## Export
+
+- `GET /api/projects/:projectId/jobs/:runId/audit?format=jsonl|csv` — one run
+  (matches `run_id` or `job_id`). Default `jsonl`.
+- `GET /api/projects/:projectId/agent-actions?format=jsonl|csv&from=&to=` — a
+  project-wide window (ISO timestamps, inclusive).
+
+Both flush pending rows first and return at most 100 000 rows, oldest first, as
+an attachment with an `X-Agent-Actions-Rows` header. CSV columns are
+`id,ts,run_id,job_id,role,kind,target,hash,source`. Cells starting with `=`,
+`+`, `-`, `@` are prefixed with `'` so spreadsheets do not evaluate them.
+
+MCP: `specrails_jobs` action `audit` (read tier) with `jobId` (or `from`/`to`
+for the project window) and `format` (`jsonl` default, or `csv`).
+
+The review packet shows **What the agent did**: counts by kind across the
+delivery's runs and per-run JSONL/CSV downloads.
+
+## Retention
+
+The project setting `agentAuditRetentionDays` (default 30, 1–3650) controls how
+long rows are kept. Retention runs 5 seconds after the project opens and then
+daily, reading the setting each time. A failure is logged and never thrown.
+
+## Code
+
+- [Module](../../server/modules/audit/README.md)
+- Tests: `npx vitest run server/modules/audit server/mcp/tools/jobs-audit.test.ts`

package/docs/internals/agent-sessions.md

@@ -74,8 +74,34 @@ Core journal ──session.event──▶ SessionEventPump ──ProjectionOp[]
   and cursor (`agent_session_cursors`), and continuation turns as messages with
   `turn_origin` `subagent`/`system` plus invocations with `origin`. User turns
   are settled by the mission manager.
+- A conversation can own more than one Core session: its own (id = the
+  conversation id) and, in Flow, `flow:<flowId>`. Each is projected by its own
+  `MissionSessionProjector`: the cursor is keyed by `(conversation_id,
+  core_session_id)` and every sub-agent row records `core_session_id`
+  (desktop migration 35). The Flow projector bills its continuation turns and
+  delegated sub-agents with `surface: 'flow'` (so they land in
+  `GET /flow/:flowId/cost` and the mission's `flowCostUsd`), and tags its
+  WebSocket messages with `coreSessionId`. The client keys them by
+  conversation, so the sub-agents card shows a Flow's agents while in Flow;
+  the resident state it receives is the conversation's across its sessions.
+- A Core session keeps the driver that opened it, so the mission's own session
+  has generations (desktop migration 36, `agent_core_sessions`): generation 0
+  keeps the conversation id, generation n is `<conversationId>:g<n>`, and the
+  table records the provider the current generation was opened with. A turn on
+  another provider (after a switch, also after a restart) or on a closed
+  session closes the current generation and opens the next one, seeded with
+  the conversation history through the fresh-session prompt path. The runner
+  also verifies the driver Core reports when it resumes a session; a mismatch
+  or a closed session (`session_driver_mismatch` / `session_closed`, nothing
+  sent) renews once and retries. A model or effort change on the same provider
+  stays in the session (`session.update`). Later generations project as the
+  mission's own (untagged broadcasts, `agent-chat` billing, ids keyed by the
+  generation's session id).
 - Continuation turns get a deterministic invocation id, so replay never records
-  a turn twice. `POST /api/agent/conversations/:id/session/rebuild` resets the
+  a turn twice. Ids of a Flow session include its session id
+  (`core-turn:<conversation>:flow:<flowId>:<turn>`,
+  `core-subagent:<conversation>:flow:<flowId>:<subagent>:<seq>`), so the two
+  sessions never collide; a rebuild replays every session of the conversation. `POST /api/agent/conversations/:id/session/rebuild` resets the
   derived rows and replays the journal silently (see the
   [API reference](api-reference.md)).
 
@@ -96,6 +122,15 @@ deferred, and the mission offers "Stop agents and apply now". If Core rejects
 a policy with `policy_unenforceable`, the mission shows a localized error that
 names the provider and the setting.
 
+## Permission boundary
+
+Mission sessions are read-only. `MissionCoreSessions.prepareTurn` takes the
+`permissions` and `tools` fields from `missionSessionBoundary`. For Claude that
+is `bypass` plus `tools: { mode: 'read-only' }`, because plan mode would block
+Specrails MCP calls. For Codex it is `permissions: 'read-only'`, the read-only
+sandbox. A tool restriction is only requested from a driver that advertises
+`toolFiltering`. See [read-only missions](mission-read-only-policy.md).
+
 ## Sub-agent runtime (who launches them)
 
 The hybrid runtime decides who launches sub-agents once the policy allows them.