@hunter-harness/workflow-harness 0.2.21 → 0.2.22

package/harness/bundles/general/codex/scripts/harness_environment.py

@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+"""Minimal environment fingerprint + lease manager (IA-3 Wave-A).
+
+Contract: prepare → fingerprint → acquire lease → reset/clone → run → record → release.
+This module implements fingerprint/lease gates with a file-backed stub suitable for
+unit tests. Full Docker orchestration is out of scope for Wave-A.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+FINGERPRINT_CANDIDATES = (
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "poetry.lock",
+    "Pipfile.lock",
+    "requirements.txt",
+    "requirements.lock",
+    "Cargo.lock",
+    "go.sum",
+    "composer.lock",
+    ".nvmrc",
+    ".node-version",
+    ".python-version",
+    "Dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "compose.yml",
+    "compose.yaml",
+)
+
+
+def now_iso() -> str:
+    return dt.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def emit_json(payload: dict[str, Any], *, ok: bool = True) -> int:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if ok else 1
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
+
+def default_lease_root(project: Path) -> Path:
+    return project / ".harness" / "runtime" / "env-leases"
+
+
+def _migration_head_token(project: Path) -> str:
+    cfg = project / ".harness" / "config" / "migration-head.json"
+    if cfg.is_file():
+        try:
+            data = _read_json(cfg)
+            if isinstance(data, dict):
+                head = data.get("head") or data.get("revision") or data.get("version")
+                if head:
+                    return f"migration-head:{head}"
+        except (OSError, json.JSONDecodeError, TypeError):
+            pass
+    versions = project / "alembic" / "versions"
+    if versions.is_dir():
+        names = sorted(p.name for p in versions.glob("*.py"))
+        if names:
+            return "alembic:" + ",".join(names[-3:])
+    return "migration-head:none"
+
+
+def compute_environment_hash(
+    project: Path,
+    *,
+    extra_paths: list[str] | None = None,
+) -> str:
+    """Stable hash over lockfiles/toolchain/compose/migration head inputs."""
+    project = project.resolve()
+    lines: list[str] = []
+    seen: set[str] = set()
+    for rel in list(FINGERPRINT_CANDIDATES) + list(extra_paths or []):
+        if rel in seen:
+            continue
+        seen.add(rel)
+        path = project / rel
+        if path.is_file():
+            lines.append(f"file:{rel}:{_sha256_file(path)}")
+    lines.append(_migration_head_token(project))
+    # Desensitized runner hint (presence only).
+    for runner in ("playwright.config.ts", "playwright.config.js", "vitest.config.ts"):
+        if (project / runner).is_file():
+            lines.append(f"runner:{runner}:present")
+    payload = "\n".join(sorted(lines)).encode("utf-8")
+    return "sha256:" + _sha256_bytes(payload)
+
+
+def _lease_path(lease_root: Path, stack_id: str) -> Path:
+    safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in stack_id)
+    return lease_root / f"{safe}.json"
+
+
+def list_leases(lease_root: Path) -> list[dict[str, Any]]:
+    if not lease_root.is_dir():
+        return []
+    out: list[dict[str, Any]] = []
+    for path in sorted(lease_root.glob("*.json")):
+        try:
+            data = _read_json(path)
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(data, dict):
+            out.append(data)
+    return out
+
+
+def require_writable_lease(
+    project: Path,
+    *,
+    change_id: str,
+    stack_id: str,
+    lease_root: Path | None = None,
+) -> dict[str, Any]:
+    """Gate: a writable stack may be used only with an active matching lease."""
+    root = lease_root or default_lease_root(project)
+    path = _lease_path(root, stack_id)
+    if not path.is_file():
+        return {
+            "ok": False,
+            "code": "ENVIRONMENT_LEASE_REQUIRED",
+            "message": f"no lease for stack={stack_id}; acquire before writable use",
+            "changeId": change_id,
+            "stackId": stack_id,
+        }
+    try:
+        lease = _read_json(path)
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "ENVIRONMENT_LEASE_REQUIRED",
+            "message": f"lease unreadable: {exc}",
+            "changeId": change_id,
+            "stackId": stack_id,
+        }
+    if str(lease.get("changeId") or "") != change_id:
+        return {
+            "ok": False,
+            "code": "ENVIRONMENT_LEASE_REQUIRED",
+            "message": (
+                f"stack={stack_id} leased by change={lease.get('changeId')}; "
+                f"requested change={change_id}"
+            ),
+            "changeId": change_id,
+            "stackId": stack_id,
+            "holder": lease.get("changeId"),
+        }
+    # Review Y2: expired leases must not remain writable.
+    expires_raw = lease.get("expiresAt")
+    if isinstance(expires_raw, str) and expires_raw.strip():
+        try:
+            raw = expires_raw.strip().replace("Z", "+00:00")
+            expires_at = dt.datetime.fromisoformat(raw)
+            # Normalize both sides to UTC so naive/aware/offset mixes compare safely.
+            if expires_at.tzinfo is None:
+                expires_at = expires_at.replace(tzinfo=dt.timezone.utc)
+            else:
+                expires_at = expires_at.astimezone(dt.timezone.utc)
+            now_utc = dt.datetime.now(dt.timezone.utc)
+            if now_utc >= expires_at:
+                return {
+                    "ok": False,
+                    "code": "ENVIRONMENT_LEASE_EXPIRED",
+                    "message": (
+                        f"lease for stack={stack_id} expired at {expires_raw}; "
+                        "re-acquire before writable use"
+                    ),
+                    "changeId": change_id,
+                    "stackId": stack_id,
+                    "expiresAt": expires_raw,
+                }
+        except ValueError:
+            return {
+                "ok": False,
+                "code": "ENVIRONMENT_LEASE_REQUIRED",
+                "message": f"lease expiresAt unreadable: {expires_raw}",
+                "changeId": change_id,
+                "stackId": stack_id,
+            }
+    return {"ok": True, "code": "LEASE_HELD", "lease": lease}
+
+
+def acquire_lease(
+    project: Path,
+    *,
+    change_id: str,
+    stack_id: str,
+    environment_hash: str,
+    lease_root: Path | None = None,
+    writable_volumes: list[str] | None = None,
+    ttl_seconds: int = 3600,
+) -> dict[str, Any]:
+    """Acquire a lease; reject cross-change sharing of the same writable volume."""
+    root = lease_root or default_lease_root(project)
+    root.mkdir(parents=True, exist_ok=True)
+    volumes = [str(v).replace("\\", "/") for v in (writable_volumes or [])]
+    for existing in list_leases(root):
+        holder = str(existing.get("changeId") or "")
+        if holder == change_id:
+            continue
+        other_vols = {
+            str(v).replace("\\", "/")
+            for v in (existing.get("writableVolumes") or [])
+        }
+        overlap = sorted(set(volumes) & other_vols)
+        if overlap:
+            return {
+                "ok": False,
+                "code": "ENVIRONMENT_LEASE_CROSS_CHANGE",
+                "message": (
+                    f"writable volume(s) {overlap} already held by change={holder}"
+                ),
+                "changeId": change_id,
+                "holder": holder,
+                "overlap": overlap,
+            }
+        if existing.get("stackId") == stack_id and holder and holder != change_id:
+            return {
+                "ok": False,
+                "code": "ENVIRONMENT_LEASE_CROSS_CHANGE",
+                "message": f"stack={stack_id} already leased by change={holder}",
+                "changeId": change_id,
+                "holder": holder,
+            }
+
+    path = _lease_path(root, stack_id)
+    if path.is_file():
+        try:
+            current = _read_json(path)
+        except (OSError, json.JSONDecodeError):
+            current = {}
+        if str(current.get("changeId") or "") not in {"", change_id}:
+            return {
+                "ok": False,
+                "code": "ENVIRONMENT_LEASE_CROSS_CHANGE",
+                "message": (
+                    f"stack={stack_id} already leased by change={current.get('changeId')}"
+                ),
+                "changeId": change_id,
+                "holder": current.get("changeId"),
+            }
+
+    started = dt.datetime.now().astimezone()
+    expires = started + dt.timedelta(seconds=max(60, int(ttl_seconds)))
+    lease = {
+        "schemaVersion": 1,
+        "changeId": change_id,
+        "stackId": stack_id,
+        "environmentHash": environment_hash,
+        "writableVolumes": volumes,
+        "acquiredAt": started.isoformat(timespec="seconds"),
+        "expiresAt": expires.isoformat(timespec="seconds"),
+        "projectRoot": str(project.resolve()),
+    }
+    _write_json(path, lease)
+    return {"ok": True, "code": "LEASE_ACQUIRED", "lease": lease, "path": str(path)}
+
+
+def release_lease(
+    project: Path,
+    *,
+    change_id: str,
+    stack_id: str,
+    lease_root: Path | None = None,
+) -> dict[str, Any]:
+    root = lease_root or default_lease_root(project)
+    path = _lease_path(root, stack_id)
+    if not path.is_file():
+        return {
+            "ok": True,
+            "code": "LEASE_ABSENT",
+            "message": "nothing to release",
+            "changeId": change_id,
+            "stackId": stack_id,
+        }
+    try:
+        lease = _read_json(path)
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "code": "LEASE_UNREADABLE", "message": str(exc)}
+    if str(lease.get("changeId") or "") != change_id:
+        return {
+            "ok": False,
+            "code": "ENVIRONMENT_LEASE_CROSS_CHANGE",
+            "message": "cannot release lease owned by another change",
+            "holder": lease.get("changeId"),
+            "changeId": change_id,
+        }
+    path.unlink(missing_ok=True)
+    return {"ok": True, "code": "LEASE_RELEASED", "changeId": change_id, "stackId": stack_id}
+
+
+def cmd_fingerprint(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    digest = compute_environment_hash(project)
+    return emit_json(
+        {
+            "ok": True,
+            "action": "fingerprint",
+            "projectRoot": str(project),
+            "environmentHash": digest,
+        }
+    )
+
+
+def cmd_acquire(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    root = Path(args.lease_root).resolve() if args.lease_root else default_lease_root(project)
+    env_hash = args.environment_hash or compute_environment_hash(project)
+    volumes = [v for v in (args.writable_volume or []) if v]
+    result = acquire_lease(
+        project,
+        change_id=args.change,
+        stack_id=args.stack_id,
+        environment_hash=env_hash,
+        lease_root=root,
+        writable_volumes=volumes,
+        ttl_seconds=int(args.ttl_seconds or 3600),
+    )
+    return emit_json(result, ok=bool(result.get("ok")))
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    root = Path(args.lease_root).resolve() if args.lease_root else default_lease_root(project)
+    result = release_lease(
+        project,
+        change_id=args.change,
+        stack_id=args.stack_id,
+        lease_root=root,
+    )
+    return emit_json(result, ok=bool(result.get("ok")))
+
+
+def cmd_require(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    root = Path(args.lease_root).resolve() if args.lease_root else default_lease_root(project)
+    result = require_writable_lease(
+        project,
+        change_id=args.change,
+        stack_id=args.stack_id,
+        lease_root=root,
+    )
+    return emit_json(result, ok=bool(result.get("ok")))
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    root = Path(args.lease_root).resolve() if args.lease_root else default_lease_root(project)
+    return emit_json(
+        {
+            "ok": True,
+            "action": "status",
+            "projectRoot": str(project),
+            "environmentHash": compute_environment_hash(project),
+            "leases": list_leases(root),
+            "leaseRoot": str(root),
+            "contract": [
+                "prepare",
+                "fingerprint",
+                "acquire",
+                "reset/clone",
+                "run",
+                "record",
+                "release",
+            ],
+        }
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness_environment.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    fp = sub.add_parser("fingerprint")
+    fp.add_argument("--project", required=True)
+    fp.set_defaults(func=cmd_fingerprint)
+
+    ac = sub.add_parser("acquire")
+    ac.add_argument("--project", required=True)
+    ac.add_argument("--change", required=True)
+    ac.add_argument("--stack-id", required=True)
+    ac.add_argument("--environment-hash")
+    ac.add_argument("--lease-root")
+    ac.add_argument("--writable-volume", action="append", default=[])
+    ac.add_argument("--ttl-seconds", type=int, default=3600)
+    ac.set_defaults(func=cmd_acquire)
+
+    rel = sub.add_parser("release")
+    rel.add_argument("--project", required=True)
+    rel.add_argument("--change", required=True)
+    rel.add_argument("--stack-id", required=True)
+    rel.add_argument("--lease-root")
+    rel.set_defaults(func=cmd_release)
+
+    req = sub.add_parser("require")
+    req.add_argument("--project", required=True)
+    req.add_argument("--change", required=True)
+    req.add_argument("--stack-id", required=True)
+    req.add_argument("--lease-root")
+    req.set_defaults(func=cmd_require)
+
+    st = sub.add_parser("status")
+    st.add_argument("--project", required=True)
+    st.add_argument("--lease-root")
+    st.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/general/codex/scripts/harness_events.py

@@ -968,28 +968,89 @@ def late_event_stats(phase_events: list[dict[str, Any]]) -> dict[str, int]:
     return {"lateEventCount": len(late_stamps), "lateEventSpanMs": span}
 
 
-def attempt_invocations(phase_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """Per-attempt invocation view: attempt, status, durationMs (RET-22)."""
+def _seal_timestamp_for_attempt(
+    events_in: list[dict[str, Any]],
+    *,
+    cutoff_ts: str | None,
+    next_attempt_start: Any = None,
+) -> tuple[Any, str | None]:
+    """Pick INCOMPLETE seal time: next start, recovery, or report cutoff."""
+    recovery_ts = None
+    for event in events_in:
+        if str(event.get("type") or "").lower() in {
+            "recovery",
+            "phase.recovery",
+            "attempt.recovery",
+        }:
+            recovery_ts = event.get("timestamp") or recovery_ts
+    if next_attempt_start:
+        return next_attempt_start, "INCOMPLETE"
+    if recovery_ts:
+        return recovery_ts, "INCOMPLETE"
+    if cutoff_ts:
+        return cutoff_ts, "INCOMPLETE"
+    # Fall back to last event timestamp so wall clock is not silently dropped.
+    for event in reversed(events_in):
+        if event.get("timestamp"):
+            return event.get("timestamp"), "INCOMPLETE"
+    return None, "INCOMPLETE"
+
+
+def attempt_invocations(
+    phase_events: list[dict[str, Any]],
+    *,
+    cutoff_ts: str | None = None,
+) -> list[dict[str, Any]]:
+    """Per-attempt invocation view: attempt, status, durationMs (RET-22 / IA-2).
+
+    Closed attempts keep phase.end status. Unclosed attempts are sealed as
+    INCOMPLETE at the next attempt start, an explicit recovery event, or cutoff.
+    """
+    attempts = split_phase_attempts(phase_events)
     invocations: list[dict[str, Any]] = []
-    for attempt in split_phase_attempts(phase_events):
+    for index, attempt in enumerate(attempts):
         events_in = attempt.get("events") or []
         start_ts = None
         end_ts = None
         status = None
+        closed_by_end = False
         for event in events_in:
             if event.get("type") == "phase.start" and start_ts is None:
                 start_ts = event.get("timestamp")
             elif event.get("type") == "phase.end":
                 end_ts = event.get("timestamp")
-                status = event.get("status", status)
+                if "status" in event:
+                    status = event.get("status")
+                closed_by_end = True
+        sealed_incomplete = False
+        if not closed_by_end:
+            next_start = None
+            if index + 1 < len(attempts):
+                for event in attempts[index + 1].get("events") or []:
+                    if event.get("type") == "phase.start" and event.get("timestamp"):
+                        next_start = event.get("timestamp")
+                        break
+            seal_ts, seal_status = _seal_timestamp_for_attempt(
+                events_in,
+                cutoff_ts=cutoff_ts,
+                next_attempt_start=next_start,
+            )
+            if seal_ts is not None:
+                end_ts = seal_ts
+                status = seal_status
+                sealed_incomplete = True
         duration = None
         if start_ts and end_ts:
             duration = duration_ms_between(start_ts, end_ts)
+        # Active execution counts phase.end-closed attempts only (INCOMPLETE seals excluded).
+        active_eligible = closed_by_end and not sealed_incomplete
         invocations.append(
             {
                 "attempt": attempt.get("attempt"),
                 "status": status,
                 "durationMs": duration,
+                "activeEligible": active_eligible,
+                "sealedIncomplete": sealed_incomplete,
             }
         )
     return invocations
@@ -1005,30 +1066,48 @@ def phase_final_state(phase_events: list[dict[str, Any]]) -> dict[str, Any]:
         "attempt": latest.get("attempt"),
         "status": latest.get("status"),
         "durationMs": latest.get("durationMs"),
-        "closed": latest.get("status") is not None,
+        "closed": latest.get("status") is not None and latest.get("status") != "INCOMPLETE",
     }
 
 
-def canonical_phase_timing(phase_events: list[dict[str, Any]]) -> dict[str, Any]:
-    """Single reducer for every duration view (RET-20).
+def canonical_phase_timing(
+    phase_events: list[dict[str, Any]],
+    *,
+    cutoff_ts: str | None = None,
+) -> dict[str, Any]:
+    """Single reducer for every duration view (RET-20 / IA-2).
 
-    activeExecutionMs: phase.start → matching phase.end (closed contract).
-    wallClockSpanMs: first → last timestamp in the bucket, late events included.
+    activeExecutionMs: sum of closed attempt start→end only (INCOMPLETE excluded).
+    wallClockSpanMs: first → last/cutoff timestamp; unclosed attempts retain span.
     """
