@hunter-harness/workflow-harness 0.2.79 → 0.2.81

package/harness/bundles/general/claude-code/scripts/harness_archive.py

@@ -10232,6 +10232,42 @@ def cmd_repair_cli(args: argparse.Namespace) -> int:
     return code
 
 
+def resolve_republish_project_root(explicit: Path | None, archive_dir: Path | None) -> Path:
+    """Locate the project root for a republish without requiring --project.
+
+    ``find_project_root`` walks ``p.parents``, which excludes ``p`` itself; it is
+    built for a change/archive subdirectory. Handing it the cwd therefore skips
+    the very directory the operator is standing in and keeps climbing — in a real
+    run that resolved ``E:/WorkProject/kb-sdd`` to its parent and made the command
+    look for archives that were never there.
+
+    Order: explicit flag, then the archive's own location, then cwd and its
+    parents (cwd included), then the deployed script's location — the script
+    lives at ``<project>/.claude|.codebuddy/skills/scripts/`` after install.
+    """
+    if explicit is not None:
+        return explicit.resolve()
+    if archive_dir is not None:
+        return find_project_root(archive_dir)
+
+    def first_with_archive(start: Path) -> Path | None:
+        start = start.resolve()
+        for candidate in (start, *start.parents):
+            if (candidate / ".harness" / "archive").is_dir():
+                return candidate
+        return None
+
+    found = first_with_archive(Path.cwd())
+    if found is not None:
+        return found
+    found = first_with_archive(Path(__file__).resolve().parent)
+    if found is not None:
+        return found
+    # Nothing carries an archive directory; report against cwd so the error names
+    # a path the operator recognises instead of some ancestor.
+    return Path.cwd().resolve()
+
+
 def resolve_archive_dir_for_change(
     project_root: Path,
     change_key: str,
@@ -10272,7 +10308,10 @@ def _republish_knowledge_entry(archive_dir: Path) -> dict[str, tuple[str, str, b
         change_key=str(summary.get("changeName") or archive_dir.name),
         archive_id=archive_dir.name,
         producer_version=SCHEMA_VERSION,
-        created_at=now_iso(),
+        # Derived from the archive, never wall-clock: `now_iso()` here made every
+        # rebuild produce different bytes, so a package could never be compared
+        # against a stored one and the "deterministic package" claim was false.
+        created_at=_archive_created_at(summary_path),
     )
     if not candidates:
         return {}
@@ -10285,12 +10324,28 @@ def _republish_knowledge_entry(archive_dir: Path) -> dict[str, tuple[str, str, b
     }
 
 
+def read_durable_archive_receipt(project_root: Path, change_key: str) -> dict[str, Any] | None:
+    """The `<key>.remote.json` written after a confirmed durable upload, if any."""
+    receipt_path = (
+        project_root / ".harness" / "state" / "local" / "archive-packages"
+        / f"{change_key}.remote.json"
+    )
+    if not receipt_path.is_file():
+        return None
+    try:
+        receipt = read_json(receipt_path)
+    except (OSError, json.JSONDecodeError, TypeError, ValueError):
+        return None
+    return receipt if isinstance(receipt, dict) else None
+
+
 def cmd_republish(
     *,
     change_key: str,
     archive_dir: Path | None,
     project_root: Path | None,
     dry_run: bool,
+    inject_knowledge: bool = True,
 ) -> tuple[int, dict[str, Any]]:
     """Rebuild and re-upload the core ZIP for an already sealed archive.
 
@@ -10311,7 +10366,7 @@ def cmd_republish(
         payload["reasonCode"] = "ARCHIVE_CHANGE_KEY_INVALID"
         return 2, payload
 
-    root = (project_root or find_project_root(archive_dir or Path.cwd())).resolve()
+    root = resolve_republish_project_root(project_root, archive_dir)
     payload["projectRoot"] = str(root)
     matches: list[str] = []
     if archive_dir is None:
@@ -10338,53 +10393,103 @@ def cmd_republish(
         payload["reasonCode"] = "ARCHIVE_SUMMARY_MISSING"
         return 1, payload
 
-    try:
-        extra_entries = _republish_knowledge_entry(archive_dir)
-    except (OSError, ValueError, json.JSONDecodeError) as exc:
-        # Knowledge is additive: never fail a re-delivery over it.
-        payload.setdefault("warnings", []).append(
-            f"knowledge candidate regeneration skipped: {exc}"
-        )
-        extra_entries = {}
+    extra_entries: dict[str, tuple[str, str, bytes]] = {}
+    if inject_knowledge:
+        try:
+            extra_entries = _republish_knowledge_entry(archive_dir)
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            # Knowledge is additive: never fail a re-delivery over it.
+            payload.setdefault("warnings", []).append(
+                f"knowledge candidate regeneration skipped: {exc}"
+            )
+            extra_entries = {}
     payload["knowledgeCandidatesInjected"] = "candidates/knowledge.json" in extra_entries
 
-    if dry_run:
-        # The package builder refuses to write outside the project, so the
-        # preview lands beside the real packages under a distinct name and is
-        # removed again; it must never be mistaken for a pending upload.
-        preview_path = (
-            root / ".harness" / "state" / "local" / "archive-packages"
-            / f"{change_key}.preview.zip"
+    # Build once, into a preview path, so the bytes can be compared against any
+    # durable receipt before an upload is attempted. The builder refuses to write
+    # outside the project, so the preview lands beside the real packages under a
+    # distinct name; it must never be mistaken for a pending upload.
+    preview_path = (
+        root / ".harness" / "state" / "local" / "archive-packages"
+        / f"{change_key}.preview.zip"
+    )
+    try:
+        package = build_archive_package(
+            root,
+            archive_dir,
+            change_key,
+            output_path=preview_path,
+            extra_entries=extra_entries,
         )
+    except (OSError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        payload["error"] = f"archive package build failed: {exc}"
+        payload["reasonCode"] = "ARCHIVE_PACKAGE_BUILD_FAILED"
+        return 1, payload
+    finally:
         try:
-            package = build_archive_package(
-                root,
-                archive_dir,
-                change_key,
-                output_path=preview_path,
-                extra_entries=extra_entries,
-            )
-        except (OSError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
-            payload["error"] = f"archive package build failed: {exc}"
-            payload["reasonCode"] = "ARCHIVE_PACKAGE_BUILD_FAILED"
-            return 1, payload
-        finally:
-            try:
-                preview_path.unlink(missing_ok=True)
-            except OSError:
-                pass
-        payload.update(
-            {
+            preview_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    payload.update(
+        {
+            "fileCount": package["fileCount"],
+            "sizeBytes": package["sizeBytes"],
+            "knowledgeCandidateCount": package["knowledgeCandidateCount"],
+            "packageSha256": package["packageSha256"],
+            "manifestSha256": package["manifestSha256"],
+            "files": package["paths"],
+        }
+    )
+
+    # The platform stores exactly one immutable package per change key. A rebuild
+    # that differs by even one byte is refused server-side, so decide here rather
+    # than spending an upload to learn it.
+    durable = read_durable_archive_receipt(root, change_key)
+    stored_sha = str((durable or {}).get("packageSha256") or "")
+    if durable is not None and str(durable.get("archiveStatus") or "") == "durable":
+        payload["remoteReceipt"] = {
+            "archiveId": durable.get("archiveId"),
+            "archiveStatus": durable.get("archiveStatus"),
+            "knowledgeStatus": durable.get("knowledgeStatus"),
+            "packageSha256": stored_sha,
+            "recordedAt": durable.get("recordedAt"),
+        }
+        if stored_sha and stored_sha == package["packageSha256"]:
+            payload.update({
                 "ok": True,
-                "reasonCode": "ARCHIVE_REPUBLISH_PREVIEW",
-                "fileCount": package["fileCount"],
-                "sizeBytes": package["sizeBytes"],
-                "knowledgeCandidateCount": package["knowledgeCandidateCount"],
-                "packageSha256": package["packageSha256"],
-                "manifestSha256": package["manifestSha256"],
-                "files": package["paths"],
-            }
-        )
+                "reasonCode": "ARCHIVE_ALREADY_PUBLISHED",
+                "message": (
+                    "远端已存有字节一致的同一个包，无需重传"
+                    f"（archiveId={durable.get('archiveId')}）。"
+                ),
+            })
+            return 0, payload
+        payload.update({
+            "ok": False,
+            "reasonCode": "ARCHIVE_REMOTE_IMMUTABLE_CONFLICT",
+            "error": (
+                "该 change 在远端已是 durable 归档，服务端对同一 change key 只保存一个"
+                "不可变包，不接受不同字节的替换。"
+            ),
+            "nextAction": (
+                "补传只适用于『从未成功上传』或『字节完全一致的重试』。"
+                + (
+                    "本次重建注入了 "
+                    f"{package['knowledgeCandidateCount']} 条知识候选"
+                    "（原包上传时还没有 candidates/knowledge.json），因此字节必然不同——"
+                    "已发布归档无法从客户端追加知识条目，需要平台侧提供重新索引或归档版本化能力。"
+                    "若只是想重试同一个包（例如知识索引失败），加 --no-knowledge-injection "
+                    "可重建与封存目录完全一致的字节。"
+                    if payload.get("knowledgeCandidatesInjected")
+                    else "本地归档内容与已上传的包不一致，请先确认哪一份才是应保留的事实。"
+                )
+            ),
+        })
+        return 1, payload
+
+    if dry_run:
+        payload.update({"ok": True, "reasonCode": "ARCHIVE_REPUBLISH_PREVIEW"})
         return 0, payload
 
     result = auto_push_archive_core(
@@ -10407,6 +10512,7 @@ def cmd_republish_cli(args: argparse.Namespace) -> int:
         archive_dir=resolve_path(args.archive_dir) if args.archive_dir else None,
         project_root=resolve_path(args.project) if args.project else None,
         dry_run=bool(args.dry_run),
+        inject_knowledge=not bool(args.no_knowledge_injection),
     )
     emit_json(payload)
     return code
@@ -10590,6 +10696,14 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="build the package and report its contents without uploading",
     )
+    p_republish.add_argument(
+        "--no-knowledge-injection",
+        action="store_true",
+        help=(
+            "rebuild exactly what the sealed archive holds; needed to retry the "
+            "same bytes the server already stored"
+        ),
+    )
     p_republish.add_argument("--json", action="store_true", default=True)
     p_republish.set_defaults(func=cmd_republish_cli)
 

package/harness/bundles/general/claude-code/scripts/harness_context.py

@@ -1165,9 +1165,11 @@ def close_transition(
             "holder": lease.get("owner"),
             "leasePhase": lease.get("phase"),
         }
+    # Owner and phase already matched above, so nobody took this lease over: a
+    # takeover rewrites the file and would have produced CONTEXT_LEASE_MISMATCH.
+    # A lapsed deadline therefore proves only that the phase outlived the TTL.
     expiry = _parse_time(lease.get("expiresAt"))
-    if expiry is None or _now() >= expiry:
-        return {"ok": False, "code": "CONTEXT_LEASE_EXPIRED"}
+    lease_lapsed = expiry is None or _now() >= expiry
 
     previous_hash = transitions[-1].get("receiptHash") if transitions else None
     attempt = (
@@ -1192,6 +1194,12 @@ def close_transition(
         "closedAt": _now().isoformat(),
         "previousReceiptHash": previous_hash,
     }
+    if lease_lapsed:
+        # Recorded, not hidden: the phase ran past its lease without a renewal.
+        receipt["leaseLapsed"] = {
+            "expiresAt": lease.get("expiresAt"),
+            "acquiredAt": lease.get("acquiredAt"),
+        }
     receipt["receiptHash"] = _payload_hash(receipt)
     _append_ndjson(paths["transitions"], receipt)
     paths["lease"].unlink(missing_ok=True)
@@ -1267,7 +1275,11 @@ def _begin_transition_unlocked(
             "legacyBootstrap": True,
             "message": (
                 "没有交接凭证。v2 计划应有 committed 的 meta/publication-journals/*.json "
-                "作为补录证据；legacy 计划需先完成 plan 阶段的 close"
+                "作为补录证据；legacy 计划需先完成 plan 阶段的 close。"
+                "首次进入某阶段（还没有任何 transition 凭证）时不要用 context begin——"
+                "改跑 `harness_gate.py begin --change-dir .harness/changes/<change> "
+                "--phase <phase> --run-id <phase>_<uuid4hex> --note \"<触发指令>\"`，"
+                "它会领取租约并写好 phase.start。"
             ),
         }
     receipt = transitions[-1]
@@ -1458,6 +1470,53 @@ def cancel_prepared_context(
     }
 
 
+def renew_lease(
+    project: Path,
+    change: str,
+    *,
+    executor: str,
+    ttl_seconds: int = 3600,
+) -> dict[str, Any]:
+    """Extend the current phase lease in place.
+
+    Only the recorded owner may renew, and only while no other executor has
+    taken the lease over. Renewal touches nothing but ``expiresAt``, so it is
+    safe to call on a heartbeat during a long phase.
+    """
+    project = project.resolve()
+    try:
+        _, _, state_root = _contract(project, change)
+    except ValueError as exc:
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
+    paths = _paths(state_root)
+    if not paths["lease"].is_file():
+        return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
+    with _exclusive_state_lock(paths["runtime"] / "branch-selection.lock"):
+        try:
+            lease = _read_json(paths["lease"])
+        except (OSError, ValueError, json.JSONDecodeError):
+            return {"ok": False, "code": "CONTEXT_LEASE_INVALID"}
+        if lease.get("owner") != executor:
+            return {
+                "ok": False,
+                "code": "CONTEXT_LEASE_MISMATCH",
+                "holder": lease.get("owner"),
+            }
+        expiry = _parse_time(lease.get("expiresAt"))
+        lapsed = expiry is None or _now() >= expiry
+        lease["expiresAt"] = (
+            _now() + dt.timedelta(seconds=max(1, int(ttl_seconds)))
+        ).isoformat()
+        lease["renewedAt"] = _now().isoformat()
+        _write_json_atomic(paths["lease"], lease)
+    return {
+        "ok": True,
+        "code": "CONTEXT_LEASE_RENEWED",
+        "lease": lease,
+        "wasLapsed": lapsed,
+    }
+
+
 def context_view(project: Path, change: str) -> dict[str, Any]:
     project = Path(project).resolve()
     try:
@@ -1536,6 +1595,14 @@ def build_parser() -> argparse.ArgumentParser:
     begin.add_argument("--change", required=True)
     begin.add_argument("--phase", required=True)
     begin.add_argument("--executor", required=True)
+    renew = sub.add_parser(
+        "renew", help="extend the current phase lease without touching context"
+    )
+    renew.add_argument("--json", action="store_true")
+    renew.add_argument("--project", required=True, type=Path)
+    renew.add_argument("--change", required=True)
+    renew.add_argument("--executor", required=True)
+    renew.add_argument("--ttl-seconds", type=int, default=3600)
     configure = sub.add_parser("configure-plan")
     configure.add_argument("--json", action="store_true")
     configure.add_argument("--project", required=True, type=Path)
@@ -1588,6 +1655,13 @@ def main(argv: list[str] | None = None) -> int:
             phase=args.phase,
             executor=args.executor,
         )
+    elif args.command == "renew":
+        result = renew_lease(
+            args.project,
+            args.change,
+            executor=args.executor,
+            ttl_seconds=args.ttl_seconds,
+        )
     elif args.command == "configure-plan":
         result = configure_phase_plan(
             args.project,

package/harness/bundles/general/claude-code/scripts/harness_events.py

@@ -1904,6 +1904,7 @@ def cmd_append(args: argparse.Namespace) -> int:
             file=sys.stderr,
         )
     phase_closed = False
+    phase_start_duplicate = False
     projection_error: str | None = None
     attempt_error: str | None = None
     auto_sealed_events: list[dict[str, Any]] = []
@@ -1951,10 +1952,25 @@ def cmd_append(args: argparse.Namespace) -> int:
                 except ValueError as exc:
                     projection_error = str(exc)
             elif args.type == "phase.start":
+                # Re-appending the same (phase, run_id) is the caller restating a
+                # start that already exists — `gate begin` writes one, and the
+                # logging protocol used to ask for a second. Treat it as a no-op
+                # rather than a duplicate; two identical phase.start events make
+                # `plan finalize` unrecoverable via PHASE_START_DUPLICATE.
+                if run_id is not None and any(
+                    item.get("phase") == args.phase
+                    and item.get("type") == "phase.start"
+                    and item.get("run_id") == run_id
+                    for item in existing_events
+                ):
+                    phase_start_duplicate = True
                 # HH-WF-20260730-001: a new phase.start must not be appended
                 # while a prior attempt for the same phase is still open —
                 # auto-seal it first so timing never has two open attempts.
-                open_attempts = open_attempts_for_phase(existing_events, args.phase)
+                open_attempts = (
+                    [] if phase_start_duplicate
+                    else open_attempts_for_phase(existing_events, args.phase)
+                )
                 if open_attempts:
                     inferred_reason = infer_auto_seal_reason(
                         open_attempts[-1].get("events") or []
@@ -1964,7 +1980,12 @@ def cmd_append(args: argparse.Namespace) -> int:
                         phase=args.phase,
                         seal_reason=inferred_reason,
                     )
-            if not phase_closed and projection_error is None and attempt_error is None:
+            if (
+                not phase_closed
+                and not phase_start_duplicate
+                and projection_error is None
+                and attempt_error is None
+            ):
                 for seal_event in auto_sealed_events:
                     atomic_append_line(
                         path,
@@ -1976,6 +1997,18 @@ def cmd_append(args: argparse.Namespace) -> int:
                 )
     except (OSError, TimeoutError, ValueError) as exc:
         return emit_error(f"append failed: {exc}", as_json=as_json)
+    if phase_start_duplicate:
+        if as_json:
+            print(json.dumps({
+                "ok": True,
+                "skipped": True,
+                "reason": "phase-start-already-recorded",
+                "phase": args.phase,
+                "run_id": event.get("run_id"),
+            }, ensure_ascii=False))
+        else:
+            print("ok (phase.start already recorded for this run id)")
+        return 0
     if phase_closed:
         return emit_error(
             "PHASE_ALREADY_CLOSED: refusing a second phase.end for the same "

package/harness/bundles/general/claude-code/scripts/harness_plan_finalize.py

@@ -735,7 +735,12 @@ def _validate_plan_start(
     if len(matching) > 1:
         return _result_error(
             "PHASE_START_DUPLICATE",
-            f"found {len(matching)} matching plan phase.start events",
+            f"found {len(matching)} matching plan phase.start events for run id "
+            f"{run_id}. `harness_gate.py begin` already appends phase.start; a "
+            "second manual append of the same run id creates this state. Recover "
+            "with a fresh run id and the next attempt number (attempts are global "
+            "per phase, not per run id): append phase.start with both, then "
+            "finalize with the same pair.",
         )
     return {"ok": True, "phaseStartCount": 1}
 

package/harness/bundles/general/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "ef40ffbb4f999ea0"
+  "coreHash": "3132d081a7790973"
 }

package/harness/bundles/general/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=ef40ffbb4f999ea0; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -144,10 +144,21 @@ python <skills-root>/scripts/harness_archive.py republish --change <change-key>
 python <skills-root>/scripts/harness_archive.py republish --change <change-key> --json             # 重建并上传
 ```
 
+脚本在 `<skills-root>/scripts/` 共享，**不在 `harness-archive/scripts/`**（见 read-protocol 第 0 条）。
+
+在项目根内任意目录直接跑即可，**不需要** `--project`。
+
 归档目录是封存的（after-manifest 覆盖其每个字节），因此 `republish` **不写回**归档目录：
 缺失的 `candidates/knowledge.json` 只在内存中按已归档 summary 生成并放进包里。平台的知识
 条目只来自这个包；`--scope all` 走的是 branch_file 通道，不进知识管道。
 
+**服务端一个 change key 只存一个不可变包**，所以补传只适用于「从未成功上传」与「字节完全一致的
+重试」。已 durable 的 change 会在本地就判出结果：字节一致 → `ARCHIVE_ALREADY_PUBLISHED`
+（exit 0，不重传）；字节不同 → `ARCHIVE_REMOTE_IMMUTABLE_CONFLICT`（exit 1，**不发起上传**）。
+**已发布归档无法从客户端补知识条目**——注入候选必然改变字节，服务端拒绝替换；要补需要平台侧
+提供重新索引或归档版本化能力。
+只想重试**同一个包**（例如知识索引失败）时加 `--no-knowledge-injection`，它按封存目录原样重建，字节与已存包一致。
+
 ### 三、文件移动只用内置工具或 PowerShell
 
 移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
@@ -247,13 +258,23 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 su
 
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
 ```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
 ```
 
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **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 边界保持最新。
 
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布的 plan 用 `harness_plan_finalize.py republish` 自动分配两者。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`archive`

package/harness/bundles/general/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=ef40ffbb4f999ea0; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -94,13 +94,23 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
 ```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
 ```
 
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **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 边界保持最新。
 
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布的 plan 用 `harness_plan_finalize.py republish` 自动分配两者。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`codebase-map`；默认写 reports，有未归档变更时另写 change events

package/harness/bundles/general/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=ef40ffbb4f999ea0; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；
@@ -81,13 +81,23 @@ ZIP 已按收据策略清理，且平台下载接口可以恢复原包。
 
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
 ```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --note "<触发指令>"
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
 ```
 
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **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 边界保持最新。
 
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布的 plan 用 `harness_plan_finalize.py republish` 自动分配两者。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`knowledge-ingest` · 记录 package hash、服务端状态与失败重试路径