@hunter-harness/workflow-harness 0.2.53 → 0.2.55

package/harness/bundles/general/cursor/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/general/cursor/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 {

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

@@ -30,6 +30,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_change as hc  # noqa: E402
+import harness_context as hctx  # noqa: E402
 import harness_events as he  # noqa: E402
 import harness_events_sync as hes  # noqa: E402
 import harness_ledger as hl  # noqa: E402
@@ -1602,6 +1603,18 @@ def append_phase_event(
     auto_sealed: list[dict[str, Any]] = []
     with he.event_file_lock(lock_path):
         existing = he.load_events(events_file)
+        phase_attempts = he.split_phase_attempts(
+            [event for event in existing if event.get("phase") == phase]
+        )
+        latest_attempt = max(
+            (
+                int(item.get("attempt"))
+                for item in phase_attempts
+                if isinstance(item.get("attempt"), int)
+            ),
+            default=0,
+        )
+        event_attempt = latest_attempt + 1 if type_ == "phase.start" else latest_attempt or 1
         args = argparse.Namespace(
             phase=phase,
             type=type_,
@@ -1619,12 +1632,18 @@ def append_phase_event(
             decision=None,
             reason=None,
             run_id=run_id,
-            attempt=None,
+            attempt=event_attempt,
             executor_tool=executor_tool,
             executor_agent=executor_agent,
             executor_model=executor_model,
             handoff_from_tool=None,
             handoff_reason=None,
+            execution_mode=None,
+            decision_reason_code=None,
+            fallback_reason_code=None,
+            trigger=("fixback" if "fixback" in note.lower() else None),
+            from_phase=("review" if phase == "run" and "fixback" in note.lower() else None),
+            result_status=None,
         )
         event = he.build_event(args, existing)
         if identity:
@@ -1655,6 +1674,7 @@ def append_phase_event(
         content = he.render_execution_log(events)
         log_path = he.write_execution_log(change_dir, content)
         rendered = True
+    he.nudge_remote_sync(change_dir)
     return {
         "ok": True,
         "eventId": event.get("id"),
@@ -1702,6 +1722,80 @@ def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -
     )
 
 
+def _latest_phase_end(
+    change_dir: Path,
+    phase: str,
+    run_id: str | None = None,
+) -> dict[str, Any] | None:
+    for event in reversed(he.load_events(he.events_path(change_dir))):
+        if event.get("phase") != phase or event.get("type") != "phase.end":
+            continue
+        if run_id and event.get("run_id") != run_id:
+            continue
+        return event
+    return None
+
+
+def _terminal_matches_context_session(
+    project: Path,
+    change_id: str,
+    phase: str,
+    terminal: dict[str, Any],
+) -> bool:
+    view = hctx.context_view(project, change_id)
+    current = view.get("current") if isinstance(view, dict) else None
+    if not isinstance(current, dict) or current.get("phase") != phase:
+        return False
+    prepared_at = he.parse_timestamp(current.get("preparedAt"))
+    terminal_at = he.parse_timestamp(
+        terminal.get("timestamp") or terminal.get("occurred_at")
+    )
+    return (
+        prepared_at is not None
+        and terminal_at is not None
+        and terminal_at >= prepared_at
+    )
+
+
+def _close_context_handoff(
+    project: Path,
+    change_id: str,
+    args: argparse.Namespace,
+    *,
+    status: str,
+) -> dict[str, Any] | None:
+    to_phase = getattr(args, "to_phase", None)
+    if not to_phase:
+        return None
+    try:
+        return hctx.close_transition(
+            project,
+            change_id,
+            from_phase=args.phase,
+            to_phase=str(to_phase),
+            executor=getattr(args, "executor", None),
+            artifacts=list(getattr(args, "artifact", None) or []),
+            status=status,
+        )
+    except Exception as exc:  # noqa: BLE001 — phase close remains locally durable
+        return {
+            "ok": False,
+            "code": "CONTEXT_HANDOFF_FAILED",
+            "message": str(exc),
+        }
+
+
+def _sync_after_phase_close(project: Path, change_dir: Path) -> dict[str, Any]:
+    try:
+        return hes.auto_events_sync(project, change_dir)
+    except Exception as exc:  # noqa: BLE001 — remote sync is recoverable
+        return {
+            "ok": False,
+            "code": "PLATFORM_EVENTS_SYNC_WARN",
+            "warning": f"events-sync hook failed: {exc}",
+        }
+
+
 def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
     """C9: validate all ledger-required scenarios are covered by ledger entries.
 
@@ -2266,6 +2360,48 @@ def cmd_close(args: argparse.Namespace) -> int:
     explicit_run_id = args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID")
     current_lease = hc.inspect_lease(project, resolved["changeId"])
     if current_lease is None:
+        terminal = _latest_phase_end(change_dir, args.phase, explicit_run_id)
+        if (
+            getattr(args, "to_phase", None)
+            and terminal is not None
+            and _terminal_matches_context_session(
+                project, str(resolved["changeId"]), args.phase, terminal
+            )
+        ):
+            terminal_status = str(terminal.get("status") or args.status)
+            handoff = _close_context_handoff(
+                project,
+                str(resolved["changeId"]),
+                args,
+                status=terminal_status,
+            )
+            monitor = _sync_after_phase_close(project, change_dir)
+            if not isinstance(handoff, dict) or not handoff.get("ok"):
+                return emit_error(
+                    "PHASE_HANDOFF_PENDING",
+                    "phase gate is closed, but context handoff still needs attention",
+                    as_json=as_json,
+                    extra={
+                        "localCloseComplete": True,
+                        "retryable": True,
+                        "contextHandoff": handoff,
+                        "platformMonitor": monitor,
+                    },
+                )
+            emit(
+                {
+                    "ok": True,
+                    "code": "PHASE_CLOSE_RESUMED",
+                    "phase": args.phase,
+                    "status": terminal_status,
+                    "changeId": resolved["changeId"],
+                    "localCloseComplete": True,
+                    "contextHandoff": handoff,
+                    "platformMonitor": monitor,
+                },
+                as_json=as_json,
+            )
+            return 0
         return emit_error("LEASE_ABSENT", "no active lease for phase close", as_json=as_json)
     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:
@@ -2597,6 +2733,29 @@ def cmd_close(args: argparse.Namespace) -> int:
         capsule["closeStatus"] = close_status
         write_phase_capsule(change_dir, args.phase, run_id, capsule)
 
+    context_handoff = _close_context_handoff(
+        project,
+        str(resolved["changeId"]),
+        args,
+        status=close_status,
+    )
+    platform_monitor = _sync_after_phase_close(project, change_dir)
+    if isinstance(context_handoff, dict) and not context_handoff.get("ok"):
+        return emit_error(
+            "PHASE_HANDOFF_PENDING",
+            "phase gate closed locally, but context handoff failed; retry the same close command",
+            as_json=as_json,
+            extra={
+                "localCloseComplete": True,
+                "retryable": True,
+                "phase": args.phase,
+                "status": close_status,
+                "changeId": resolved["changeId"],
+                "contextHandoff": context_handoff,
+                "platformMonitor": platform_monitor,
+            },
+        )
+
     payload = {
         "ok": True,
         "code": close_code,
@@ -2612,6 +2771,8 @@ def cmd_close(args: argparse.Namespace) -> int:
         "lease": release,
         "gateSeverityMode": severity_mode,
         "gateWarnings": gate_warnings,
+        "contextHandoff": context_handoff,
+        "platformMonitor": platform_monitor,
     }
     emit(payload, as_json=as_json)
     return 0
@@ -2806,6 +2967,9 @@ def build_parser() -> argparse.ArgumentParser:
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)
     p_close.add_argument("--note", default="")
+    p_close.add_argument("--to-phase", default=None)
+    p_close.add_argument("--executor", default=None)
+    p_close.add_argument("--artifact", action="append", default=[])
     p_close.set_defaults(func=cmd_close)
 
     p_classify = sub.add_parser("classify", parents=[shared])

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

@@ -1160,6 +1160,8 @@ _DYNAMIC_OWN_DIRS = ("events.ndjson", "logs", "evidence", "reports", "runtime",
 
 def _matches_ownership_path(rel: str, declared: Any) -> bool:
     scope = str(declared).replace("\\", "/").strip("/")
+    if scope.endswith("/**"):
+        scope = scope[:-3].rstrip("/")
     if not scope:
         return False
     normalized = rel.replace("\\", "/").strip("/")

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

@@ -1155,6 +1155,7 @@ def finalize_plan(
                 "artifactsHash": validation["artifactsHash"],
                 "files": validation["files"],
                 "receiptPath": str(receipt_path),
+                "artifactRef": "meta/plan-finalization.json",
             }
 
     lock_path.parent.mkdir(parents=True, exist_ok=True)
@@ -1253,6 +1254,7 @@ def finalize_plan(
             "artifactsHash": validation["artifactsHash"],
             "files": validation["files"],
             "receiptPath": str(receipt_path),
+            "artifactRef": "meta/plan-finalization.json",
             "executionLogPath": str(harness_events.execution_log_path(change_dir)),
         }
     except OSError as exc: