@hunter-harness/workflow-harness 0.2.14 → 0.2.16

package/harness/bundles/java/cursor/scripts/harness_preflight.py

@@ -367,10 +367,41 @@ def _resolve_agents_root(skills_root: Path, agents_root: Path | None) -> tuple[P
     if skills_root.name == "skills" and skills_root.parent.name in (".claude", ".codebuddy"):
         return (skills_root.parent / "agents").resolve(), None
     if skills_root.name == "skills" and skills_root.parent.name in (".agents", ".cursor"):
-        return None, "CUSTOM_AGENTS_UNSUPPORTED"
+        # These adapters (Codex/Cursor) may provide agent roles via host
+        # capability manifest rather than local .md files. Return None without
+        # a hard error; the caller checks runtime.json for host capabilities.
+        return None, None
     return (skills_root / "agents").resolve(), None
 
 
+def _read_host_capabilities(skills_root: Path) -> set[str]:
+    """Read agent capabilities declared by the host adapter (retro §5.3).
+
+    Adapter installs may declare available agent roles in
+    `meta/runtime.json` under `agentCapabilities` (list of role names).
+    Returns an empty set if the file or field is absent.
+    """
+    # runtime.json lives in the change's meta/ dir, but agent capabilities are
+    # project-level. Check the adapter's runtime.json at the project root.
+    candidates = [
+        skills_root.parent / "runtime.json",
+        skills_root / "runtime.json",
+    ]
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            data = json.loads(path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(data, dict):
+            continue
+        caps = data.get("agentCapabilities")
+        if isinstance(caps, list):
+            return {str(c) for c in caps if isinstance(c, str)}
+    return set()
+
+
 def cmd_check_agents(
     skills_root: Path,
     agent: str,
@@ -388,98 +419,136 @@ def cmd_check_agents(
             "reason": "agent name is empty",
         }
 
-    resolved_agents_root, capability_error = _resolve_agents_root(skills_root, agents_root)
-    if capability_error is not None:
-        return {
-            "ok": True,
-            "action": "check-agents",
-            "agent": agent_name,
-            "usable": False,
-            "definitionValid": False,
-            "runtimeSupported": False,
-            "reasonCode": capability_error,
-            "reason": "current adapter runtime does not support custom agent definitions; use main-session fallback",
-        }
-
-    assert resolved_agents_root is not None
-    # Accept bare name or with .md
-    filename = agent_name if agent_name.endswith(".md") else f"{agent_name}.md"
-    agent_path = resolved_agents_root / filename
-
-    if not agent_path.is_file():
+    resolved_agents_root, _ = _resolve_agents_root(skills_root, agents_root)
+    host_capabilities = _read_host_capabilities(skills_root)
+    host_callable = agent_name in host_capabilities
+
+    # Three independent fields (retro §5.3):
+    # - definitionPresent: local .md file exists
+    # - hostCallable: host adapter declares this agent role
+    # - toolContractValid: tools declaration is valid (non-empty list)
+    definition_present = False
+    tool_contract_valid = False
+    agent_path: Path | None = None
+    meta: dict[str, Any] | None = None
+
+    if resolved_agents_root is not None:
+        filename = agent_name if agent_name.endswith(".md") else f"{agent_name}.md"
+        agent_path = resolved_agents_root / filename
+        definition_present = agent_path.is_file()
+
+    # If no local definition and host doesn't declare the role, we can't
+    # determine usability. Distinguish "host says no" from "unknown".
+    if not definition_present and not host_callable:
+        # Check if this adapter is known to not support custom agents
+        adapter_name = skills_root.parent.name
+        if adapter_name in (".agents", ".cursor"):
+            # Codex/Cursor: may support via host manifest. If runtime.json
+            # has agentCapabilities but this role isn't listed, it's a
+            # genuine "not available". If no agentCapabilities field at all,
+            # we can't know — return UNKNOWN.
+            runtime_path = skills_root.parent / "runtime.json"
+            if not runtime_path.is_file():
+                return {
+                    "ok": True,
+                    "action": "check-agents",
+                    "agent": agent_name,
+                    "usable": False,
+                    "definitionPresent": False,
+                    "hostCallable": False,
+                    "toolContractValid": False,
+                    "reasonCode": "UNKNOWN",
+                    "reason": (
+                        "no local agent definition and no host capability manifest; "
+                        "cannot determine agent availability"
+                    ),
+                }
         return {
             "ok": False,
             "action": "check-agents",
             "agent": agent_name,
-            "path": str(agent_path),
-            "agentsRoot": str(resolved_agents_root),
+            "path": str(agent_path) if agent_path else None,
+            "agentsRoot": str(resolved_agents_root) if resolved_agents_root else None,
             "usable": False,
-            "definitionValid": False,
-            "runtimeSupported": True,
+            "definitionPresent": False,
+            "hostCallable": False,
+            "toolContractValid": False,
             "reasonCode": "AGENT_DEFINITION_NOT_FOUND",
-            "reason": f"agent file not found: {agent_path}",
+            "reason": f"agent file not found and host does not declare role: {agent_name}",
         }
 
-    try:
-        text = agent_path.read_text(encoding="utf-8")
-    except OSError as exc:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": f"cannot read agent file: {exc}",
-        }
+    # If definition present, validate frontmatter and tools
+    if definition_present and agent_path is not None:
+        try:
+            text = agent_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            return {
+                "ok": False,
+                "action": "check-agents",
+                "agent": agent_name,
+                "path": str(agent_path),
+                "usable": False,
+                "definitionPresent": True,
+                "hostCallable": host_callable,
+                "toolContractValid": False,
+                "reason": f"cannot read agent file: {exc}",
+            }
+
+        meta, err = parse_frontmatter(text)
+        if err or meta is None:
+            return {
+                "ok": False,
+                "action": "check-agents",
+                "agent": agent_name,
+                "path": str(agent_path),
+                "usable": False,
+                "definitionPresent": True,
+                "hostCallable": host_callable,
+                "toolContractValid": False,
+                "reason": f"frontmatter parse failed: {err or 'unknown'}",
+            }
+
+        tools = meta.get("tools")
+        if tools is None:
+            tool_contract_valid = False
+        elif isinstance(tools, list) and len(tools) > 0:
+            tool_contract_valid = True
+        else:
+            tool_contract_valid = False
 
-    meta, err = parse_frontmatter(text)
-    if err or meta is None:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": f"frontmatter parse failed: {err or 'unknown'}",
-        }
+    # usable = hostCallable (host provides the agent role, tools validated by host)
+    # OR definitionPresent AND toolContractValid (definition-based adapters)
+    usable = host_callable or (
+        definition_present and tool_contract_valid
+    )
 
-    tools = meta.get("tools")
-    if tools is None:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": "tools declaration missing",
-            "frontmatter": meta,
-        }
-    if not isinstance(tools, list) or len(tools) == 0:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": "tools declaration empty or invalid",
-            "frontmatter": meta,
-        }
+    name_field = meta.get("name") if meta else None
+    tools_field = meta.get("tools") if meta else None
+
+    reason_code = "READY" if usable else "AGENT_DEFINITION_NOT_FOUND"
+    if not definition_present and host_callable:
+        reason_code = "DEFINITION_NOT_FOUND_HOST_CAPABLE"
 
-    name_field = meta.get("name")
     return {
         "ok": True,
         "action": "check-agents",
         "agent": agent_name,
-        "path": str(agent_path),
-        "agentsRoot": str(resolved_agents_root),
-        "usable": True,
-        "definitionValid": True,
-        "runtimeSupported": True,
-        "reasonCode": "READY",
-        "reason": "agent file exists; frontmatter parsed; tools declared",
+        "path": str(agent_path) if agent_path else None,
+        "agentsRoot": str(resolved_agents_root) if resolved_agents_root else None,
+        "usable": usable,
+        "definitionPresent": definition_present,
+        "hostCallable": host_callable,
+        "toolContractValid": tool_contract_valid,
+        "reasonCode": reason_code,
+        "reason": (
+            "agent available; "
+            f"definition={'present' if definition_present else 'absent'}, "
+            f"hostCallable={host_callable}, "
+            f"tools={'valid' if tool_contract_valid else 'invalid'}"
+        ),
         "name": name_field,
-        "tools": tools,
-        "frontmatterKeys": sorted(meta.keys()),
+        "tools": tools_field,
+        "frontmatterKeys": sorted(meta.keys()) if meta else [],
     }
 
 

package/harness/bundles/java/cursor/scripts/harness_profile.py

@@ -27,6 +27,12 @@ import sys
 from pathlib import Path
 from typing import Any
 
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+import harness_paths  # noqa: E402
+
 
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8")
@@ -358,14 +364,53 @@ def empty_profile_skeleton(excluded: tuple[str, ...] | list[str]) -> dict[str, A
 
 
 def load_profile(project: Path) -> dict[str, Any] | None:
-    path = project / PROFILE_REL
-    if not path.is_file():
-        return None
-    try:
-        data = read_json(path)
-    except (OSError, json.JSONDecodeError):
+    """C7: 分层读取 — 先读 common_root 的 build-profile.json，再叠加 execution root 的 override。
+
+    common_root 是 worktree 共享的主项目根（git common dir 的父目录）；
+    execution root 是当前工作目录（可能是 linked worktree）。
+    override 合并策略：execution 的 buildCommands 覆盖 common 的同名 key；
+    common 独有的 key 保留。
+    """
+    project = Path(project).resolve()
+    common = harness_paths.common_root(project)
+    common_path = common / PROFILE_REL
+    exec_path = project / PROFILE_REL
+
+    common_data: dict[str, Any] | None = None
+    if common_path.is_file():
+        try:
+            data = read_json(common_path)
+            if isinstance(data, dict):
+                common_data = data
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    exec_data: dict[str, Any] | None = None
+    if exec_path.is_file():
+        try:
+            data = read_json(exec_path)
+            if isinstance(data, dict):
+                exec_data = data
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    if common_data is None and exec_data is None:
         return None
-    return data if isinstance(data, dict) else None
+    if common_data is None:
+        return exec_data
+    if exec_data is None:
+        return common_data
+
+    # Merge: start from common, overlay execution's buildCommands.
+    merged = dict(common_data)
+    common_cmds = common_data.get("buildCommands") or {}
+    exec_cmds = exec_data.get("buildCommands") or {}
+    if common_cmds or exec_cmds:
+        merged_cmds = dict(common_cmds) if isinstance(common_cmds, dict) else {}
+        if isinstance(exec_cmds, dict):
+            merged_cmds.update(exec_cmds)
+        merged["buildCommands"] = merged_cmds
+    return merged
 
 
 def _merge_user_overrides(
@@ -616,6 +661,8 @@ def resolve_command(
     *,
     test_classes: list[str] | None = None,
     modules: list[str] | None = None,
+    common_root: Path | None = None,
+    execution_root: Path | None = None,
 ) -> dict[str, Any]:
     cmd = (profile.get("commands") or {}).get(key)
     if not isinstance(cmd, dict):
@@ -625,6 +672,10 @@ def resolve_command(
         replacements["{testClasses}"] = ",".join(test_classes)
     if modules is not None:
         replacements["{modules}"] = ",".join(modules)
+    if common_root is not None:
+        replacements["{commonRoot}"] = str(common_root)
+    if execution_root is not None:
+        replacements["{executionRoot}"] = str(execution_root)
 
     command = cmd.get("command", "")
     for placeholder, val in replacements.items():

package/harness/bundles/java/cursor/scripts/harness_review.py

@@ -14,6 +14,7 @@ Python 3.10+, stdlib only.
 from __future__ import annotations
 
 import argparse
+import datetime as dt
 import hashlib
 import json
 import os
@@ -270,6 +271,112 @@ def _emit(payload: Any, *, as_json: bool) -> int:
     return 0 if payload.get("ok") else 1
 
 
+def dispatch_review(
+    *,
+    change_dir: Path,
+    run_id: str,
+    budget_seconds: int = 300,
+) -> dict[str, Any]:
+    """C11: dispatch a bounded review task.
+
+    Returns reviewTaskId / deadline / heartbeatAt. The caller is expected to
+    poll the review subagent and collect partial findings on timeout.
+    """
+    now = dt.datetime.now(dt.timezone.utc).astimezone()
+    task_id = f"review-{uuid.uuid4().hex}"
+    deadline = now + dt.timedelta(seconds=budget_seconds)
+    # heartbeat at midpoint of the budget
+    heartbeat = now + dt.timedelta(seconds=budget_seconds // 2)
+    return {
+        "ok": True,
+        "code": "DISPATCHED",
+        "reviewTaskId": task_id,
+        "runId": run_id,
+        "deadline": deadline.isoformat(timespec="milliseconds"),
+        "heartbeatAt": heartbeat.isoformat(timespec="milliseconds"),
+        "budgetSeconds": budget_seconds,
+    }
+
+
+def collect_partial_findings(
+    *,
+    change_dir: Path,
+    run_id: str,
+    completed_dimensions: list[str],
+    pending_dimensions: list[str],
+) -> dict[str, Any]:
+    """C11: collect partial findings after timeout — completed dimensions only.
+
+    Applies the degradation matrix to decide the fallback path.
+    """
+    matrix = degradation_matrix(
+        subagent_timed_out=bool(pending_dimensions),
+        main_session_available=True,
+    )
+    return {
+        "ok": True,
+        "code": "PARTIAL_FINDINGS",
+        "runId": run_id,
+        "completedDimensions": list(completed_dimensions),
+        "pendingDimensions": list(pending_dimensions),
+        "degradationMatrix": matrix,
+    }
+
+
+def degradation_matrix(
+    *,
+    subagent_timed_out: bool,
+    main_session_available: bool,
+) -> dict[str, Any]:
+    """C11: degradation matrix — subagent timeout → main session; main fail → ADVISORY."""
+    if not subagent_timed_out:
+        return {"fallback": "none", "status": "OK"}
+    if main_session_available:
+        return {"fallback": "main-session", "status": "DEGRADED"}
+    return {"fallback": "advisory", "status": "ADVISORY"}
+
+
+def validate_codegraph_identity(
+    *,
+    response: dict[str, Any],
+    expected_repository_id: str,
+    expected_head: str,
+) -> dict[str, Any]:
+    """C12: validate CodeGraph identity — repositoryId/indexedHead must match.
+
+    On mismatch, signal CODEGRAPH_IDENTITY_MISMATCH with fallback to Grep/Glob + Read.
+    """
+    repo_id = response.get("repositoryId")
+    indexed_head = response.get("indexedHead")
+    indexed_at = response.get("indexedAt")
+    if (
+        repo_id == expected_repository_id
+        and indexed_head == expected_head
+        and indexed_at
+    ):
+        return {
+            "ok": True,
+            "code": "IDENTITY_OK",
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        }
+    return {
+        "ok": False,
+        "code": "CODEGRAPH_IDENTITY_MISMATCH",
+        "expected": {
+            "repositoryId": expected_repository_id,
+            "indexedHead": expected_head,
+        },
+        "actual": {
+            "repositoryId": repo_id,
+            "indexedHead": indexed_head,
+            "indexedAt": indexed_at,
+        },
+        "fallback": "grep-glob-read",
+    }
+
+
 def cmd_validate_findings(args: argparse.Namespace) -> int:
     doc = _read_json(Path(args.input))
     problems = validate_findings(doc)

package/harness/bundles/java/cursor/scripts/harness_state.py

@@ -268,6 +268,7 @@ def capture_current_state(
     changed: list[str] = []
     baseline_created = previous is None
     unresolved: list[str] = []
+    unresolved_reasons: list[dict[str, str]] = []
     if previous:
         old_segments = previous.get("segments") or {}
         for name, segment in fresh["segments"].items():
@@ -276,13 +277,17 @@ def capture_current_state(
                 segment["capturedAt"] = old.get("capturedAt", segment["capturedAt"])
             else:
                 changed.append(name)
-    else:
-        # A first observation establishes the baseline; it is not evidence
-        # that every segment changed during the current phase.
-        unresolved = sorted(fresh["segments"])
+    # First observation establishes the baseline; it is not evidence that
+    # segments changed, nor that they are "unresolved". Segments are only
+    # unresolved when they genuinely fail to read/compute (retro §5.6).
+    # On first capture, all successfully-captured segments are baseline,
+    # not unresolved.
     fresh["baselineCreated"] = baseline_created
     fresh["changedSegments"] = sorted(changed)
     fresh["unresolvedSegments"] = unresolved
+    fresh["unresolvedReasons"] = unresolved_reasons
+    fresh["comparisonAvailable"] = not baseline_created
+    fresh["baselineStatus"] = "created" if baseline_created else "reused"
     write_snapshot(change_dir, fresh)
     return fresh, changed
 
@@ -325,7 +330,10 @@ def main(argv: list[str] | None = None) -> int:
             - set(snapshot.get("unresolvedSegments") or [])
         ),
         "baselineCreated": bool(snapshot.get("baselineCreated")),
+        "baselineStatus": snapshot.get("baselineStatus", "reused"),
+        "comparisonAvailable": bool(snapshot.get("comparisonAvailable", True)),
         "unresolvedSegments": list(snapshot.get("unresolvedSegments") or []),
+        "unresolvedReasons": list(snapshot.get("unresolvedReasons") or []),
         "git": snapshot["git"],
     }
     if args.json: