@ikon85/agent-workflow-kit 0.36.5 → 0.38.0

package/scripts/wrapup-land.py

@@ -26,7 +26,9 @@ import os
 import re
 import subprocess
 import sys
+import time
 from pathlib import Path
+from urllib.parse import quote
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
@@ -41,7 +43,32 @@ ISSUE_BRANCH_RE = re.compile(r"^(feat|fix|chore|docs)/(\d+)-")
 DRIFT_LINE_RE = re.compile(r"^-\s*#(\d+)(?:\s*§([^:]+?))?\s*:\s*(.+)$")
 RETRO_LINE_RE = re.compile(r"^\*\*Retro:\*\*", re.MULTILINE)
 DRIFT_MARKER_RE = re.compile(r"<!--\s*annahme-drift:\s*(\{.*?\})\s*-->")
-RED_CHECK_CONCLUSIONS = {"FAILURE", "CANCELLED", "TIMED_OUT"}
+RED_CHECK_CONCLUSIONS = {
+    "ACTION_REQUIRED",
+    "CANCELLED",
+    "FAILURE",
+    "STALE",
+    "STARTUP_FAILURE",
+    "TIMED_OUT",
+}
+GREEN_CHECK_CONCLUSIONS = {"NEUTRAL", "SKIPPED", "SUCCESS"}
+CHECK_WAIT_SECONDS = 20 * 60
+CHECK_POLL_SECONDS = 10
+MAX_EXTERNAL_DETAIL = 500
+INFRA_FAILURE_RE = re.compile(
+    r"(?:"
+    r"account payments? (?:have )?failed|"
+    r"billing issue|"
+    r"spending limit|"
+    r"no hosted parallelism|"
+    r"no (?:hosted )?runners? (?:are )?available|"
+    r"no runner matching|"
+    r"runner (?:is )?unavailable|"
+    r"failed to (?:acquire|assign) (?:a )?job|"
+    r"job was not started"
+    r")",
+    re.IGNORECASE,
+)
 
 
 class Stop(Exception):
@@ -62,6 +89,311 @@ def git(args: list[str], cwd: str | None = None, check: bool = False) -> subproc
     return run(["git", *args], cwd=cwd, check=check)
 
 
+# ---------- PR check gate ----------
+
+def check_name(check: dict) -> str:
+    return str(check.get("name") or check.get("context") or "?")
+
+
+def check_conclusion(check: dict) -> str:
+    # CheckRun entries carry `conclusion: null` while pending. Do not let a
+    # simultaneously present legacy `state` field turn that explicit null green.
+    value = check.get("conclusion") if "conclusion" in check else check.get("state")
+    return str(value or "").upper()
+
+
+def pending_checks(checks: list[dict]) -> list[dict]:
+    pending = []
+    for check in checks:
+        conclusion = check_conclusion(check)
+        status = str(check.get("status") or "").upper()
+        if conclusion in RED_CHECK_CONCLUSIONS | GREEN_CHECK_CONCLUSIONS:
+            continue
+        if conclusion in {"EXPECTED", "IN_PROGRESS", "PENDING", "QUEUED", "REQUESTED", "WAITING"}:
+            pending.append(check)
+            continue
+        if not conclusion or status not in {"", "COMPLETED"}:
+            pending.append(check)
+    return pending
+
+
+def red_checks(checks: list[dict]) -> list[dict]:
+    return [
+        check for check in checks
+        if check_conclusion(check) in RED_CHECK_CONCLUSIONS | {"ERROR"}
+    ]
+
+
+def sanitize_external_detail(text: str) -> str:
+    compact = re.sub(r"[\x00-\x1f\x7f]+", " ", text)
+    return re.sub(r"\s+", " ", compact).strip()[:MAX_EXTERNAL_DETAIL]
+
+
+def _check_text(check: dict) -> str:
+    values = []
+    for key in ("name", "context", "description", "title", "summary", "text"):
+        value = check.get(key)
+        if isinstance(value, str):
+            values.append(value)
+    return " ".join(values)
+
+
+def _matching_actions_job(check: dict, jobs: list[dict]) -> dict | None:
+    """Return the one Actions job represented by this check, never a run sibling."""
+    candidates = [job for job in jobs if isinstance(job, dict)]
+    details_url = check.get("link") or check.get("detailsUrl") or check.get("targetUrl")
+    job_match = (
+        re.search(r"/job/(\d+)(?:/|$)", details_url)
+        if isinstance(details_url, str)
+        else None
+    )
+    if job_match is not None:
+        job_id = job_match.group(1)
+        matching_ids = [
+            job for job in candidates
+            if str(job.get("databaseId") or "") == job_id
+            or re.search(
+                rf"/job/{re.escape(job_id)}(?:/|$)",
+                str(job.get("url") or ""),
+            )
+        ]
+        return matching_ids[0] if len(matching_ids) == 1 else None
+
+    name = check_name(check)
+    matching_names = [
+        job for job in candidates if str(job.get("name") or "") == name
+    ]
+    return matching_names[0] if len(matching_names) == 1 else None
+
+
+def _job_database_id(job: dict) -> str:
+    database_id = job.get("databaseId")
+    if database_id is not None:
+        return str(database_id)
+    match = re.search(r"/job/(\d+)(?:/|$)", str(job.get("url") or ""))
+    return match.group(1) if match is not None else ""
+
+
+def infrastructure_failure_diagnosis(
+    check: dict,
+    *,
+    command_runner=run,
+) -> str:
+    """Classify known Actions billing/runner failures with bounded read-only detail."""
+    if INFRA_FAILURE_RE.search(_check_text(check)):
+        return "infrastructure failure (billing or runner unavailable)"
+
+    details_url = check.get("link") or check.get("detailsUrl") or check.get("targetUrl")
+    run_match = (
+        re.search(r"/actions/runs/(\d+)(?:/|$)", details_url)
+        if isinstance(details_url, str)
+        else None
+    )
+    if run_match is None:
+        return ""
+    run_id = run_match.group(1)
+
+    jobs_result = command_runner(
+        ["gh", "run", "view", run_id, "--json", "jobs"]
+    )
+    matching_job = None
+    if jobs_result.returncode == 0:
+        try:
+            jobs = json.loads(jobs_result.stdout).get("jobs") or []
+        except (AttributeError, json.JSONDecodeError):
+            jobs = []
+        matching_job = _matching_actions_job(check, jobs)
+        zero_step_failure = (
+            matching_job is not None
+            and str(matching_job.get("conclusion") or "").lower()
+            in {"failure", "cancelled", "timed_out", "startup_failure"}
+            and not (matching_job.get("steps") or [])
+        )
+        if zero_step_failure:
+            return "infrastructure failure (failed Actions job had zero steps)"
+
+    job_id = _job_database_id(matching_job) if matching_job is not None else ""
+    if not job_id:
+        return ""
+    log_result = command_runner([
+        "gh", "run", "view", run_id, "--job", job_id, "--log-failed"
+    ])
+    external = sanitize_external_detail(
+        (log_result.stdout or "") + " " + (log_result.stderr or "")
+    )
+    if INFRA_FAILURE_RE.search(external):
+        return "infrastructure failure (billing or runner unavailable)"
+    return ""
+
+
+def _pr_gate_snapshot(pr: str, command_runner) -> dict:
+    result = command_runner([
+        "gh", "pr", "view", pr, "--json",
+        "state,mergeable,mergeStateStatus,statusCheckRollup,baseRefName",
+    ])
+    if result.returncode != 0:
+        raise Stop(
+            "0c merge-gate",
+            "cannot inspect PR checks",
+            sanitize_external_detail(result.stderr or result.stdout),
+        )
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise Stop("0c merge-gate", "invalid PR check response", str(error)) from error
+
+
+def _required_checks_snapshot(pr: str, command_runner) -> list[dict]:
+    result = command_runner([
+        "gh", "pr", "checks", pr, "--required", "--json",
+        "name,state,link,bucket,workflow",
+    ])
+    # gh uses 1 for failed checks and 8 for pending checks. Both still carry
+    # the authoritative JSON needed by this gate.
+    if result.returncode not in {0, 1, 8}:
+        raise Stop(
+            "0c merge-gate",
+            "cannot inspect required PR checks",
+            sanitize_external_detail(result.stderr or result.stdout),
+        )
+    try:
+        checks = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise Stop(
+            "0c merge-gate", "invalid required PR check response", str(error)
+        ) from error
+    if not isinstance(checks, list) or not all(
+        isinstance(check, dict) for check in checks
+    ):
+        raise Stop(
+            "0c merge-gate",
+            "invalid required PR check response",
+            "expected a JSON array of checks",
+        )
+    return checks
+
+
+def _configured_required_check_names(snapshot: dict, command_runner) -> set[str]:
+    branch = snapshot.get("baseRefName")
+    if not isinstance(branch, str) or not branch:
+        raise Stop("0c merge-gate", "PR response has no base branch")
+    repo_result = command_runner(["gh", "repo", "view", "--json", "nameWithOwner"])
+    if repo_result.returncode != 0:
+        raise Stop(
+            "0c merge-gate",
+            "cannot inspect repository identity",
+            sanitize_external_detail(repo_result.stderr or repo_result.stdout),
+        )
+    try:
+        repository = json.loads(repo_result.stdout)["nameWithOwner"]
+    except (KeyError, TypeError, json.JSONDecodeError) as error:
+        raise Stop("0c merge-gate", "invalid repository identity response", str(error)) from error
+    rules_result = command_runner([
+        "gh", "api",
+        f"repos/{quote(repository, safe='/')}/rules/branches/{quote(branch, safe='')}",
+    ])
+    if rules_result.returncode != 0:
+        raise Stop(
+            "0c merge-gate",
+            "cannot inspect required-check rules",
+            sanitize_external_detail(rules_result.stderr or rules_result.stdout),
+        )
+    try:
+        rules = json.loads(rules_result.stdout)
+    except json.JSONDecodeError as error:
+        raise Stop("0c merge-gate", "invalid required-check rules response", str(error)) from error
+    if not isinstance(rules, list):
+        raise Stop("0c merge-gate", "invalid required-check rules response", "expected a JSON array")
+    return {
+        check["context"]
+        for rule in rules
+        if isinstance(rule, dict) and rule.get("type") == "required_status_checks"
+        for check in (rule.get("parameters", {}).get("required_status_checks") or [])
+        if isinstance(check, dict) and isinstance(check.get("context"), str)
+    }
+
+
+def _failed_check_detail(failed: list[dict], command_runner) -> str:
+    details = []
+    for check in failed:
+        diagnosis = infrastructure_failure_diagnosis(
+            check, command_runner=command_runner
+        )
+        suffix = f" — {diagnosis}" if diagnosis else ""
+        details.append(f"{check_name(check)}{suffix}")
+    return ", ".join(details)
+
+
+def _waiting_checks(
+    required_checks: list[dict],
+    configured_required_names: set[str],
+) -> list[dict]:
+    waiting = pending_checks(required_checks)
+    observed = {check_name(check) for check in required_checks}
+    waiting.extend(
+        {"name": f"{name} (awaiting discovery)"}
+        for name in sorted(configured_required_names - observed)
+    )
+    return waiting
+
+
+def wait_for_merge_gate(
+    pr: str,
+    *,
+    timeout_seconds: float = CHECK_WAIT_SECONDS,
+    poll_interval: float = CHECK_POLL_SECONDS,
+    command_runner=run,
+    clock=time.monotonic,
+    sleeper=time.sleep,
+    progress_stream=sys.stderr,
+    configured_required_names: set[str] | None = None,
+) -> bool:
+    """Wait for pending checks. Return True when the PR was already merged."""
+    started = clock()
+    while True:
+        snapshot = _pr_gate_snapshot(pr, command_runner)
+        state = snapshot.get("state")
+        if state == "MERGED":
+            return True
+        if state != "OPEN":
+            raise Stop("0c merge-gate", f"PR state {state} — cannot merge")
+        if snapshot.get("mergeable") == "CONFLICTING":
+            raise Stop("0c merge-gate", "PR is CONFLICTING — rebase/resolve the branch")
+
+        if configured_required_names is None:
+            configured_required_names = _configured_required_check_names(
+                snapshot, command_runner
+            )
+        checks = _required_checks_snapshot(pr, command_runner)
+        failed = red_checks(checks)
+        if failed:
+            raise Stop(
+                "0c merge-gate",
+                "red checks on the PR",
+                _failed_check_detail(failed, command_runner),
+            )
+
+        waiting = _waiting_checks(checks, configured_required_names)
+        if not waiting:
+            return False
+
+        elapsed = clock() - started
+        names = ", ".join(check_name(check) for check in waiting)
+        if elapsed >= timeout_seconds:
+            raise Stop(
+                "0c merge-gate",
+                "check wait budget exceeded",
+                f"elapsed={elapsed:.1f}s; still pending: {names}",
+            )
+        print(
+            f"wrapup: waiting for PR #{pr} checks "
+            f"({elapsed:.1f}s elapsed): {names}",
+            file=progress_stream,
+            flush=True,
+        )
+        sleeper(min(poll_interval, timeout_seconds - elapsed))
+
+
 # ---------- context ----------
 
 def worktree_map(cwd: str | None = None) -> tuple[str, dict[str, str]]:
@@ -105,18 +437,189 @@ def load_worktree_cleanup_core():
     return module
 
 
-def ensure_worktree_removable(wt: str, main_tree: str):
-    profile_path = Path(main_tree) / "docs/agents/workflow-capabilities.json"
-    if not profile_path.is_file():
-        return None
+def load_candidate_landing_profile(core, wt: str):
+    """Let the committed worktree policy nominate evidence without deletion."""
+    result = core.run(
+        [
+            "git", "show",
+            "HEAD:docs/agents/workflow-capabilities.json",
+        ],
+        cwd=Path(wt),
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise core.LifecycleError(
+            f"committed landing profile cannot be read from worktree HEAD: {detail}"
+        )
+    candidate = core.load_profile_text(result.stdout)
+    if not candidate.landing_generated_artifact_policy_configured:
+        raise core.LifecycleError(
+            "worktree landing artifact policy is not configured; "
+            "run setup-workflow and commit the explicit policy decision first"
+        )
+    return candidate
+
+
+def load_canonical_landing_profile(core, wt: str, main_tree: str):
+    """Authorize deletion only after the candidate policy is canonical."""
+    candidate = load_candidate_landing_profile(core, wt)
+    result = core.run(
+        [
+            "git", "show",
+            "origin/main:docs/agents/workflow-capabilities.json",
+        ],
+        cwd=Path(main_tree),
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise core.LifecycleError(
+            f"canonical landing profile cannot be read from origin/main: {detail}"
+        )
+    canonical = core.load_profile_text(result.stdout)
+    if not canonical.landing_generated_artifact_policy_configured:
+        raise core.LifecycleError(
+            "merged canonical landing artifact policy is not configured"
+        )
+    if (
+        candidate.landing_generated_artifact_patterns
+        != canonical.landing_generated_artifact_patterns
+        or candidate.scratch_patterns != canonical.scratch_patterns
+    ):
+        raise core.LifecycleError(
+            "worktree cleanup policy differs from merged canonical origin/main"
+        )
+    attempt_path = core.artifact_baseline_path(Path(wt)).with_name(
+        core.LANDING_ATTEMPT_FILE
+    )
+    if not os.path.lexists(attempt_path):
+        raise core.LifecycleError(
+            "landing attempt is missing before canonical cleanup authorization"
+        )
+    attempt = core.landing_start_artifact_inventory(candidate, Path(wt))
+    if (
+        attempt["policyDigest"]
+        != core.landing_cleanup_policy_digest(canonical)
+    ):
+        raise core.LifecycleError(
+            "landing attempt cleanup policy differs from merged canonical origin/main"
+        )
+    return canonical
+
+
+def landing_artifact_baseline_digest(wt: str, main_tree: str) -> str:
     core = load_worktree_cleanup_core()
     try:
-        profile = core.load_profile(profile_path)
-        assessment = core.cleanup_assessment(
+        load_candidate_landing_profile(core, wt)
+        return core.load_artifact_baseline(Path(wt)).digest
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def landing_start_artifact_inventory(wt: str, main_tree: str) -> dict:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.landing_start_artifact_inventory(profile, Path(wt))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def landing_verified_scratch_evidence(
+    wt: str,
+    main_tree: str,
+    *,
+    expected_baseline_digest: str | None = None,
+    landing_start_files: tuple[str, ...] = (),
+) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.verified_landing_scratch_evidence(
             profile,
-            Path(main_tree),
             Path(wt),
-            merge_target="origin/main",
+            expected_baseline_digest=expected_baseline_digest,
+            landing_start_files=landing_start_files,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def freeze_landing_artifact_evidence(
+    wt: str,
+    main_tree: str,
+    *,
+    push_succeeded: bool,
+) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.freeze_landing_artifact_evidence(
+            profile,
+            Path(wt),
+            push_succeeded=push_succeeded,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def reopen_frozen_landing_attempt(wt: str, main_tree: str) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.reopen_frozen_landing_attempt(profile, Path(wt))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def abandon_unfinished_landing_attempt(wt: str, main_tree: str) -> str:
+    core = load_worktree_cleanup_core()
+    try:
+        return str(core.abandon_unfinished_landing_attempt(Path(wt)))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def landing_verified_scratch_files(
+    wt: str,
+    main_tree: str,
+    *,
+    expected_baseline_digest: str | None = None,
+) -> tuple[str, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.verified_landing_scratch_files(
+            profile,
+            Path(wt),
+            expected_baseline_digest=expected_baseline_digest,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def ensure_worktree_removable(
+    wt: str,
+    main_tree: str,
+    *,
+    verified_scratch_files: tuple[str, ...] = (),
+    verified_scratch_evidence: tuple[dict, ...] = (),
+):
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_canonical_landing_profile(core, wt, main_tree)
+        kwargs = {"merge_target": "origin/main"}
+        paths = (
+            tuple(item["path"] for item in verified_scratch_evidence)
+            or verified_scratch_files
+        )
+        if paths:
+            kwargs["verified_scratch_files"] = paths
+        if verified_scratch_evidence:
+            kwargs["verified_scratch_evidence"] = verified_scratch_evidence
+        assessment = core.cleanup_assessment(
+            profile, Path(main_tree), Path(wt), **kwargs
         )
     except core.LifecycleError as error:
         raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
@@ -129,6 +632,69 @@ def ensure_worktree_removable(wt: str, main_tree: str):
     return assessment
 
 
+def remove_verified_worktree_scratch(
+    wt: str,
+    main_tree: str,
+    assessment,
+    *,
+    verified_scratch_files: tuple[str, ...] = (),
+    verified_scratch_evidence: tuple[dict, ...] = (),
+):
+    """Re-verify and delete only assessed regular scratch files."""
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_canonical_landing_profile(core, wt, main_tree)
+        evidence = verified_scratch_evidence
+        paths = tuple(item["path"] for item in evidence) or verified_scratch_files
+        latest = core.cleanup_assessment(
+            profile,
+            Path(main_tree),
+            Path(wt),
+            merge_target="origin/main",
+            verified_scratch_files=paths,
+            verified_scratch_evidence=evidence,
+        )
+        if latest.reasons:
+            raise core.LifecycleError(
+                "cleanup changed before removal: " + "; ".join(latest.reasons)
+            )
+        if (
+            latest.branch != assessment.branch
+            or latest.scratch_files != assessment.scratch_files
+            or latest.assumptions != assessment.assumptions
+            or latest.root_device != assessment.root_device
+            or latest.root_inode != assessment.root_inode
+            or latest.scratch_evidence != assessment.scratch_evidence
+        ):
+            raise core.LifecycleError(
+                "cleanup changed before removal: inventory no longer matches preview"
+            )
+        with core.verified_worktree_root(
+            latest.worktree,
+            latest.root_device,
+            latest.root_inode,
+        ) as root_descriptor:
+            core.remove_authorized_scratch(
+                profile,
+                root_descriptor,
+                latest.scratch_files,
+                latest.scratch_evidence,
+            )
+        final = core.cleanup_assessment(
+            profile,
+            Path(main_tree),
+            Path(wt),
+            merge_target="origin/main",
+        )
+        if final.reasons:
+            raise core.LifecycleError(
+                "cleanup changed after scratch removal: " + "; ".join(final.reasons)
+            )
+        return final
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
 # ---------- drift log (ANNAHMEN.md) ----------
 
 def parse_annahmen(text: str, default_section: str) -> tuple[list[dict], list[str]]:
@@ -370,9 +936,39 @@ def cmd_land(args) -> dict:
 
     # drift markers from the build-time log — mechanical, no gate
     markers: list[dict] = []
+    artifact_baseline_digest: str | None = None
+    landing_start_files: tuple[str, ...] = ()
+    landing_attempt: dict | None = None
+    generated_evidence: tuple[dict, ...] = ()
     if wt_exists:
         if git(["status", "--porcelain"], cwd=wt, check=True).stdout.strip():
             raise Stop("land", "worktree dirty — run `commit` first", wt)
+        if getattr(args, "abandon_unfinished_attempt", False):
+            return {
+                "landing_attempt_abandoned": abandon_unfinished_landing_attempt(
+                    wt, main_tree
+                ),
+                "files_removed": [],
+                "next": (
+                    "current files remain protected; classify or move blockers, "
+                    "then rerun land"
+                ),
+            }
+        landing_attempt = landing_start_artifact_inventory(wt, main_tree)
+        if landing_attempt["state"] == "started" and not landing_attempt["newAttempt"]:
+            raise Stop(
+                "cleanup",
+                "unfinished landing generator attempt has no frozen output evidence; "
+                "classify its files, then rerun with --abandon-unfinished-attempt",
+            )
+        landing_start_files = tuple(landing_attempt["generatedFiles"])
+        if landing_start_files:
+            raise Stop(
+                "cleanup",
+                "landing-start generated paths are consumer-owned and protected: "
+                + ", ".join(landing_start_files),
+            )
+        artifact_baseline_digest = landing_attempt["baselineDigest"]
         annahmen = Path(wt) / "ANNAHMEN.md"
         if annahmen.is_file():
             markers, malformed = parse_annahmen(annahmen.read_text(), default_section)
@@ -384,9 +980,25 @@ def cmd_land(args) -> dict:
 
     # Step 0b — push
     if wt_exists:
-        p = git(["push", "-u", "origin", branch], cwd=wt)
-        if p.returncode != 0:
-            raise Stop("0b push", "push rejected", (p.stderr or p.stdout).strip()[-2000:])
+        assert landing_attempt is not None
+        if landing_attempt["state"] == "frozen" and landing_attempt["pushSucceeded"]:
+            generated_evidence = freeze_landing_artifact_evidence(
+                wt, main_tree, push_succeeded=True
+            )
+        else:
+            if landing_attempt["state"] == "frozen":
+                # Validate every previously frozen identity before a retry can
+                # invoke the generator-capable pre-push hook.
+                reopen_frozen_landing_attempt(wt, main_tree)
+            p = git(["push", "-u", "origin", branch], cwd=wt)
+            generated_evidence = freeze_landing_artifact_evidence(
+                wt, main_tree, push_succeeded=p.returncode == 0
+            )
+            if p.returncode != 0:
+                raise Stop(
+                    "0b push", "push rejected",
+                    (p.stderr or p.stdout).strip()[-2000:],
+                )
 
     # Step 0c — ensure PR + final body
     p = run(["gh", "pr", "view", branch, "--json", "number,state,body"])
@@ -432,20 +1044,9 @@ def cmd_land(args) -> dict:
         report["warnings"].append("pr-body-check exit 2 (fail-open): "
                                   + (p.stdout + p.stderr).strip()[:300])
 
-    # merge gate
-    d = json.loads(run(["gh", "pr", "view", pr, "--json",
-                        "state,mergeable,mergeStateStatus,statusCheckRollup"],
-                       check=True).stdout)
-    red = [c for c in (d.get("statusCheckRollup") or [])
-           if (c.get("conclusion") or "").upper() in RED_CHECK_CONCLUSIONS]
-    if red:
-        raise Stop("0c merge-gate", "red checks on the PR",
-                   ", ".join(c.get("name") or c.get("context", "?") for c in red))
-    if d.get("mergeable") == "CONFLICTING":
-        raise Stop("0c merge-gate", "PR is CONFLICTING — rebase/resolve the branch")
-    already_merged = d.get("state") == "MERGED"
-    if d.get("state") not in ("OPEN", "MERGED"):
-        raise Stop("0c merge-gate", f"PR state {d.get('state')} — cannot merge")
+    # merge gate — wait boundedly for fresh-PR checks; already-MERGED resumes
+    # directly at teardown. Progress stays on stderr so stdout remains one JSON.
+    already_merged = wait_for_merge_gate(pr)
 
     # Step 1 — merge (= prod deploy; authorization = the user's /wrapup invocation).
     # PR state is the authority, not gh's exit code: `--delete-branch` also tries
@@ -468,12 +1069,26 @@ def cmd_land(args) -> dict:
     # Step 2 — kill the worktree's dev server, then Step 4 — teardown
     if wt_exists:
         git(["fetch", "origin", "main"], cwd=main_tree, check=True)
-        cleanup = ensure_worktree_removable(wt, main_tree)
+        generated = tuple(item["path"] for item in generated_evidence)
+        cleanup = ensure_worktree_removable(
+            wt,
+            main_tree,
+            verified_scratch_files=generated,
+            verified_scratch_evidence=generated_evidence,
+        )
         report["cleanup_guard"] = {
             "active": cleanup is not None,
             "assumptions_read": bool(cleanup and cleanup.assumptions),
+            "landing_generated_files": list(generated),
         }
         report["killed_processes"] = kill_worktree_processes(wt)
+        if cleanup is not None:
+            cleanup = remove_verified_worktree_scratch(
+                wt,
+                main_tree,
+                cleanup,
+                verified_scratch_evidence=generated_evidence,
+            )
         p = git(["worktree", "remove", wt], cwd=main_tree)
         if p.returncode != 0:
             raise Stop("4 worktree-remove", "git worktree remove refused — no --force; "
@@ -601,6 +1216,14 @@ def main() -> int:
     l.add_argument("--body-file", help="final PR body (create or overwrite)")
     l.add_argument("--anchor", help="wave-anchor issue # (derived via parent-of when omitted)")
     l.add_argument("--skip-malformed-drift", action="store_true")
+    l.add_argument(
+        "--abandon-unfinished-attempt",
+        action="store_true",
+        help=(
+            "archive an interrupted pre-freeze landing attempt without deleting "
+            "or claiming its ambiguous files"
+        ),
+    )
     args = ap.parse_args()
 
     try: