@hunter-harness/workflow-harness 0.2.41 → 0.2.43

package/harness/bundles/general/codex/harness-knowledge-query/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

package/harness/bundles/general/codex/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/codex/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/codex/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/codex/harness-run/reference.md

@@ -94,7 +94,7 @@ requested=true + path missing
 6. **读取测试场景表**：`.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` → 获取测试真相源
 7. **读取验证账本**：`.harness/changes/<change-name>/evidence/verification-ledger.json`（如存在）→ 复用已有 compile/unitTest 结果
 8. **读取任务状态**：`.harness/changes/<change-name>/evidence/run-task-status.md`（如存在）→ 恢复上次运行状态
-9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并将 RED/YELLOW 条目映射为本轮变更簇
+9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并用 `harness_fixback.py` 将相关 RED/YELLOW 条目合并为一个批次；每条问题保留 RED/GREEN 证据，批次关闭后只触发一次 affected verification 与一次 review
 10. 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 11. **执行测试基础设施探测**（见下方"步骤 0.5"）
 12. 确认构建环境正常（构建命令按技术栈，见项目 CLAUDE.md 或 `.harness/config/harness-build-config.md`；如 Java 的 `powershell.exe -Command "mvn compile -pl <module> -o -q"`）
@@ -102,6 +102,11 @@ requested=true + path missing
 14. **依赖模块预安装**：如果在 worktree 中执行，检查上游依赖是否已安装（如 Java 的 `mvn install` 到本地仓库、前端的依赖已 install）。缺失时先执行对应安装命令（Java 示例：`powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"`）
 15. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `项目 codegraph 规则` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
 
+长时编译或验证不得依赖当前对话持续在线；使用 `harness_runtime.py run-start` 创建
+受管会话，并以状态/日志游标重连。并行执行前先调用
+`harness_verification.py` 的 `plan` 模式取得资源锁 wave；没有资源声明的重任务保持串行。详见
+`../protocols/execution-session-protocol.md`。
+
 ### 步骤 0.0：正式产物来源确认
 
 在读取计划文件后，确认本次执行只使用 `.harness/changes/<change-name>/` 下的正式产物：

package/harness/bundles/general/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/codex/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, knowledge, rules, instruction entrypoints, config origins,
   or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-sync
 
 ## Purpose
@@ -13,13 +13,10 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
 
 ## Before running
 
-读取 `reference.md`。先执行只读能力握手；若最低 CLI 版本或任一必需能力不满足，立即停止，不得先运行 knowledge、refresh 或其他重操作：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流要求 `sync@1`、`rules-sync@1`、`rules-review@1`、`knowledge-sync@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，不得降级为手工拼接旧流程。
+读取 `reference.md`。`sync` 自身会在任何重操作之前完成能力握手；不要另起一个
+`capabilities` 进程。工作流要求 `sync@2`、`rules-sync@1`、`rules-review@1`、
+`knowledge-sync@3`、`codegraph-status@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，
+不得降级为手工拼接旧流程。
 
 ## Run
 
@@ -29,17 +26,26 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 
 CLI 负责 Python runtime 解析、投影事务、knowledge、rules、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用内部 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。
 
-长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的 `reportPath`，并带 `reportSha256`。不得把完整 JSON 报告直接回显到对话。
+只读诊断使用 `--check`（`--dry-run` 为兼容别名）；它不得写报告、receipt 或投影。
+长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的
+`reportPath`，并带 `reportSha256`。需要组件级证据时显式加 `--verbose`，不得默认把完整
+JSON 报告回显到对话。
+
+摘要中的 `remediations[]` 是稳定修复契约。先用对应 `previewCommand` 预览；低风险修复用
+`--apply safe`，指定修复用 `--fix <id>`。需覆盖受管投影的修复必须同时提供 `--yes`，
+并依赖 refresh 事务留下的 before snapshot；不允许绕过确认或无备份覆盖。指定修复时，
+无关组件只做只读评估，不得顺带写入。
 
 ## Interpret
 
 - `OK`：所有可验证组件通过。
+- `ADVISORY`：索引最新，但有待评审候选等非阻塞健康提示；退出码仍为 0。
 - `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按 `reportPath` 中的 `nextAction` 处理。
 - `FAIL`：组件执行失败；不得宣称同步完成。
 - `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。
 - `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。
 
-非交互或 CI 使用 `--profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
+非交互或 CI 使用 `--check --profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
 
 ## Safety
 

package/harness/bundles/general/codex/harness-sync/reference.md

@@ -6,13 +6,8 @@ description: harness-sync 的能力契约、统一状态模型、报告收据和
 
 ## 1. 能力握手
 
-统一入口执行前读取：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。CLI 在任何高成本阶段之前核对版本与能力；缺失时返回：
+工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。`sync` 在任何高成本
+阶段之前自行核对版本与能力；Skill 不要再运行独立的 `capabilities` 子进程。缺失时返回：
 
 ```json
 {
@@ -47,22 +42,41 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 CI/非交互式：
 
 ```powershell
-npx hunter-harness sync --project <项目路径> --profile general --progress jsonl --json
+npx hunter-harness sync --check --project <项目路径> --profile general --progress jsonl --json
 ```
 
-`--dry-run` 只做只读检查或事务预览，不应生成持久报告、receipt 或投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 只输出：
+`--check` 是严格只读检查；`--dry-run` 是兼容别名。两者都不生成持久报告、receipt 或
+投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 默认只输出：
 
 ```json
 {
   "status": "WARN",
   "runId": "<run-id>",
-  "components": {"ok": 7, "warn": 1, "fail": 0, "blocked": 0, "unknown": 1},
+  "components": {"ok": 7, "advisory": 1, "warn": 0, "fail": 0, "blocked": 0, "unknown": 0},
+  "versions": {
+    "cliVersion": "0.0.0",
+    "workflowBundleVersion": "0.0.0",
+    "adapterBundleVersions": {}
+  },
+  "remediations": [],
   "reportPath": ".harness/runtime/sync/<run-id>/reports/sync-report.json",
   "reportSha256": "<sha256>"
 }
 ```
 
-详细报告必须受大小限制，并包含每个组件的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动修复及 `nextAction`。
+只读检查的 `reportPath/reportSha256` 为 `null`。详细报告必须受大小限制，并包含每个组件
+的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动
+修复及 `nextAction`；只有显式 `--verbose` 才把组件级详情写到 stdout。
+
+### 结构化修复
+
+- `remediations[]` 含稳定 `id`、风险、写入范围、备份/回滚说明、预计耗时、是否需确认、
+  `previewCommand` 与 `applyCommand`。
+- `--apply safe` 只执行低风险、无需确认的修复。
+- `--fix <id>` 只执行该项；需要覆盖受管 Adapter 时必须加 `--yes`。
+- 指定修复时，其他组件仍参与诊断但保持只读。
+- Adapter 覆盖由 refresh 事务执行，before snapshot 位于最新 committed refresh
+  transaction；事务失败会自动回滚。预览永远不得产生写入。
 
 ## 4. 组件状态
 
@@ -77,15 +91,21 @@ npx hunter-harness sync --project <项目路径> --profile general --progress js
 | instruction graph | 入口、include 边、环、主题可达性 | 缺失引用或循环为 `FAIL` |
 | config origins | canonical/projection 路径与 hash | 漂移 `WARN`，不静默覆盖 |
 | changes | 五态分类及归档收据 | `INVALID`/`ORPHAN` 不自动删除 |
-| CodeGraph | 索引文件、守护进程管道、watcher 日志、pending、watcher lag | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；不自动全量 reindex |
+| CodeGraph | `codegraph status --json` 的 pending、数据库观察时间、watcher 可达性 | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；日志 mtime 只证明 watcher 活动，不证明索引完成；不自动全量 reindex |
 
-全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `OK`。任一 `UNKNOWN` 至少使全局结果为 `WARN`。
+全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `ADVISORY` → `OK`。任一 `UNKNOWN`
+至少使全局结果为 `WARN`。knowledge freshness 与 health 分开：索引一致但仍有待裁决候选时
+为 `ADVISORY`，不得误报为过期。
 
 ## 5. Git 与 CodeGraph
 
 增量基线来自上次成功 sync receipt 的 `headCommit`。首次运行或 receipt 不可用时，仅收集当前 HEAD 和有界文件统计；禁止固定 `HEAD~5`。
 
-CodeGraph 状态探测读取 `.codegraph/codegraph.db`、daemon receipt/log，尝试有界管道连接，并比较项目文件与最近索引观察时间。只有服务可达、watcher 已启用且 `pendingFileCount=0` 时为 `CURRENT`；此时才可将当前 HEAD 记录为推断的 `indexedCommit`。不可用、待同步或证据不足时分别报告 `STALE/PENDING/INDEX_PRESENT_UNVERIFIED/UNKNOWN` 与明确后续动作。不要在 sync 内执行全量索引，不使用依赖 shell 连接符的跨平台命令。
+CodeGraph 状态探测优先读取 `codegraph status --json` 的权威 pending 列表；只有该 API
+不可用时才退回受限文件扫描，并把来源标成 `database-scan` 或 `unverified`。`.agents/`、
+`.cursor/`、`.claude/` 等 Adapter 投影和 Markdown 文档不计入源码 pending。daemon log
+mtime 只写入 `watcherObservedAt`，不能冒充 `indexObservedAt`。只有服务可达、watcher 已
+启用且权威 `pendingFileCount=0` 时为 `CURRENT`。不要在 sync 内执行全量索引。
 
 ## 6. Instruction graph
 

package/harness/bundles/general/codex/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -72,11 +72,17 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 动态数据库/Redis/令牌字段必须先由 `harness_environment.py prepare` 生成 secret-free receipt，再用 `exec --environment-receipt <file> --required-environment-field <NAME>` 闭包注入；缺失或指纹变化在启动测试前返回 `VERIFICATION_ENVIRONMENT_INCOMPLETE`。复杂 JSON、Docker template 或含引号参数不得跨多层 `-Command` 传递，改用 `exec --argv-file <utf8-json> --runtime-receipt <file>`；参数文件记录 PowerShell edition/version，运行回执只存 argv hash。`harness_service.py ensure` 属于正式持久服务模式，禁止从 bounded runner 内启动；命中时返回 `PERSISTENT_SERVICE_MODE_REQUIRED`。
 
+预计超过交互窗口的正式验证使用 `harness_runtime.py run-start`，随后通过
+`run-status` / `run-log --cursor` 重连；不得把调用方存活当作验证存活条件。环境 acquire
+必须显式选择 `change-session`（同 change + 内容指纹复用）或 `ephemeral`（每次重置）。
+验证 DAG 的并行度由 `resourceLocks` 决定，未分类重任务默认串行。完整合同见
+`../protocols/execution-session-protocol.md`。
+
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 
 先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
 
-验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时改为 `--to-phase run` 并由 context 失效受影响 target。
+验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再 `--to-phase run` 并由 context 失效受影响 target。
 
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续

package/harness/bundles/general/codex/protocols/execution-session-protocol.md

@@ -0,0 +1,52 @@
+---
+description: 长时命令、验证调度、环境复用与 fixback 的可恢复执行协议。
+---
+
+# Execution Session Protocol
+
+## 受管运行会话
+
+可能超过交互窗口的命令必须通过 `harness_runtime.py run-start` 创建受管会话，而不是依赖调用方进程持续在线。会话状态位于：
+
+```text
+runtime/run-sessions/<session-id>/
+├── session.json
+├── stdout.log
+├── stderr.log
+└── worker.log
+```
+
+`session.json` 只持久化脱敏身份：命令哈希、环境哈希、产品身份、验证目标、阶段、资源锁、进程身份、心跳、进度、超时和原因码。原始环境变量和敏感 argv 不得写入回执。
+
+- `run-status` 可由新进程重连；心跳丢失超过 grace period 才标记 `INCOMPLETE`。
+- `run-log --cursor` 按字节游标增量读取 UTF-8 日志，返回下一游标。
+- `run-cancel` 只终止身份完全匹配的进程树；身份不确定时 fail closed。
+- launcher 尚未启动子进程时失败，状态为 `INCOMPLETE/LAUNCHER_FAILED`；子进程非零退出为 `FAIL/CHILD_EXIT_NONZERO`；超时为 `CANCELLED/TIMEOUT`。
+- `resourceLocks` 通过 `runtime/resource-locks/<lock-hash>.json` 原子独占；冲突会在启动测试进程前返回 `INCOMPLETE/RESOURCE_LOCK_BUSY`，终态写入前必须释放持有的锁。
+- Windows 使用 shell-free argv 和 kill-on-close Job Object；Job Object 绑定失败时必须终止已验证的子进程并返回 `PROCESS_TREE_ISOLATION_UNAVAILABLE`，不得降级为无隔离运行。
+
+## 验证调度
+
+`harness_verification.py plan` 对验证 DAG 做拓扑调度。每个目标声明 `dependsOn`、`resourceLocks`、identity 与复用策略。
+
+- 只有资源锁不相交的 ready 目标可进入同一 wave。
+- 未声明资源锁且预计大于等于 60 秒的目标自动使用 `harness:unclassified-heavy`，因此默认串行。
+- 冻结后的产品 identity 发生变化时返回 `FROZEN_IDENTITY_DRIFT`，禁止继续执行或复用。
+- 复用和跳过必须记录 `decision`、`reasonCode` 与人类可读 `explanation`；无证据不得返回 `REUSE`。
+
+## 环境会话
+
+环境租约支持两种模式：
+
+- `change-session`：同一 change、stack、内容指纹和通过的 canary 可复用。
+- `ephemeral`：每次 acquire 都创建新 session；替换既有 session 前必须提供匹配 stack/environment identity 的 provider reset 回执。
+
+租约获取通过注册锁原子串行化，跨 change 的 writable volume 永不共享。`change-session` 只有在内容指纹非空、environment hash、owner identity、expiry、mode、volume 和 canary 全部匹配时才可复用。内容指纹漂移标记 `STALE_CONTENT`；过期租约不可写。prepare/reuse 写入事实回执；reset/cleanup 只有在 provider operation evidence 为 `OK` 时才可如此命名。单纯释放租约只能记录 `release`，不得声称已清理外部环境。回执写入 change 的 `runtime/environment-receipts/`，文件名使用 stack hash，且不包含凭据明文。
+
+## Fixback 批次
+
+Review/Test 回灌通过 `harness_fixback.py` 形成批次。一个批次可包含多条相关问题，但每条问题必须保留可读取的 JSON RED/GREEN 证据。证据必须位于项目或 change state 内，包含 evidence id、状态和产品 identity，并在批次中固定 SHA-256；RED 必须为 `FAIL`，GREEN 必须为 `PASS/OK`。affected verification 与 review 回执必须绑定最终产品 identity，其 `passedGates` 合集覆盖风险扩展后的全部门禁。`freeze-readiness` 会重新校验证据摘要；开放问题、证据漂移或缺门禁均阻止 code freeze。
+
+## 效率摘要
+
+`harness_efficiency.py summary` 从运行会话、环境回执和失效回执生成事实型指标：墙钟区间并集、累计活动/资源等待、execution/launcher/verification 尝试、失败分类、环境 prepare/reuse/reset/cleanup、重复且没有新 result digest 的命令和人工 wrapper 数。reset/cleanup 只统计带有效 provider evidence 的回执。归档摘要自动包含该结构；指标不得归责个人，也不得在历史样本不足时虚构 ETA。

package/harness/bundles/general/codex/protocols/state-layout-protocol.md

@@ -60,7 +60,14 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 ├── sqls/
 ├── scripts/
 ├── runtime/
-│   └── service-session.json
+│   ├── service-session.json
+│   ├── run-sessions/<session-id>/
+│   │   ├── session.json
+│   │   ├── stdout.log
+│   │   └── stderr.log
+│   ├── environment-receipts/
+│   ├── invalidations/
+│   └── fixback/batches/
 └── backups/
     └── uncommitted-tests/
 ```
@@ -73,6 +80,10 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 
 `build-profile.json` 的 `serviceStart.inputFiles`（glob 列表，相对 project 展开）是 `moduleInputsHash` 的来源。`harness_service.py ensure` 取 CLI `--files` ∪ `serviceStart.inputFiles` 计算依赖闭包；**空输入被拒绝**（exit 非 0），**不得生成可复用的空指纹**。通用项目 detect 无法猜 module 源，`inputFiles` 默认空数组，须人工配置。
 
+过期的 service session 只有在进程身份明确不匹配时才允许由 `retire-stale` 移入
+`runtime/retired-service-sessions/`；该动作保留原始回执且不终止进程。受管命令、
+环境会话和 fixback 的完整合同见 `execution-session-protocol.md`。
+
 ## knowledge maintenance-outbox（§8）
 
 归档 close 不再同步执行知识维护；它写一个 pending outbox 项即返回：
@@ -179,3 +190,15 @@ Harness skill 读取的项目级配置（不提交 git）。缺失时使用下
 | `knowledge.manualReview` | boolean | `false` | `true` 时 knowledge-ingest promote 等高价值操作需人工确认；`false` 时按 skill 默认策略 |
 
 读取顺序：`.harness/config/harness.json` → 缺失则默认值。plan 阶段 5 设计审批包须读取 `defaultWorktree` 作为 worktree 选项的推荐值。
+
+## 可恢复文件事务
+
+schema v3 事务在本地 `transactions/<transaction-id>/` 保存 journal、before snapshot、staged payload、after manifest 和小型 status 投影。journal 固定 project identity、执行器版本、目标 Bundle identity、ownership manifest hash、plan hash 与 snapshot digest。
+
+未完成事务同时镜像到用户级恢复根：
+
+```text
+${HUNTER_HARNESS_RECOVERY_ROOT:-~/.hunter-harness/recovery}/<project-path-hash>/transactions/<transaction-id>/
+```
+
+因此项目内 `.harness` 局部丢失后，`status` 仍可只读发现恢复项。`resume` 仅在 plan/snapshot/staged digest 与已完成操作的当前文件状态全部匹配时继续 pending operations；任一不匹配均 fail closed。`rollback` 在写回 before snapshot 前重新校验 snapshot digest。事务提交或回滚成功后删除用户级镜像；本地 committed 事务仍按保留策略提供显式回滚。

package/harness/bundles/general/codex/protocols/verification-graph-protocol.md

@@ -11,6 +11,9 @@ Build Profile v3 用 `verificationGraph` 取代账本内的固定验证目标清
 - `requiredCoverage`：`incremental/module-am/module`；
 - `candidate`：是否为发布候选门禁；
 - `requiredCapabilities`：执行环境必须具备的能力。
+- `resourceLocks`：目标独占或共享的数据库、端口、浏览器、容器等资源身份；
+- `estimatedDurationSeconds`：供默认串行策略和进度显示使用，不作为虚构 ETA 的依据；
+- `reusePolicy`：允许复用时必须匹配的产品、环境、命令与覆盖身份。
 
 `candidateTarget` 必须引用已声明目标。未知目标、未知依赖、循环依赖、命令缺失都 fail closed。
 
@@ -22,5 +25,8 @@ Build Profile v3 用 `verificationGraph` 取代账本内的固定验证目标清
 4. 未进入闭包的目标是 `omitted`，与“执行失败”或“因能力阻断”分开报告。
 5. 账本记录目标定义的规范化 identity；依赖、覆盖度或能力声明变化后，旧证据必须失效。
 6. 候选目标即使自身命令可运行，也必须等待所有依赖和能力满足。
+7. ready 目标按 `resourceLocks` 分 wave；锁相交的目标不得并行。预计 ≥60 秒且未声明锁的目标默认归入 `harness:unclassified-heavy` 串行队列。
+8. code freeze 后产品 identity 漂移必须返回 `FROZEN_IDENTITY_DRIFT`；禁止在旧候选上补跑后声称覆盖新候选。
+9. 每个 `RUN / REUSE / SKIP / BLOCKED` 决策都必须带稳定 `reasonCode` 和解释；`REUSE` 还必须绑定现有证据 identity。
 
 JSON 合同见 `contracts/build-profile-v3.schema.json`；通用选择器为 `@hunter-harness/core` 的 `selectVerificationTargets`。

package/harness/bundles/general/codex/scripts/harness_archive.py

@@ -70,6 +70,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_events as he  # noqa: E402
+import harness_efficiency as heff  # noqa: E402
 import harness_gate as hgate  # noqa: E402
 import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
@@ -3890,12 +3891,15 @@ def collect_summary_data(
             "retention",
             "archiveDurability",
             "remoteCost",
+            "efficiency",
             "projection",
         ):
             if key in existing:
                 data[key] = _deepcopy_json(existing[key])
     if not for_replay or not isinstance(data.get("remoteCost"), dict):
         data["remoteCost"] = remote_cost
+    if not for_replay or not isinstance(data.get("efficiency"), dict):
+        data["efficiency"] = heff.collect_efficiency_summary(change_dir)
 
     event_summary = he.build_summary(change_dir, events) if events else {
         "ok": True,