@hunter-harness/workflow-harness 0.2.85 → 0.2.86

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

@@ -564,18 +564,36 @@ def _lease_expired(lease: dict[str, Any]) -> bool:
     return dt.datetime.now().astimezone() >= exp_dt
 
 
-def inspect_lease(project_root: Path, change_id: str) -> dict[str, Any] | None:
-    """Return the current non-expired lease without mutating it."""
+def inspect_lease_state(project_root: Path, change_id: str) -> dict[str, Any]:
+    """Read the lease without mutating it, keeping the three failure modes apart.
+
+    ``inspect_lease`` collapses absent / expired / corrupt into ``None``, so a
+    caller cannot tell "nobody ever held this" from "the phase outlived its
+    TTL". Those need different answers: an expired lease still carries the
+    runId that proves who owns the phase, a corrupt one proves nothing, and an
+    absent one may just mean the phase already closed.
+
+    state is one of ``active`` | ``expired`` | ``absent`` | ``corrupt``. The
+    lease dict is returned for ``active`` and ``expired``; ``None`` otherwise.
+    """
     path = _lease_path(project_root, change_id)
     if not path.is_file():
-        return None
+        return {"state": "absent", "lease": None}
     try:
         lease = _read_json(path)
     except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(lease, dict) or _lease_expired(lease):
-        return None
-    return lease
+        return {"state": "corrupt", "lease": None}
+    if not isinstance(lease, dict):
+        return {"state": "corrupt", "lease": None}
+    if _lease_expired(lease):
+        return {"state": "expired", "lease": lease}
+    return {"state": "active", "lease": lease}
+
+
+def inspect_lease(project_root: Path, change_id: str) -> dict[str, Any] | None:
+    """Return the current non-expired lease without mutating it."""
+    state = inspect_lease_state(project_root, change_id)
+    return state["lease"] if state["state"] == "active" else None
 
 
 def _claim_lease_locked(

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

@@ -21,6 +21,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_ledger as hl  # noqa: E402
+import harness_paths as hpaths  # noqa: E402
 
 
 PHASE_GRAPH = {
@@ -31,17 +32,8 @@ PHASE_GRAPH = {
     "submit": (),
 }
 
-WORKFLOW_PHASES = (
-    "plan",
-    "run",
-    "test",
-    "review",
-    "package",
-    "apidoc",
-    "submit",
-    "merge",
-    "archive",
-)
+# 唯一权威清单在 harness_paths（叶子模块，harness_phase 引的是同一个对象）。
+WORKFLOW_PHASES = hpaths.WORKFLOW_PHASES
 
 DISPLAY_TITLE_MAX_LENGTH = 80
 
@@ -270,13 +262,24 @@ def _contract(project: Path, change: str) -> tuple[Path, dict[str, Any], Path]:
 
 
 def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
+    """读出阶段计划；无法采信时说明原因，而不是悄悄退成 legacy。
+
+    以前这里遇到未知阶段名一律返回 (None, "legacy")：阶段计划整个失效，
+    `_allowed_next_phases` 退回硬编码的 PHASE_GRAPH，而调用方看不出发生过这件事。
+    未知阶段名不是假想问题——阶段清单少一个 merge 时，worktree 变更的
+    plannedPhases 就会带着 merge 走到这里。
+
+    未知名先过 LEGACY_PHASE_ALIASES 读时映射（阶段改名后历史 change 靠它继续可读），
+    仍然解析不了才降级，并把原因与具体阶段名带在 source 里。
+    """
     policy_path = contract_root / "meta" / "gate-policy.json"
     if not policy_path.is_file():
         return None, "legacy"
     try:
         policy = _read_json(policy_path)
     except (OSError, ValueError, json.JSONDecodeError):
-        return None, "legacy"
+        return None, "legacy:policy-unreadable"
+    unknown: list[str] = []
     for field, source in (
         ("plannedPhases", "change"),
         ("defaultPhases", "policy-default"),
@@ -285,12 +288,17 @@ def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
         if not isinstance(raw, list):
             continue
         phases = [str(item).strip() for item in raw if str(item).strip()]
-        if (
-            phases
-            and len(phases) == len(set(phases))
-            and all(item in WORKFLOW_PHASES for item in phases)
-        ):
-            return phases, source
+        if not phases or len(phases) != len(set(phases)):
+            continue
+        resolved = [hpaths.resolve_phase_name(item) for item in phases]
+        missing = [item for item, hit in zip(phases, resolved) if hit is None]
+        if missing:
+            unknown.extend(missing)
+            continue
+        # 映射后可能出现重复（两个旧名合并成同一个新阶段），保序去重。
+        return list(dict.fromkeys(str(item) for item in resolved)), source
+    if unknown:
+        return None, "legacy:unknown-phases=" + ",".join(dict.fromkeys(unknown))
     return None, "legacy"
 
 
@@ -405,6 +413,7 @@ def _paths(state_root: Path) -> dict[str, Path]:
         "begins": runtime / "transition-begins.ndjson",
         "current": runtime / "current-context.json",
         "lease": runtime / "context-lease.json",
+        "adoptions": runtime / "context-adoptions.ndjson",
     }
 
 
@@ -604,8 +613,14 @@ def _claim_prepared_context(
             )
         except (OSError, ValueError, json.JSONDecodeError):
             return {"ok": False, "code": "CONTEXT_CURRENT_INVALID"}
+        # 跨阶段推进必须有 receipt 证明它合法；同一个阶段换执行者不需要。
+        # 以前两者都要 receipt，于是上一阶段崩溃没能正常 close 时，接手的工具
+        # 连"继续把这个阶段干完"都做不到。并发保护不受影响：租约未过期而
+        # owner 不同，上面 CONTEXT_LEASE_HELD 已经拦下了，能走到这里只剩
+        # 「租约已过期」和「租约已被上一阶段 close 删除」两种情况。
+        adoption: dict[str, Any] | None = None
         if recovery is None and isinstance(current, dict) and (
-            current.get("executor") != executor or current.get("phase") != phase
+            current.get("phase") != phase
         ):
             valid_receipt = (
                 isinstance(latest, dict)
@@ -621,6 +636,19 @@ def _claim_prepared_context(
                     "toExecutor": executor,
                     "toPhase": phase,
                 }
+        executor_changed = (
+            isinstance(current, dict) and current.get("executor") != executor
+        )
+        if recovery is not None or executor_changed:
+            adoption = {
+                "previousExecutor": (
+                    current.get("executor") if isinstance(current, dict) else None
+                ),
+                "newExecutor": executor,
+                "reason": (
+                    "lease_expired" if recovery is not None else "same_phase_handoff"
+                ),
+            }
 
         try:
             execution_root = _execution_root(project, contract_root, state_root)
@@ -657,6 +685,20 @@ def _claim_prepared_context(
             current_context["preparationId"] = preparation_id
         _write_json_atomic(paths["lease"], lease)
         _write_json_atomic(paths["current"], current_context)
+        if adoption is not None:
+            # 接管必须留痕。过期租约本来就允许任何执行者顶替，但以前只在返回体
+            # 里挂一个 recovery，退出进程就没了——事后查"这个阶段是谁接手的"
+            # 无据可依。收据形状照 harness_archive.adopt_existing_range。
+            adoption = {
+                "schemaVersion": 1,
+                "changeName": change,
+                "phase": phase,
+                **adoption,
+                "previousOwner": recovery.get("previousOwner") if recovery else None,
+                "expiredAt": recovery.get("expiredAt") if recovery else None,
+                "adoptedAt": now.isoformat(),
+            }
+            _append_ndjson(paths["adoptions"], adoption)
         return {
             "ok": True,
             "lease": lease,
@@ -664,6 +706,7 @@ def _claim_prepared_context(
             "transitions": transitions,
             "latestTransition": latest,
             "recovery": recovery,
+            "adoption": adoption,
             "executionRoot": str(execution_root),
         }
 

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

@@ -405,6 +405,10 @@ def _default_gate_begin(**kwargs: Any) -> dict[str, Any]:
         str(kwargs["run_id"]),
         "--note",
         "开始处理评审中确认需要修改的代码问题。",
+        # 显式标记这一轮是 review fixback。以前靠 gate 嗅探 note 里有没有
+        # "fixback" 字样——而上面这条 note 一个都没有，于是 fixback 的 run 事件
+        # 从来没被打上 trigger/from_phase。
+        "--fixback",
     ]
     for option, key in (
         ("--executor-tool", "executor_tool"),

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

@@ -157,6 +157,47 @@ GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
 # phase close. Must stay a superset-ordering of hpf.VALID_OWNER_PHASES.
 SCENARIO_OWNER_PHASE_ORDER = ("plan", "run", "test", "review", "submit")
 
+# ---------------------------------------------------------------------------
+# 阶段能力表：每个阶段在 begin/close 里额外做什么，集中在这里声明。
+#
+# 这些开关以前是 cmd_begin / cmd_close 里散落的 `if args.phase == ...` —— 两个
+# 五百行的函数，想知道"test 阶段关门时到底跑哪几项"要通读全文。更要紧的是
+# run/test/review 的差异被摊平在控制流里，看不出它们其实共用同一套生命周期。
+#
+# 键的含义：
+#   plan_handoff      begin 时校验 plan 已 finalize（只有进入实现的第一个阶段需要）
+#   test_guard        begin 建测试基线快照、close 比对（改测试的阶段才需要）
+#   scenario_coverage close 时跑 C9 场景覆盖
+#   ledger_blocking   close 时 ledger 校验失败是否阻断（否则只进 payload）
+#   review_outputs    close 时校验 review sidecar 与 runId 绑定
+#   head_may_advance  capsule 校验允许 HEAD 前移（会产生 commit 的阶段）
+#   projection_drift  close 时 projection receipt 变化即硬失败（外发边界）
+PHASE_GATE_RULES: dict[str, frozenset[str]] = {
+    "plan": frozenset(),
+    "run": frozenset({
+        "plan_handoff", "test_guard", "scenario_coverage",
+        "ledger_blocking", "head_may_advance",
+    }),
+    "test": frozenset({"test_guard", "scenario_coverage", "ledger_blocking"}),
+    "review": frozenset({"review_outputs"}),
+    "package": frozenset({"ledger_blocking"}),
+    "apidoc": frozenset(),
+    "submit": frozenset({"head_may_advance", "projection_drift"}),
+    "merge": frozenset({"head_may_advance"}),
+    "archive": frozenset({"projection_drift"}),
+}
+# 不在 WORKFLOW_PHASES 里、但 projection 门禁按发布阶段对待的名字。
+_EXTRA_PROJECTION_DRIFT_PHASES = frozenset({"release", "deploy"})
+
+
+def phase_gate_rule(phase: str | None, rule: str) -> bool:
+    """这个阶段是否启用某项门禁能力。未知阶段一律不启用（fail-safe）。"""
+    name = str(phase or "")
+    if rule == "projection_drift" and name in _EXTRA_PROJECTION_DRIFT_PHASES:
+        return True
+    resolved = hp.resolve_phase_name(name) or name
+    return rule in PHASE_GATE_RULES.get(resolved, frozenset())
+
 
 def gate_severity_mode(project: Path, change_dir: Path | None = None) -> str:
     """Resolve gate severity mode: env > change gate-policy > project config.
@@ -554,19 +595,39 @@ def load_checkpoints(change_dir: Path) -> dict[str, Any] | None:
         data = _read_json(path)
     except (OSError, json.JSONDecodeError):
         return None
+    # 刻意返回**原样**文档：cmd_checkpoint approve 会把这里的返回值写回盘，
+    # 返回归一化结构会用合成内容覆盖 v2 的哈希绑定产物（ARTIFACT_HASH_DRIFT）。
+    # 形状差异在只读的 checkpoint_status 里消化。
     return data if isinstance(data, dict) else None
 
 
 def checkpoint_status(checkpoints: dict[str, Any] | None, checkpoint_id: str) -> str:
+    """Read a checkpoint's status across the three shapes this file is written in.
+
+    `meta/implementation-checkpoints.json` 有三个写入者，形状各不相同：
+    `harness_change.migrate` 写 ``checkpoints[{id,status}]``；legacy plan finalize 写
+    顶层 ``foundationGate``；v2 plan finalize 写 artifact 包装体，状态在
+    ``content.foundation_gate``。以前只认第一种，另外两种一律返回 "missing"
+    ——checkpoint 的状态对整条 v2 路径和 legacy finalize 之后都是读不出来的。
+
+    只读归一化：调用方拿到的是状态，不是文档。写回路径（cmd_checkpoint approve）
+    仍然操作原始文档，不能用归一化结构覆盖哈希绑定的 v2 产物。
+    """
     if not checkpoints:
         return "missing"
     items = checkpoints.get("checkpoints")
-    if not isinstance(items, list):
+    if isinstance(items, list):
+        for item in items:
+            if isinstance(item, dict) and item.get("id") == checkpoint_id:
+                return str(item.get("status") or "pending")
         return "missing"
-    for item in items:
-        if isinstance(item, dict) and item.get("id") == checkpoint_id:
-            return str(item.get("status") or "pending")
-    return "missing"
+    if checkpoint_id != "foundation-gate":
+        return "missing"
+    unpacked = hpf.unpack_v2_implementation_checkpoints(checkpoints)
+    if unpacked is not None:
+        return str(unpacked["checkpoints"][0]["status"])
+    legacy = checkpoints.get("foundationGate")
+    return str(legacy).strip() if str(legacy or "").strip() else "missing"
 
 
 def foundation_gate_blocks(task_number: int | None, change_dir: Path) -> dict[str, Any] | None:
@@ -901,8 +962,13 @@ def validate_identity(
     core_hash = str(build.get("coreHash") or "").strip()
     if not agent or not core_hash:
         raise ValueError("BUNDLE_IDENTITY_INVALID: agent/coreHash is required")
-    if executor_tool and executor_tool != agent:
-        raise ValueError(f"BUNDLE_IDENTITY_MISMATCH: executor {executor_tool} uses {agent} bundle")
+
+    # 「这个 bundle 是否可信」和「现在是哪个工具在跑」是两件事。以前
+    # executor_tool != agent 直接 BUNDLE_IDENTITY_MISMATCH，于是 Codex 换
+    # CodeBuddy 接手同一个 change 会被当成 bundle 身份不符挡下来。下面每一项
+    # 校验用的都是 bundle 自称的 agent，与当前工具无关；工具名降级为审计字段，
+    # 随 phase.start 事件留痕。
+    executor_matches_bundle = not executor_tool or executor_tool == agent
 
     context = _read_json(project / ".harness" / "context-index.json")
     installed = _read_json(
@@ -953,6 +1019,8 @@ def validate_identity(
         "adapter": agent,
         "buildMarkerHash": actual_hash,
         "contextIndexPresent": True,
+        "executorTool": executor_tool or None,
+        "executorMatchesBundle": executor_matches_bundle,
     }
 
 
@@ -1295,8 +1363,13 @@ def classify_risk(
     stage: str,
     workflow: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    tier = "full"
-    source = "default-full"
+    # 无风险信号时的起步档。曾经是 full，于是每个普通变更都默认背上
+    # plan→run→test→review→submit→archive 六阶段和 apiTest；风险信号推断只在
+    # --stage post-run 下跑，而生产流程没有任何地方调用它，起步值实际就是终值。
+    # standard 保留 compile/unitTest/unitTestFull 的证据闭环，只去掉默认的
+    # review 阶段与 apiTest。下面的单调升级逻辑不变，有信号照样升到 full。
+    tier = "standard"
+    source = "default-standard"
     capabilities = _design_capabilities(change_dir)
     plan_path = change_dir / "plans"
     for candidate in sorted(plan_path.glob("*.md")) if plan_path.is_dir() else []:
@@ -1551,8 +1624,9 @@ def classify_defaults(
     change_id: str,
     stage: str,
 ) -> dict[str, Any]:
-    tier = "full"
-    source = "default-full"
+    # change 目录不存在时的兜底，与 classify_risk 的起步档保持一致。
+    tier = "standard"
+    source = "default-standard"
     tier_policy = workflow["riskTiers"][tier]
     payload = {
         "ok": True,
@@ -1668,6 +1742,7 @@ def append_phase_event(
     executor_agent: str | None = None,
     executor_model: str | None = None,
     code: str | None = None,
+    fixback: bool = False,
 ) -> dict[str, Any]:
     """Skill-facing phase lifecycle append (begin/close use this directly).
 
@@ -1720,8 +1795,17 @@ def append_phase_event(
             execution_mode=None,
             decision_reason_code=None,
             fallback_reason_code=None,
-            trigger=("fixback" if "fixback" in note.lower() else None),
-            from_phase=("review" if phase == "run" and "fixback" in note.lower() else None),
+            # 显式信号优先。以前只嗅探 note 文本，而真正的 fixback 启动路径
+            # （harness_fixback._default_gate_begin）写的 note 是
+            # "开始处理评审中确认需要修改的代码问题。"，一个 "fixback" 字都没有
+            # ——于是 fixback 的 run 事件从来没被打上 trigger/from_phase。
+            # note 嗅探保留为兼容回退：手工传 --note 带 fixback 的老用法仍然有效。
+            trigger=("fixback" if fixback or "fixback" in note.lower() else None),
+            from_phase=(
+                "review"
+                if phase == "run" and (fixback or "fixback" in note.lower())
+                else None
+            ),
             result_status=None,
         )
         event = he.build_event(args, existing)
@@ -2068,52 +2152,6 @@ def _resolve_project(args: argparse.Namespace) -> Path:
     return hc.resolve_main_project_root()
 
 
-# 门禁消费的场景字段。v2 plan finalize 派生的 scenario_manifest 一个都没有：
-# 它只带 scenario_id/coverage_dimension/execution_level/evidence_requirements/
-# risk_level/task_refs/requirement_refs。
-_V2_MANIFEST_REQUIRED_FIELDS = (
-    "id",
-    "priority",
-    "requiredEvidenceKind",
-    "ownerPhase",
-    "executableTestId",
-    "testFile",
-    "testTitle",
-)
-
-
-def _v2_artifact_manifest_gap(manifest: Any) -> dict[str, Any] | None:
-    """v2 plan artifact 包装的 scenario-manifest → 明确的不可消费错误。
-
-    不能"解包 + 字段改名"了事：包装体里既没有 priority 也没有
-    requiredEvidenceKind，`required_ids` 会算成空集，C9 随即返回
-    NO_LEDGER_REQUIRED_SCENARIOS——那是把证据门禁对所有 v2 计划静默关掉，
-    比直接失败危险得多。所以这里点名缺口，让调用方回规划阶段补齐后重新发布。
-
-    v2 场景契约补齐这些字段后，解包逻辑加在这里。
-    """
-    if not isinstance(manifest, dict) or manifest.get("artifact_type") != "scenario_manifest":
-        return None
-    content = manifest.get("content")
-    present: set[str] = set()
-    if isinstance(content, dict) and isinstance(content.get("scenarios"), list):
-        for scenario in content["scenarios"]:
-            if isinstance(scenario, dict):
-                present.update(scenario.keys())
-    return {
-        "ok": False,
-        "code": "SCENARIO_MANIFEST_V2_UNSUPPORTED",
-        "message": (
-            "meta/scenario-manifest.json 是 v2 plan artifact 包装体，缺少门禁消费的场景字段；"
-            "请在规划阶段补齐后重新发布，不要手改派生产物"
-        ),
-        "missingFields": [
-            field for field in _V2_MANIFEST_REQUIRED_FIELDS if field not in present
-        ],
-        "artifactType": "scenario_manifest",
-    }
-
-
 def _validate_scenario_coverage(
     change_dir: Path, phase: str | None = None
 ) -> dict[str, Any]:
@@ -2140,9 +2178,12 @@ def _validate_scenario_coverage(
             "code": "SCENARIO_MANIFEST_INVALID",
             "message": f"scenario-manifest.json unreadable: {exc}",
         }
-    v2_gap = _v2_artifact_manifest_gap(manifest)
-    if v2_gap is not None:
-        return v2_gap
+    unpacked = hpf.unpack_v2_scenario_manifest(manifest)
+    if unpacked is not None:
+        if not unpacked.get("ok"):
+            return unpacked
+        # 解包成 legacy 形状后，下面的判定逻辑对 v2 与 legacy 完全一致。
+        manifest = unpacked["manifest"]
     scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
     if not isinstance(scenarios, list):
         return {
@@ -2514,7 +2555,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
     severity_mode = gate_severity_mode(project, change_dir)
     gate_warnings: list[dict[str, Any]] = []
     plan_verification: dict[str, Any] | None = None
-    if args.phase == "run":
+    if phase_gate_rule(args.phase, "plan_handoff"):
         plan_verification = validate_plan_handoff(change_dir)
         if not plan_verification.get("ok"):
             code = str(
@@ -2700,7 +2741,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
         if capsule is not None:
             guard_result = {"ok": True, "code": "SNAPSHOT_REUSED"}
         else:
-            if args.phase in {"run", "test"}:
+            if phase_gate_rule(args.phase, "test_guard"):
                 guard_result = htg.begin(execution_root, change_dir)
                 if not guard_result.get("ok"):
                     if gate_soft_allowed(severity_mode, args.phase, "test-guard"):
@@ -2767,6 +2808,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 phase=args.phase,
                 type_="phase.start",
                 note=args.note or "",
+                fixback=bool(getattr(args, "fixback", False)),
                 identity=identity,
                 run_id=run_id,
                 executor_tool=executor_tool,
@@ -2857,6 +2899,83 @@ def cmd_close(args: argparse.Namespace) -> int:
 
     explicit_run_id = args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID")
     current_lease = hc.inspect_lease(project, resolved["changeId"])
+    lease_lapsed: dict[str, Any] | None = None
+    # 只有在"没有活跃租约"时才需要区分不存在/已过期/已损坏——三者要给的答案
+    # 完全不同，而 inspect_lease 把它们一律压成 None。
+    lease_state = (
+        {"state": "active", "lease": current_lease}
+        if current_lease is not None
+        else hc.inspect_lease_state(project, resolved["changeId"])
+    )
+
+    if lease_state["state"] == "corrupt":
+        # 损坏的租约证明不了"没人抢占过"，所以不自动恢复——那正是自动重取唯一
+        # 的安全前提。
+        return emit_error(
+            "LEASE_INVALID",
+            "phase lease file is unreadable; it cannot prove the phase was not taken over",
+            as_json=as_json,
+            extra={
+                "phase": args.phase,
+                "changeId": resolved["changeId"],
+                "recoveryAction": (
+                    "租约文件已损坏，无法自动恢复。确认没有其他进程在跑同一个 change 后，"
+                    "用本阶段原 run-id 重新取得租约再重试 close："
+                    "python <skills-root>/scripts/harness_change.py claim "
+                    f"--change {resolved['changeId']} --phase {args.phase} "
+                    "--run-id <原 run-id> --ttl-seconds 3600 --json"
+                ),
+            },
+        )
+
+    if lease_state["state"] == "expired":
+        expired_lease = lease_state["lease"] or {}
+        expired_run_id = str(expired_lease.get("runId") or "")
+        expected_run_id = explicit_run_id or expired_run_id
+        # 租约过期、runId 还是本轮的，恰好证明没有第三方抢占过：抢占会重写
+        # 租约文件把 runId 换掉。所以过期只说明这个阶段跑得比 TTL 久，不说明
+        # 所有权变了——harness_context.close_transition 早就是这么推理的
+        # （只记 leaseLapsed 照常收尾），这里把 Gate 侧对齐过去，不再要求
+        # 用户手工 claim 一遍再原样重试。
+        if (
+            expired_run_id
+            and expired_run_id == expected_run_id
+            and str(expired_lease.get("phase") or "") == args.phase
+        ):
+            reacquired = hc.claim_lease(
+                project,
+                change_id=str(resolved["changeId"]),
+                phase=args.phase,
+                run_id=expired_run_id,
+                ttl_seconds=int(getattr(args, "ttl_seconds", 0) or 3600),
+            )
+            if not reacquired.get("ok"):
+                return emit_error(
+                    str(reacquired.get("code") or "LEASE_CONFLICT"),
+                    "expired phase lease could not be reacquired for close",
+                    as_json=as_json,
+                    extra={
+                        "phase": args.phase,
+                        "changeId": resolved["changeId"],
+                        "holder": reacquired.get("holder"),
+                    },
+                )
+            current_lease = reacquired.get("lease")
+            lease_lapsed = {
+                "acquiredAt": expired_lease.get("acquiredAt"),
+                "expiresAt": expired_lease.get("expiresAt"),
+                "reacquiredAt": (current_lease or {}).get("refreshedAt")
+                or (current_lease or {}).get("acquiredAt"),
+                "runId": expired_run_id,
+            }
+        else:
+            return emit_error(
+                "LEASE_OWNER_MISMATCH",
+                "expired lease belongs to a different run or phase",
+                as_json=as_json,
+                extra={"holder": expired_lease},
+            )
+
     if current_lease is None:
         terminal = _latest_phase_end(change_dir, args.phase, explicit_run_id)
         if (
@@ -2911,8 +3030,10 @@ def cmd_close(args: argparse.Namespace) -> int:
                 "changeId": resolved["changeId"],
                 "resumeRunId": resume_run_id,
                 "recoveryAction": (
-                    "阶段租约已过期（TTL 由 begin 的 --ttl-seconds 决定，默认 3600 秒）或已被释放。"
-                    "用本阶段原 run-id 重新取得租约后原样重试 close："
+                    "本阶段没有任何租约记录——过期租约现在由 close 自动重取，所以这里说明的是"
+                    "租约从未建立或已被释放。先确认 gate begin 是否真的跑过（events.ndjson 里"
+                    f"应有 phase={args.phase} 的 phase.start）。确有本轮 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"
@@ -2994,7 +3115,7 @@ def cmd_close(args: argparse.Namespace) -> int:
                 run_id=run_id,
                 project=project,
                 execution_root=execution_root,
-                allow_head_advance=args.phase in {"run", "submit", "merge"},
+                allow_head_advance=phase_gate_rule(args.phase, "head_may_advance"),
             )
         except ValueError as exc:
             if gate_soft_allowed(severity_mode, args.phase, "capsule"):
@@ -3049,7 +3170,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         and captured_projection.get("receiptHash")
         and captured_projection.get("receiptHash")
         != projection.get("receiptHash")
-        and args.phase in {"submit", "archive", "release", "deploy"}
+        and phase_gate_rule(args.phase, "projection_drift")
     ):
         mismatch = {
             "code": "PROJECTION_CHANGED_DURING_PHASE",
@@ -3076,7 +3197,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         change_dir, args.phase, policy, execution_root=execution_root,
         phase_status=args.status,
     )
-    if not ledger_result.get("ok") and args.phase in {"run", "test", "package"}:
+    if not ledger_result.get("ok") and phase_gate_rule(args.phase, "ledger_blocking"):
         persist_close_failure(
             change_dir,
             args.phase,
@@ -3102,7 +3223,7 @@ def cmd_close(args: argparse.Namespace) -> int:
             extra={k: v for k, v in ledger_result.items() if k not in {"ok", "message", "code"}},
         )
 
-    if args.phase == "review":
+    if phase_gate_rule(args.phase, "review_outputs"):
         review_outputs = validate_review_outputs_for_close(change_dir, run_id)
         if not review_outputs.get("ok"):
             persist_close_failure(
@@ -3134,7 +3255,7 @@ def cmd_close(args: argparse.Namespace) -> int:
     # C9: scenario coverage check — every P0/ledger scenario *due by this phase*
     # must have a ledger entry. Scenarios with a later ownerPhase are deferred,
     # not missing (see _validate_scenario_coverage).
-    if args.phase in {"run", "test"}:
+    if phase_gate_rule(args.phase, "scenario_coverage"):
         coverage = _validate_scenario_coverage(change_dir, args.phase)
         if not coverage.get("ok"):
             if gate_soft_allowed(severity_mode, args.phase, "scenario-coverage"):
@@ -3192,7 +3313,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         write_phase_capsule(change_dir, args.phase, run_id, capsule)
 
     guard_result = None
-    if args.phase in {"run", "test"}:
+    if phase_gate_rule(args.phase, "test_guard"):
         if close_transaction.get("guardClosed"):
             guard_result = {"ok": True, "code": "ALREADY_CLOSED", "reused": True}
         else:
@@ -3247,6 +3368,7 @@ def cmd_close(args: argparse.Namespace) -> int:
                 type_="phase.end",
                 status=close_status,
                 note=args.note or "",
+                fixback=bool(getattr(args, "fixback", False)),
                 run_id=run_id,
             )
         except BaseException as exc:
@@ -3364,6 +3486,10 @@ def cmd_close(args: argparse.Namespace) -> int:
         "gateRecovery": recovery_result,
         "scratchSwept": scratch_swept,
     }
+    if lease_lapsed is not None:
+        # 与 context transition receipt 的 leaseLapsed 同名同义：记录这个阶段
+        # 跑过了 TTL 且租约是自动重取的，不隐藏。
+        payload["leaseLapsed"] = lease_lapsed
     emit(payload, as_json=as_json)
     return 0
 
@@ -3551,6 +3677,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_begin.add_argument("--ttl-seconds", type=int, default=3600)
     p_begin.add_argument("--task", type=int, default=None)
     p_begin.add_argument("--note", default="")
+    p_begin.add_argument(
+        "--fixback",
+        action="store_true",
+        help="This phase is a review fixback round (tags the lifecycle event).",
+    )
     p_begin.add_argument("--executor-tool", default=None)
     p_begin.add_argument("--executor-agent", default=None)
     p_begin.add_argument("--executor-model", default=None)
@@ -3571,6 +3702,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)
     p_close.add_argument("--note", default="")
+    p_close.add_argument(
+        "--fixback",
+        action="store_true",
+        help="This phase is a review fixback round (tags the lifecycle event).",
+    )
     p_close.add_argument("--to-phase", default=None)
     p_close.add_argument("--executor", default=None)
     p_close.add_argument("--artifact", action="append", default=[])