nobrainer-tech-flow 0.0.0-stage → 2.4.1

package/skills/nobrainer-tech-flow/scripts/check_flow_update.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""Read-only daily check for a newer nobrainer-tech-flow GitHub release."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+
+RELEASE_API = "https://api.github.com/repos/nobrainer-tech/nobrainer-tech-flow/releases/latest"
+TIMEOUT_SECONDS = 5
+MAX_RESPONSE_BYTES = 256 * 1024
+SUPPORTED_CLIENTS = ("agents", "claude", "codex", "copilot", "opencode")
+VERSION_RE = re.compile(
+    r"^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$"
+)
+
+
+class UpdateCheckError(Exception):
+    """A bounded API or local-state failure suitable for a short CLI report."""
+
+
+def parse_version(value: str) -> tuple[int, int, int, tuple[tuple[int, Any], ...] | None]:
+    """Parse SemVer without guessing from arbitrary version strings."""
+    match = VERSION_RE.fullmatch(value.strip())
+    if not match:
+        raise UpdateCheckError(f"unsupported version format: {value!r}")
+    core = tuple(int(match.group(index)) for index in (1, 2, 3))
+    prerelease = match.group(4)
+    if prerelease is None:
+        return core[0], core[1], core[2], None
+    parts: list[tuple[int, Any]] = []
+    for item in prerelease.split("."):
+        if item.isdigit():
+            if len(item) > 1 and item.startswith("0"):
+                raise UpdateCheckError(f"invalid numeric prerelease identifier: {item!r}")
+            parts.append((0, int(item)))
+        else:
+            parts.append((1, item))
+    return core[0], core[1], core[2], tuple(parts)
+
+
+def is_newer(latest: str, installed: str) -> bool:
+    """Return whether latest is strictly newer according to SemVer precedence."""
+    left = parse_version(latest)
+    right = parse_version(installed)
+    if left[:3] != right[:3]:
+        return left[:3] > right[:3]
+    left_pre, right_pre = left[3], right[3]
+    if left_pre is None:
+        return right_pre is not None
+    if right_pre is None:
+        return False
+    for left_item, right_item in zip(left_pre, right_pre):
+        if left_item != right_item:
+            # Numeric identifiers have lower precedence than non-numeric ones.
+            if left_item[0] != right_item[0]:
+                return left_item[0] < right_item[0]
+            return left_item[1] > right_item[1]
+    return len(left_pre) > len(right_pre)
+
+
+def fetch_latest_release(timeout: float = TIMEOUT_SECONDS) -> tuple[str, str]:
+    """Fetch only the public latest-release metadata; never execute remote data."""
+    request = urllib.request.Request(
+        RELEASE_API,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "NoBrainer-Tech-Flow-update-check",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read(MAX_RESPONSE_BYTES + 1)
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise UpdateCheckError(f"GitHub release check failed: {type(exc).__name__}") from None
+    if len(raw) > MAX_RESPONSE_BYTES:
+        raise UpdateCheckError("GitHub release metadata exceeded the size limit")
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise UpdateCheckError("GitHub returned invalid release metadata") from None
+    if not isinstance(data, dict) or data.get("draft") is not False or data.get("prerelease") is not False:
+        raise UpdateCheckError("GitHub response is not a published stable release")
+    tag = data.get("tag_name")
+    url = data.get("html_url")
+    if not isinstance(tag, str) or not isinstance(url, str):
+        raise UpdateCheckError("GitHub release metadata is missing a valid tag or release URL")
+    parse_version(tag)
+    parsed_url = urlsplit(url)
+    expected_path = "/nobrainer-tech/nobrainer-tech-flow/releases/tag/" + quote(tag, safe="")
+    if (
+        parsed_url.scheme != "https"
+        or parsed_url.netloc != "github.com"
+        or parsed_url.path != expected_path
+        or parsed_url.query
+        or parsed_url.fragment
+    ):
+        raise UpdateCheckError("GitHub release URL does not match the official repository and tag")
+    return tag, url
+
+
+def state_root() -> Path:
+    """Return a portable per-user state directory outside the source checkout."""
+    override = os.environ.get("NOBRAINER_TECH_FLOW_STATE_HOME")
+    if override:
+        return Path(override).expanduser() / "update-checks"
+    if sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    elif os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state"))
+    return base / "nobrainer-tech-flow" / "update-checks"
+
+
+def _read_state(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {"schema_version": 1, "checks": {}, "latest_verified": None}
+    except (OSError, json.JSONDecodeError):
+        return {"schema_version": 1, "checks": {}, "latest_verified": None}
+    if not isinstance(value, dict) or value.get("schema_version") != 1:
+        return {"schema_version": 1, "checks": {}, "latest_verified": None}
+    if not isinstance(value.get("checks"), dict):
+        value["checks"] = {}
+    return value
+
+
+def _write_state(path: Path, state: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
+    temp = path.with_suffix(f".{os.getpid()}.tmp")
+    try:
+        temp.write_text(json.dumps(state, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+        try:
+            os.chmod(temp, 0o600)
+        except OSError:
+            pass
+        temp.replace(path)
+    finally:
+        try:
+            temp.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def read_installed_version(path: Path | None = None) -> str:
+    version_file = path or Path(__file__).resolve().parents[1] / "VERSION"
+    try:
+        version = version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        raise UpdateCheckError(
+            "installed skill version is unavailable; include its VERSION file or pass --installed-version"
+        ) from None
+    if not version:
+        raise UpdateCheckError("installed skill VERSION file is empty; pass --installed-version")
+    parse_version(version)
+    return version
+
+
+def check_update(
+    client: str,
+    installed: str,
+    *,
+    force: bool = False,
+    unattended: bool = False,
+    now: dt.datetime | None = None,
+    root: Path | None = None,
+    fetcher=fetch_latest_release,
+) -> dict[str, Any]:
+    """Check/cached-read one client and installed ref for the local calendar day."""
+    if client not in SUPPORTED_CLIENTS:
+        raise UpdateCheckError(f"unsupported client: {client!r}")
+    parse_version(installed)
+    today = (now or dt.datetime.now().astimezone()).date().isoformat()
+    client_root = (root or state_root()) / client
+    path = client_root / "state.json"
+    state = _read_state(path)
+    key = f"{today}|{installed}"
+    cached = state["checks"].get(key)
+    if isinstance(cached, dict) and not force:
+        return {**cached, "cached": True, "unattended": unattended}
+
+    checked_at = (now or dt.datetime.now().astimezone()).isoformat(timespec="seconds")
+    try:
+        latest, release_url = fetcher()
+        parse_version(latest)
+        result: dict[str, Any] = {
+            "date": today,
+            "checked_at": checked_at,
+            "client": client,
+            "installed_ref": installed,
+            "latest_ref": latest,
+            "release_url": release_url,
+            "status": "UPDATE_AVAILABLE" if is_newer(latest, installed) else "CURRENT",
+            "stale": False,
+        }
+        state["latest_verified"] = {
+            "latest_ref": latest,
+            "release_url": release_url,
+            "checked_at": checked_at,
+            "date": today,
+        }
+    except UpdateCheckError as exc:
+        previous = state.get("latest_verified")
+        result = {
+            "date": today,
+            "checked_at": checked_at,
+            "client": client,
+            "installed_ref": installed,
+            "latest_ref": previous.get("latest_ref") if isinstance(previous, dict) else None,
+            "release_url": previous.get("release_url") if isinstance(previous, dict) else None,
+            "status": "CHECK_FAILED",
+            "error": str(exc),
+            "stale": isinstance(previous, dict),
+            "previously_checked_at": previous.get("checked_at") if isinstance(previous, dict) else None,
+        }
+    result["cached"] = False
+    result["unattended"] = unattended
+    state["checks"][key] = result
+    # Bound local state while retaining the latest known successful release.
+    if len(state["checks"]) > 90:
+        ordered = sorted(state["checks"].items(), key=lambda item: item[1].get("checked_at", ""))
+        for old_key, _ in ordered[: len(state["checks"]) - 90]:
+            del state["checks"][old_key]
+    try:
+        _write_state(path, state)
+    except OSError as exc:
+        raise UpdateCheckError(f"could not save update-check state: {type(exc).__name__}") from None
+    return result
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--client", required=True, choices=SUPPORTED_CLIENTS)
+    parser.add_argument(
+        "--installed-version",
+        help="Override the version in the installed skill's adjacent VERSION file",
+    )
+    parser.add_argument("--force", action="store_true", help="Fetch again even if already checked today")
+    parser.add_argument("--unattended", action="store_true", help="Emit a stable machine-readable line for schedulers")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        installed = args.installed_version or read_installed_version()
+        result = check_update(args.client, installed, force=args.force, unattended=args.unattended)
+    except UpdateCheckError as exc:
+        print(f"UPDATE_CHECK: ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    status = result["status"]
+    if args.unattended:
+        fields = [
+            f"status={status}",
+            f"client={result['client']}",
+            f"installed_ref={result['installed_ref']}",
+            f"latest_ref={result.get('latest_ref') or 'unknown'}",
+            f"cached={str(result['cached']).lower()}",
+            f"stale={str(result.get('stale', False)).lower()}",
+        ]
+        print("UPDATE_CHECK: " + " ".join(fields))
+    else:
+        print(f"UPDATE_CHECK: {status} client={result['client']} installed={result['installed_ref']} latest={result.get('latest_ref') or 'unknown'}")
+        if status == "UPDATE_AVAILABLE":
+            print(f"Release: {result['release_url']}")
+            print(
+                f"Next: obtain and review release tag {result['latest_ref']} from the official repository; "
+                "verify its source and release evidence, then run the installer dry-run, apply "
+                "the reviewed update, and read back the installed files and version."
+            )
+        elif status == "CHECK_FAILED":
+            print(f"Details: {result['error']}")
+            if result.get("stale"):
+                print(f"Last verified release: {result['latest_ref']} at {result['previously_checked_at']} (stale; verify online before acting)")
+    return 0 if status in ("CURRENT", "UPDATE_AVAILABLE") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/nobrainer-tech-flow/scripts/cleanup_worktree.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Safely remove one task-owned worktree after its exact PR is merged."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+from urllib.parse import urlsplit
+
+
+SHA_RE = re.compile(r"^[0-9a-f]{40}$", re.IGNORECASE)
+WRITER_MAX_AGE_SECONDS = 60
+
+
+class CleanupError(Exception):
+    """A failed safety gate or an unverifiable cleanup result."""
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    allow_clean_no_match: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    try:
+        result = subprocess.run(
+            argv,
+            cwd=cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except OSError as exc:
+        raise CleanupError(f"cannot run {Path(argv[0]).name}: {type(exc).__name__}") from None
+    if result.returncode and not (
+        allow_clean_no_match
+        and result.returncode == 1
+        and not result.stdout.strip()
+        and not result.stderr.strip()
+    ):
+        detail = result.stderr.strip() or result.stdout.strip() or f"exit {result.returncode}"
+        raise CleanupError(f"command failed ({Path(argv[0]).name}): {detail[:500]}")
+    return result
+
+
+def git(git_bin: str, repo: Path, *args: str) -> str:
+    return run([git_bin, "-C", str(repo), *args]).stdout.strip()
+
+
+def required_string(obj: dict, key: str) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise CleanupError(f"manifest is missing non-empty {key}")
+    return value.strip()
+
+
+def read_manifest(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        raise CleanupError("cannot read a valid JSON task manifest") from None
+    if not isinstance(data, dict) or data.get("schema_version") != 1:
+        raise CleanupError("unsupported worktree manifest schema")
+    return data
+
+
+def verify_writer_readback(data: dict, worktree: Path, now: dt.datetime | None = None) -> None:
+    readback = data.get("writer_readback")
+    if not isinstance(readback, dict):
+        raise CleanupError("missing authoritative host writer readback")
+    if readback.get("status") != "IDLE" or readback.get("active_writers") != []:
+        raise CleanupError("host writer readback does not prove IDLE with no active writers")
+    if Path(required_string(readback, "worktree_path")).expanduser().resolve() != worktree:
+        raise CleanupError("writer readback names a different worktree")
+    required_string(readback, "source")
+    try:
+        observed = dt.datetime.fromisoformat(required_string(readback, "observed_at").replace("Z", "+00:00"))
+    except ValueError:
+        raise CleanupError("writer readback has an invalid observed_at timestamp") from None
+    if observed.tzinfo is None:
+        raise CleanupError("writer readback timestamp must include a timezone")
+    now = now or dt.datetime.now(dt.timezone.utc)
+    age = (now - observed.astimezone(dt.timezone.utc)).total_seconds()
+    if age < -5 or age > WRITER_MAX_AGE_SECONDS:
+        raise CleanupError("host writer readback is stale or from the future")
+
+
+def remote_identity(url: str) -> tuple[str, str]:
+    """Extract host and owner/repository from common GitHub remote URL forms."""
+    if re.match(r"^[^/@:]+@[^:]+:.+$", url):
+        host, path = url.split(":", 1)
+        host = host.rsplit("@", 1)[1]
+    else:
+        parsed = urlsplit(url)
+        if parsed.scheme not in {"https", "ssh", "git"} or not parsed.hostname:
+            raise CleanupError("task remote is not a verifiable GitHub URL")
+        host, path = parsed.hostname, parsed.path.lstrip("/")
+    path = path.removesuffix(".git").strip("/")
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", path):
+        raise CleanupError("task remote URL has no exact owner/repository identity")
+    return host.lower(), path.lower()
+
+
+def parse_worktrees(value: str) -> list[dict[str, str]]:
+    entries: list[dict[str, str]] = []
+    for block in value.split("\n\n"):
+        entry: dict[str, str] = {}
+        for line in block.splitlines():
+            key, _, rest = line.partition(" ")
+            if key in {"worktree", "HEAD", "branch"}:
+                entry[key] = rest
+        if "worktree" in entry:
+            entries.append(entry)
+    return entries
+
+
+def lsof_writer_check(lsof_bin: str, worktree: Path) -> None:
+    """Fail if lsof reports a process cwd or open file inside this worktree."""
+    worktree = worktree.resolve()
+    commands = [
+        [lsof_bin, "-nP", "-Fpcfn", "-d", "cwd"],
+        [lsof_bin, "-nP", "-Fpcfn", "+D", str(worktree)],
+    ]
+    for command in commands:
+        result = run(command, allow_clean_no_match=True)
+        offenders: list[str] = []
+        process = "unknown process"
+        for line in result.stdout.splitlines():
+            if line.startswith("p"):
+                process = line[1:]
+            elif line.startswith("n"):
+                raw = line[1:].removesuffix(" (deleted)")
+                try:
+                    candidate = Path(raw).resolve()
+                    if candidate == worktree or worktree in candidate.parents:
+                        offenders.append(process)
+                except (OSError, RuntimeError):
+                    continue
+        if offenders:
+            raise CleanupError("active process is using the task worktree (PID(s): " + ",".join(sorted(set(offenders))) + ")")
+
+
+def verify_and_cleanup(manifest_path: Path, *, apply: bool, gh_bin: str = "gh", git_bin: str = "git") -> dict:
+    manifest = read_manifest(manifest_path)
+    repo_path = Path(required_string(manifest, "repository_path")).expanduser().resolve()
+    worktree = Path(required_string(manifest, "worktree_path")).expanduser().resolve()
+    task_id = required_string(manifest, "task_id")
+    remote = required_string(manifest, "remote")
+    repository = required_string(manifest, "repository").lower()
+    branch = required_string(manifest, "branch")
+    expected_head = required_string(manifest, "submitted_head_sha").lower()
+    if not repo_path.is_dir() or not worktree.is_dir() or repo_path == worktree:
+        raise CleanupError("repository or task worktree path is missing or ambiguous")
+    if not SHA_RE.fullmatch(expected_head):
+        raise CleanupError("submitted_head_sha must be a full 40-character commit SHA")
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository):
+        raise CleanupError("repository must be an exact owner/repository slug")
+    if remote.startswith("-") or remote not in git(git_bin, repo_path, "remote").splitlines():
+        raise CleanupError("manifest remote is not an exact configured Git remote")
+    git(git_bin, repo_path, "check-ref-format", "refs/heads/" + branch)
+
+    registered = parse_worktrees(git(git_bin, repo_path, "worktree", "list", "--porcelain"))
+    matching = [entry for entry in registered if Path(entry["worktree"]).resolve() == worktree]
+    if len(matching) != 1:
+        raise CleanupError("exact task worktree is not uniquely registered")
+    entry = matching[0]
+    if entry.get("branch") != "refs/heads/" + branch:
+        raise CleanupError("registered worktree branch does not match the task manifest")
+    if entry.get("HEAD", "").lower() != expected_head:
+        raise CleanupError("registered worktree HEAD does not match the submitted PR head")
+    if git(git_bin, worktree, "rev-parse", "--show-toplevel") != str(worktree):
+        raise CleanupError("resolved worktree root does not match the task path")
+    if git(git_bin, worktree, "status", "--porcelain=v1", "--untracked-files=all"):
+        raise CleanupError("task worktree has staged, unstaged, conflicted, or untracked files")
+    if git(git_bin, worktree, "clean", "-ndx"):
+        raise CleanupError("task worktree contains ignored or other removable user data")
+
+    remote_url = git(git_bin, repo_path, "remote", "get-url", remote)
+    host, remote_repo = remote_identity(remote_url)
+    try:
+        pr_number = int(manifest["pr_number"])
+    except (KeyError, TypeError, ValueError):
+        raise CleanupError("manifest pr_number must be an integer") from None
+    if pr_number <= 0:
+        raise CleanupError("manifest pr_number must be positive")
+
+    gh_repo = json.loads(run([gh_bin, "repo", "view", repository, "--json", "nameWithOwner,defaultBranchRef"]).stdout)
+    if not isinstance(gh_repo, dict) or str(gh_repo.get("nameWithOwner", "")).lower() != repository:
+        raise CleanupError("GitHub repository readback does not match the manifest repository")
+    default_ref = gh_repo.get("defaultBranchRef")
+    default_branch = default_ref.get("name") if isinstance(default_ref, dict) else None
+    if not isinstance(default_branch, str) or not default_branch:
+        raise CleanupError("GitHub did not return a verified default branch")
+
+    pr = json.loads(
+        run([
+            gh_bin,
+            "pr",
+            "view",
+            str(pr_number),
+            "--repo",
+            repository,
+            "--json",
+            "number,state,mergedAt,headRefName,headRefOid,baseRefName,mergeCommit,url",
+        ]).stdout
+    )
+    if not isinstance(pr, dict):
+        raise CleanupError("GitHub PR readback is invalid")
+    try:
+        returned_number = int(pr.get("number", 0))
+    except (TypeError, ValueError):
+        raise CleanupError("GitHub returned an invalid PR number") from None
+    if returned_number != pr_number:
+        raise CleanupError("GitHub returned a different PR number")
+    if pr.get("state") != "MERGED" or not isinstance(pr.get("mergedAt"), str) or not pr.get("mergedAt"):
+        raise CleanupError("PR is not verified as merged")
+    if pr.get("headRefName") != branch or str(pr.get("headRefOid", "")).lower() != expected_head:
+        raise CleanupError("PR source branch or submitted head SHA does not match this task worktree")
+    if pr.get("baseRefName") != default_branch:
+        raise CleanupError("PR target is not the verified repository default branch")
+    merge_commit = pr.get("mergeCommit")
+    merge_sha = merge_commit.get("oid") if isinstance(merge_commit, dict) else None
+    if not isinstance(merge_sha, str) or not SHA_RE.fullmatch(merge_sha):
+        raise CleanupError("GitHub did not return a valid PR merge-result SHA")
+    pr_url = urlsplit(str(pr.get("url", "")))
+    if pr_url.scheme != "https" or pr_url.hostname != host:
+        raise CleanupError("PR URL host does not match the task Git remote")
+    expected_path = f"/{repository}/pull/{pr_number}"
+    if pr_url.path.rstrip("/").lower() != expected_path.lower():
+        raise CleanupError("PR URL does not identify the exact repository and PR")
+    if remote_repo != repository:
+        raise CleanupError("task Git remote and verified PR repository do not match")
+
+    git(git_bin, repo_path, "check-ref-format", "refs/heads/" + default_branch)
+    fetched_ref = "refs/nobrainer-tech-flow/cleanup/" + uuid.uuid4().hex + "/base"
+    try:
+        run([
+            git_bin,
+            "-C",
+            str(repo_path),
+            "fetch",
+            "--no-tags",
+            remote,
+            f"+refs/heads/{default_branch}:{fetched_ref}",
+        ])
+        fetched_base = git(git_bin, repo_path, "rev-parse", fetched_ref).lower()
+        if not SHA_RE.fullmatch(fetched_base):
+            raise CleanupError("fetched target branch did not resolve to a full commit SHA")
+        ancestor = subprocess.run(
+            [git_bin, "-C", str(repo_path), "merge-base", "--is-ancestor", merge_sha, fetched_base],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+            text=True,
+        )
+        if ancestor.returncode != 0:
+            raise CleanupError("verified PR merge-result SHA is not in fetched default-branch history")
+    finally:
+        run([git_bin, "-C", str(repo_path), "update-ref", "-d", fetched_ref])
+
+    verify_writer_readback(manifest, worktree)
+    lsof = shutil.which("lsof")
+    if lsof:
+        lsof_writer_check(lsof, worktree)
+
+    result = {
+        "status": "DRY_RUN_READY" if not apply else "REMOVED",
+        "task_id": task_id,
+        "repository": repository,
+        "pr_number": pr_number,
+        "branch": branch,
+        "submitted_head_sha": expected_head,
+        "merge_sha": merge_sha.lower(),
+        "fetched_default_branch_sha": fetched_base,
+        "worktree_path": str(worktree),
+        "active_writer_check": "authoritative host readback is fresh and IDLE",
+        "local_process_check": "lsof passed" if lsof else "UNAVAILABLE; host readback only",
+    }
+    if not apply:
+        return result
+
+    # Re-read volatile safety gates immediately before the destructive Git operation.
+    verify_writer_readback(manifest, worktree)
+    if lsof:
+        lsof_writer_check(lsof, worktree)
+    if git(git_bin, worktree, "status", "--porcelain=v1", "--untracked-files=all") or git(
+        git_bin, worktree, "clean", "-ndx"
+    ):
+        raise CleanupError("worktree changed after verification; refusing removal")
+    run([git_bin, "-C", str(repo_path), "worktree", "remove", str(worktree)])
+    after = parse_worktrees(git(git_bin, repo_path, "worktree", "list", "--porcelain"))
+    if any(Path(item["worktree"]).resolve() == worktree for item in after):
+        raise CleanupError("Git removal returned but the task worktree is still registered")
+    result["status"] = "REMOVED"
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", required=True, type=Path, help="exact task worktree lifecycle JSON")
+    parser.add_argument("--apply", action="store_true", help="remove the worktree after every safety gate passes")
+    parser.add_argument("--gh-bin", default="gh", help=argparse.SUPPRESS)
+    parser.add_argument("--git-bin", default="git", help=argparse.SUPPRESS)
+    args = parser.parse_args(argv)
+    try:
+        result = verify_and_cleanup(args.manifest, apply=args.apply, gh_bin=args.gh_bin, git_bin=args.git_bin)
+    except (CleanupError, json.JSONDecodeError) as exc:
+        print(json.dumps({"status": "BLOCKED", "reason": str(exc)}, sort_keys=True))
+        return 2
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())