@hunter-harness/workflow-harness 0.2.82 → 0.2.84

package/harness/bundles/java/codex/scripts/harness_gate.py

@@ -37,6 +37,7 @@ import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
 import harness_plan_finalize as hpf  # noqa: E402
 import harness_review as hr  # noqa: E402
+import harness_runtime as hruntime  # noqa: E402
 import harness_workflow_policy as hwp  # noqa: E402
 import harness_test_guard as htg  # noqa: E402
 
@@ -1906,6 +1907,31 @@ def _latest_phase_end(
     return None
 
 
+def _latest_open_run_id(change_dir: Path, phase: str) -> str | None:
+    """Return the newest ``phase.start`` run_id that has no matching ``phase.end``.
+
+    A long phase can outlive its lease TTL; close then reports ``LEASE_ABSENT``
+    with no way back.  Resuming needs the *original* run_id, so surface it here
+    instead of making the caller reconstruct it from ``events.ndjson``.
+    """
+    started: list[str] = []
+    ended: set[str] = set()
+    for event in he.load_events(he.events_path(change_dir)):
+        if event.get("phase") != phase:
+            continue
+        run_id = str(event.get("run_id") or "")
+        if not run_id:
+            continue
+        if event.get("type") == "phase.start":
+            started.append(run_id)
+        elif event.get("type") == "phase.end":
+            ended.add(run_id)
+    for run_id in reversed(started):
+        if run_id not in ended:
+            return run_id
+    return None
+
+
 def _terminal_matches_context_session(
     project: Path,
     change_id: str,
@@ -2631,11 +2657,42 @@ def cmd_begin(args: argparse.Namespace) -> int:
         ttl_seconds=int(args.ttl_seconds),
     )
     if not claim.get("ok"):
+        claim_code = str(claim.get("code", "LEASE_CONFLICT"))
+        claim_extra = {
+            k: v for k, v in claim.items() if k not in {"ok", "message", "code"}
+        }
+        holder = claim.get("holder")
+        if claim_code == "LEASE_CONFLICT" and isinstance(holder, dict):
+            holder_phase = str(holder.get("phase") or "")
+            holder_run_id = str(holder.get("runId") or "")
+            # A lease whose own phase already recorded phase.end is leftover state:
+            # only close releases the lease, so any begin-without-close strands it
+            # for the full TTL and blocks the next phase.
+            holder_closed = (
+                bool(holder_phase)
+                and bool(holder_run_id)
+                and _latest_phase_end(change_dir, holder_phase, holder_run_id) is not None
+            )
+            claim_extra["holderPhaseClosed"] = holder_closed
+            if holder_closed:
+                claim_extra["recoveryAction"] = (
+                    f"持有租约的 {holder_phase} 阶段（run-id {holder_run_id}）已写入 phase.end，"
+                    "这是残留租约，释放后重试 begin 是安全的："
+                    "python <skills-root>/scripts/harness_change.py release "
+                    f"--change {resolved['changeId']} --phase {holder_phase} "
+                    f"--run-id {holder_run_id} --json"
+                )
+            else:
+                claim_extra["recoveryAction"] = (
+                    f"{holder_phase or '另一个'} 阶段（run-id {holder_run_id or '未知'}）"
+                    "仍在进行中且尚未写入 phase.end。先让该阶段正常关门；"
+                    "确认其执行进程已不存在时才可释放租约，不要直接 --steal。"
+                )
         return emit_error(
-            str(claim.get("code", "LEASE_CONFLICT")),
+            claim_code,
             str(claim.get("message", "lease claim failed")),
             as_json=as_json,
-            extra={k: v for k, v in claim.items() if k not in {"ok", "message", "code"}},
+            extra=claim_extra,
         )
 
     guard_result: dict[str, Any] | None = None
@@ -2843,7 +2900,26 @@ def cmd_close(args: argparse.Namespace) -> int:
                 as_json=as_json,
             )
             return 0
-        return emit_error("LEASE_ABSENT", "no active lease for phase close", as_json=as_json)
+        resume_run_id = explicit_run_id or _latest_open_run_id(change_dir, args.phase)
+        return emit_error(
+            "LEASE_ABSENT",
+            "no active lease for phase close",
+            as_json=as_json,
+            extra={
+                "retryable": True,
+                "phase": args.phase,
+                "changeId": resolved["changeId"],
+                "resumeRunId": resume_run_id,
+                "recoveryAction": (
+                    "阶段租约已过期（TTL 由 begin 的 --ttl-seconds 决定，默认 3600 秒）或已被释放。"
+                    "用本阶段原 run-id 重新取得租约后原样重试 close："
+                    "python <skills-root>/scripts/harness_change.py claim "
+                    f"--change {resolved['changeId']} --phase {args.phase} "
+                    f"--run-id {resume_run_id or '<原 run-id>'} --ttl-seconds 3600 --json"
+                    "。不要重跑 gate begin——那会新开一次 attempt 并丢失本轮 capsule。"
+                ),
+            },
+        )
     run_id = explicit_run_id or str(current_lease.get("runId") or "")
     if str(current_lease.get("runId")) != run_id or str(current_lease.get("phase")) != args.phase:
         return emit_error(
@@ -3260,6 +3336,14 @@ def cmd_close(args: argparse.Namespace) -> int:
         phase=args.phase,
         run_id=run_id,
     )
+    # 关门时清掉本阶段的过程草稿（diff、临时输入、命令输出重定向）。没人清它们，
+    # 而且它们会被别的门禁读到——2026-08-19 那次，review 自己生成的两个 diff
+    # 直接把归档挡住了。白名单式删除，证据/报告/运行态一律不碰；失败只记不阻断。
+    try:
+        scratch_swept = hruntime.sweep_scratch(change_dir)
+    except OSError as exc:
+        scratch_swept = {"ok": False, "code": "SCRATCH_SWEEP_FAILED", "error": str(exc)}
+
     payload = {
         "ok": True,
         "code": close_code,
@@ -3278,6 +3362,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         "contextHandoff": context_handoff,
         "platformMonitor": platform_monitor,
         "gateRecovery": recovery_result,
+        "scratchSwept": scratch_swept,
     }
     emit(payload, as_json=as_json)
     return 0

package/harness/bundles/java/codex/scripts/harness_integration.py

@@ -378,6 +378,121 @@ def _normalize_verify_command(
     return result
 
 
+# 合并态验证的兜底优先级：先跑覆盖面最广的，再退到窄的。profile 里这些命令
+# 本来就是 ledger 一直在用的规范命令，没有理由让调用方在合并时另行手敲一遍。
+MERGE_VERIFICATION_FALLBACK_ORDER = ("unitTestFull", "unitTest", "apiTest", "compile")
+
+
+def verify_plan_recovery_action() -> str:
+    """把 VERIFY_PLAN_MISSING 补成一句能照做的话。
+
+    此前它只说 "requires at least one executable command"。于是调用方要么去读
+    实现，要么随手塞一条命令让门过去——两条路都走过，后者更糟：它让"验证通过"
+    这句话失去含义。
+    """
+    return (
+        "合并态验证没有可执行计划。两条正规出路："
+        "(1) 在 .harness/config/build-profile.json 增加 mergeVerification.requiredOnMerge "
+        "声明合并时必跑的命令（推荐，一次配置长期生效）；"
+        "(2) 本次用 --command 传入。注意 --command 可重复，每次只接**一条**命令，"
+        "且按 argv 直接执行（不经过 shell）——`&&`、`|`、`cd x && y` 都不成立，"
+        "需要拆成多个 --command。"
+        "示例：--command \"npm test\" --command \"npm run lint\"。"
+    )
+
+
+def _fallback_merge_commands(profile: Any) -> list[dict[str, Any]]:
+    """从 profile 已有的验证目标推导合并态计划。"""
+    commands = profile.get("commands") if isinstance(profile, dict) else None
+    if not isinstance(commands, dict):
+        return []
+    for name in MERGE_VERIFICATION_FALLBACK_ORDER:
+        entry = commands.get(name)
+        if not isinstance(entry, dict):
+            continue
+        argv = entry.get("argvTemplate")
+        if isinstance(argv, list) and argv and all(
+            isinstance(item, str) and item for item in argv
+        ):
+            return [{
+                "command": [str(item) for item in argv],
+                "kind": "heavyweight",
+                "verification": name,
+                "source": "profile-fallback",
+                "reuseContext": {},
+            }]
+        raw = entry.get("command")
+        if isinstance(raw, str) and raw.strip():
+            return [{
+                "command": _split_verify_command(raw.strip()),
+                "kind": "heavyweight",
+                "verification": name,
+                "source": "profile-fallback",
+                "reuseContext": {},
+            }]
+    return []
+
+
+def merge_verification_plan(profile: Any) -> list[dict[str, Any]]:
+    """声明优先，推导兜底；两者都没有才返回空计划。"""
+    merge = profile.get("mergeVerification") if isinstance(profile, dict) else None
+    required = merge.get("requiredOnMerge") if isinstance(merge, dict) else None
+    if isinstance(required, list) and required:
+        plan: list[dict[str, Any]] = []
+        for index, item in enumerate(required):
+            if isinstance(item, str) and item.strip():
+                plan.append({
+                    "command": _split_verify_command(item.strip()),
+                    "kind": "smoke",
+                    "verification": None,
+                    "source": "profile",
+                    "reuseContext": {},
+                })
+                continue
+            if not isinstance(item, dict):
+                raise ValueError(f"requiredOnMerge[{index}] must be string or object")
+            raw = item.get("command")
+            if isinstance(raw, list) and raw and all(
+                isinstance(value, str) and value for value in raw
+            ):
+                command = [str(value) for value in raw]
+            elif isinstance(raw, str) and raw.strip():
+                command = _split_verify_command(raw.strip())
+            else:
+                raise ValueError(f"requiredOnMerge[{index}].command missing")
+            kind = str(item.get("kind") or "smoke")
+            plan.append({
+                "command": command,
+                "kind": kind,
+                "verification": item.get("verification"),
+                "source": "profile",
+                "reuseContext": {
+                    field: str(item.get(field)).strip()
+                    for field in (
+                        "environmentHash",
+                        "toolchainHash",
+                        "lockHash",
+                        "dbSchemaHash",
+                    )
+                    if str(item.get(field) or "").strip()
+                },
+            })
+        return plan
+    return _fallback_merge_commands(profile)
+
+
+def verification_depth(plan: Sequence[dict[str, Any]]) -> str:
+    """一条临时探测命令通过，不该和跑完整条链读起来一样。
+
+    2026-08-19 那次合并，verify 只跑了一个测试文件就 DONE，报告里看不出任何差别。
+    真正的全链验证是人工在事务外补跑的——账面与事实脱节，正是这种静默造成的。
+    """
+    entries = [item for item in plan if isinstance(item, dict)]
+    if len(entries) == 1 and entries[0].get("source") not in {"profile", "profile-fallback"}:
+        return "thin"
+    return "declared"
+
+
 class IntegrationError(Exception):
     code = "INTEGRATION_ERROR"
 
@@ -1330,47 +1445,16 @@ class IntegrationTransaction:
         return commands
 
     def _required_on_merge_plan(self) -> list[dict[str, Any]]:
-        """Classify profile commands without breaking the legacy command API."""
+        """合并态验证计划：profile 声明优先，缺声明时从既有验证目标推导。
+
+        此前只读 mergeVerification.requiredOnMerge，没配就是空计划 → VERIFY_PLAN_MISSING。
+        但 profile 里本来就有 ledger 一直在用的规范命令；让调用方在合并时另行手敲一遍，
+        换来的通常是一条随手写的探测命令。
+        """
         import harness_profile
 
         profile = harness_profile.load_profile(self.project_root)
-        merge = profile.get("mergeVerification") if isinstance(profile, dict) else None
-        required = merge.get("requiredOnMerge") if isinstance(merge, dict) else []
-        if not isinstance(required, list):
-            return []
-        plan: list[dict[str, Any]] = []
-        for index, item in enumerate(required):
-            if isinstance(item, str) and item.strip():
-                plan.append({"command": _split_verify_command(item.strip()), "kind": "smoke"})
-                continue
-            if not isinstance(item, dict):
-                raise ValueError(f"requiredOnMerge[{index}] must be string or object")
-            raw = item.get("command")
-            if isinstance(raw, list) and raw and all(isinstance(value, str) and value for value in raw):
-                command = [str(value) for value in raw]
-            elif isinstance(raw, str) and raw.strip():
-                command = _split_verify_command(raw.strip())
-            else:
-                raise ValueError(f"requiredOnMerge[{index}].command missing")
-            kind, verification = _merge_command_kind(item)
-            plan.append(
-                {
-                    "command": command,
-                    "kind": kind,
-                    "verification": verification,
-                    "reuseContext": {
-                        field: str(item.get(field)).strip()
-                        for field in (
-                            "environmentHash",
-                            "toolchainHash",
-                            "lockHash",
-                            "dbSchemaHash",
-                        )
-                        if str(item.get(field) or "").strip()
-                    },
-                }
-            )
-        return plan
+        return merge_verification_plan(profile)
 
     def verify(
         self,
@@ -1384,7 +1468,12 @@ class IntegrationTransaction:
         except Exception as exc:  # noqa: BLE001 — surface as verify plan error
             raise VerifyPlanMissingError(f"mergeVerification load failed: {exc}") from exc
         plan = [
-            {"command": list(command), "kind": "smoke", "verification": None}
+            {
+                "command": list(command),
+                "kind": "smoke",
+                "verification": None,
+                "source": "cli",
+            }
             for command in commands
         ]
         plan.extend(profile_plan)
@@ -1399,7 +1488,21 @@ class IntegrationTransaction:
             ):
                 raise VerifyPlanMissingError(
                     "integration verification requires at least one executable command"
+                    " — " + verify_plan_recovery_action()
                 )
+            # 计划先落盘：verify 失败时也要看得见"打算跑什么"，
+            # 而不是只剩一个 FAILED 状态。
+            journal["verifyPlan"] = [
+                {
+                    "command": list(item["command"]),
+                    "kind": item.get("kind"),
+                    "verification": item.get("verification"),
+                    "source": item.get("source"),
+                }
+                for item in plan
+            ]
+            journal["verificationDepth"] = verification_depth(plan)
+            self._save(journal)
             evidence_change = self._bound_evidence_change(journal)
             intg_root = Path(journal["integrationRoot"]).resolve()
             results: list[dict[str, Any]] = []
@@ -2253,6 +2356,20 @@ class IntegrationTransaction:
             "steps": journal["steps"],
             "mergeCommit": journal.get("mergeCommit"),
             "pushedHead": journal.get("pushedHead"),
+            # "verify = DONE" 单独一句什么也没说明。把计划、来源和退出码一起回显，
+            # 调用方才看得出这次合并到底验证了什么。
+            "verifyPlan": journal.get("verifyPlan") or [],
+            "verificationDepth": journal.get("verificationDepth"),
+            "verifyResults": [
+                {
+                    "command": item.get("command"),
+                    "exitCode": item.get("exitCode"),
+                    "reused": bool(item.get("reused")),
+                    "durationMs": item.get("durationMs"),
+                }
+                for item in (journal.get("verifyResults") or [])
+                if isinstance(item, dict)
+            ],
         }
 
 

package/harness/bundles/java/codex/scripts/harness_review.py

@@ -515,13 +515,42 @@ def cmd_validate_codegraph_identity(args: argparse.Namespace) -> int:
     return _emit(payload, as_json=True)
 
 
+def _input_document(args: argparse.Namespace) -> Any:
+    """--input <file> 或 --stdin，二选一。
+
+    为了把一段 JSON 交给命令而先在 runtime/ 落一个临时文件，既多一次往返，
+    也给 runtime/ 又添一件没人清的草稿。
+    """
+    use_stdin = bool(getattr(args, "stdin", False))
+    raw_input_path = getattr(args, "input", None)
+    if use_stdin and raw_input_path:
+        raise ValueError("--input 与 --stdin 只能二选一")
+    if use_stdin:
+        text = getattr(args, "_stdin_text", None)
+        if text is None:
+            text = sys.stdin.read()
+        return json.loads(text)
+    if not raw_input_path:
+        raise ValueError("需要 --input <file> 或 --stdin")
+    return _read_json(Path(raw_input_path))
+
+
 def cmd_write_findings(args: argparse.Namespace) -> int:
-    doc = _read_json(Path(args.input))
+    try:
+        doc = _input_document(args)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return _emit({"ok": False, "code": "FINDINGS_INPUT_INVALID", "error": str(exc)}, as_json=True)
     return _emit(write_findings(Path(args.change_dir), doc), as_json=True)
 
 
 def cmd_write_dispositions(args: argparse.Namespace) -> int:
-    doc = _read_json(Path(args.input))
+    try:
+        doc = _input_document(args)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return _emit(
+            {"ok": False, "code": "DISPOSITIONS_INPUT_INVALID", "error": str(exc)},
+            as_json=True,
+        )
     return _emit(write_dispositions(Path(args.change_dir), doc), as_json=True)
 
 
@@ -547,12 +576,18 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_findings = sub.add_parser("write-findings")
     p_findings.add_argument("--change-dir", required=True)
-    p_findings.add_argument("--input", required=True)
+    p_findings.add_argument("--input", help="findings JSON 文件路径")
+    p_findings.add_argument(
+        "--stdin", action="store_true", help="从标准输入读 JSON，免落临时文件"
+    )
     p_findings.set_defaults(func=cmd_write_findings)
 
     p_dispositions = sub.add_parser("write-dispositions")
     p_dispositions.add_argument("--change-dir", required=True)
-    p_dispositions.add_argument("--input", required=True)
+    p_dispositions.add_argument("--input", help="dispositions JSON 文件路径")
+    p_dispositions.add_argument(
+        "--stdin", action="store_true", help="从标准输入读 JSON，免落临时文件"
+    )
     p_dispositions.set_defaults(func=cmd_write_dispositions)
 
     p_status = sub.add_parser("status")
@@ -562,9 +597,12 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] | None = None) -> int:
+def main(argv: list[str] | None = None, *, stdin_text: str | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
+    if stdin_text is not None:
+        # 测试注入用；正式路径仍然读真正的 stdin。
+        args._stdin_text = stdin_text
     return int(args.func(args))