@hunter-harness/workflow-harness 0.2.83 → 0.2.85

package/harness/bundles/java/codex/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codex/harness-plan/SKILL.md

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

package/harness/bundles/java/codex/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/java/codex/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/java/codex/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/codex/harness-run/SKILL.md

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/java/codex/harness-run/protocols.md

@@ -79,3 +79,63 @@ REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回
 ```
 
 RED 问题必须在当前 run 中处理或明确记录为未处理风险；YELLOW 问题可交给后续 `/harness-review`。
+
+## fixback 证据契约
+
+> `launch-review` 的返回体里带 `evidenceContract` 字段，内容与本节一致。这里写一份是因为
+> 光靠运行时返回，调用方往往已经动手改代码了才看到。
+
+### 命令链
+
+```text
+run-start（修复前，采 RED）→ 改代码 → run-start（修复后，采 GREEN）
+  → evidence-template ×2 → register-evidence ×2 → resolve-issue
+  → run-start（受影响链）→ evidence-template --kind verification
+  → evidence-template --kind review → close
+```
+
+### 别手写证据 JSON
+
+证据文件的 `provenance` 需要 `sessionId` / `commandHash` / `resultDigest` / `runReceiptPath`
+四个字段，全部能从 `session.json` 直接读出来。用模板生成，不要手抄：
+
+```text
+python <skills-root>/scripts/harness_fixback.py evidence-template \
+  --change-dir <change-dir> --kind red|green|verification|review \
+  --session <sessionId> --out <证据 JSON 路径> --json
+```
+
+输出即可直接喂给 `register-evidence`。撞 `FIXBACK_RUN_PROVENANCE_INVALID` 时，错误体会点名
+**哪个字段、期望什么、实际什么**——按它改，不要去读实现反推。
+
+### `--product-identity`
+
+产品身份指纹，把 RED/GREEN 绑定到同一产品状态。规范取值是**当前 git HEAD**。省略即自动推导，
+`launch-review` 会在返回体的 `resolvedProductIdentity` 里回显；`close --final-product-identity`
+**原样引用那个值**，不要另行推导——推导方式不同就会撞 `FIXBACK_GREEN_IDENTITY_MISMATCH`。
+
+### RED 必须在修复之前
+
+RED 证明问题真实存在，GREEN 证明修复真的生效。先改完再把改动回退来凑 RED，证明的只是回退后的
+状态，不是原始缺陷，中途还会留下脏工作树。
+
+### close 的两张收据与 review-findings.json
+
+`close` 要 `--affected-receipt`（`kind=verification`，受影响链的托管会话）和 `--review-receipt`
+（`kind=review`，指向 `reports/review/review-findings.json`）。
+
+review 收据的放行规则按 **disposition**，不按 severity：
+
+| disposition | 是否阻塞 | 说明 |
+|---|---|---|
+| `OPEN` / 未登记 | ❌ 阻塞 | 还没人处置，必须先给结论 |
+| `FIXED` / `NOT_APPLICABLE` | ✅ 放行 | 已闭环 |
+| `ACCEPTED_RISK` / `DEFERRED` | ✅ 放行 | 记入收据 `residualRisks` 留痕 |
+
+> ⚠️ **不要为了让 close 通过而清空或删改 `review-findings.json`。** 它是发现的真相源，写空等于
+> 抹掉整轮审查的审计轨迹。处置结论属于另一个 sidecar：
+>
+> ```text
+> python <skills-root>/scripts/harness_review.py write-dispositions \
+>   --change-dir <change-dir> --input <dispositions.json>
+> ```

package/harness/bundles/java/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/codex/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/codex/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=8481b17fd585c343; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -2167,6 +2167,185 @@ def _advisory_sensitive_gate(result: dict[str, Any], policy: str) -> dict[str, A
     }
 
 
+ARCHIVE_EXECUTE_RESULT_REL = Path("meta") / "archive-execute-result.json"
+
+
+def resolve_execute_result_path(change_dir: Path, raw_path: str) -> dict[str, Any]:
+    """校验 `--output`：execute 会移走 change 目录，写进去的结果必然丢失。
+
+    这个错误只能在**动手前**报。等 execute 跑完再发现输出文件不见了，steps 结果
+    已经随目录被移走且无法重建——调用方只剩考古一条路。
+    """
+    change_dir = change_dir.expanduser().resolve()
+    target = Path(raw_path).expanduser()
+    target = target if target.is_absolute() else (Path.cwd() / target)
+    target = target.resolve()
+    try:
+        target.relative_to(change_dir)
+    except ValueError:
+        return {"ok": True, "path": str(target)}
+    suggestion = change_dir.parent / f"{change_dir.name}-archive-result.json"
+    return {
+        "ok": False,
+        "reasonCode": "ARCHIVE_RESULT_PATH_VOLATILE",
+        "path": str(target),
+        "changeDir": str(change_dir),
+        "recoveryAction": (
+            f"归档会把 {change_dir} 整个移进 .harness/archive/，写在它内部的输出文件"
+            f"会随之消失。把 --output 指到目录之外，例如 {suggestion}；"
+            "归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。"
+        ),
+    }
+
+
+def persist_execute_result(archive_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
+    """把 execute 的完整结果写进归档目录——移动之后的位置，不会再被搬走。
+
+    调用方此前只能靠 shell 重定向抓 stdout，而唯一"顺手"的落点（change 目录）正是
+    要被移走的那个。结果落盘在归档里，并把路径回显进 payload，重定向就不再必要。
+    """
+    archive_dir = archive_dir.expanduser().resolve()
+    path = archive_dir / ARCHIVE_EXECUTE_RESULT_REL
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, default=str) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+    except (OSError, TypeError, ValueError) as exc:
+        return {"ok": False, "reasonCode": "ARCHIVE_RESULT_WRITE_FAILED", "error": str(exc)}
+    payload["resultPath"] = str(path)
+    return {"ok": True, "path": str(path)}
+
+
+def publication_member_paths(source_dir: Path) -> list[str]:
+    """归档包会包含哪些文件——由 `_archive_core_file_specs` 单一定义，不另起一套。
+
+    包成员在 execute 之前就已确定：`reports/final/summary-data.json`、`spec/**.md`、
+    `plans/**.md`、`candidates/knowledge.json`、`meta/archive-meta.md`、
+    `meta/change-context.json`。其中 summary-data.json / archive-meta.md 由 execute
+    生成，预检时尚不存在，会被自动跳过——它们是机器产物，承载不了人写的敏感串。
+    """
+    project_root = find_project_root(source_dir)
+    try:
+        _, _, specs = _archive_core_file_specs(project_root, source_dir)
+    except (OSError, ValueError):
+        return []
+    return sorted(package_path for _, package_path, _, _ in specs)
+
+
+def precheck_publication_content(
+    source_dir: Path,
+    *,
+    timeout_seconds: int = 60,
+) -> dict[str, Any]:
+    """用**发布同款规则**扫描**会被发布的那批文件**，在归档开始时就给出结论。
+
+    此前这两件事都不成立：本地跑的是 harness_runtime 自建的赋值式正则，扫的是整棵
+    change 树（含从不入包的 runtime/）；服务端跑的是 packages/core 的
+    `scanSensitiveFiles`，扫的是 ZIP 里那几个文件。范围与规则双双错位，于是本地在
+    草稿上误报阻塞，真正会被拒的设计文档一个字没查——直到 upload 收到 422。
+
+    这里改为调用 CLI 的 `scan-sensitive`（直接复用 core 的导出），保证与服务端同源。
+    CLI 不可用时降级为警告：预检本身不该变成新的卡点。
+    """
+    members = publication_member_paths(source_dir)
+    if not members:
+        return {
+            "ok": True,
+            "reasonCode": "PUBLICATION_CONTENT_SCAN_EMPTY",
+            "blocked": False,
+            "findings": [],
+            "members": [],
+        }
+    project_root = find_project_root(source_dir)
+    try:
+        prefix = resolve_hunter_cli_command(project_root)
+    except (FileNotFoundError, OSError) as exc:
+        return _publication_scan_unavailable(members, str(exc))
+    command = [*prefix, "scan-sensitive", "--root", str(source_dir), "--json"]
+    for member in members:
+        command.extend(["--file", member])
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return _publication_scan_unavailable(members, str(exc))
+    try:
+        report = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        return _publication_scan_unavailable(
+            members, f"scan-sensitive output was not JSON: {exc}"
+        )
+    if not isinstance(report, dict) or "findings" not in report:
+        return _publication_scan_unavailable(
+            members, "scan-sensitive output missing findings"
+        )
+    findings = [item for item in report.get("findings") or [] if isinstance(item, dict)]
+    blocked = [item for item in findings if item.get("disposition") == "blocked"]
+    hard = [item for item in blocked if item.get("overridable") is False]
+    return {
+        "ok": True,
+        "reasonCode": (
+            "PUBLICATION_CONTENT_SCAN_FLAGGED" if blocked
+            else "PUBLICATION_CONTENT_SCAN_CLEAN"
+        ),
+        "scannerVersion": report.get("scanner_version"),
+        "members": members,
+        "blocked": bool(blocked),
+        "hardBlocked": bool(hard),
+        "findings": findings,
+        "nextAction": _publication_scan_next_action(blocked, hard),
+    }
+
+
+def _publication_scan_unavailable(members: list[str], error: str) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "reasonCode": "PUBLICATION_CONTENT_SCAN_UNAVAILABLE",
+        "blocked": False,
+        "findings": [],
+        "members": members,
+        "error": error,
+        "message": (
+            "无法运行发布内容预检（hunter-harness CLI 不可用）。归档继续，但上传时"
+            "仍可能被服务端以 422 拒收；装好 CLI 后可用 "
+            "`hunter-harness scan-sensitive` 单独复查。"
+        ),
+    }
+
+
+def _publication_scan_next_action(
+    blocked: list[dict[str, Any]], hard: list[dict[str, Any]]
+) -> str:
+    if not blocked:
+        return "发布内容预检通过。"
+    if hard:
+        names = ", ".join(
+            f"{item.get('path')}:{item.get('line')} {item.get('rule_id')}"
+            for item in hard
+        )
+        return (
+            f"以下命中不可豁免（high）：{names}。必须真正脱敏后重新打包，"
+            "不要用行内标注绕过。"
+        )
+    lines = "; ".join(
+        str(item.get("recovery_action") or "") for item in blocked
+    )
+    return (
+        "服务端会以同款规则拒收这些内容（HTTP 422）。若确属设计固有内容，"
+        f"按下列写法加行内标注后重新打包：{lines}"
+    )
+
+
 def validate_sensitive_evidence_publication_gate(
     change_dir: Path,
     *,
@@ -2194,7 +2373,11 @@ def validate_sensitive_evidence_publication_gate(
             "receiptPath": str(receipt_path),
             "unresolvedFailures": [],
         }
-    candidates = hruntime.sensitive_evidence_candidates(change_dir)
+    # 只扫会被发布出去的字节。runtime/ 是各阶段草稿（review 的 diff、临时校验脚本、
+    # 命令输出），从不进归档包——拿它挡发布，挡的是永远不会离开本机的内容。
+    candidates = hruntime.sensitive_evidence_candidates(
+        change_dir, exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS
+    )
     if candidates:
         return _advisory_sensitive_gate(
             {
@@ -2265,8 +2448,17 @@ def validate_sensitive_evidence_publication_gate(
         issues.append({"code": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED", "count": len(unresolved)})
     elif unresolved not in (None, []):
         issues.append({"code": "SECRET_SCAN_UNRESOLVED_INVALID"})
+    # 用收据自己声明的排除项复算，两侧口径才一致；写死一套常量会让旧收据
+    # 在升级后集体报 digest 漂移。
+    receipt_excluded = receipt.get("publicationExcludedDirs")
+    if not isinstance(receipt_excluded, list) or any(
+        not isinstance(item, str) for item in receipt_excluded
+    ):
+        receipt_excluded = []
     try:
-        actual_digest = hruntime.publishable_tree_digest(change_dir)
+        actual_digest = hruntime.publishable_tree_digest(
+            change_dir, exclude_dirs=tuple(receipt_excluded)
+        )
     except OSError as exc:
         actual_digest = None
         issues.append({"code": "SECRET_SCAN_TREE_UNREADABLE", "error": str(exc)})
@@ -2407,6 +2599,13 @@ def check_status(
             }
         )
 
+    checks["publication_content_scan"] = {
+        "ok": True,
+        "scan_performed": False,
+        "findings": [],
+        "message": "上传归档链路已停用内容敏感扫描；保留路径、凭据与 ZIP 安全校验。",
+    }
+
     sensitive_gate = validate_sensitive_evidence_publication_gate(
         change_dir,
         copy_root=change_dir,
@@ -7842,6 +8041,7 @@ def cmd_finalize(
     source_sensitive_refresh = hruntime.refresh_sensitive_evidence_scan_receipt(
         original_change_dir,
         persist=False,
+        exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS,
     )
     payload["steps"]["sensitive_evidence_source_refresh"] = source_sensitive_refresh
     if not source_sensitive_refresh.get("ok"):
@@ -7981,7 +8181,8 @@ def cmd_finalize(
                 "stateDir": str(split_state_dir),
             }
         staged_sensitive_refresh = hruntime.refresh_sensitive_evidence_scan_receipt(
-            work_dir
+            work_dir,
+            exclude_dirs=hruntime.PUBLICATION_EXCLUDED_DIRS,
         )
         payload["steps"][
             "sensitive_evidence_staging_refresh"
@@ -8742,6 +8943,12 @@ def cmd_finalize(
     payload["finalStatus"] = "OK"
     payload["warnings"] = warnings
     payload["summary_data"] = str(summary_path)
+    # 结果落在归档里（移动之后的位置），调用方不必再靠 shell 重定向去接 stdout。
+    persisted = persist_execute_result(archive_dir, payload)
+    if not persisted.get("ok"):
+        warnings.append(
+            f"could not persist archive execute result: {persisted.get('error')}"
+        )
     return 0, payload
 
 
@@ -9190,6 +9397,9 @@ def resolve_hunter_cli_command(project_root: Path) -> list[str]:
     """Command prefix that runs the hunter-harness CLI, cheapest route first."""
     node = shutil.which("node")
     if node:
+        current_entry = os.environ.get("HUNTER_HARNESS_CLI_ENTRY", "").strip()
+        if current_entry and Path(current_entry).is_file():
+            return [node, str(Path(current_entry).resolve())]
         entry = _installed_cli_entry(project_root)
         if entry is not None:
             return [node, str(entry)]
@@ -9556,6 +9766,7 @@ def auto_push_archive_core(
     change_key: str | None = None,
     extra_entries: dict[str, tuple[str, str, bytes]] | None = None,
     reuse_retained_package: bool = False,
+    prepared_package: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Build and upload one deterministic core ZIP after finalize.
 
@@ -9568,11 +9779,13 @@ def auto_push_archive_core(
     """
     project_root = project_root.resolve()
     effective_change_key = change_key or archive_dir.name
-    package = (
-        load_retained_package(project_root, effective_change_key)
-        if reuse_retained_package
-        else None
-    )
+    package = prepared_package
+    if package is None:
+        package = (
+            load_retained_package(project_root, effective_change_key)
+            if reuse_retained_package
+            else None
+        )
     if package is None:
         try:
             package = build_archive_package(
@@ -10120,9 +10333,45 @@ def cmd_certify_local_cli(args: argparse.Namespace) -> int:
     return 0
 
 
+def _emit_with_optional_output(args: argparse.Namespace, payload: dict[str, Any]) -> int | None:
+    """Write the result to --output, refusing a path the archive will delete."""
+    raw = getattr(args, "output", None)
+    if not raw:
+        return None
+    resolved = resolve_execute_result_path(resolve_path(args.change_dir), str(raw))
+    if not resolved.get("ok"):
+        emit_json(resolved)
+        return 2
+    try:
+        target = Path(resolved["path"])
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, default=str) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+    except (OSError, TypeError, ValueError) as exc:
+        emit_json({
+            "ok": False,
+            "reasonCode": "ARCHIVE_RESULT_WRITE_FAILED",
+            "path": resolved["path"],
+            "error": str(exc),
+        })
+        return 2
+    payload["resultPath"] = resolved["path"]
+    return None
+
+
 def cmd_finalize_cli(args: argparse.Namespace) -> int:
     change_dir = resolve_path(args.change_dir)
     archive_root = resolve_path(args.archive_root)
+    # 先验路径再干活：跑完才发现输出落点会被移走，结果已经无法重建。
+    raw_output = getattr(args, "output", None)
+    if raw_output:
+        resolved = resolve_execute_result_path(change_dir, str(raw_output))
+        if not resolved.get("ok"):
+            emit_json(resolved)
+            return 2
     durable_root = (
         resolve_path(args.durable_root)
         if getattr(args, "durable_root", None)
@@ -10141,6 +10390,9 @@ def cmd_finalize_cli(args: argparse.Namespace) -> int:
         closure_disposition=str(getattr(args, "closure", "completed")),
         closure_reason=str(getattr(args, "closure_reason", "")),
     )
+    failure = _emit_with_optional_output(args, payload)
+    if failure is not None:
+        return failure
     emit_json(payload)
     return code
 
@@ -10151,6 +10403,14 @@ def cmd_execute_cli(args: argparse.Namespace) -> int:
         if getattr(args, "durable_root", None)
         else None
     )
+    raw_output = getattr(args, "output", None)
+    if raw_output:
+        resolved = resolve_execute_result_path(
+            resolve_path(args.change_dir), str(raw_output)
+        )
+        if not resolved.get("ok"):
+            emit_json(resolved)
+            return 2
     code, payload = execute_archive(
         resolve_path(args.change_dir),
         resolve_path(args.archive_root),
@@ -10164,6 +10424,9 @@ def cmd_execute_cli(args: argparse.Namespace) -> int:
         closure_disposition=str(getattr(args, "closure", "completed")),
         closure_reason=str(getattr(args, "closure_reason", "")),
     )
+    failure = _emit_with_optional_output(args, payload)
+    if failure is not None:
+        return failure
     emit_json(payload)
     return code
 
@@ -10369,6 +10632,28 @@ def resolve_archive_dir_for_change(
     return archive_root / matches[-1], matches
 
 
+def resolve_latest_unpublished_archive(project_root: Path) -> tuple[str | None, list[str]]:
+    """Choose the newest sealed archive without a durable local receipt."""
+    archive_root = project_root / ".harness" / "archive"
+    if not archive_root.is_dir():
+        return None, []
+    candidates: list[tuple[str, str]] = []
+    for entry in archive_root.iterdir():
+        if not entry.is_dir():
+            continue
+        change = entry.name
+        try:
+            summary = read_json(entry / "reports" / "final" / "summary-data.json")
+            if isinstance(summary, dict) and isinstance(summary.get("changeName"), str):
+                change = str(summary["changeName"]).strip() or change
+        except (OSError, ValueError, json.JSONDecodeError):
+            pass
+        if read_durable_archive_receipt(project_root, change) is None:
+            candidates.append((entry.name, change))
+    candidates.sort(reverse=True)
+    return (candidates[0][1] if candidates else None), [item[1] for item in candidates]
+
+
 def _republish_knowledge_entry(archive_dir: Path) -> dict[str, tuple[str, str, bytes]]:
     """Knowledge candidates for archives sealed before the candidates step.
 
@@ -10439,12 +10724,26 @@ def cmd_republish(
         "changeKey": change_key,
         "dryRun": dry_run,
     }
+    root = resolve_republish_project_root(project_root, archive_dir)
+    if change_key == "latest":
+        selected, available = resolve_latest_unpublished_archive(root)
+        if selected is None:
+            payload.update({
+                "ok": True,
+                "reasonCode": "ARCHIVE_NO_UNPUBLISHED_ARCHIVE",
+                "noChanges": True,
+                "availableChanges": available,
+                "projectRoot": str(root)
+            })
+            return 0, payload
+        change_key = selected
+        payload["changeKey"] = change_key
+        payload["selectedChange"] = selected
     if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,159}", change_key) is None:
         payload["error"] = "change key must be a portable path segment"
         payload["reasonCode"] = "ARCHIVE_CHANGE_KEY_INVALID"
         return 2, payload
 
-    root = resolve_republish_project_root(project_root, archive_dir)
     payload["projectRoot"] = str(root)
     matches: list[str] = []
     if archive_dir is None:
@@ -10553,7 +10852,7 @@ def cmd_republish(
     # distinct name; it must never be mistaken for a pending upload.
     preview_path = (
         root / ".harness" / "state" / "local" / "archive-packages"
-        / f"{change_key}.preview.zip"
+        / f"{change_key}{'.preview.zip' if dry_run else '.zip'}"
     )
     try:
         package = build_archive_package(
@@ -10569,7 +10868,8 @@ def cmd_republish(
         return 1, payload
     finally:
         try:
-            preview_path.unlink(missing_ok=True)
+            if dry_run:
+                preview_path.unlink(missing_ok=True)
         except OSError:
             pass
 
@@ -10639,6 +10939,7 @@ def cmd_republish(
         archive_dir,
         change_key=change_key,
         extra_entries=extra_entries,
+        prepared_package=package,
     )
     payload["push"] = result
     payload["ok"] = bool(result.get("ok"))
@@ -10771,6 +11072,7 @@ def build_parser() -> argparse.ArgumentParser:
         default="release-candidate",
         help="release-candidate enforces candidate evidence; record-only archives facts without release eligibility",
     )
+    p_fin.add_argument("--output", default=None, help="把完整结果另存到该路径。**不得**指向 --change-dir 内部：归档会把该目录整个移走，写在里面的文件必然丢失。归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。")
     p_fin.add_argument("--json", action="store_true", default=True)
     p_fin.set_defaults(func=cmd_finalize_cli)
 
@@ -10795,6 +11097,7 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("release-candidate", "record-only"),
         default="release-candidate",
     )
+    p_execute.add_argument("--output", default=None, help="把完整结果另存到该路径。**不得**指向 --change-dir 内部：归档会把该目录整个移走，写在里面的文件必然丢失。归档成功后结果也会自动落在 <archiveDir>/meta/archive-execute-result.json。")
     p_execute.add_argument("--json", action="store_true", default=True)
     p_execute.set_defaults(func=cmd_execute_cli)