@hunter-harness/workflow-harness 0.2.53 → 0.2.55

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

@@ -23,6 +23,8 @@ PHASE_GRAPH = {
     "submit": (),
 }
 
+DISPLAY_TITLE_MAX_LENGTH = 80
+
 
 def _now() -> dt.datetime:
     return dt.datetime.now(dt.timezone.utc)
@@ -35,6 +37,41 @@ def _read_json(path: Path) -> dict[str, Any]:
     return data
 
 
+def _normalize_display_title(value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError("display title must be text")
+    title = value.strip()
+    if not title:
+        raise ValueError("display title must not be empty")
+    if len(title) > DISPLAY_TITLE_MAX_LENGTH:
+        raise ValueError(
+            f"display title exceeds {DISPLAY_TITLE_MAX_LENGTH} characters"
+        )
+    if any(ord(character) < 32 or ord(character) == 127 for character in title):
+        raise ValueError("display title contains control characters")
+    return title
+
+
+def _ensure_display_title(contract_root: Path, value: Any) -> str | None:
+    path = contract_root / "meta" / "change-title.json"
+    if path.is_file():
+        payload = _read_json(path)
+        return _normalize_display_title(payload.get("displayTitle"))
+    title = _normalize_display_title(value)
+    if title is None:
+        return None
+    _write_json_atomic(
+        path,
+        {
+            "schemaVersion": 1,
+            "displayTitle": title,
+        },
+    )
+    return title
+
+
 def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, raw = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent))
@@ -243,6 +280,7 @@ def prepare_context(
     phase: str,
     executor: str,
     change: str | None = None,
+    display_title: str | None = None,
     ttl_seconds: int = 3600,
 ) -> dict[str, Any]:
     project = Path(project).resolve()
@@ -265,6 +303,16 @@ def prepare_context(
         contract_root, contract, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return {"ok": False, "code": str(exc).split(":", 1)[0], "error": str(exc)}
+    try:
+        resolved_display_title = _ensure_display_title(
+            contract_root, display_title
+        )
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "DISPLAY_TITLE_INVALID",
+            "error": str(exc),
+        }
     lifecycle = contract.get("lifecycle")
     if (
         isinstance(lifecycle, dict)
@@ -343,6 +391,7 @@ def prepare_context(
             "executionRoot": str(execution_root),
             "preparedAt": now.isoformat(),
             "receiptHash": latest.get("receiptHash") if latest else None,
+            "displayTitle": resolved_display_title,
         },
     )
     next_phases = (
@@ -363,6 +412,7 @@ def prepare_context(
         "latestTransition": latest,
         "lease": lease,
         "recovery": recovery,
+        "displayTitle": resolved_display_title,
     }
 
 
@@ -424,7 +474,7 @@ def close_transition(
     *,
     from_phase: str,
     to_phase: str,
-    executor: str,
+    executor: str | None,
     artifacts: list[str] | None = None,
     status: str = "OK",
 ) -> dict[str, Any]:
@@ -441,13 +491,81 @@ def close_transition(
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
     paths = _paths(state_root)
+
+    artifact_entries: list[dict[str, Any]] = []
+    for raw in artifacts or []:
+        requested = Path(raw)
+        candidates = (
+            [requested]
+            if requested.is_absolute()
+            else [project / requested, contract_root / requested]
+        )
+        valid: list[Path] = []
+        for candidate in candidates:
+            try:
+                resolved_candidate = candidate.resolve()
+            except OSError:
+                continue
+            if resolved_candidate in valid:
+                continue
+            if resolved_candidate.is_relative_to(project) and resolved_candidate.is_file():
+                valid.append(resolved_candidate)
+        if len(valid) > 1:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_AMBIGUOUS",
+                "path": raw,
+                "candidates": [item.relative_to(project).as_posix() for item in valid],
+                "message": "relative artifact exists under both project and change roots",
+            }
+        if not valid:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_INVALID",
+                "path": raw,
+                "acceptedBases": [str(project), str(contract_root)],
+                "examples": [
+                    str(contract_root / "meta" / "plan-finalization.json"),
+                    f".harness/changes/{change}/meta/plan-finalization.json",
+                    "meta/plan-finalization.json",
+                ],
+            }
+        resolved_artifact = valid[0]
+        artifact_entries.append(
+            {
+                "path": resolved_artifact.relative_to(project).as_posix(),
+                "sha256": _sha256(resolved_artifact),
+            }
+        )
+
+    transitions = _read_ndjson(paths["transitions"])
     if not paths["lease"].is_file():
+        latest = transitions[-1] if transitions else None
+        if (
+            isinstance(latest, dict)
+            and latest.get("fromPhase") == from_phase
+            and latest.get("toPhase") == to_phase
+            and latest.get("status") == status
+            and latest.get("artifacts") == artifact_entries
+            and (executor is None or latest.get("executor") == executor)
+        ):
+            return {
+                "ok": True,
+                "code": "TRANSITION_ALREADY_CLOSED",
+                "idempotent": True,
+                "receipt": latest,
+                "path": str(paths["transitions"]),
+                "invalidation": None,
+            }
         return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
     try:
         lease = _read_json(paths["lease"])
     except (OSError, ValueError, json.JSONDecodeError):
         return {"ok": False, "code": "CONTEXT_LEASE_INVALID"}
-    if lease.get("owner") != executor or lease.get("phase") != from_phase:
+    effective_executor = executor or str(lease.get("owner") or "")
+    if not effective_executor:
+        return {"ok": False, "code": "CONTEXT_EXECUTOR_REQUIRED"}
+    if lease.get("owner") != effective_executor or lease.get("phase") != from_phase:
         return {
             "ok": False,
             "code": "CONTEXT_LEASE_MISMATCH",
@@ -458,25 +576,6 @@ def close_transition(
     if expiry is None or _now() >= expiry:
         return {"ok": False, "code": "CONTEXT_LEASE_EXPIRED"}
 
-    artifact_entries: list[dict[str, Any]] = []
-    for raw in artifacts or []:
-        path = Path(raw)
-        if not path.is_absolute():
-            path = contract_root / path
-        resolved = path.resolve()
-        if not resolved.is_relative_to(project) or not resolved.is_file():
-            return {
-                "ok": False,
-                "code": "TRANSITION_ARTIFACT_INVALID",
-                "path": str(path),
-            }
-        artifact_entries.append(
-            {
-                "path": resolved.relative_to(project).as_posix(),
-                "sha256": _sha256(resolved),
-            }
-        )
-    transitions = _read_ndjson(paths["transitions"])
     previous_hash = transitions[-1].get("receiptHash") if transitions else None
     attempt = (
         1
@@ -493,7 +592,7 @@ def close_transition(
         "fromPhase": from_phase,
         "toPhase": to_phase,
         "status": status,
-        "executor": executor,
+        "executor": effective_executor,
         "productCommit": _head(project),
         "artifacts": artifact_entries,
         "attempt": attempt,
@@ -657,6 +756,7 @@ def build_parser() -> argparse.ArgumentParser:
     prepare.add_argument("--change")
     prepare.add_argument("--phase", required=True)
     prepare.add_argument("--executor", required=True)
+    prepare.add_argument("--title")
     prepare.add_argument("--ttl-seconds", type=int, default=3600)
     close = sub.add_parser("close")
     close.add_argument("--json", action="store_true")
@@ -688,6 +788,7 @@ def main(argv: list[str] | None = None) -> int:
             phase=args.phase,
             executor=args.executor,
             change=args.change,
+            display_title=args.title,
             ttl_seconds=args.ttl_seconds,
         )
     elif args.command == "close":

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

@@ -41,7 +41,7 @@ def _project_root_for_change(change_dir: Path) -> Path | None:
     return None
 
 
-def _nudge_remote_sync(change_dir: Path) -> None:
+def nudge_remote_sync(change_dir: Path) -> None:
     """Best-effort wake-up after the event append has been flushed to disk."""
     project_root = _project_root_for_change(change_dir)
     if project_root is None:
@@ -55,6 +55,11 @@ def _nudge_remote_sync(change_dir: Path) -> None:
         return
 
 
+def _nudge_remote_sync(change_dir: Path) -> None:
+    """Compatibility wrapper for older callers and focused tests."""
+    nudge_remote_sync(change_dir)
+
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8")
 if hasattr(sys.stderr, "reconfigure"):
@@ -121,6 +126,12 @@ OPTIONAL_FIELDS = (
     "renamed_from",
     "renamed_to",
     "change_uuid",
+    "execution_mode",
+    "decision_reason_code",
+    "fallback_reason_code",
+    "trigger",
+    "from_phase",
+    "result_status",
 )
 
 _PROVENANCE_FIELDS = frozenset(
@@ -139,6 +150,12 @@ _PROVENANCE_FIELDS = frozenset(
         "orchestration_active_ms",
         "wall_clock_ms",
         "user_wait_ms",
+        "execution_mode",
+        "decision_reason_code",
+        "fallback_reason_code",
+        "trigger",
+        "from_phase",
+        "result_status",
     }
 )
 _EVENT_ALLOWED_FIELDS = {
@@ -1698,6 +1715,22 @@ def append_with_auto_seal(
                 else []
             )
         )
+        if event_type in {"phase.start", "phase.end", "phase.auto_sealed"} and phase:
+            phase_attempts = split_phase_attempts(
+                [item for item in loaded if item.get("phase") == phase]
+            )
+            latest_attempt = max(
+                (
+                    int(item.get("attempt"))
+                    for item in phase_attempts
+                    if isinstance(item.get("attempt"), int)
+                ),
+                default=0,
+            )
+            if not isinstance(event.get("attempt"), int) or int(event["attempt"]) <= 0:
+                event["attempt"] = (
+                    latest_attempt + 1 if event_type == "phase.start" else latest_attempt or 1
+                )
         if event_type == "phase.start" and phase:
             auto_sealed = seal_open_phase_attempts(loaded, phase=phase)
             for seal_event in auto_sealed:
@@ -1967,6 +2000,12 @@ def build_parser() -> argparse.ArgumentParser:
     p_append.add_argument("--orchestration-active-ms", type=int, default=None)
     p_append.add_argument("--wall-clock-ms", type=int, default=None)
     p_append.add_argument("--user-wait-ms", type=int, default=None)
+    p_append.add_argument("--execution-mode", default=None)
+    p_append.add_argument("--decision-reason-code", default=None)
+    p_append.add_argument("--fallback-reason-code", default=None)
+    p_append.add_argument("--trigger", default=None)
+    p_append.add_argument("--from-phase", default=None)
+    p_append.add_argument("--result-status", default=None)
     p_append.add_argument(
         "--legacy-lenient",
         action="store_true",

package/harness/bundles/java/claude-code/scripts/harness_events_sync.py

@@ -40,6 +40,7 @@ WHITELIST = {
     "phase",
     "status",
     "note",
+    "message",
     "attempt",
     "name",
     "code",
@@ -49,11 +50,34 @@ WHITELIST = {
     "exit_code",
     "duration_ms",
     "schemaVersion",
+    "summary",
+    "executor_tool",
+    "executor_agent",
+    "executor_model",
+    "execution_mode",
+    "decision_reason_code",
+    "fallback_reason_code",
+    "trigger",
+    "from_phase",
+    "result_status",
 }
 
 MAX_BATCH_SIZE = 100
 ACCEPTED_STATUSES = {"accepted", "duplicate_accepted"}
 QUARANTINE_STATUSES = {"id_conflict", "rejected", "rejected_schema"}
+DISPLAY_TITLE_MAX_LENGTH = 200
+EVENT_SUMMARY_MAX_LENGTH = 500
+
+PHASE_LABELS = {
+    "plan": "计划",
+    "run": "编码",
+    "test": "测试",
+    "review": "评审",
+    "package": "打包",
+    "apidoc": "接口文档",
+    "submit": "提交",
+    "archive": "归档",
+}
 
 
 def _yaml_scalar(text: str, key: str) -> str | None:
@@ -87,8 +111,162 @@ def load_endpoint(project: Path) -> dict[str, str] | None:
     }
 
 
+def _summary_text(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    text = re.sub(r"\s+", " ", value).strip()
+    text = "".join(character for character in text if ord(character) >= 32 and ord(character) != 127)
+    return text[:EVENT_SUMMARY_MAX_LENGTH].rstrip()
+
+
+_MACHINE_DETAIL_RE = re.compile(
+    r"(?:\s*[；;,，]?\s*)"
+    r"(?:artifactsHash|artifactHash|receiptHash|content_sha256|contentSha256)"
+    r"\s*[:=]\s*(?:sha256:)?[0-9a-f]{32,64}",
+    re.IGNORECASE,
+)
+
+
+def _readable_summary_text(value: Any) -> str:
+    text = _summary_text(value)
+    if not text:
+        return ""
+    text = _MACHINE_DETAIL_RE.sub("", text)
+    text = re.sub(
+        r"\bfinalize\s+ok\b",
+        "规划产物已校验并发布",
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(r"\s*([；;，,])\s*([；;，,])", r"\1", text)
+    return _summary_text(text.strip(" ；;，,"))
+
+
+def build_event_summary(event: dict[str, Any]) -> str:
+    explicit = _readable_summary_text(event.get("summary"))
+    if explicit:
+        return explicit
+
+    event_type = _summary_text(event.get("type"))
+    phase = _summary_text(event.get("phase"))
+    phase_label = PHASE_LABELS.get(phase, phase or "当前")
+    note = _readable_summary_text(event.get("note"))
+    message = _readable_summary_text(event.get("message"))
+    decision = _readable_summary_text(event.get("decision"))
+    reason = _readable_summary_text(event.get("reason"))
+    name = _readable_summary_text(event.get("name"))
+    code = _readable_summary_text(event.get("code"))
+    status = _summary_text(event.get("status"))
+
+    if event_type == "decision" and decision:
+        return _summary_text(f"{decision}；原因：{reason}" if reason else decision)
+    if event_type == "issue":
+        detail = message or note or code
+        if detail and reason and reason != detail:
+            return _summary_text(f"{detail}；原因：{reason}")
+        return detail or "发现一项需要处理的问题。"
+    if event_type == "issue.resolve":
+        detail = message or note or code
+        return _summary_text(f"问题已解决：{detail}" if detail else "已解决此前记录的问题。")
+    if event_type == "phase.start":
+        return _summary_text(
+            f"开始执行{phase_label}阶段：{note}" if note else f"开始执行{phase_label}阶段。"
+        )
+    if event_type in {"phase.end", "phase.auto_sealed"}:
+        detail = note or status
+        return _summary_text(
+            f"{phase_label}阶段已结束：{detail}" if detail else f"{phase_label}阶段已结束。"
+        )
+    if event_type == "command":
+        detail = name or note
+        return _summary_text(f"执行步骤：{detail}" if detail else "执行了一项工作步骤。")
+    if event_type == "verification":
+        detail = name or note or status
+        return _summary_text(f"完成验证：{detail}" if detail else "完成了一项结果验证。")
+    if event_type == "artifact":
+        detail = name or note
+        return _summary_text(f"生成或更新产物：{detail}" if detail else "生成或更新了一项交付内容。")
+    if event_type == "correction":
+        detail = note or reason or message
+        return _summary_text(f"调整执行方式：{detail}" if detail else "根据当前结果调整了执行方式。")
+    if event_type == "change.rename":
+        return note or message or "更新了变更名称。"
+    if event_type in {"recovery", "phase.recovery", "attempt.recovery"}:
+        return note or reason or message or "恢复了中断的运行状态。"
+    if event_type == "heartbeat":
+        return "客户端保持在线，并同步了最新运行状态。"
+
+    return note or message or name or reason or code or "记录了一项运行事件。"
+
+
 def sanitize(event: dict[str, Any]) -> dict[str, Any]:
-    return {key: event[key] for key in WHITELIST if key in event}
+    payload = {key: event[key] for key in WHITELIST if key in event}
+    payload["summary"] = build_event_summary(event)
+    return payload
+
+
+def _valid_display_title(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    title = value.strip()
+    if (
+        not title
+        or len(title) > DISPLAY_TITLE_MAX_LENGTH
+        or any(ord(character) < 32 or ord(character) == 127 for character in title)
+    ):
+        return None
+    return title
+
+
+def _safe_file_within(change_dir: Path, path: Path) -> Path | None:
+    try:
+        root = change_dir.resolve()
+        resolved = path.resolve()
+    except OSError:
+        return None
+    if path.is_symlink() or not resolved.is_relative_to(root) or not resolved.is_file():
+        return None
+    return resolved
+
+
+def load_display_title(change_dir: Path, change_key: str) -> str:
+    metadata_path = _safe_file_within(
+        change_dir, change_dir / "meta" / "change-title.json"
+    )
+    if metadata_path is not None:
+        try:
+            payload = json.loads(metadata_path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            payload = None
+        if isinstance(payload, dict):
+            title = _valid_display_title(payload.get("displayTitle"))
+            if title is not None:
+                return title
+
+    # Legacy migration: older Plan runs already wrote a human title into the
+    # approved design H1 but had no structured title metadata.
+    design_path = _safe_file_within(
+        change_dir, change_dir / "spec" / f"{change_key}-design.md"
+    )
+    if design_path is not None:
+        try:
+            with design_path.open("r", encoding="utf-8-sig") as stream:
+                for _ in range(40):
+                    line = stream.readline()
+                    if not line:
+                        break
+                    if not line.startswith("# "):
+                        continue
+                    candidate = re.sub(
+                        r"\s+(?:设计文档|设计方案|设计)$", "", line[2:].strip()
+                    )
+                    title = _valid_display_title(candidate)
+                    if title is not None and title != change_key:
+                        return title
+                    break
+        except OSError:
+            pass
+    return change_key
 
 
 def cursor_path(change_dir: Path) -> Path:
@@ -252,6 +430,7 @@ def sync_change(
     resolved_key = change_key or change_dir.name
     rid = run_id or run_id_for(change_dir)
     project_id = endpoint["project_id"]
+    display_title = load_display_title(change_dir, resolved_key)
 
     # Always heartbeat so the console can separate connection vs run status.
     try:
@@ -264,7 +443,7 @@ def sync_change(
                 "run_id": rid,
                 "change_key": resolved_key,
                 "client_time": client_time,
-                "title": resolved_key,
+                "title": display_title,
             },
         )
     except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
@@ -337,7 +516,7 @@ def sync_change(
                         "protocol_version": "hunter-progress-sync/v1",
                         "run_id": rid,
                         "change_key": resolved_key,
-                        "title": resolved_key,
+                        "title": display_title,
                         "events": batch,
                     },
                 )
@@ -607,6 +786,39 @@ def _discover_changes(project_root: Path) -> list[Path]:
     return sorted(path for path in root.glob("*") if path.is_dir()) if root.is_dir() else []
 
 
+def _change_has_open_phase(change_dir: Path) -> bool:
+    """Project the append-only stream into open/closed phase state."""
+    try:
+        path = Path(harness_paths.resolve_state_dir_for_contract(change_dir)) / "events.ndjson"
+    except (OSError, ValueError):
+        return False
+    if not path.is_file():
+        return False
+    open_phases: dict[str, bool] = {}
+    try:
+        for line in path.read_text(encoding="utf-8-sig").splitlines():
+            if not line.strip():
+                continue
+            event = json.loads(line)
+            if not isinstance(event, dict):
+                continue
+            phase = event.get("phase")
+            event_type = event.get("type")
+            if not isinstance(phase, str) or not phase:
+                continue
+            if event_type == "phase.start":
+                open_phases[phase] = True
+            elif event_type in {"phase.end", "phase.auto_sealed", "workflow.end", "run.end"}:
+                open_phases[phase] = False
+    except (OSError, json.JSONDecodeError):
+        return False
+    return any(open_phases.values())
+
+
+def _project_has_open_phase(project_root: Path) -> bool:
+    return any(_change_has_open_phase(path) for path in _discover_changes(project_root))
+
+
 def _run_agent_session(project_root: Path) -> dict[str, Any]:
     attempts = 0
     uploaded = 0
@@ -619,14 +831,28 @@ def _run_agent_session(project_root: Path) -> dict[str, Any]:
         if all(item.get("ok") for item in results):
             time.sleep(0.6)
             if generation == _read_nudge_generation(project_root):
-                return {
-                    "ok": True,
-                    "uploaded": uploaded,
-                    "quarantined": quarantined,
-                    "attempts": attempts + 1,
-                }
+                if not _project_has_open_phase(project_root):
+                    return {
+                        "ok": True,
+                        "uploaded": uploaded,
+                        "quarantined": quarantined,
+                        "attempts": attempts + 1,
+                    }
+                # Keep a finite workflow lease alive while a phase is open.
+                # A phase.end nudge is observed on the next pass and releases
+                # the worker naturally; no terminal window is created.
+                time.sleep(10.0)
+                heartbeat_results = [
+                    sync_change(project_root, path, heartbeat_only=True)
+                    for path in _discover_changes(project_root)
+                ]
+                if all(item.get("ok") for item in heartbeat_results):
+                    attempts = 0
+                    continue
+                results = heartbeat_results
             attempts = 0
-            continue
+            if generation != _read_nudge_generation(project_root):
+                continue
         time.sleep(min(16.0, float(2 ** attempts)))
         attempts += 1
     return {