+    invocations = attempt_invocations(phase_events, cutoff_ts=cutoff_ts)
     stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
-    invocation_durations = [
+    # Cutoff seals INCOMPLETE attempts but must not inflate stage wall by itself.
+    # Include cutoff in the wall span only when it sealed an otherwise-open attempt.
+    if cutoff_ts and any(inv.get("sealedIncomplete") for inv in invocations):
+        stamps = list(stamps) + [cutoff_ts]
+    closed_durations = [
         invocation["durationMs"]
-        for invocation in attempt_invocations(phase_events)
-        if invocation.get("durationMs") is not None
+        for invocation in invocations
+        if invocation.get("activeEligible") and invocation.get("durationMs") is not None
     ]
-    active = sum(invocation_durations) if invocation_durations else None
+    active = sum(closed_durations) if closed_durations else (0 if invocations else None)
     late = late_event_stats(phase_events)
-    wall = duration_ms_between(stamps[0], stamps[-1]) if len(stamps) >= 2 else active
+    if len(stamps) >= 2:
+        wall = duration_ms_between(stamps[0], stamps[-1])
+    else:
+        wall = active
+    unclosed = sum(
+        1
+        for invocation in invocations
+        if invocation.get("sealedIncomplete") or invocation.get("status") == "INCOMPLETE"
+    )
     return {
         "activeExecutionMs": active,
         "wallClockSpanMs": wall,
         "lateEventCount": late["lateEventCount"],
         "lateEventSpanMs": late["lateEventSpanMs"],
+        "unclosedAttemptCount": unclosed,
     }
 
 

package/harness/bundles/general/cursor/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "cd03d22b60760428"
+  "coreHash": "36597f7648520b90"
 }

package/harness/bundles/general/cursor/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=cd03d22b60760428; overlay=none; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=36597f7648520b90; overlay=none; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/general/cursor/harness-archive/checklist.md

@@ -14,6 +14,20 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - before/after checksum 不一致时，不得删除原目录。
 - 默认渲染器 `templates/render-summary.mjs`（finalize 内嵌调用）。
 
+### Wave-A 状态机与身份（IA-1 / IA-4）
+
+硬顺序：feature frozen → local gates → product candidate CI → **CI green** → merge → authoritative CI → archive product candidate → archive-only governance → release。
+
+- [ ] `evidence/product-candidate-ci.json`（或等价 ledger 字段）`conclusion=success`，含 `runUrl` + `commit`；否则 `PRODUCT_CI_NOT_GREEN` 阻断
+- [ ] summary/identity 含 `productCommit` / `productTreeHash` / `archiveCommit`；`productTreeHash` 排除 `.harness/**`
+- [ ] 产品输入在 archive 后变化 → `ARCHIVE_EVIDENCE_REOPEN_REQUIRED`，旧 archive 不可作发布证据
+- [ ] Manifest：coverage 字节在最终 snapshot 后不得静默漂移；后写报告必须 `exclusionReasons`，禁止假绿 `checksumStatus=OK`
+
+### Environment 合同（IA-3）
+
+- [ ] 使用可写环境栈前：`harness_environment.py fingerprint` → `acquire` lease → run → `release`
+- [ ] 租约落在主仓 `.harness/runtime/env-leases/`；跨 change 默认不得共享可写 volume
+
 ## 归档前检查（Phase 1）
 
 > ⚠️ **单一所有权**：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。