@hunter-harness/workflow-harness 0.4.0 → 0.4.1

package/harness/bundles/general/pi/scripts/harness_sync.py

@@ -0,0 +1,407 @@
+"""harness_sync — 受管 sync runtime 清理器（变更簇 D / task 13，RET-36/37/38/39）。
+
+每次 sync 使用 `.harness/runtime/sync/<run-id>/deploy/<agent>/` 并写
+`owner.json`（runId/pid/processStart/startedAt/agent/purpose/expiresAt）。
+正常、失败与异常退出均在 finally 清理本 run（`SyncRun` 上下文管理器 /
+`finalize_run`）。启动时 `reap_stale_runs` 只回收同时满足以下条件的目录：
+
+1. owner 进程已死亡（pid liveness + create-time 匹配，可注入）；
+2. 已超过 TTL（expiresAt < now）；
+3. 删除目标 resolved 后仍位于精确 sync runtime root 内；
+4. 不是当前活跃 run。
+
+owner 缺失的 legacy 目录默认只报告 `unverifiable`，不删除；显式
+`--diagnose` 模式才处理。删除失败只产生带精确路径的 warning。
+
+本模块不做任何 `.gitignore` / `git check-ignore` 判断（RET-34/COM-004），
+不修改也不建议修改项目 Git 策略。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+SYNC_RUNTIME_REL = Path(".harness") / "runtime" / "sync"
+OWNER_FILE = "owner.json"
+OWNER_SCHEMA_VERSION = 1
+DEFAULT_TTL_SECONDS = 3600
+
+_RUN_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _iso(value: datetime) -> str:
+    return value.astimezone(timezone.utc).isoformat()
+
+
+def _parse_iso(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    text = raw.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def sync_runtime_root(project_root: Path | str) -> Path:
+    return Path(project_root) / SYNC_RUNTIME_REL
+
+
+def _validate_run_id(run_id: str) -> str:
+    if not isinstance(run_id, str) or not _RUN_ID_RE.match(run_id):
+        raise ValueError(f"invalid run id: {run_id!r}")
+    if run_id in {".", ".."} or "/" in run_id or "\\" in run_id:
+        raise ValueError(f"run id must not escape sync root: {run_id!r}")
+    return run_id
+
+
+def _process_start_marker() -> str:
+    """Best-effort process create-time marker for owner liveness matching.
+
+    跨平台保守实现：boot 时间 + pid 足以区分同 pid 的不同世代进程。
+    """
+    try:
+        with open("/proc/stat", "r", encoding="utf-8") as handle:
+            for line in handle:
+                if line.startswith("btime"):
+                    return f"boot:{line.split()[1]}"
+    except OSError:
+        pass
+    return f"pid:{os.getpid()} boot:unknown"
+
+
+def _default_pid_alive(pid: int, process_start: str | None) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+@dataclass
+class SyncRun:
+    """Handle for one sync run; use as context manager for finally cleanup."""
+
+    project_root: Path
+    run_id: str
+    purpose: str
+    ttl_seconds: int = DEFAULT_TTL_SECONDS
+    keep_temp: bool = False
+    agents: list[str] = field(default_factory=list)
+    _finalized: bool = False
+
+    @property
+    def run_dir(self) -> Path:
+        return sync_runtime_root(self.project_root) / self.run_id
+
+    def workspace(self, agent: str) -> Path:
+        return self.run_dir / "deploy" / agent
+
+    def __enter__(self) -> "SyncRun":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        finalize_run(self)
+        return False
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def begin_run(
+    project_root: Path | str,
+    *,
+    run_id: str | None = None,
+    agent: str,
+    purpose: str,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    keep_temp: bool = False,
+) -> SyncRun:
+    """Create `.harness/runtime/sync/<run-id>/deploy/<agent>/` + owner.json."""
+    root = Path(project_root)
+    run_id = _validate_run_id(run_id or f"sync-{uuid.uuid4().hex[:12]}")
+    run = SyncRun(
+        project_root=root,
+        run_id=run_id,
+        purpose=purpose,
+        ttl_seconds=ttl_seconds,
+        keep_temp=keep_temp,
+        agents=[agent],
+    )
+    workspace = run.workspace(agent)
+    workspace.mkdir(parents=True, exist_ok=True)
+    started = _now()
+    owner = {
+        "schemaVersion": OWNER_SCHEMA_VERSION,
+        "runId": run_id,
+        "pid": os.getpid(),
+        "processStart": _process_start_marker(),
+        "startedAt": _iso(started),
+        "agent": agent,
+        "agents": [agent],
+        "purpose": purpose,
+        "expiresAt": _iso(started + timedelta(seconds=ttl_seconds)),
+    }
+    _write_json(run.run_dir / OWNER_FILE, owner)
+    return run
+
+
+def register_agent_workspace(run: SyncRun, agent: str) -> Path:
+    """Add another agent workspace under the same run-id (INT-008)."""
+    workspace = run.workspace(agent)
+    workspace.mkdir(parents=True, exist_ok=True)
+    if agent not in run.agents:
+        run.agents.append(agent)
+    owner_path = run.run_dir / OWNER_FILE
+    owner = _read_json(owner_path)
+    if owner is not None:
+        agents = owner.get("agents")
+        if not isinstance(agents, list):
+            agents = [owner.get("agent")]
+        if agent not in agents:
+            agents.append(agent)
+        owner["agents"] = agents
+        _write_json(owner_path, owner)
+    return workspace
+
+
+def finalize_run(run: SyncRun) -> None:
+    """Remove this run's workspace unless keep_temp diagnostics requested it."""
+    if run._finalized:
+        return
+    run._finalized = True
+    if run.keep_temp:
+        return
+    run_dir = run.run_dir
+    if run_dir.exists():
+        shutil.rmtree(run_dir, ignore_errors=True)
+
+
+def finalize_run_id(
+    project_root: Path | str, run_id: str, *, keep_temp: bool = False
+) -> dict[str, Any]:
+    """Finalize one exact CLI-managed run with the same boundary checks."""
+    run_id = _validate_run_id(run_id)
+    root = sync_runtime_root(project_root).resolve()
+    run_dir = (root / run_id).resolve()
+    if not _inside_resolved(run_dir, root) or run_dir == root:
+        raise ValueError(f"run path escapes sync root: {run_dir}")
+    existed = run_dir.is_dir()
+    if existed and not keep_temp:
+        shutil.rmtree(run_dir)
+    return {
+        "ok": True,
+        "action": "finalize",
+        "runId": run_id,
+        "deleted": existed and not keep_temp,
+        "kept": bool(existed and keep_temp),
+    }
+
+
+def _inside_resolved(child: Path, parent: Path) -> bool:
+    try:
+        resolved_child = child.resolve()
+        resolved_parent = parent.resolve()
+    except OSError:
+        return False
+    return resolved_child == resolved_parent or resolved_parent in resolved_child.parents
+
+
+def reap_stale_runs(
+    project_root: Path | str,
+    *,
+    now: datetime | None = None,
+    pid_alive: Callable[[int, str | None], bool] | None = None,
+    active_run_ids: set[str] | None = None,
+    diagnose: bool = False,
+) -> dict[str, Any]:
+    """Reap only dead-owner + past-TTL dirs inside the exact sync root.
+
+    Ownerless legacy dirs are reported as ``unverifiable`` and left alone
+    unless ``diagnose=True`` explicitly handles them.
+    """
+    now = now or _now()
+    alive = pid_alive or _default_pid_alive
+    active = active_run_ids or set()
+    result: dict[str, Any] = {
+        "ok": True,
+        "reaped": [],
+        "skipped": [],
+        "unverifiable": [],
+        "warnings": [],
+    }
+    root = sync_runtime_root(project_root)
+    if not root.is_dir():
+        return result
+
+    for entry in sorted(root.iterdir()):
+        if not entry.is_dir():
+            continue
+        run_id = entry.name
+        # 删除目标必须 resolved 后仍位于精确 sync root 内（RET-39）。
+        if not _inside_resolved(entry, root):
+            result["warnings"].append(f"path escapes sync root, untouched: {entry}")
+            continue
+        if run_id in active:
+            result["skipped"].append(run_id)
+            continue
+        owner_path = entry / OWNER_FILE
+        owner = _read_json(owner_path) if owner_path.is_file() else None
+        if owner is None:
+            # owner 缺失的 legacy 目录：默认只报告 UNVERIFIABLE，不删除。
+            result["unverifiable"].append(run_id)
+            if diagnose:
+                try:
+                    shutil.rmtree(entry)
+                    result["reaped"].append(run_id)
+                except OSError as exc:
+                    result["warnings"].append(f"failed to remove {entry}: {exc}")
+            continue
+        pid = owner.get("pid")
+        process_start = owner.get("processStart")
+        expires = _parse_iso(owner.get("expiresAt"))
+        owner_dead = not alive(int(pid) if isinstance(pid, int) else -1, process_start)
+        past_ttl = expires is not None and expires < now
+        if owner_dead and past_ttl:
+            try:
+                shutil.rmtree(entry)
+                result["reaped"].append(run_id)
+            except OSError as exc:
+                result["warnings"].append(f"failed to remove {entry}: {exc}")
+        else:
+            result["skipped"].append(run_id)
+    return result
+
+
+def cmd_reap(args: argparse.Namespace) -> int:
+    result = reap_stale_runs(
+        Path(args.project),
+        active_run_ids=set(args.active_run or []),
+        diagnose=bool(args.diagnose),
+    )
+    payload = {"action": "reap", **result}
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False))
+    else:
+        reaped = ", ".join(result["reaped"]) or "-"
+        skipped = ", ".join(result["skipped"]) or "-"
+        unverifiable = ", ".join(result["unverifiable"]) or "-"
+        print(f"reaped: {reaped}")
+        print(f"skipped: {skipped}")
+        print(f"unverifiable: {unverifiable}")
+        for warning in result["warnings"]:
+            print(f"warning: {warning}", file=sys.stderr)
+    return 0
+
+
+def cmd_begin(args: argparse.Namespace) -> int:
+    run = begin_run(
+        Path(args.project),
+        run_id=args.run_id,
+        agent=args.agent,
+        purpose=args.purpose,
+        ttl_seconds=args.ttl_seconds,
+        keep_temp=bool(args.keep_temp),
+    )
+    payload = {
+        "ok": True,
+        "action": "begin",
+        "runId": run.run_id,
+        "runDir": str(run.run_dir.resolve()),
+        "workspace": str(run.workspace(args.agent).resolve()),
+    }
+    print(json.dumps(payload, ensure_ascii=False) if args.json else payload["workspace"])
+    return 0
+
+
+def cmd_finalize(args: argparse.Namespace) -> int:
+    payload = finalize_run_id(
+        Path(args.project), args.run_id, keep_temp=bool(args.keep_temp)
+    )
+    print(json.dumps(payload, ensure_ascii=False) if args.json else payload["runId"])
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="harness_sync",
+        description="managed sync runtime owner/TTL/finally cleaner",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_begin = sub.add_parser("begin", help="create one owned sync runtime")
+    p_begin.add_argument("--project", required=True)
+    p_begin.add_argument("--run-id")
+    p_begin.add_argument("--agent", required=True)
+    p_begin.add_argument("--purpose", required=True)
+    p_begin.add_argument("--ttl-seconds", type=int, default=DEFAULT_TTL_SECONDS)
+    p_begin.add_argument("--keep-temp", action="store_true")
+    p_begin.add_argument("--json", action="store_true")
+    p_begin.set_defaults(func=cmd_begin)
+    p_finalize = sub.add_parser("finalize", help="remove one exact owned sync runtime")
+    p_finalize.add_argument("--project", required=True)
+    p_finalize.add_argument("--run-id", required=True)
+    p_finalize.add_argument("--keep-temp", action="store_true")
+    p_finalize.add_argument("--json", action="store_true")
+    p_finalize.set_defaults(func=cmd_finalize)
+    p_reap = sub.add_parser("reap", help="reap dead-owner past-TTL sync run dirs")
+    p_reap.add_argument("--project", required=True, help="project root path")
+    p_reap.add_argument("--json", action="store_true", help="emit JSON payload")
+    p_reap.add_argument(
+        "--diagnose",
+        action="store_true",
+        help="explicit diagnostics mode: also remove ownerless legacy dirs",
+    )
+    p_reap.add_argument(
+        "--active-run",
+        action="append",
+        default=[],
+        help="run id still active (never reaped); repeatable",
+    )
+    p_reap.set_defaults(func=cmd_reap)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/harness/bundles/general/pi/scripts/harness_test_cleanup.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Controlled cleanup helper for test fixtures (retro §5.23).
+
+Provides a host-policy-friendly entry point for removing gitignored test
+fixtures (e.g. .pytest_data) within an execution root. Performs realpath
+containment, rejects symlink/reparse escapes, lists exact counts before
+deletion, and outputs a structured receipt.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+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")
+
+
+def _resolve_within(execution_root: Path, rel: str) -> Path | None:
+    """Resolve rel under execution_root, rejecting escapes and symlinks."""
+    if not rel or rel.startswith("/"):
+        return None
+    # Reject absolute paths (Windows drive letter or POSIX).
+    if len(rel) >= 2 and rel[1] == ":":
+        return None
+    parts = rel.replace("\\", "/").split("/")
+    if ".." in parts:
+        return None
+    candidate = (execution_root / rel).resolve(strict=False)
+    # Containment check: candidate must be under execution_root.
+    try:
+        candidate.relative_to(execution_root.resolve(strict=False))
+    except ValueError:
+        return None
+    # Reject symlink/reparse escape: if the path is a symlink, check its target.
+    if candidate.is_symlink():
+        target = Path(os.readlink(candidate)).resolve(strict=False)
+        try:
+            target.relative_to(execution_root.resolve(strict=False))
+        except ValueError:
+            return None
+        # Even if target is inside, a symlinked cleanup root is suspicious;
+        # reject to avoid following links into unexpected locations.
+        return None
+    return candidate
+
+
+def _count_files(root: Path) -> tuple[int, int]:
+    """Count files and total bytes under root."""
+    count = 0
+    total = 0
+    for dirpath, _dirs, files in os.walk(root):
+        for name in files:
+            fp = Path(dirpath) / name
+            try:
+                total += fp.stat().st_size
+                count += 1
+            except OSError:
+                continue
+    return count, total
+
+
+def cleanup(execution_root: Path, cleanup_roots: list[str]) -> dict[str, Any]:
+    """Remove allowlisted cleanup roots within execution_root.
+
+    Returns a structured receipt. Any path escape, symlink escape, or
+    unallowed root results in ok=false with zero files removed.
+    """
+    execution_root = Path(execution_root).resolve(strict=False)
+    if not execution_root.is_dir():
+        return {
+            "ok": False,
+            "code": "EXECUTION_ROOT_MISSING",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+        }
+
+    rejected: list[dict[str, str]] = []
+    removed_files = 0
+    removed_bytes = 0
+    cleaned: list[str] = []
+
+    for rel in cleanup_roots:
+        target = _resolve_within(execution_root, rel)
+        if target is None:
+            rejected.append({"path": rel, "reason": "PATH_ESCAPE_REJECTED"})
+            continue
+        if not target.exists():
+            # Already absent — idempotent reentry.
+            continue
+        # Re-check symlink after resolution (the parent might be a symlink).
+        if target.is_symlink():
+            rejected.append({"path": rel, "reason": "SYMLINK_ESCAPE_REJECTED"})
+            continue
+        # Count before deletion for the receipt.
+        try:
+            count, total = _count_files(target)
+        except OSError:
+            count, total = 0, 0
+        # Delete.
+        try:
+            shutil.rmtree(target)
+        except OSError as exc:
+            rejected.append({"path": rel, "reason": f"DELETE_FAILED: {exc}"})
+            continue
+        removed_files += count
+        removed_bytes += total
+        cleaned.append(rel)
+
+    if rejected:
+        return {
+            "ok": False,
+            "code": rejected[0]["reason"],
+            "executionRoot": str(execution_root),
+            "removedFiles": removed_files,
+            "removedBytes": removed_bytes,
+            "rejectedEscapes": rejected,
+            "cleaned": cleaned,
+        }
+
+    if removed_files == 0 and not cleaned:
+        return {
+            "ok": True,
+            "code": "ALREADY_ABSENT",
+            "executionRoot": str(execution_root),
+            "removedFiles": 0,
+            "removedBytes": 0,
+            "rejectedEscapes": [],
+            "cleaned": [],
+        }
+
+    return {
+        "ok": True,
+        "code": "CLEANUP_COMPLETE",
+        "executionRoot": str(execution_root),
+        "removedFiles": removed_files,
+        "removedBytes": removed_bytes,
+        "rejectedEscapes": [],
+        "cleaned": cleaned,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    clean_parser = sub.add_parser("cleanup")
+    clean_parser.add_argument("--execution-root", required=True)
+    clean_parser.add_argument("--cleanup-roots", required=True, help="JSON array of relative paths")
+    clean_parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    try:
+        roots = json.loads(args.cleanup_roots)
+        if not isinstance(roots, list):
+            raise ValueError("cleanup-roots must be a JSON array")
+    except (json.JSONDecodeError, ValueError) as exc:
+        result = {"ok": False, "code": "INVALID_CLEANUP_ROOTS", "error": str(exc)}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 1
+
+    result = cleanup(Path(args.execution_root), roots)
+    print(json.dumps(result, ensure_ascii=False, indent=2 if args.json else None))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())