@hunter-harness/workflow-harness 0.2.81 → 0.2.83

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "3132d081a7790973"
+  "coreHash": "d1ddcf707a26d7b6"
 }

package/harness/bundles/general/claude-code/harness-archive/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -175,7 +175,11 @@ python <skills-root>/scripts/harness_archive.py republish --change <change-key>
 （exit 0，不重传）；字节不同 → `ARCHIVE_REMOTE_IMMUTABLE_CONFLICT`（exit 1，**不发起上传**）。
 **已发布归档无法从客户端补知识条目**——注入候选必然改变字节，服务端拒绝替换；要补需要平台侧
 提供重新索引或归档版本化能力。
-只想重试**同一个包**（例如知识索引失败）时加 `--no-knowledge-injection`，它按封存目录原样重建，字节与已存包一致。
+只想重试**同一个包**（例如知识索引失败）时用 `--retry-retained`：它上传盘上留存的原包字节，
+不重建。**重建得不到已发布的字节**——包 manifest 绑定归档自己的提交，封存目录与 harness 本身
+也都会前进；`--no-knowledge-injection` 只是不注入候选，不等于能复现旧包。
+留存包与远端字节不同（即那是一次失败尝试的残留）时，`--retry-retained` 同样在本地判出
+`ARCHIVE_REMOTE_IMMUTABLE_CONFLICT` 并拒绝上传。
 
 ### 三、文件移动只用内置工具或 PowerShell
 

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/general/claude-code/harness-plan/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-pull/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-push/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose
@@ -72,7 +72,11 @@ stderr 里直接给出上面的 republish 命令；`--dry-run` 会列出本地
 `ARCHIVE_REMOTE_IMMUTABLE_CONFLICT`（exit 1，**不发起上传**）。
 **已发布的归档无法从客户端补上知识条目**——注入 `candidates/knowledge.json` 必然改变字节，
 服务端拒绝替换。要让旧归档产生知识条目，需要平台侧提供重新索引或归档版本化能力。
-只想重试**同一个包**（例如知识索引失败）时加 `--no-knowledge-injection`，它按封存目录原样重建，字节与已存包一致。
+只想重试**同一个包**（例如知识索引失败）时用 `--retry-retained`：它上传盘上留存的原包字节，
+不重建。**重建得不到已发布的字节**——包 manifest 绑定归档自己的提交，封存目录与 harness 本身
+也都会前进；`--no-knowledge-injection` 只是不注入候选，不等于能复现旧包。
+留存包与远端字节不同（即那是一次失败尝试的残留）时，`--retry-retained` 同样在本地判出
+`ARCHIVE_REMOTE_IMMUTABLE_CONFLICT` 并拒绝上传。
 
 ## 关键规则
 

package/harness/bundles/general/claude-code/harness-review/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -92,6 +92,24 @@ disallowed-tools:
 
 **Fixback**：入口只用 `launch-review`，后续问题处理通过 `resolve-issue/close` 驱动，不得把修复说明当成新的普通 Run。只读取返回的受影响问题和文件；验证仅失效与 `changedFiles` 相交的目标，其他 Test/Review 证据继续复用。RED 优先；`manual`、`workflow` 或未选用的建议不进入代码批次，使用中文记录处理结论。
 
+**构建/测试执行入口**：所有构建与测试命令（mvn / gradle / npm test / pytest 等）必须经 `harness_test_runner.py exec` 发起，**禁止**用 `powershell.exe -Command` 直接裸跑：
+
+```text
+python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
+```
+
+该入口持有项目级互斥锁并托管进程树。裸跑构建在宿主工具超时后会被推入后台，多个后台构建同时写同一个 `target/`、`build/` 或 `node_modules/.cache`，表现为编译产物被清空、日志文件被占用、"增量编译抖动"——这些都不是代码缺陷，是并发自相残杀，排查成本极高。`--timeout-seconds` 按最慢的一次全量构建估（默认 300 秒偏短），宁可给足也不要让命令被中途掐断。
+
+返回 `TEST_RUN_ALREADY_ACTIVE`（退出码 3）说明**已有构建在跑**：等它结束或用 `lock-status` 查明持有者，**不得**改用裸跑绕开锁，也不得另起一个并行构建。确认持有进程已消失时才用 `lock-reap` 回收。
+
+**长阶段租约续期**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，只会让最后的 `gate close` 报 `LEASE_ABSENT`。凡预计超过 1 小时的阶段，每完成一个变更簇就用本阶段**原 run-id** 续租一次（同 run-id 重复 claim 即刷新，不会新开 attempt）：
+
+```text
+python <skills-root>/scripts/harness_change.py claim --change <id> --phase run --run-id <本阶段 run-id> --ttl-seconds 3600 --json
+```
+
+已经报了 `LEASE_ABSENT` 也按同一条命令恢复——错误响应的 `resumeRunId` 就是要用的 run-id；**不要**重跑 `gate begin`，那会新开 attempt 并丢失本轮 capsule。
+
 **执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。
 
 **Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
