@hunter-harness/workflow-harness 0.2.16 → 0.2.17

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

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=10114ac730b539b5; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d2eb65d744fddce3; overlay=none; agent=cursor; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -39,6 +39,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol
 
 ## Workflow
 
@@ -87,6 +88,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
 - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+> 片段：p0-trust
 
 ## 关键规则（硬门禁速查）
 
@@ -126,11 +128,11 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 ### 六、服务启动 + 生命周期管理
 
-启动等待状态机：0–30s 每 2s 探测、30–120s 每 5s 探测、>120s 读日志判定；遇启动失败特征立即停。**Service Gate**：`harness_service.py ensure` 返回 `action=needs-user-decision`（用户自启服务占端口）时 **才** AskUserQuestion；AI 托管服务或端口空闲则自动继续，不询问。服务指纹（`moduleInputsHash`，来自 CLI `--files` ∪ `serviceStart.inputFiles`）+ `startCommandHash` + `profile` + `overlayPath` + 进程身份任一变化即 restart；**空输入被拒绝**，不生成可复用空指纹。测试结束默认清理 AI 启动的服务。详见 `reference.md`「服务决策门」。
+启动等待状态机：0–30s 每 2s 探测、30–120s 每 5s 探测、>120s 读日志判定；遇启动失败特征立即停。**Service Gate**：`harness_service.py ensure` 返回 `action=needs-user-decision`（用户自启服务占端口）时 **才** blocking user confirmation；AI 托管服务或端口空闲则自动继续，不询问。服务指纹（`moduleInputsHash`，来自 CLI `--files` ∪ `serviceStart.inputFiles`）+ `startCommandHash` + `profile` + `overlayPath` + 进程身份任一变化即 restart；**空输入被拒绝**，不生成可复用空指纹。测试结束默认清理 AI 启动的服务。详见 `reference.md`「服务决策门」。
 
 ### 七、运行时配置叠加（不动 tracked 配置）
 
-禁止默认 Edit tracked 应用配置文件。默认运行时配置叠加（ASCII 绝对路径）；改 tracked 配置 → 默认拒绝，记 `decision` 事件（不 AskUserQuestion，报告 🟡 WARN）。详见 `reference.md`。
+禁止默认 Edit tracked 应用配置文件。默认运行时配置叠加（ASCII 绝对路径）；改 tracked 配置 → 默认拒绝，记 `decision` 事件（不 blocking user confirmation，报告 🟡 WARN）。详见 `reference.md`。
 
 ### 八、Token 缓存与复用
 
@@ -162,7 +164,7 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 ## 交互白名单
 
-本 skill **仅允许**以下 AskUserQuestion；其余默认值 + `decision` 事件：
+本 skill **仅允许**以下 blocking user confirmation；其余默认值 + `decision` 事件：
 
 1. **Service Gate**：仅当 `harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时询问处理方式
 
@@ -179,3 +181,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
 
 每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`test` · 事件：phase/command/verification/decision/issue/artifact

package/harness/bundles/general/cursor/harness-test/checklist.md

@@ -276,7 +276,7 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] **只有首选执行器不可执行才降级**：PowerShell batch (.ps1) → 多次 MCP `browser_evaluate` → curl
 - [ ] **如果执行器在 PowerShell 可用，禁止使用 Playwright MCP 逐条执行接口测试**
 - [ ] 执行器直连本地 baseURL，复用认证凭证，不依赖浏览器 origin
-- [ ] 记录每个请求的 durationMs、status、code、message、assertionResult
+- [ ] 记录每个请求的 requestDurationMs、status、code、message、assertionResult
 - [ ] 支持失败时继续执行后续非依赖场景
 - [ ] 报告区分四种执行器：**接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl**（不得与"Playwright"混写）
 
@@ -287,11 +287,14 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] 测试结束后清理可清理的数据
 - [ ] 不能清理的记录遗留数据和原因
 
-### 请求耗时
+### 请求耗时（§5.22 分层耗时）
 
-- [ ] 每个请求记录 durationMs
-- [ ] durationMs > 10000 → 🟡SLOW，说明原因
-- [ ] durationMs > 30000 → ❌TIMEOUT_RISK，说明原因
+- [ ] 每个请求记录 requestDurationMs（单 HTTP 请求耗时）
+- [ ] 整个批次记录 batchDurationMs（runner wall-clock）
+- [ ] requestDurationMs > 10000 → 🟡SLOW，说明原因
+- [ ] requestDurationMs > 30000 → ❌TIMEOUT_RISK，说明原因
+- [ ] batchDurationMs > 180000 → 🟡BATCH_SLOW
+- [ ] 聚合合同套件场景只记录 batch reference + coveredTests，**禁止均摊生成伪 requestDurationMs**
 
 ### 覆盖标注诚实性（✅ 实测 vs 🟡 推断）
 

package/harness/bundles/general/cursor/harness-test/pitfalls.md

@@ -191,7 +191,7 @@ $cred = $resp.data.accessToken
 **严重度**：🟡WARN
 **场景**：测试期间为了切换外部服务配置直接 Edit tracked 配置文件（如 `application-local-dev.yml`），测试后再还原，留下 diff 噪声
 **后果**：git diff --stat 出现意外文件、提交风险、误以为有业务变更
-**正确做法**：生成运行时配置叠加 `.harness/changes/<change>/runtime/application-harness-test.yml`（不提交），启动用 `-Dspring.config.additional-location=file:...` 叠加（按技术栈）；如必须改 tracked 配置，先 AskUserQuestion，最终报告至少 🟡 WARN
+**正确做法**：生成运行时配置叠加 `.harness/changes/<change>/runtime/application-harness-test.yml`（不提交），启动用 `-Dspring.config.additional-location=file:...` 叠加（按技术栈）；如必须改 tracked 配置，先 blocking user confirmation，最终报告至少 🟡 WARN
 
 ### 规则 22：唯一约束字段与本地预存数据冲突
 **严重度**：❌FAIL

package/harness/bundles/general/cursor/harness-test/reference.md

@@ -150,7 +150,7 @@ spring:
 powershell.exe -NoProfile -Command "mvn spring-boot:run -pl <module> -Dspring-boot.run.profiles=<profile> -Dspring-boot.run.jvmArguments='-Dspring.config.additional-location=file:C:/temp/harness-test-overlay/<change-name>/application-harness-test.yml'"
 ```
 
-不得默认使用 `.harness/changes/<change>/runtime/application-harness-test.yml` 相对路径作为 JVM `additional-location`。如必须修改 tracked 配置文件，先 AskUserQuestion，最终报告至少 🟡 WARN。
+不得默认使用 `.harness/changes/<change>/runtime/application-harness-test.yml` 相对路径作为 JVM `additional-location`。如必须修改 tracked 配置文件，先 blocking user confirmation，最终报告至少 🟡 WARN。
 
 ## 服务决策门（Service Decision Gate）与服务生命周期管理
 
@@ -361,11 +361,13 @@ async function cleanup(token) {
 
 // ===== 主流程 =====
 const token = await resolveCredential('admin');
+const batchStart = Date.now();
 await setup(token);
 for (const scenario of scenarios) {
   await runOne(scenario, token);
 }
 const cleanupResult = await cleanup(token);
+const batchDurationMs = Date.now() - batchStart;
 
 const summary = {
   runner: 'api-test-executor',
@@ -377,7 +379,11 @@ const summary = {
   setupErrors: setupState.errors,
   cleanupResult,
   credentialRefreshCount,
-  startedAt: '<ISO>', finishedAt: '<ISO>', durationMs: 0
+  // §5.22: 分层耗时 schema — batchDurationMs 是整个 runner wall-clock；
+  // 每个场景的 requestDurationMs 是单 HTTP 请求耗时。聚合合同套件场景
+  // 只记录 batch reference/coveredTests，不允许均摊生成伪请求耗时。
+  batchDurationMs,
+  startedAt: '<ISO>', finishedAt: '<ISO>'
 };
 writeFileSync(RESULTS_FILE, JSON.stringify({ results, summary }, null, 2));
 console.log(`\n结果已写入 ${RESULTS_FILE}`);
@@ -389,6 +395,7 @@ console.log(`\n结果已写入 ${RESULTS_FILE}`);
 > - 凭证从本地 cache 读 + 本地轻量接口验证，**完全不依赖浏览器当前页面 origin**
 > - 同一次执行内 `credentialRefreshCount` 不得 > 1
 > - payload 从数据契约/接口定义/真实样例生成，并在脚本注释中标注字段来源
+> - **§5.22 分层耗时**：`batchDurationMs` 是 runner wall-clock（整个批次耗时），`requestDurationMs` 是单 HTTP 请求耗时。聚合合同套件场景（如 API-C01~C04 共享同一 pytest 批次）只记录 `batchReference` + `coveredTests`，**禁止用 `batchDurationMs / N` 均摊生成伪 `requestDurationMs`**
 
 ### 执行器降级方案（PowerShell batch runner .ps1）
 
@@ -445,18 +452,20 @@ $results | ConvertTo-Json -Depth 4
 | 接口测试执行器（普通） | 30s | **60s** | 抛错继续报告，不再重试 |
 | 接口测试执行器（复杂场景） | 60s | **120s** | 同上 |
 | 凭证获取（认证服务） | 5–10s | **15s** | 计 1 次重取；超过 1 次 → 🟡 WARN |
-| 单个 HTTP GET | < 1s | **8s** | durationMs > 10s → 🟡 SLOW |
-| 单个 HTTP POST/PUT | < 2s | **10s** | durationMs > 10s → 🟡 SLOW |
+| 单个 HTTP GET | < 1s | **8s** | requestDurationMs > 10s → 🟡 SLOW |
+| 单个 HTTP POST/PUT | < 2s | **10s** | requestDurationMs > 10s → 🟡 SLOW |
 | health probe | < 1s | **3s** | 计入启动状态机 |
 | 构建工具编译（如 Maven compile） | 10–60s | **180s** | 输出最后 30 行日志后停 |
 | 测试命令（如 Maven test） | 60–180s | **300s** | 输出失败用例后停 |
 | service start | 30–60s | **120s** | 4.1 启动状态机收敛 |
 
-**反馈规则**：
+**§5.22 分层耗时与反馈规则**：
 - 等待 > 10s 必须输出一次状态行（启动等待、执行器、构建工具均适用）
 - 不得静默等待
-- `durationMs > 10000` → 🟡 SLOW
-- `durationMs > 30000` → ❌ TIMEOUT_RISK
+- **`requestDurationMs`**（单 HTTP 请求耗时）：`> 10000` → 🟡 SLOW；`> 30000` → ❌ TIMEOUT_RISK
+- **`batchDurationMs`**（runner wall-clock，整个批次耗时）：`> 180000`（3 分钟）→ 🟡 BATCH_SLOW；`> 300000`（5 分钟）→ ❌ BATCH_TIMEOUT_RISK
+- **聚合合同套件场景**（如 API-C01~C04 共享同一 pytest 批次）：只记录 `batchReference` + `coveredTests`，**禁止用 `batchDurationMs / N` 均摊生成伪 `requestDurationMs`**
+- 报告必须明确标注是哪一层越界（batch-level 还是 request-level），不得混用
 - 请求慢不得忽略，必须说明是服务、网络、认证还是工具调用开销
 
 ## 认证凭证缓存与复用
@@ -638,17 +647,23 @@ TEST_<change-name>_<timestamp>_<short-random>
 | cleanup | cleaned=X / leftover=Y | 接口 /<resource> 不支持删除，2 条遗留 |
 
 ### 接口测试
-| # | 场景 | 方法 | URL | 预期 | 实际 | durationMs | 状态 |
+| # | 场景 | 方法 | URL | 预期 | 实际 | requestDurationMs | 状态 |
 |:--:|------|:----:|-----|------|------|----------:|:--:|
 | API-001 | 创建资源 | POST | /api/xxx | 200, code=0 | 200, code=0 | 245 | ✅ PASS |
 | API-002 | 参数校验 | POST | /api/xxx | code=xxx | code=xxx | 180 | ✅ PASS |
 | API-003 | 查询子规则 | GET | /api/xxx/{id} | 200 | — | — | 🟡 BLOCKED（setup.createRule 失败） |
 
-### 请求耗时统计
-| 场景 | 方法 | URL | durationMs | 状态 |
-|------|:----:|-----|----------:|:----:|
-| API-001 | POST | /api/xxx | 245 | ✅ |
-| API-010 | GET | /api/yyy | 12450 | 🟡SLOW |
+### 请求耗时统计（§5.22 分层耗时）
+| 层级 | 场景/批次 | 方法 | URL | 耗时 | 状态 |
+|------|----------|:----:|-----|----:|:----:|
+| request | API-001 | POST | /api/xxx | 245ms | ✅ |
+| request | API-010 | GET | /api/yyy | 12450ms | 🟡SLOW |
+| batch | pytest-batch-1 | — | — | 158000ms | 🟡BATCH_SLOW |
+
+> **§5.22 分层耗时说明**：
+> - `request` 层级记录单 HTTP 请求耗时（`requestDurationMs`）
+> - `batch` 层级记录 runner wall-clock（`batchDurationMs`），整个 pytest 批次耗时
+> - 聚合合同套件场景（如 API-C01~C04 共享同一批次）只记录一行 `batch` 条目 + `coveredTests` 列表，**不得均摊为 4 个伪 `request` 条目**
 
 ### 数据兼容
 | # | 场景 | 预期 | 实际 | 结果 |

package/harness/bundles/general/cursor/protocols/submit-protocol.md

@@ -1,5 +1,5 @@
 ---
-description: harness-submit 的确定性提交协议。用于避免 AskUserQuestion 参数错误、中文 commit message 失败、Co-Authored-By 违规和先 commit 后 amend。
+description: harness-submit 的确定性提交协议。用于避免 blocking user confirmation 参数错误、中文 commit message 失败、Co-Authored-By 违规和先 commit 后 amend。
 ---
 
 # Submit Protocol

package/harness/bundles/general/cursor/scripts/harness_deploy.py

@@ -26,6 +26,10 @@ if hasattr(sys.stderr, "reconfigure"):
     sys.stderr.reconfigure(encoding="utf-8")
 
 INCLUDE_RE = re.compile(r"<!--\s*@include\s+shared/([^\s]+)\s*-->")
+# retro §5.17: wiki links [[shared/xxx.md|alias]] reference shared fragments
+# that are inlined by expand_includes. After expansion, replace the wiki link
+# with the alias text (the shared content is already in the document).
+WIKI_LINK_RE = re.compile(r"\[\[shared/([^\]|]+)\|([^\]]*)\]\]")
 # §7.5: overlay anchors support both new section-id and legacy section:"title".
 OVERRIDE_RE = re.compile(r'<!--\s*@override\s+(?:section-id:"([^"]+)"|section:"([^"]+)")\s*-->')
 APPEND_RE = re.compile(r'<!--\s*@append-after\s+(?:section-id:"([^"]+)"|section:"([^"]+)")\s*-->')
@@ -148,6 +152,9 @@ def expand_includes(text: str, shared_dir: Path) -> str:
         return body
 
     expanded = INCLUDE_RE.sub(repl, text)
+    # §5.17: replace [[shared/xxx.md|alias]] wiki links with the alias text,
+    # since the shared content has been inlined by @include expansion above.
+    expanded = WIKI_LINK_RE.sub(lambda m: m.group(2), expanded)
     lines = [ln for ln in expanded.splitlines() if not FRAGMENT_HINT_RE.match(ln)]
     return "\n".join(lines) + ("\n" if text.endswith("\n") else "")
 

package/harness/bundles/general/cursor/scripts/harness_integration.py

@@ -1049,10 +1049,11 @@ class IntegrationTransaction:
                     heavy_removed.append(name)
                 except OSError as exc:
                     heavy_failures.append({"path": name, "error": str(exc)})
-        self.runner.run(
+        remove_result = self.runner.run(
             self.project_root, "worktree", "remove", "--force", str(resolved),
             check=False,
         )
+        remove_returncode = getattr(remove_result, "returncode", 0)
         listed = self.runner.text(self.project_root, "worktree", "list", "--porcelain")
         registered_after = {
             str(Path(line.removeprefix("worktree ")).resolve())
@@ -1061,7 +1062,8 @@ class IntegrationTransaction:
         }
         still_registered = str(resolved) in registered_after
         residual_paths: list[str] = []
-        if resolved.exists():
+        disk_path_present = resolved.exists()
+        if disk_path_present:
             if resolved.is_file():
                 residual_paths.append(resolved.name)
             else:
@@ -1075,6 +1077,27 @@ class IntegrationTransaction:
                             break
                     if len(residual_paths) >= 200:
                         break
+        # §5.30: Windows half-success — git worktree remove returned non-zero
+        # but registration is already deleted and disk path remains. Return a
+        # structured status distinct from generic CLEANUP_RESIDUAL so callers
+        # can apply the allowlisted residual cleaner.
+        if (
+            remove_returncode != 0
+            and not still_registered
+            and disk_path_present
+            and residual_paths
+            and not heavy_failures
+        ):
+            return {
+                "ok": False,
+                "code": "REGISTRATION_REMOVED_RESIDUAL_PRESENT",
+                "target": str(resolved),
+                "heavyRootsRemoved": heavy_removed,
+                "heavyRootFailures": heavy_failures,
+                "worktreeRegistered": False,
+                "diskPathPresent": True,
+                "residualPaths": residual_paths,
+            }
         ok = not heavy_failures and not still_registered and not residual_paths
         return {
             "ok": ok,
@@ -1083,6 +1106,7 @@ class IntegrationTransaction:
             "heavyRootsRemoved": heavy_removed,
             "heavyRootFailures": heavy_failures,
             "worktreeRegistered": still_registered,
+            "diskPathPresent": disk_path_present,
             "residualPaths": residual_paths,
         }
 

package/harness/bundles/general/cursor/scripts/harness_plan_finalize.py

@@ -300,6 +300,152 @@ def _terminal_exists(change_dir: Path, run_id: str, attempt: int) -> bool:
     )
 
 
+def verify_plan(change_dir: Path) -> dict[str, Any]:
+    """Read-only verification of a finalized plan (retro §5.8).
+
+    Validates the published artifacts, receipt and events stream without
+    requiring the original staging directory. Returns the artifact hash,
+    phase.end count/status, frontmatter, and consistency checks. Any parse
+    error or inconsistency results in ok=false with a non-zero exit code.
+    """
+    change_dir = change_dir.resolve()
+    receipt_path = change_dir / "meta" / "plan-finalization.json"
+    if not receipt_path.is_file():
+        return _result_error("RECEIPT_MISSING", f"receipt not found: {receipt_path}")
+
+    try:
+        receipt = json.loads(receipt_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("RECEIPT_INVALID", str(exc))
+    if not isinstance(receipt, dict):
+        return _result_error("RECEIPT_INVALID", "receipt top-level must be an object")
+
+    change_name = str(receipt.get("changeName") or "").strip()
+    if not change_name:
+        return _result_error("RECEIPT_INVALID", "receipt missing changeName")
+
+    expected_hash = str(receipt.get("artifactsHash") or "").strip()
+    if not expected_hash.startswith("sha256:"):
+        return _result_error("RECEIPT_INVALID", "receipt artifactsHash missing or malformed")
+
+    files_list = receipt.get("files")
+    if not isinstance(files_list, list) or not files_list:
+        return _result_error("RECEIPT_INVALID", "receipt files list missing or empty")
+
+    # Recompute artifacts hash from published files.
+    digest = hashlib.sha256()
+    artifact_names: list[str] = []
+    for rel_text in files_list:
+        rel = rel_text.as_posix() if hasattr(rel_text, "as_posix") else str(rel_text)
+        target = change_dir / rel
+        if not target.is_file():
+            return _result_error(
+                "ARTIFACT_MISSING", f"published artifact missing: {rel}"
+            )
+        artifact_names.append(rel)
+        digest.update(rel.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(target.read_bytes())
+        digest.update(b"\0")
+    actual_hash = "sha256:" + digest.hexdigest()
+    if actual_hash != expected_hash:
+        return _result_error(
+            "ARTIFACT_HASH_DRIFT",
+            f"published artifacts hash {actual_hash} != receipt {expected_hash}",
+        )
+
+    # Validate frontmatter on markdown artifacts.
+    frontmatter_results: dict[str, Any] = {}
+    for rel in artifact_names:
+        if not rel.endswith(".md"):
+            continue
+        target = change_dir / rel
+        try:
+            text = target.read_text(encoding="utf-8-sig")
+        except OSError as exc:
+            return _result_error("ARTIFACT_UNREADABLE", f"{rel}: {exc}")
+        fm = _frontmatter(text)
+        if fm is None:
+            return _result_error(
+                "ARTIFACT_FRONTMATTER_MISSING", f"{rel}: no frontmatter"
+            )
+        if fm.get("change-name") != change_name:
+            return _result_error(
+                "ARTIFACT_FRONTMATTER_INVALID",
+                f"{rel}: change-name '{fm.get('change-name')}' != '{change_name}'",
+            )
+        frontmatter_results[rel] = {
+            "change-name": fm.get("change-name"),
+            "status": fm.get("status"),
+        }
+
+    # Validate gate-policy.json is parseable JSON.
+    gate_policy_path = change_dir / "meta" / "gate-policy.json"
+    gate_policy_consistent = True
+    if gate_policy_path.is_file():
+        try:
+            json.loads(gate_policy_path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            gate_policy_consistent = False
+    else:
+        gate_policy_consistent = False
+
+    # Validate events.ndjson: count phase.end, check for parse errors.
+    events_path = change_dir / "events.ndjson"
+    phase_end_count = 0
+    phase_end_status: str | None = None
+    events_parse_errors: list[str] = []
+    if events_path.is_file():
+        for line_no, line in enumerate(events_path.read_text(encoding="utf-8").splitlines(), 1):
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError as exc:
+                events_parse_errors.append(f"line {line_no}: {exc}")
+                continue
+            if not isinstance(event, dict):
+                events_parse_errors.append(f"line {line_no}: not an object")
+                continue
+            if (
+                event.get("phase") == "plan"
+                and event.get("type") == "phase.end"
+            ):
+                phase_end_count += 1
+                phase_end_status = str(event.get("status") or "").upper()
+    else:
+        events_parse_errors.append("events.ndjson missing")
+
+    if events_parse_errors:
+        return _result_error(
+            "EVENTS_PARSE_ERROR", "; ".join(events_parse_errors[:5])
+        )
+
+    if phase_end_count == 0:
+        return _result_error("PHASE_END_MISSING", "no plan phase.end event found")
+    if phase_end_count > 1:
+        return _result_error(
+            "PHASE_END_DUPLICATE", f"found {phase_end_count} phase.end events"
+        )
+
+    # Receipt consistency: status should be finalized.
+    receipt_consistent = receipt.get("status") == "finalized"
+
+    return {
+        "ok": True,
+        "action": "verify",
+        "changeDir": str(change_dir),
+        "changeName": change_name,
+        "artifactsHash": actual_hash,
+        "phaseEndCount": phase_end_count,
+        "phaseEndStatus": phase_end_status,
+        "frontmatter": frontmatter_results,
+        "gatePolicyConsistent": gate_policy_consistent,
+        "receiptConsistent": receipt_consistent,
+        "files": artifact_names,
+    }
+
+
 def _read_design_capabilities(staging: Path, change_name: str) -> list[str]:
     """Read capabilities from design frontmatter (retro §5.4)."""
     design_path = staging / "spec" / f"{change_name}-design.md"
@@ -569,18 +715,24 @@ def build_parser() -> argparse.ArgumentParser:
     finalize.add_argument("--run-id", required=True)
     finalize.add_argument("--attempt", required=True, type=int)
     finalize.add_argument("--json", action="store_true")
+    verify = sub.add_parser("verify")
+    verify.add_argument("--change-dir", required=True)
+    verify.add_argument("--json", action="store_true")
     return parser
 
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
-    result = finalize_plan(
-        Path(args.change_dir),
-        Path(args.staging_dir),
-        change_name=args.change,
-        run_id=args.run_id,
-        attempt=args.attempt,
-    )
+    if args.command == "verify":
+        result = verify_plan(Path(args.change_dir))
+    else:
+        result = finalize_plan(
+            Path(args.change_dir),
+            Path(args.staging_dir),
+            change_name=args.change,
+            run_id=args.run_id,
+            attempt=args.attempt,
+        )
     stream = sys.stdout if result["ok"] else sys.stderr
     if args.json:
         stream.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")

package/harness/bundles/general/cursor/scripts/harness_test_cleanup.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Controlled cleanup helper for test fixtures (retro §5.23).
+
+Provides a host-policy-friendly entry point for removing gitignored test
+fixtures (e.g. .pytest_data) within an execution root. Performs realpath
+containment, rejects symlink/reparse escapes, lists exact counts before
+deletion, and outputs a structured receipt.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+def _resolve_within(execution_root: Path, rel: str) -> Path | None:
+    """Resolve rel under execution_root, rejecting escapes and symlinks."""
+    if not rel or rel.startswith("/"):
+        return None
+    # Reject absolute paths (Windows drive letter or POSIX).
+    if len(rel) >= 2 and rel[1] == ":":
+        return None
+    parts = rel.replace("\\", "/").split("/")
+    if ".." in parts:
+        return None
+    candidate = (execution_root / rel).resolve(strict=False)
+    # Containment check: candidate must be under execution_root.
+    try:
+        candidate.relative_to(execution_root.resolve(strict=False))
+    except ValueError:
+        return None
+    # Reject symlink/reparse escape: if the path is a symlink, check its target.
+    if candidate.is_symlink():
+        target = Path(os.readlink(candidate)).resolve(strict=False)
+        try:
+            target.relative_to(execution_root.resolve(strict=False))
+        except ValueError:
+            return None
+        # Even if target is inside, a symlinked cleanup root is suspicious;
+        # reject to avoid following links into unexpected locations.
+        return None
+    return candidate
+
+
+def _count_files(root: Path) -> tuple[int, int]:
+    """Count files and total bytes under root."""
+    count = 0
+    total = 0
+    for dirpath, _dirs, files in os.walk(root):
+        for name in files:
+            fp = Path(dirpath) / name
+            try:
+                total += fp.stat().st_size
+                count += 1
+            except OSError:
+                continue
+    return count, total
+
+
+def cleanup(execution_root: Path, cleanup_roots: list[str]) -> dict[str, Any]:
+    """Remove allowlisted cleanup roots within execution_root.
+
+    Returns a structured receipt. Any path escape, symlink escape, or
+    unallowed root results in ok=false with zero files removed.
+    """
+    execution_root = Path(execution_root).resolve(strict=False)
+    if not execution_root.is_dir():
+        return {
+            "ok": False,
+            "code": "EXECUTION_ROOT_MISSING",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+        }
+
+    rejected: list[dict[str, str]] = []
+    removed_files = 0
+    removed_bytes = 0
+    cleaned: list[str] = []
+
+    for rel in cleanup_roots:
+        target = _resolve_within(execution_root, rel)
+        if target is None:
+            rejected.append({"path": rel, "reason": "PATH_ESCAPE_REJECTED"})
+            continue
+        if not target.exists():
+            # Already absent — idempotent reentry.
+            continue
+        # Re-check symlink after resolution (the parent might be a symlink).
+        if target.is_symlink():
+            rejected.append({"path": rel, "reason": "SYMLINK_ESCAPE_REJECTED"})
+            continue
+        # Count before deletion for the receipt.
+        try:
+            count, total = _count_files(target)
+        except OSError:
+            count, total = 0, 0
+        # Delete.
+        try:
+            shutil.rmtree(target)
+        except OSError as exc:
+            rejected.append({"path": rel, "reason": f"DELETE_FAILED: {exc}"})
+            continue
+        removed_files += count
+        removed_bytes += total
+        cleaned.append(rel)
+
+    if rejected:
+        return {
+            "ok": False,
+            "code": rejected[0]["reason"],
+            "executionRoot": str(execution_root),
+            "removedFiles": removed_files,
+            "removedBytes": removed_bytes,
+            "rejectedEscapes": rejected,
+            "cleaned": cleaned,
+        }
+
+    if removed_files == 0 and not cleaned:
+        return {
+            "ok": True,
+            "code": "ALREADY_ABSENT",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+            "cleaned": [],
+        }
+
+    return {
+        "ok": True,
+        "code": "CLEANUP_COMPLETE",
+        "executionRoot": str(execution_root),
+        "removedFiles": removed_files,
+        "removedBytes": removed_bytes,
+        "rejectedEscapes": [],
+        "cleaned": cleaned,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    clean_parser = sub.add_parser("cleanup")
+    clean_parser.add_argument("--execution-root", required=True)
+    clean_parser.add_argument("--cleanup-roots", required=True, help="JSON array of relative paths")
+    clean_parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    try:
+        roots = json.loads(args.cleanup_roots)
+        if not isinstance(roots, list):
+            raise ValueError("cleanup-roots must be a JSON array")
+    except (json.JSONDecodeError, ValueError) as exc:
+        result = {"ok": False, "code": "INVALID_CLEANUP_ROOTS", "error": str(exc)}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 1
+
+    result = cleanup(Path(args.execution_root), roots)
+    print(json.dumps(result, ensure_ascii=False, indent=2 if args.json else None))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/java/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "822ced2e1d949aed"
+  "coreHash": "6e87bc67bd51cbe9"
 }