@hunter-harness/workflow-harness 0.2.12 → 0.2.14

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

@@ -623,6 +623,107 @@ def collect_files(root: Path) -> dict[str, str]:
     return files
 
 
+# --- Per-file bundle manifest (retro 2026-07-20 §5.1/5.25) -----------------
+#
+# registry_version + bundle_hash alone cannot prove every installed file
+# belongs to the declared bundle. The bundle therefore ships a per-file
+# manifest (relpath/sha256/size/mode/adapterTransformationId); install
+# verifies staging content against it BEFORE the atomic switch and never
+# updates metadata on partial failure.
+
+BUNDLE_MANIFEST_NAME = "bundle-manifest.json"
+_MANIFEST_EXCLUDED = frozenset(
+    {BUILD_MARKER, MANIFEST_NAME, AGENTS_MANAGED_NAME, BUNDLE_MANIFEST_NAME}
+)
+
+
+def build_manifest(root: Path, transformation_id: str = "raw") -> list[dict[str, Any]]:
+    """Return per-file manifest entries for every bundle file under ``root``.
+
+    Install metadata (build marker, managed manifests, the manifest itself)
+    is excluded. Entries are sorted by relpath for deterministic output.
+    """
+    root = root.resolve()
+    entries: list[dict[str, Any]] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or "__pycache__" in path.parts:
+            continue
+        rel = path.relative_to(root).as_posix()
+        if rel in _MANIFEST_EXCLUDED:
+            continue
+        stat = path.stat()
+        entries.append(
+            {
+                "relpath": rel,
+                "sha256": sha256_file(path),
+                "size": stat.st_size,
+                "mode": stat.st_mode,
+                "adapterTransformationId": transformation_id,
+            }
+        )
+    return entries
+
+
+def compute_bundle_manifest_hash(entries: list[dict[str, Any]]) -> str:
+    """Deterministic aggregate hash over manifest entries (order-independent).
+
+    Must match packages/contracts/src/bundle-manifest.ts computeBundleManifestHash.
+    """
+    ordered = sorted(entries, key=lambda entry: entry["relpath"])
+    lines = [
+        f"{entry['relpath']}:{entry['sha256']}:{entry['size']}:{entry['mode']}:{entry['adapterTransformationId']}"
+        for entry in ordered
+    ]
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def aggregate_installed_content_hash(files: dict[str, str]) -> str:
+    """Deterministic aggregate hash over actually-installed relpath->sha256."""
+    lines = [f"{rel}:{files[rel]}" for rel in sorted(files)]
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def _verify_tree_against_manifest(
+    root: Path, entries: list[dict[str, Any]]
+) -> list[dict[str, str]]:
+    """Return mismatch details for files under ``root`` vs manifest entries."""
+    mismatches: list[dict[str, str]] = []
+    actual = collect_files(root)
+    declared = {entry["relpath"]: entry["sha256"] for entry in entries}
+    for rel, expected in sorted(declared.items()):
+        if rel not in actual:
+            mismatches.append({"relpath": rel, "expected": expected, "actual": "<missing>"})
+        elif actual[rel] != expected:
+            mismatches.append(
+                {"relpath": rel, "expected": expected, "actual": actual[rel]}
+            )
+    return mismatches
+
+
+def cmd_verify_installed(
+    installed_dir: Path, entries: list[dict[str, Any]], bundle_version: str
+) -> dict[str, Any]:
+    """Verify installed content against the bundle manifest, per file."""
+    installed_dir = installed_dir.resolve()
+    mismatches = _verify_tree_against_manifest(installed_dir, entries)
+    actual = collect_files(installed_dir)
+    declared = {entry["relpath"] for entry in entries}
+    content = {
+        rel: digest
+        for rel, digest in actual.items()
+        if rel not in _MANIFEST_EXCLUDED and rel in declared
+    }
+    return {
+        "ok": not mismatches,
+        "action": "verify-installed",
+        "bundleVersion": bundle_version,
+        "verificationStatus": "verified" if not mismatches else "degraded",
+        "installedContentHash": aggregate_installed_content_hash(content),
+        "verifiedAt": now_iso(),
+        "mismatchDetails": mismatches,
+    }
+
+
 def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str, Any]:
     build_out = build_out.resolve()
     project = project.resolve()
@@ -644,6 +745,23 @@ def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str
     backup: str | None = None
     staging = dest.parent / f".{dest.name}.staging-{uuid.uuid4().hex[:8]}"
     shutil.copytree(build_out, staging)
+    # Per-file content proof (retro §5.1): if the build carries a
+    # bundle-manifest.json, staging must match it exactly before anything is
+    # switched. A mismatch aborts the install without touching dest or any
+    # metadata — never a partial install under a fresh version label.
+    manifest_path = staging / BUNDLE_MANIFEST_NAME
+    if manifest_path.is_file():
+        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        manifest_entries = (
+            manifest_data.get("files", []) if isinstance(manifest_data, dict) else []
+        )
+        mismatches = _verify_tree_against_manifest(staging, manifest_entries)
+        if mismatches:
+            shutil.rmtree(staging, ignore_errors=True)
+            raise ValueError(
+                "BUNDLE_CONTENT_MISMATCH: staging diverges from bundle-manifest.json: "
+                + ", ".join(m["relpath"] for m in mismatches)
+            )
     if dest.exists() and any(dest.iterdir()):
         managed_old = _read_managed_set(dest / MANIFEST_NAME)
         # Preserve user-owned files: anything in dest that was NOT managed by a
@@ -771,6 +889,28 @@ def build_parser() -> argparse.ArgumentParser:
     v.add_argument("--bundle", type=Path, required=True)
     v.add_argument("--manifest", type=Path, required=True)
     v.add_argument("--json", action="store_true")
+
+    g = sub.add_parser(
+        "generate-manifest",
+        help="Generate per-file bundle-manifest.json for a bundle dir",
+    )
+    g.add_argument("--bundle", type=Path, required=True)
+    g.add_argument("--bundle-version", required=True)
+    g.add_argument(
+        "--transformation",
+        choices=["raw", "adapted", "workflow-packaged"],
+        default="raw",
+    )
+    g.add_argument("--out", type=Path)
+    g.add_argument("--json", action="store_true")
+
+    vi = sub.add_parser(
+        "verify-installed",
+        help="Verify installed tree content against bundle-manifest.json",
+    )
+    vi.add_argument("--installed", type=Path, required=True)
+    vi.add_argument("--manifest", type=Path, required=True)
+    vi.add_argument("--json", action="store_true")
     return p
 
 
@@ -794,6 +934,43 @@ def main(argv: list[str] | None = None) -> int:
             if args.json:
                 return emit_json(result)
             return 0 if result["ok"] else 1
+        if args.command == "generate-manifest":
+            entries = build_manifest(args.bundle, transformation_id=args.transformation)
+            manifest = {
+                "schemaVersion": 1,
+                "bundleVersion": args.bundle_version,
+                "bundleManifestHash": compute_bundle_manifest_hash(entries),
+                "files": entries,
+            }
+            text = json.dumps(manifest, ensure_ascii=False, indent=2) + "\n"
+            if args.out is not None:
+                args.out.parent.mkdir(parents=True, exist_ok=True)
+                args.out.write_text(text, encoding="utf-8", newline="\n")
+            result = {
+                "ok": True,
+                "action": "generate-manifest",
+                "bundleVersion": args.bundle_version,
+                "bundleManifestHash": manifest["bundleManifestHash"],
+                "fileCount": len(entries),
+                "out": str(args.out) if args.out is not None else None,
+            }
+            if args.json:
+                return emit_json(result)
+            if args.out is None:
+                print(text, end="")
+            return 0
+        if args.command == "verify-installed":
+            manifest_data = json.loads(args.manifest.read_text(encoding="utf-8"))
+            if not isinstance(manifest_data, dict):
+                raise ValueError("manifest must be a JSON object")
+            result = cmd_verify_installed(
+                args.installed,
+                manifest_data.get("files", []),
+                str(manifest_data.get("bundleVersion", "")),
+            )
+            if args.json:
+                return emit_json(result)
+            return 0 if result["ok"] else 1
     except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
         if getattr(args, "json", False):
             return emit_json({"ok": False, "error": str(exc)}, ok=False)

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

@@ -506,6 +506,81 @@ def new_event_id(existing: list[dict[str, Any]] | None = None) -> str:
     return f"evt-{uuid.uuid4().hex}"
 
 
+def append_event(
+    change_dir: Path,
+    *,
+    phase: str,
+    type_: str,
+    note: str = "",
+    kind: str | None = None,
+    path: str | None = None,
+    run_id: str | None = None,
+    executor_tool: str | None = None,
+) -> dict[str, Any]:
+    """Programmatic append API (retro §5.31 C5/T16).
+
+    Validates and appends an event without going through argparse. Returns
+    a payload dict with ``ok``/``code``/``event``.
+    """
+    args = argparse.Namespace(
+        change_dir=str(change_dir),
+        phase=phase,
+        type=type_,
+        note=note,
+        kind=kind,
+        path=path,
+        run_id=run_id,
+        executor_tool=executor_tool,
+        command=None,
+        exit_code=None,
+        duration_ms=None,
+        status=None,
+        name=None,
+        code=None,
+        severity=None,
+        message=None,
+        decision=None,
+        reason=None,
+        issue_id=None,
+        scope=None,
+        target_event_id=None,
+        target_field=None,
+        old_value_hash=None,
+        new_value_json=None,
+        attempt=None,
+        executor_agent=None,
+        executor_model=None,
+        handoff_from_tool=None,
+        handoff_reason=None,
+        trace_id=None,
+        span_id=None,
+        parent_span_id=None,
+        runner_ms=None,
+        orchestration_active_ms=None,
+        wall_clock_ms=None,
+        user_wait_ms=None,
+        legacy_lenient=False,
+        json=True,
+    )
+    as_json = True
+    if type_ not in EVENT_TYPES:
+        return {"ok": False, "code": "EVENT_TYPE_INVALID", "message": f"unsupported type: {type_}"}
+    validation = validate_append_event(args)
+    if validation:
+        error_code, message = validation
+        return {"ok": False, "code": error_code, "message": message}
+    archived = archived_change_dir(change_dir)
+    if archived is not None:
+        return {"ok": False, "code": "ARCHIVED_CHANGE_IMMUTABLE", "message": str(archived)}
+    events_path_obj = events_path(change_dir)
+    lock_path = events_path_obj.with_name(events_path_obj.name + ".lock")
+    existing = []
+    event = build_event(args, existing)
+    with event_file_lock(lock_path):
+        atomic_append_line(events_path_obj, json.dumps(event, ensure_ascii=False))
+    return {"ok": True, "event": event, "events_path": str(events_path_obj), "rendered": False}
+
+
 def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dict[str, Any]:
     event: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
@@ -588,8 +663,31 @@ def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
         except json.JSONDecodeError as exc:
             return (
                 "CORRECTION_VALUE_INVALID_JSON",
-                f"CORRECTION_VALUE_INVALID_JSON: {exc.msg}",
+                f"CORRECTION_VALUE_INVALID_JSON: {exc}",
+            )
+    # Retro §5.31: artifact events must distinguish file-backed from
+    # informational. file-backed requires a change-relative path; informational
+    # (preview/summary) must not masquerade as a file artifact. Legacy kind
+    # values (ledger, report, etc.) are treated as file-backed aliases.
+    if event_type == "artifact":
+        kind = str(getattr(args, "kind", "") or "").strip()
+        path = str(getattr(args, "path", "") or "").strip()
+        is_informational = kind == "informational"
+        if kind == "file-backed" and not path:
+            return (
+                "ARTIFACT_PATH_REQUIRED",
+                "ARTIFACT_PATH_REQUIRED: file-backed artifact requires --path",
+            )
+        # If kind is explicitly informational, path is optional. If kind is
+        # absent and path is absent, reject (can't infer file-backed without path).
+        if not kind and not path:
+            return (
+                "ARTIFACT_PATH_REQUIRED",
+                "ARTIFACT_PATH_REQUIRED: artifact without --kind or --path is ambiguous; "
+                "use --kind informational for previews or --path for file artifacts",
             )
+        # If no kind is provided, infer from path presence: a path implies
+        # file-backed, absence implies informational (legacy compatibility).
     return None
 
 

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

@@ -329,6 +329,12 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
 
     Returns ``(missing_fields, degraded_ok)`` where ``degraded_ok`` is True only when
     the entry is a valid DEGRADED NOT_RUN record with no other missing fields.
+
+    Retro §5.14: ``status=OK``/``status=NOT_RUN``/``status=FAIL`` in the
+    missing list is a *status value* hint, not a field-completeness defect.
+    Callers consuming this under ``phase_status=FAIL`` must filter out
+    ``status=*`` entries from the missing list before treating them as
+    blocking problems.
     """
     missing: list[str] = []
     degraded = is_degraded_ledger_entry(entry)
@@ -341,7 +347,7 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
                 missing.append("inputsFiles(non-empty)")
         elif field == "status":
             if value != "OK" and not degraded:
-                missing.append("status=OK")
+                missing.append(f"status={value}")
         elif not (isinstance(value, str) and value.strip()):
             missing.append(field)
         elif field == "coverage" and str(value).strip() not in hl.COVERAGE_RANK:
@@ -357,8 +363,16 @@ def validate_ledger_for_phase_close(
     policy: dict[str, Any],
     *,
     execution_root: Path | None = None,
+    phase_status: str = "OK",
 ) -> dict[str, Any]:
-    """Validate ledger v2 fields required for phase close (UT-026)."""
+    """Validate ledger v2 fields required for phase close (UT-026).
+
+    Retro §5.14: ``phase_status`` separates phase outcome from promotion gate.
+    ``phase_status=OK`` (default) requires all required validations to be OK;
+    ``phase_status=FAIL`` validates field completeness and identity but allows
+    individual validation status to be FAIL/NOT_RUN, so a failing phase can
+    close honestly without polluting evidence or blocking lease release.
+    """
     required = policy.get("requiredValidations", {}).get(phase, [])
     if not required:
         return {"ok": True, "code": "LEDGER_NOT_REQUIRED", "phase": phase}
@@ -443,6 +457,7 @@ def validate_ledger_for_phase_close(
 
     problems: list[dict[str, Any]] = []
     degraded: list[str] = []
+    fail_status: list[str] = []
     for verification in required:
         entry = validations.get(verification)
         if not isinstance(entry, dict):
@@ -455,6 +470,12 @@ def validate_ledger_for_phase_close(
             )
             continue
         missing, is_degraded = validate_ledger_entry_v2(entry, verification)
+        # Retro §5.14: under phase_status=FAIL/WARN, status value hints
+        # (status=FAIL, status=NOT_RUN) are acceptable; only real field-
+        # completeness defects block close. Under phase_status=OK, status
+        # value hints are blocking.
+        if phase_status.upper() in {"FAIL", "WARN"}:
+            missing = [m for m in missing if not m.startswith("status=")]
         if missing:
             code = (
                 "MISSING_V2_FIELDS"
@@ -476,8 +497,21 @@ def validate_ledger_for_phase_close(
                     "code": code,
                 }
             )
-        elif is_degraded:
+            continue
+        if is_degraded:
             degraded.append(verification)
+            continue
+        # Under phase_status=FAIL/WARN, a FAIL/NOT_RUN status is acceptable.
+        entry_status = str(entry.get("status") or "").upper()
+        if entry_status in {"FAIL", "NOT_RUN"}:
+            if phase_status.upper() in {"FAIL", "WARN"}:
+                fail_status.append(verification)
+            else:
+                problems.append({
+                    "verification": verification,
+                    "missing": [f"status={entry_status}"],
+                    "code": "VALIDATION_NOT_OK",
+                })
 
     if problems:
         return {
@@ -489,6 +523,16 @@ def validate_ledger_for_phase_close(
             "ledgerPath": str(ledger_path) if ledger_path else None,
             "detail": "natural-language override is not permitted",
         }
+    if fail_status:
+        return {
+            "ok": True,
+            "code": "LEDGER_OK_FAIL",
+            "phase": phase,
+            "validated": required,
+            "failed": fail_status,
+            "degraded": degraded,
+            "ledgerPath": str(ledger_path) if ledger_path else None,
+        }
     if degraded:
         return {
             "ok": True,
@@ -1169,6 +1213,14 @@ def cmd_begin(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    concurrency_block = hc.check_concurrency_block(project, resolved["changeId"])
+    if concurrency_block is not None:
+        return emit_error(
+            str(concurrency_block.get("code", "CONCURRENCY_BLOCKED")),
+            str(concurrency_block.get("message", "concurrency mode blocked begin")),
+            as_json=as_json,
+            extra={k: v for k, v in concurrency_block.items() if k not in {"ok", "message"}},
+        )
     blocked = foundation_gate_blocks(getattr(args, "task", None), change_dir)
     if blocked:
         return emit_error(
@@ -1407,7 +1459,8 @@ def cmd_close(args: argparse.Namespace) -> int:
             return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
 
     ledger_result = validate_ledger_for_phase_close(
-        change_dir, args.phase, policy, execution_root=execution_root
+        change_dir, args.phase, policy, execution_root=execution_root,
+        phase_status=args.status,
     )
     if not ledger_result.get("ok") and args.phase in {"run", "test", "package"}:
         return emit_error(

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

@@ -422,6 +422,9 @@ class IntegrationTransaction:
         else:
             result = hl.record_integration_hashes(
                 ledger_path,
+                change_dir=(
+                    self.project_root / ".harness" / "changes" / self.change_id
+                ),
                 repository_id=str(journal["repositoryId"]),
                 merge_final_hash=merge_commit,
                 ci_expected_head=merge_commit,

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

@@ -621,12 +621,13 @@ def validate_ledger_identity(ledger: dict[str, Any]) -> list[str]:
 def record_integration_hashes(
     ledger_path: Path,
     *,
+    change_dir: Path | None = None,
     repository_id: str,
     merge_final_hash: str,
     ci_expected_head: str,
     remote_head: str,
 ) -> dict[str, Any]:
-    """Atomically attach post-push identity to an existing ledger v3."""
+    """Atomically attach post-push hashes using the change contract's ledger rules."""
     path = Path(ledger_path).resolve()
     if not path.is_file():
         return {"ok": False, "code": "LEDGER_MISSING", "ledgerPath": str(path)}
@@ -637,15 +638,26 @@ def record_integration_hashes(
             "ok": False, "code": "LEDGER_INVALID", "ledgerPath": str(path),
             "message": str(exc),
         }
+    legacy_contract = False
+    if change_dir is not None:
+        resolved_change_dir = Path(change_dir).resolve()
+        if ledger.get("changeName") != resolved_change_dir.name:
+            return {
+                "ok": False,
+                "code": "LEDGER_CHANGE_MISMATCH",
+                "ledgerPath": str(path),
+            }
+        legacy_contract = not _contract_is_v2(resolved_change_dir)
+
     missing = validate_ledger_identity(ledger)
-    if missing:
+    if missing and not legacy_contract:
         return {
             "ok": False,
             "code": "LEDGER_IDENTITY_INVALID",
             "ledgerPath": str(path),
             "missing": missing,
         }
-    if ledger.get("repositoryId") != repository_id:
+    if not missing and ledger.get("repositoryId") != repository_id:
         return {
             "ok": False,
             "code": "LEDGER_REPOSITORY_MISMATCH",

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

@@ -29,6 +29,7 @@ if hasattr(sys.stderr, "reconfigure"):
     sys.stderr.reconfigure(encoding="utf-8")
 
 
+import harness_change as hc  # noqa: E402
 import harness_profile as hprof  # noqa: E402
 
 
@@ -69,6 +70,52 @@ def cmd_check(project: Path) -> dict[str, Any]:
     return result
 
 
+def check_concurrency(project: Path) -> dict[str, Any]:
+    """Report the configured concurrency mode and active Change landscape.
+
+    Retro §5.2: preflight must surface concurrencyMode, activeChanges, and
+    allowedParallelLevels so agents don't have to guess whether parallel
+    Changes are supported.
+    """
+    mode = hc.read_concurrency_mode(project)
+    active = hc.list_active_changes(project)
+    shared_conflicts: list[dict[str, Any]] = []
+    # In isolated-multi-active, surface any shared-state conflicts (e.g. same
+    # worktree path) so callers know isolation is incomplete.
+    if mode == "isolated-multi-active" and len(active) > 1:
+        seen_worktrees: dict[str, str] = {}
+        for entry in active:
+            change_dir = Path(entry["path"])
+            worktree_meta = change_dir / "meta" / "worktree.json"
+            if not worktree_meta.is_file():
+                continue
+            try:
+                meta = json.loads(worktree_meta.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            wt = meta.get("path") if isinstance(meta, dict) else None
+            if isinstance(wt, str) and wt:
+                if wt in seen_worktrees:
+                    shared_conflicts.append({
+                        "kind": "worktree",
+                        "path": wt,
+                        "changes": [seen_worktrees[wt], entry["changeId"]],
+                    })
+                else:
+                    seen_worktrees[wt] = entry["changeId"]
+    levels = ["change-internal"] if mode == "single-active" else [
+        "change-internal",
+        "multi-change",
+    ]
+    return {
+        "ok": True,
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "sharedStateConflicts": shared_conflicts,
+        "allowedParallelLevels": levels,
+    }
+
+
 # ---------------------------------------------------------------------------
 # record-quirk — 适配 v2 commands（source=user override）
 # ---------------------------------------------------------------------------