@ckanner/flywheel 0.31.1 → 0.32.1

package/docs/zh-CN/jev.md

@@ -0,0 +1,192 @@
+# JEV 决策
+
+[文档目录](../README.zh-CN.md) · [English](../en/jev.md) · 简体中文
+
+Flywheel 只有一个 JEV 开关：**启用 JEV**（`jev.enabled`），默认关闭。
+开启后，所有已支持的 JEV 决策点自动参与流程，不再分别设置影子、建议、采用或
+分功能开关。
+
+## 配置一次，继续使用原来的入口
+
+桌面进入 **Flywheel → 设置 → JEV**，选择需要的全局或项目范围。打开**启用 JEV**
+以显示连接字段，填写或确认 System One 地址、固定模型版本和密钥环境变量名，
+再点击**保存修改**。开关先修改草稿，保存后才启用；编辑和保存都不测试服务
+连通性。后续任务不为同一设置重复询问。
+
+执行 Flywheel 的进程需要继承该环境变量；配置只保存变量名称，不保存密钥值。
+高级字段限定超时、调用次数、阈值和发送数据类别。
+
+`key-env` 接受 1–120 位 ASCII 字母、数字和下划线，首位须为字母或下划线。
+大写、小写和混合大小写名称均可使用；调查冻结配置与重新读取状态时保留原始拼写。
+
+等价配置片段：
+
+```json
+{
+  "jev": {
+    "enabled": true,
+    "endpoint": "https://your-service.example/v1/systemone",
+    "model": "jev-1.14.0",
+    "key-env": "MEROUTER_API_KEY",
+    "timeout-ms": 5000,
+    "max-calls": 8,
+    "min-applicability": 0.8,
+    "min-choice": 0.6,
+    "allowed-data": ["task-summary", "diagnostic-facts", "source"]
+  }
+}
+```
+
+把示例地址替换为实际服务地址。模型必须固定为 `jev-x.y.z`，并与响应版本匹配。
+分发模板的地址为空、开关关闭；开启但目标配置非法时，配置校验失败。运行时缺少
+凭据则继续原有确定性路径；已形成的决策／请求记录保留实际跳过或失败原因。
+实施任务可能在建立首个运行时决策账本前就不满足前提，不承诺每次前置跳过都有回执。
+
+配置按**任务 → 项目 → 全局 → 内嵌表选择一份完整文件**，不跨文件深合并。项目
+配置中的关闭会覆盖全局开启。通过 `config inspect --cwd <项目> --task-dir <任务>
+--json` 查看实际配置来源；详见[配置参考](configuration.md)。
+
+配置好以后照常使用：
+
+- **Task**：从目标准备并运行已授权的调查或实施。Go 自动解析 JEV 策略，宿主不再手写决策模式。
+- **New**：准备调查契约或实现方案后停下，等待用户要求运行。
+- **Run**：在原目录启动或恢复已准备的调查或实现任务。
+- **Auto、Quick、Full**：仍是实现工作流策略；适用资格、验收和 review 由 Go 执行。
+
+## 一个开关控制哪些路径
+
+| 决策点 | 开启 JEV | 关闭 JEV |
+| --- | --- | --- |
+| 下一项取证动作 | 有不确定性时，在已批准的读取、搜索、目录列举、诊断命令与 HTTP 查询中选择 | 原有确定性顺序 |
+| 重复取证 | 通过绑定实际观察的控制选项，跳过已经取证的假设所对应的冗余动作 | 保留原动作集 |
+| 是否进入报告 | 满足引擎证据前提时，可以提前结束收集 | 按原动作、时间、输出预算结束 |
+| 已确认失败后的下一步 | 在合法的局部修复、反馈检查、重新规划候选中选择 | 原有有界返修与升级规则 |
+| 模型／推理等级选择 | 在已批准的完整执行绑定候选中选择，并记录实际切换 | 原有固定绑定与确定性升级／渠道后备 |
+| 反馈检查优先级 | 优先选择一个已批准的检查补充事实，再继续有界执行 | 原有反馈与验收顺序 |
+| 显式在线评估 | 服从同一总开关、目标和配置边界 | 在创建评估账本或请求前拒绝 |
+| 已有记录的离线回放 | 本地读取和解析，不调用模型 | 仍可查看，不调用模型 |
+
+开启所有已支持的决策点，不等于每个任务都增加一次 JEV 调用。单一合法动作和
+确定性选择直接执行。数据范围不允许、硬预算无法可靠约束单次消耗、次数耗尽、
+适用性不足、服务错误或响应非法时，继续基线路径；已形成的决策／请求记录保留
+实际原因，记录前的前置条件不足不代表会新建跳过回执。Auto 仍按 Go 的契约
+资格选择 Quick／Full；不为每次入口增加一次 JEV 分类请求。
+
+提前结束和跳过动作只决定如何收集证据，不证明根因成立。Go 保存决策、观察和
+动作的具体绑定；分析者仍须提交覆盖全部假设的报告，引用真实观察并说明不确定性。
+没有结论仍是 inconclusive。后续修复须沿用原来的授权范围，完成实现、review 和
+验证流程。详见[调查指南](investigation.md)。
+
+## 失败后的下一步与模型选择
+
+引擎先确认上一轮调用已结束、结果已消费、候选与失败证据可核对，并检查剩余尝试
+次数和预算，再生成候选。JEV 返回具体 action ID；Go 复核身份和当前开关后，原子
+保存选择与效果。现有失败上限、Quick → Full 单向升级、完整验收和独立 Review
+仍然成立；JEV 不能把未知执行结果解释成失败后重新调用。
+
+| 动作 | 实际效果 | 前提 |
+| --- | --- | --- |
+| `repair` | 在原 packet 范围内继续局部修复 | 还有合法的执行尝试与预算 |
+| `feedback-N` | 执行契约 `feedback-checks` 中的一项短反馈检查，把物理结果交给下一轮 | 检查已明确批准并有 `purpose` 用途说明；不能由模型新建或修改命令 |
+| `recheck-N` | 重新执行一项已经失败且结果完整的 L1 检查，取得最新反馈 | 检查来自冻结验收集合，已有失败已确认 |
+| `replan` | 进入现有受限规划／流程升级路径 | 当前任务允许规划，保留范围、修订次数与历史 |
+| `model-N` | 选择允许集合中的具体执行配置 | 已配置 `execution-policy`，完整绑定与切换次数符合规则 |
+
+`N` 是冻结候选集合的索引，不是模型名称或自定义命令。模型候选解析成实际
+绑定 ID、harness、Provider、账号渠道、模型、effort、权限与会话
+策略；没有批准候选时不猜测模型名称，也不增加付费渠道。模型／effort 改变继续
+使用已有冷启动规则，不把执行者会话交给 Reviewer。AUTH／QUOTA 等渠道问题仍走
+对应后备规则，不被当成模型推理能力不足。允许集配置见[配置参考](configuration.md)。
+
+短反馈检查的 `purpose` 是 1–160 字符的非空白用途说明；JEV 候选发送该说明，
+不附加 `cmd`／`script` 文本。说明本身也不要填写密钥、原日志或命令文本。
+没有 `purpose` 的条目仍可供 Executor 参考，但不进入 JEV
+定向选择候选。`purpose` 仅属于 `feedback-checks`，不会扩展验收字段或授权范围。
+
+反馈检查只为下一次行动提供证据。即使某项检查已经通过，最终仍在当前候选上运行
+全部必需验收；不能以这一次选择删除检查。桌面在任务与节点中显示决策请求、采用
+或基线原因、反馈检查和实际效果。`applied` 表示控制决策已经应用，后续修复、
+规划或新模型会话仍以节点记录为准；`completed` 表示该次控制动作已经收尾，
+不代表整个任务已交付。`feedback-completed` 也只是反馈检查收尾。
+`pending` 需要核对请求；`feedback-running`、`feedback-unknown` 需要核对原执行，
+不能自动重放。`feedback-stale` 表示反馈改变了候选或验证输入，流程已阻断。
+`replan-running` 表示重规划尚未收尾，恢复时须核对原 Plan 会话，不能再次派发来
+猜测前一次的结果。
+已采用的模型切换另列实际绑定前后值、尝试次数、原因和时间；不能从 `model-N`
+猜测实际模型，也不能把配置切换当成新会话已经成功运行。
+
+## 数据、预算与恢复
+
+调查创建准备记录时，Go 冻结有效 JEV 目标、数据类别、阈值和调用预算。任务输入中
+旧的 `decision` 模式不能绕过关闭的总开关。启用后的默认数据集合允许任务摘要、
+诊断假设、结构化命令／HTTP 结果，以及已批准文件取证的有界片段；可通过
+`allowed-data` 缩小范围。原命令／HTTP 输出只有明确允许 `logs` 时才附加，否则
+标记原内容缺失并使用结构化事实。数据范围不等同自动脱敏：若其余快照仍包含
+未授权类别，请求整体跳过，不能借摘要绕过原有数据权限。
+
+运行中关闭总开关，会停止后续 JEV 请求及建议采用，包括开关关闭后才返回的结果。
+已经派发的请求仍按原身份核对，保留已知或未知用量，未知请求不重发。结果未知的
+**实际动作**仍阻断执行，不能借切换开关绕过。
+
+创建时关闭的调查准备记录继续基线路径，后续开启不会改写这份准备记录；新准备
+记录才可冻结新开启的策略。
+
+实施阶段在已启用的运行中，首次符合条件的失败处冻结自己的运行时决策策略。
+如果当前进程启动时 JEV 关闭，且尚无运行时决策账本，仅保存开启设置不会立即
+启用该进程；须启动或恢复任务，读取已开启的配置。已有运行时决策账本时，关闭
+再开启仍保留冻结目标、记录和剩余额度，包括调查导入的次数。修改目标或收紧
+权限、限制，使当前配置与冻结策略不再相容时，停止后续可选决策，不偷偷重写策略。
+查看界面中的 JEV 状态和原因，不复制账本、重置预算来重新派发。
+
+`max-calls` 是每项任务的调用上限，包括已派发但结果未知的请求。调查移交实施时，
+已使用的次数计入实施额度；多个 packet、模型切换、重规划和恢复不能重新获得完整
+额度。这个限制不等于 token 或金额上限。配置了硬预算而服务无法强制单次消耗上限
+时，跳过 JEV。请求记录服务实际返回的用量，缺失保持 unknown。
+
+实施阶段的 `runtime-decisions` 位于 `state.json`，记录冻结策略、已用次数、
+调查导入次数和逐项请求／选择／效果，沿用已有 state 提交与交付规则。私有且排除
+自动交付的是 `.investigation/runtime-decisions` 请求 journal；这个排除规则不
+覆盖 `state.json` 中的决策信息副本。
+
+桌面只展示有界摘要，投影移除原始快照和目标配置；这只限制桌面输出，不构成 Git
+交付脱敏。批准的目标、事实、绑定和反馈输出仍与已有失败反馈一样，遵守不记录
+凭据的规则。请求或动作尚未完成时，从原任务恢复核对，不能用新账本或切换模型
+绕过未知结果。
+
+## 离线回放与显式评估
+
+正常任务在私有决策账本中保存冻结的 `*.input.json` 和回执。离线回放也接受历史
+`*.snapshot.json`：
+
+```bash
+flywheel decision replay --input frozen.input.json --response native-response.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
+```
+
+离线回放不读取密钥、不发请求、不写账本或任务状态。裸 Snapshot 需要
+`--policy reviewed-policy.json`；显式策略完整替换原策略，不继承省略的数据权限。
+
+需要实际在线评估时，先在相应范围开启 JEV：
+
+```bash
+flywheel decision evaluate --cwd "$repo_dir" --input frozen.input.json \
+  --directory ./decision-evaluation --max-calls 5
+```
+
+目标、固定模型和密钥变量取自同一配置；旧的显式目标参数必须与配置一致。评估
+命令强制只建议，不执行动作、不改任务状态；其次数、超时、阈值和数据范围不能
+放宽配置边界。同一输入和账本只读取原回执，未知请求不会重发。
+
+两种工具都输出 `adopted: false`。在线错误或未知返回退出码 3，输入／配置错误
+为 1，取消为 143。离线 fixture 通过不能证明真实模型成功率或任务加速。
+
+## 从影子功能迁移
+
+旧自动观察器和独立影子请求客户端已经移除。旧 `jev-shadow` 配置仍可读取并迁移
+连接信息，但旧开启值不会自动启用在线决策。明确的新 `jev` 配置优先。编辑器保存
+统一配置并移除旧 key，保留原来的备份和 revision 检查。旧 `shadow` 命令只提示
+迁移方式，不再执行实验；历史记录及其 schema 保留作证据。
+
+评估实际价值时，对比开关关闭与开启的完整任务：获得有效证据的时间、执行／跳过
+动作数、总耗时、实际与未知用量、最终质量。只改变顺序或通过离线 fixture，均不能
+单独证明加速。

package/docs/zh-CN/model-policy.md

@@ -104,6 +104,11 @@ hard 执行，`loops.judge.thinking` 只影响 Judge。阶段覆盖可以避免
 不证明后一个模型更好。渠道错误使用单独声明的后备，两种机制都不能选择未声明
 的模型或费用渠道。
 
+开启唯一 [JEV 总开关](jev.md) 后，确认结束的失败也可把已有允许绑定作为决策
+候选。采用前核对冻结允许集、权限、剩余尝试与切换预算，不再设置 JEV 模型路由
+开关。没有合法备选时继续当前绑定。语义选择只记录为实际选择，不代表已经测得
+该模型更快或更好。
+
 effort 改变会冷启动角色，并记录完整前后绑定。对照必须计入重读、启动及实际
 已知／未知用量与成本。离线测试以受控 driver 结果运行真实引擎返修和恢复路径，
 不能证明实际模型质量或速度；改变默认值或宣称节省前仍须使用配对真实任务与

package/docs/zh-CN/session-recovery.md

@@ -65,6 +65,35 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 共享目录并行的 Execute 回执使用已声明写入范围的候选指纹，并把该范围绑定到会话身份；其他任务的独立变更不会导致本调用无故丢失归属。自己的范围变化仍拒绝旧回执。L1、独立 Review 与批次提交始终核对完整共同候选；范围回执不能证明整组完成，也不能绕过未知派发、结果或清理。
 
+### DSH 预热运行时的重启核对
+
+可选 `scheduler.prewarm` 在确定性检查期间准备 DSH Review runtime，不发送
+模型 prompt。Go 在启动前保存单个 `worker-prewarm` 清理责任，绑定准备 ID、
+角色／范围、配置身份和 run；终态回执私有保存在 `.control/prewarm/` 下。
+这份回执不是模型调用或 Review 通过证据。
+
+完整终态 JSON 在 UTF-8 序列化后最多 8 KiB，包含转义字符和末尾换行。过长的错误
+诊断会保留带截断标记的前缀，正常短错误以及全部身份、派发和清理字段保持完整。
+诊断截断不会放宽任何恢复检查，也不会把初始化失败变成允许冷启动回退的安全过期。
+
+引擎重启不会续用这个待用 worker。只有原身份匹配的回执证明没有提交 prompt、
+SDK 清理已确认，且记录的 worker 与其原进程组都已退出，才可解除原清理责任。
+发布回执时同步文件与目录；恢复时在清除状态前重新确认这两项持久化。实际从未
+启动进程时，可以使用明确记录的本地 no-process 回执；不能仅凭经过时间或缺失
+PID 推断。回执缺失、超限、损坏、身份不匹配、进程或进程组仍存活或无法确认退出、
+清理未知都会保持阻断；关闭预热也不能跳过核对。安全收束后，后续工作才按当前
+配置和正常调用检查继续。
+
+在同一个引擎运行中，待用实例安全过期、且尚未尝试任何正式派发时，可在同一
+已持久化 invocation 身份和剩余时限内冷启动一次。这不属于重启续用，不增加一次
+模型计费尝试，也不能绕过未知效果。取消、正式调用时限耗尽、清理不完整或输出
+不可信时都不能这样回退。
+
+首次创建预热记录会将 `state.sessions.version` 提升为 **3**，后续操作保持该
+版本。这个存储兼容标记使旧引擎拒绝无法理解的清理责任；新引擎仍支持版本 1、2。
+配置的 `sessions.policy-version` 仍为 1，worker 和 lifecycle 各自维持独立的
+协议版本。不要手改存储版本或删回执来强行降级。
+
 ## 计量与预算
 
 已消费的调用不再次计数，不重发模型请求。原调用曾因丢失回执计为 unknown、后又找回可信 usage 时，Go 按同一调用记一条可审计 correction；保留原 provider、原日桶和 lifetime 归属。已过保留窗口的日桶不会因为恢复而重新出现。

package/docs/zh-CN/workflow.md

@@ -48,6 +48,11 @@ Full 复用已确认且持久化的有效 Plan 检查点；显式 Plan、verific
 不可信基线仍重规划。执行者先跑针对性检查，Go 完整门禁与独立 Review 继续负责完成。
 模型绑定默认不变；允许集合和可信增量上下文是独立 opt-in，见[配置](configuration.md)。
 
+已授权调查可使用输入副本中的确切复现命令及明确 GET／HEAD 请求，执行权限边界、
+deadline、输出上限和回执写入调查契约。开启 JEV 后，确认结束的实施失败也可在
+返修、已批准反馈检查、重规划或已有允许执行绑定中选择；流程资格和最终完整门禁
+仍由 Go 负责。一次反馈实验成功不等于实现完成。
+
 ## 1. 选择准备阶段的模型
 
 `flywheel-task` 与 `flywheel-new` 使用宿主当前对话的模型。`loops.plan` 只控制
@@ -204,6 +209,15 @@ DSH 对应使用 `/flywheel-run <绝对任务目录>` 和 `/flywheel-status <同
 Execute，再验证和评审完整共同候选。Review、集成与终验保持串行。hard 预算在前一调用
 完成持久化计量前只允许一个模型调用在飞，详见[控制台指南](flow-console.md#串行与并行)。
 
+可选 `scheduler.dispatch="ready-queue"` 在自动管理 Worktree 的 Full 任务中，为
+已就绪的独立 packet 补充空闲 Execute／L1 槽位；Review、Plan 修订和集成仍等待
+已启动 worker 停稳。`scheduler.prewarm=true` 可以在串行 packet 的确定性检查
+期间准备一个 DSH Review runtime，不提前发送模型 prompt。并行执行 lane 和共享
+候选不预热；独立并行组停稳后，串行 Review 路径才可开始准备。主要重叠机会是
+串行 Execute 后的 L1 和适用 Quick 检查。默认仍为 batch 调度且不预热；
+Task／New／Run 和 Auto／Quick／Full 的职责保持，详见
+[配置与限制](configuration.md#就绪队列与运行时准备)。
+
 `scoped` 历史可在资格满足时复用同 packet Executor Session 返修。Review 使用独立
 历史，每次仍检查完整当前候选；Plan 按任务／里程碑划分，Judge 和第二意见分别独立。
 旧配置省略 `sessions` 时继续 fresh。两种模式都有调用安全记录，派发、结果或清理未知
@@ -266,5 +280,5 @@ flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 - [配置](configuration.md)：模型绑定、权限、预算与策略。
 - [流程控制台](flow-console.md)：任务、阶段、会话、运行对比与远端交付。
 - [恢复与上下文质量](session-recovery.md)：中断核对与安全续用。
-- [JEV 影子评估](jev-shadow.md)：可选且默认关闭，不改变实际工作流选择。
+- [JEV 决策](jev.md)：一个默认关闭的总开关控制调查及有界失败决策，Go 保留工作流资格与验收规则。
 - [系统设计](../design.md)：权威实现契约。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
@@ -36,10 +36,10 @@
     "docs"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.31.1",
-    "@ckanner/flywheel-darwin-amd64": "0.31.1",
-    "@ckanner/flywheel-linux-arm64": "0.31.1",
-    "@ckanner/flywheel-linux-amd64": "0.31.1"
+    "@ckanner/flywheel-darwin-arm64": "0.32.1",
+    "@ckanner/flywheel-darwin-amd64": "0.32.1",
+    "@ckanner/flywheel-linux-arm64": "0.32.1",
+    "@ckanner/flywheel-linux-amd64": "0.32.1"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
@@ -47,10 +47,10 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.31.1 dist-npm",
+    "build:npm": "bash scripts/build-npm.sh 0.32.1 dist-npm",
     "test:sessions": "node scripts/test-session-evaluation.js"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.31.1"
+    "@ckanner/dsh-plugin-flywheel": "0.32.1"
   }
 }