@@ -123,7 +141,9 @@ disallowed-tools:
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；仅 run-owned P0 静态-only 导致 WARN；test-owned 待办正常移交 |
 | **Worktree** | `requested=true` 时代码只写 worktree |
-| **PowerShell** | 所有 git/构建经 `powershell.exe -NoProfile -Command` |
+| **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑 mvn/gradle/npm test；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
+| **租约** | 阶段超 1 小时按变更簇用原 run-id 续租；`LEASE_ABSENT` 用 `harness_change.py claim` 恢复，不重跑 begin |
+| **PowerShell** | 所有 git 经 `powershell.exe -NoProfile -Command` |
 
 ### 陈旧测试安全修复与精确跟踪
 

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -9041,7 +9041,27 @@ def collect_archive_core_paths(project_root: Path, archive_dir: Path) -> list[st
     return [source.relative_to(root).as_posix() for source, *_ in file_specs]
 
 
-def _archive_source_identity(project_root: Path) -> dict[str, str | None]:
+def _archive_recorded_commit(archive_dir: Path | None) -> str | None:
+    """The commit the archive itself recorded as its endpoint, if any."""
+    if archive_dir is None:
+        return None
+    try:
+        summary = read_json(archive_dir / "reports" / "final" / "summary-data.json")
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    if not isinstance(summary, dict):
+        return None
+    for key in ("finalCommit", "final_commit", "currentHead", "headCommit"):
+        value = summary.get(key)
+        if isinstance(value, str) and re.fullmatch(r"[0-9a-f]{40}", value.strip()):
+            return value.strip()
+    return None
+
+
+def _archive_source_identity(
+    project_root: Path,
+    archive_dir: Path | None = None,
+) -> dict[str, str | None]:
     def git_value(*args: str) -> str | None:
         try:
             completed = subprocess.run(
@@ -9060,6 +9080,15 @@ def _archive_source_identity(project_root: Path) -> dict[str, str | None]:
         value = completed.stdout.strip()
         return value if completed.returncode == 0 and value else None
 
+    # Prefer the archive's own endpoint over live HEAD so the package stays a
+    # pure function of the sealed directory. Falling back to HEAD keeps older
+    # archives that never recorded a commit working exactly as before.
+    recorded = _archive_recorded_commit(archive_dir)
+    if recorded is not None:
+        return {
+            "commit": recorded,
+            "tree": git_value("rev-parse", f"{recorded}^{{tree}}"),
+        }
     return {
         "commit": git_value("rev-parse", "HEAD"),
         "tree": git_value("rev-parse", "HEAD^{tree}"),
@@ -9244,7 +9273,7 @@ def build_archive_package(
         "profile": "core-v1",
         "change_key": change_key,
         "created_at": _archive_created_at(summary_path),
-        "source": _archive_source_identity(project_root),
+        "source": _archive_source_identity(project_root, archive_dir),
         "files": entries,
     }
     manifest_bytes = (
@@ -9482,35 +9511,83 @@ def auto_push_managed_snapshot(project_root: Path) -> dict[str, Any]:
     }
 
 
+def load_retained_package(project_root: Path, change_key: str) -> dict[str, Any] | None:
+    """A package kept on disk for retry, described by its own pending receipt.
+
+    Retrying is only meaningful against the bytes the server already saw. A
+    rebuild is a different package: the archive directory and the harness both
+    move on, so "retry the same ZIP" has to mean exactly that.
+    """
+    packages = project_root / ".harness" / "state" / "local" / "archive-packages"
+    zip_path = packages / f"{change_key}.zip"
+    receipt_path = packages / f"{change_key}.upload.json"
+    if not zip_path.is_file() or not receipt_path.is_file():
+        return None
+    try:
+        receipt = read_json(receipt_path)
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    if not isinstance(receipt, dict):
+        return None
+    recorded = str(receipt.get("packageSha256") or "")
+    actual = "sha256:" + hashlib.sha256(zip_path.read_bytes()).hexdigest()
+    if recorded and recorded != actual:
+        # The receipt no longer describes the file beside it; refuse to guess.
+        return None
+    return {
+        "schemaVersion": 1,
+        "profile": "core-v1",
+        "changeKey": change_key,
+        "packagePath": str(zip_path),
+        "packageSha256": actual,
+        "manifestSha256": receipt.get("manifestSha256"),
+        "fileCount": receipt.get("fileCount"),
+        "sizeBytes": zip_path.stat().st_size,
+        "paths": list(receipt.get("paths") or []),
+        "knowledgeCandidateCount": receipt.get("knowledgeCandidateCount"),
+        "reused": True,
+    }
+
+
 def auto_push_archive_core(
     project_root: Path,
     archive_dir: Path,
     *,
     change_key: str | None = None,
     extra_entries: dict[str, tuple[str, str, bytes]] | None = None,
+    reuse_retained_package: bool = False,
 ) -> dict[str, Any]:
     """Build and upload one deterministic core ZIP after finalize.
 
     The ZIP and its per-change receipt are always created before auth is
     evaluated. Failures become warnings so archive success is never rolled
     back by missing credentials or a remote outage.
+
+    With ``reuse_retained_package`` a package already kept for retry is uploaded
+    as-is instead of being rebuilt, which is what the retry messages promise.
     """
     project_root = project_root.resolve()
     effective_change_key = change_key or archive_dir.name
-    try:
-        package = build_archive_package(
-            project_root,
-            archive_dir,
-            effective_change_key,
-            extra_entries=extra_entries,
-        )
-    except (OSError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
-        return {
-            "skipped": False,
-            "ok": False,
-            "reasonCode": "ARCHIVE_PACKAGE_BUILD_FAILED",
-            "warning": f"核心归档 ZIP 生成失败：{exc}",
-        }
+    package = (
+        load_retained_package(project_root, effective_change_key)
+        if reuse_retained_package
+        else None
+    )
+    if package is None:
+        try:
+            package = build_archive_package(
+                project_root,
+                archive_dir,
+                effective_change_key,
+                extra_entries=extra_entries,
+            )
+        except (OSError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+            return {
+                "skipped": False,
+                "ok": False,
+                "reasonCode": "ARCHIVE_PACKAGE_BUILD_FAILED",
+                "warning": f"核心归档 ZIP 生成失败：{exc}",
+            }
     core_paths = list(package["paths"])
     package_path = Path(str(package["packagePath"]))
     try:
@@ -10346,6 +10423,7 @@ def cmd_republish(
     project_root: Path | None,
     dry_run: bool,
     inject_knowledge: bool = True,
+    retry_retained: bool = False,
 ) -> tuple[int, dict[str, Any]]:
     """Rebuild and re-upload the core ZIP for an already sealed archive.
 
@@ -10405,6 +10483,70 @@ def cmd_republish(
             extra_entries = {}
     payload["knowledgeCandidatesInjected"] = "candidates/knowledge.json" in extra_entries
 
+    if retry_retained:
+        retained = load_retained_package(root, change_key)
+        if retained is None:
+            payload.update({
+                "ok": False,
+                "reasonCode": "ARCHIVE_RETAINED_PACKAGE_UNAVAILABLE",
+                "error": (
+                    "没有可重试的留存包：需要 "
+                    f".harness/state/local/archive-packages/{change_key}.zip 与同名 "
+                    ".upload.json 同时存在，且回执记录的 packageSha256 与 ZIP 字节一致。"
+                ),
+                "nextAction": "去掉 --retry-retained 可按封存目录重建一个新包。",
+            })
+            return 1, payload
+        payload["retainedPackage"] = {
+            "packagePath": retained["packagePath"],
+            "packageSha256": retained["packageSha256"],
+            "fileCount": retained["fileCount"],
+            "sizeBytes": retained["sizeBytes"],
+        }
+        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"
+            and stored_sha
+            and stored_sha != retained["packageSha256"]
+        ):
+            # Identical bytes stay allowed below — re-uploading the same package
+            # is the documented way to retry a failed knowledge index. Different
+            # bytes are refused by the server, so do not spend the upload.
+            payload.update({
+                "ok": False,
+                "reasonCode": "ARCHIVE_REMOTE_IMMUTABLE_CONFLICT",
+                "remoteReceipt": {
+                    "archiveId": durable.get("archiveId"),
+                    "packageSha256": stored_sha,
+                },
+                "error": (
+                    "留存包与远端已发布的包字节不同，服务端对同一 change key 只保存一个"
+                    "不可变包，不接受替换。"
+                ),
+                "nextAction": (
+                    "该留存包是一次失败尝试的残留，不是已发布的那一份；"
+                    "确认无用后可删除 .zip 与 .upload.json。"
+                ),
+            })
+            return 1, payload
+        if dry_run:
+            payload.update({"ok": True, "reasonCode": "ARCHIVE_RETAINED_PACKAGE_PREVIEW"})
+            return 0, payload
+        result = auto_push_archive_core(
+            root,
+            archive_dir,
+            change_key=change_key,
+            reuse_retained_package=True,
+        )
+        payload["push"] = result
+        payload["ok"] = bool(result.get("ok"))
+        payload["reasonCode"] = result.get("reasonCode")
+        if result.get("warning"):
+            payload.setdefault("warnings", []).append(str(result["warning"]))
+        return 0 if payload["ok"] else 1, payload
+
     # 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
@@ -10479,8 +10621,8 @@ def cmd_republish(
                     f"{package['knowledgeCandidateCount']} 条知识候选"
                     "（原包上传时还没有 candidates/knowledge.json），因此字节必然不同——"
                     "已发布归档无法从客户端追加知识条目，需要平台侧提供重新索引或归档版本化能力。"
-                    "若只是想重试同一个包（例如知识索引失败），加 --no-knowledge-injection "
-                    "可重建与封存目录完全一致的字节。"
+                    "若只是想重试同一个包（例如知识索引失败），用 --retry-retained "
+                    "上传盘上留存的原包字节；重建得不到已发布的字节。"
                     if payload.get("knowledgeCandidatesInjected")
                     else "本地归档内容与已上传的包不一致，请先确认哪一份才是应保留的事实。"
                 )
@@ -10513,6 +10655,7 @@ def cmd_republish_cli(args: argparse.Namespace) -> int:
         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),
+        retry_retained=bool(args.retry_retained),
     )
     emit_json(payload)
     return code
@@ -10696,12 +10839,22 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="build the package and report its contents without uploading",
     )
+    p_republish.add_argument(
+        "--retry-retained",
+        action="store_true",
+        help=(
+            "upload the package already kept on disk for retry, byte for byte, "
+            "instead of rebuilding it"
+        ),
+    )
     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"
+            "rebuild without injecting knowledge candidates. Note this does NOT "
+            "reproduce an already-published package: the manifest also binds the "
+            "archive's own commit and the sealed directory may have moved on. To "
+            "retry the exact bytes the server saw, use --retry-retained"
         ),
     )
     p_republish.add_argument("--json", action="store_true", default=True)

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

@@ -1906,6 +1906,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 +2656,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 +2899,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(

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

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

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=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -157,7 +157,11 @@ python <skills-root>/scripts/harness_archive.py republish --change <change-key>
 （exit 0，不重传）；字节不同 → `ARCHIVE_REMOTE_IMMUTABLE_CONFLICT`（exit 1，**不发起上传**）。
 **已发布归档无法从客户端补知识条目**——注入候选必然改变字节，服务端拒绝替换；要补需要平台侧
 提供重新索引或归档版本化能力。
-只想重试**同一个包**（例如知识索引失败）时加 `--no-knowledge-injection`，它按封存目录原样重建，字节与已存包一致。
+只想重试**同一个包**（例如知识索引失败）时用 `--retry-retained`：它上传盘上留存的原包字节，
+不重建。**重建得不到已发布的字节**——包 manifest 绑定归档自己的提交，封存目录与 harness 本身
+也都会前进；`--no-knowledge-injection` 只是不注入候选，不等于能复现旧包。
+留存包与远端字节不同（即那是一次失败尝试的残留）时，`--retry-retained` 同样在本地判出
+`ARCHIVE_REMOTE_IMMUTABLE_CONFLICT` 并拒绝上传。
 
 ### 三、文件移动只用内置工具或 PowerShell
 

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=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

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

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

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

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=3132d081a7790973; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=d1ddcf707a26d7b6; overlay=none; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose