@ikon85/agent-workflow-kit 0.36.5 → 0.38.0

package/scripts/worktree-lifecycle/session.py

@@ -0,0 +1,1857 @@
+#!/usr/bin/env python3
+"""Claim-bound creation and teardown of one orchestration run's exact worktrees."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+from contextlib import contextmanager
+import fcntl
+from hashlib import sha256
+import json
+import os
+from pathlib import Path
+import stat
+import subprocess
+import sys
+from typing import Any
+
+from cleanup import pr_state
+from core import (
+    LifecycleError,
+    capture_artifact_baseline,
+    bind_cleanup_scratch_evidence,
+    classify_cleanup,
+    collect_cleanup_facts,
+    contained_untracked_identity,
+    durable_atomic_json,
+    load_profile,
+    load_artifact_baseline,
+    main_worktree,
+    registered_worktrees,
+    remove_authorized_scratch,
+    remove_contained_untracked,
+    run,
+    verified_landing_scratch_evidence,
+    verified_worktree_root,
+)
+from setup import execute_step
+
+SCHEMA_VERSION = 1
+
+
+def resolve_commit(repo: Path, rev: str) -> str | None:
+    result = run(
+        ["git", "rev-parse", "--verify", f"{rev}^{{commit}}"],
+        cwd=repo,
+        check=False,
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def resolve_ref(repo: Path, ref: str) -> str | None:
+    result = run(["git", "rev-parse", "--verify", ref], cwd=repo, check=False)
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def active_claim(main: Path, anchor: str, owner: str) -> tuple[str, dict[str, Any]]:
+    if not anchor.isdigit() or int(anchor) <= 0:
+        raise LifecycleError("anchor must be a positive issue number")
+    if not owner.strip():
+        raise LifecycleError("owner must be non-empty")
+    ref = f"refs/tags/wave-active/{anchor}"
+    tag_oid = resolve_ref(main, ref)
+    if tag_oid is None:
+        raise LifecycleError(f"active wave claim is missing: {ref}")
+    kind = run(["git", "cat-file", "-t", tag_oid], cwd=main).stdout.strip()
+    if kind != "tag":
+        raise LifecycleError(f"active wave claim is not annotated: {ref}")
+    raw = run(["git", "cat-file", "-p", tag_oid], cwd=main).stdout
+    separator = raw.find("\n\n")
+    try:
+        claim = json.loads(raw[separator + 2:].strip()) if separator >= 0 else None
+    except json.JSONDecodeError as error:
+        raise LifecycleError("active wave claim has invalid ownership evidence") from error
+    if (
+        not isinstance(claim, dict)
+        or claim.get("contractVersion") != 1
+        or str(claim.get("anchor")) != anchor
+        or claim.get("owner") != owner
+    ):
+        raise LifecycleError("active wave claim belongs to another or incoherent run")
+    return tag_oid, claim
+
+
+def common_git_dir(main: Path) -> Path:
+    value = run(
+        ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+        cwd=main,
+    ).stdout.strip()
+    return Path(value).resolve()
+
+
+def receipt_path(main: Path, anchor: str, claim_oid: str) -> Path:
+    return common_git_dir(main) / "agent-workflow-kit" / "session-teardown" / (
+        f"{anchor}-{claim_oid}.json"
+    )
+
+
+def ownership_proof_ref(claim_oid: str, branch: str) -> str:
+    branch_digest = sha256(branch.encode("utf-8")).hexdigest()
+    return (
+        "refs/agent-workflow-kit/session-owned/"
+        f"{claim_oid}/{branch_digest}"
+    )
+
+
+def validated_proof_ref(receipt: dict[str, Any], entry: dict[str, Any]) -> str:
+    expected = ownership_proof_ref(receipt["claimOid"], entry["branch"])
+    if entry.get("proofRef") != expected:
+        raise LifecycleError("session ownership proof identity is incoherent")
+    return expected
+
+
+def acquire_owned_branch(
+    main: Path,
+    branch: str,
+    proof_ref: str,
+    target_oid: str,
+    claim_ref: str,
+    claim_oid: str,
+) -> bool:
+    transaction = (
+        "start\n"
+        f"verify {claim_ref} {claim_oid}\n"
+        f"create refs/heads/{branch} {target_oid}\n"
+        f"create {proof_ref} {target_oid}\n"
+        "prepare\n"
+        "commit\n"
+    )
+    result = subprocess.run(
+        ["git", "update-ref", "--stdin"],
+        cwd=main,
+        input=transaction,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def delete_owned_refs_prepared(
+    main: Path,
+    branch: str,
+    proof_ref: str,
+    expected_oid: str,
+    proof_oid: str,
+    claim_ref: str,
+    claim_oid: str,
+    *,
+    remove_worktree: Path | None = None,
+    main_ref: str | None = None,
+    main_oid: str | None = None,
+    root_identity: tuple[int, int] | None = None,
+) -> bool:
+    process = subprocess.Popen(
+        ["git", "update-ref", "--stdin"],
+        cwd=main,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    assert process.stdin is not None
+    assert process.stdout is not None
+    commands = [
+        "start",
+        f"verify {claim_ref} {claim_oid}",
+    ]
+    if main_ref is not None and main_oid is not None:
+        commands.append(f"verify {main_ref} {main_oid}")
+    commands.extend([
+        f"delete refs/heads/{branch} {expected_oid}",
+        f"delete {proof_ref} {proof_oid}",
+        "prepare",
+    ])
+    try:
+        process.stdin.write("\n".join(commands) + "\n")
+        process.stdin.flush()
+        responses = [process.stdout.readline().strip(), process.stdout.readline().strip()]
+        if responses != ["start: ok", "prepare: ok"]:
+            process.stdin.close()
+            process.wait()
+            return False
+        linked = worktree_branches(main)
+        if (
+            (remove_worktree is None and branch in linked)
+            or (
+                remove_worktree is not None
+                and linked.get(branch) != remove_worktree.resolve()
+            )
+        ):
+            process.stdin.write("abort\n")
+            process.stdin.flush()
+            process.stdin.close()
+            process.wait()
+            return False
+        if remove_worktree is not None:
+            try:
+                metadata = remove_worktree.lstat()
+            except OSError:
+                metadata = None
+            if (
+                metadata is None
+                or not stat.S_ISDIR(metadata.st_mode)
+                or root_identity is None
+                or (metadata.st_dev, metadata.st_ino) != root_identity
+            ):
+                process.stdin.write("abort\n")
+                process.stdin.flush()
+                process.stdin.close()
+                process.wait()
+                return False
+            removed = run(
+                ["git", "worktree", "remove", str(remove_worktree)],
+                cwd=main,
+                check=False,
+            )
+            if removed.returncode != 0:
+                process.stdin.write("abort\n")
+                process.stdin.flush()
+                process.stdin.close()
+                process.wait()
+                return False
+        process.stdin.write("commit\n")
+        process.stdin.flush()
+        process.stdin.close()
+        return process.wait() == 0
+    except (BrokenPipeError, OSError):
+        if process.poll() is None:
+            process.kill()
+        process.wait()
+        return False
+
+
+@contextmanager
+def receipt_lock(main: Path, anchor: str):
+    directory = common_git_dir(main) / "agent-workflow-kit" / "session-teardown"
+    directory.mkdir(parents=True, exist_ok=True)
+    lock_path = directory / f"{anchor}.lock"
+    descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(descriptor, fcntl.LOCK_UN)
+        os.close(descriptor)
+
+
+def write_receipt(path: Path, receipt: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    durable_atomic_json(
+        path,
+        receipt,
+        label="write session teardown receipt",
+        mode=0o600,
+        sort_keys=True,
+    )
+
+
+def read_receipt(
+    main: Path,
+    anchor: str,
+    owner: str,
+) -> tuple[Path, dict[str, Any]]:
+    claim_oid, _ = active_claim(main, anchor, owner)
+    path = receipt_path(main, anchor, claim_oid)
+    try:
+        receipt = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise LifecycleError(f"cannot read this run's teardown receipt: {error}") from error
+    if (
+        not isinstance(receipt, dict)
+        or receipt.get("schemaVersion") != SCHEMA_VERSION
+        or receipt.get("anchor") != anchor
+        or receipt.get("owner") != owner
+        or receipt.get("claimOid") != claim_oid
+        or Path(str(receipt.get("repoRoot", ""))).resolve() != main.resolve()
+        or not isinstance(receipt.get("targets"), list)
+    ):
+        raise LifecycleError("teardown receipt belongs to another or incoherent run")
+    return path, receipt
+
+
+def begin(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    claim_oid, _ = active_claim(main, args.anchor, args.owner)
+    base_oid = resolve_commit(main, args.base)
+    if base_oid is None:
+        raise LifecycleError(f"base is not resolvable: {args.base}")
+    path = receipt_path(main, args.anchor, claim_oid)
+    with receipt_lock(main, args.anchor):
+        if path.exists():
+            _, receipt = read_receipt(main, args.anchor, args.owner)
+            if receipt.get("baseOid") != base_oid:
+                raise LifecycleError("existing receipt has a different base OID")
+            return receipt_report(path, receipt)
+        receipt = {
+            "schemaVersion": SCHEMA_VERSION,
+            "anchor": args.anchor,
+            "owner": args.owner,
+            "claimOid": claim_oid,
+            "repoRoot": str(main.resolve()),
+            "baseRef": args.base,
+            "baseOid": base_oid,
+            "state": "open",
+            "targets": [],
+        }
+        write_receipt(path, receipt)
+    return receipt_report(path, receipt)
+
+
+def profile_path(main: Path, value: str) -> Path:
+    path = Path(value)
+    return path.resolve() if path.is_absolute() else (main / path).resolve()
+
+
+def contained_target(main: Path, relative: Path) -> Path:
+    if relative.is_absolute() or not relative.parts or any(
+        part in {"", ".", ".."} for part in relative.parts
+    ):
+        raise LifecycleError(f"worktree path escapes repository root: {relative}")
+    return main.resolve().joinpath(*relative.parts)
+
+
+def create_target(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    with receipt_lock(main, args.anchor):
+        path, receipt = read_receipt(main, args.anchor, args.owner)
+        if receipt.get("state") != "open":
+            raise LifecycleError("teardown receipt is already sealed")
+        configured_path = profile_path(main, args.profile)
+        profile = load_profile(configured_path)
+        branch = profile.branch_name(args.issue, args.slug, args.branch_type)
+        if run(
+            ["git", "check-ref-format", "--branch", branch],
+            cwd=main,
+            check=False,
+        ).returncode != 0:
+            raise LifecycleError("generated session branch is not a valid branch name")
+        target = contained_target(
+            main,
+            profile.relative_path(args.issue, args.slug, args.branch_type),
+        )
+        if branch in profile.protected_branches:
+            raise LifecycleError(f"refusing protected session branch: {branch}")
+        if any(entry.get("branch") == branch or entry.get("worktree") == str(target)
+               for entry in receipt["targets"]):
+            raise LifecycleError("target is already present in this receipt")
+        if resolve_ref(main, f"refs/heads/{branch}") is not None:
+            raise LifecycleError(f"branch pre-existed this run: {branch}")
+        if os.path.lexists(target) or target in registered_worktrees(main):
+            raise LifecycleError(f"worktree path pre-existed this run: {target}")
+        target_base = (
+            resolve_commit(main, args.base) if args.base else receipt["baseOid"]
+        )
+        if target_base is None or not is_ancestor(main, receipt["baseOid"], target_base):
+            raise LifecycleError("target base is unresolved or incoherent with the receipt base")
+        proof_ref = ownership_proof_ref(receipt["claimOid"], branch)
+        if resolve_ref(main, proof_ref) is not None:
+            raise LifecycleError("session ownership proof pre-existed this run")
+
+        entry = {
+            "state": "provisional",
+            "acquisitionState": "pending",
+            "branch": branch,
+            "worktree": str(target),
+            "profile": str(configured_path),
+            "proofRef": proof_ref,
+            "createdOid": target_base,
+            "expectedOid": target_base,
+            "rootDevice": None,
+            "rootInode": None,
+            "artifactBaselineDigest": None,
+            "removed": False,
+        }
+        # Pre-journal the deterministic proof identity, then acquire the branch
+        # and proof ref in one Git ref transaction. The proof, rather than this
+        # provisional row alone, is the durable ownership authority.
+        receipt["targets"].append(entry)
+        write_receipt(path, receipt)
+        failure_class = "ref-acquisition"
+        try:
+            if not acquire_owned_branch(
+                main,
+                branch,
+                proof_ref,
+                target_base,
+                f"refs/tags/wave-active/{args.anchor}",
+                receipt["claimOid"],
+            ):
+                entry["acquisitionState"] = "failed"
+                write_receipt(path, receipt)
+                raise LifecycleError("session branch ownership acquisition failed")
+            entry["acquisitionState"] = "acquired"
+            write_receipt(path, receipt)
+            failure_class = "root-preparation"
+            parent, prepared = prepare_target_root_nofollow(main, target)
+            entry.update({
+                "state": "worktree-pending",
+                "parentDevice": parent.st_dev,
+                "parentInode": parent.st_ino,
+                "rootDevice": prepared.st_dev,
+                "rootInode": prepared.st_ino,
+            })
+            write_receipt(path, receipt)
+            failure_class = "worktree-add"
+            verify_target_parent_nofollow(
+                main,
+                target,
+                (entry["parentDevice"], entry["parentInode"]),
+            )
+            run(
+                ["git", "worktree", "add", str(target), branch],
+                cwd=main,
+            )
+            failure_class = "root-journal"
+            created_oid = resolve_ref(main, f"refs/heads/{branch}")
+            if created_oid != target_base:
+                raise LifecycleError("new session branch did not retain the recorded base OID")
+            metadata = verify_created_worktree_root(
+                main,
+                target,
+                branch,
+                expected_parent_identity=(
+                    entry["parentDevice"], entry["parentInode"]
+                ),
+            )
+            if (metadata.st_dev, metadata.st_ino) != (
+                entry["rootDevice"], entry["rootInode"]
+            ):
+                raise LifecycleError("new session worktree root identity changed")
+            entry.update({
+                "state": "baseline-pending",
+                "rootDevice": metadata.st_dev,
+                "rootInode": metadata.st_ino,
+            })
+            write_receipt(path, receipt)
+
+            # This baseline must precede every project setup step: only its
+            # exact untracked delta can later be attributed to failed setup.
+            failure_class = "baseline-capture"
+            verify_created_worktree_root(
+                main,
+                target,
+                branch,
+                expected_identity=(entry["rootDevice"], entry["rootInode"]),
+                expected_parent_identity=(
+                    entry["parentDevice"], entry["parentInode"]
+                ),
+            )
+            artifact_baseline = capture_artifact_baseline(target)
+            if artifact_baseline.setup_head != created_oid:
+                raise LifecycleError(
+                    "artifact provenance baseline does not match the created OID"
+                )
+            entry.update({
+                "state": "setting-up",
+                "artifactBaselineDigest": artifact_baseline.digest,
+            })
+            write_receipt(path, receipt)
+            failure_class = "setup-step"
+            for step in profile.setup_steps:
+                verify_created_worktree_root(
+                    main,
+                    target,
+                    branch,
+                    expected_identity=(entry["rootDevice"], entry["rootInode"]),
+                    expected_parent_identity=(
+                        entry["parentDevice"], entry["parentInode"]
+                    ),
+                )
+                execute_step(
+                    step,
+                    main=main,
+                    worktree=target,
+                    issue=args.issue,
+                    branch=branch,
+                )
+            failure_class = "promotion"
+            verify_created_worktree_root(
+                main,
+                target,
+                branch,
+                expected_identity=(entry["rootDevice"], entry["rootInode"]),
+                expected_parent_identity=(
+                    entry["parentDevice"], entry["parentInode"]
+                ),
+            )
+            created_oid = resolve_ref(main, f"refs/heads/{branch}")
+            if created_oid != target_base:
+                raise LifecycleError("new session branch did not retain the recorded base OID")
+            metadata = target.lstat()
+            if (metadata.st_dev, metadata.st_ino) != (
+                entry["rootDevice"], entry["rootInode"]
+            ):
+                raise LifecycleError("session worktree root changed during setup")
+            entry.update({
+                "state": "active",
+                "rootDevice": metadata.st_dev,
+                "rootInode": metadata.st_ino,
+                "expectedOid": None,
+            })
+            write_receipt(path, receipt)
+        except Exception as error:
+            entry["state"] = "recovery-pending"
+            entry.pop("failure", None)
+            entry["failureClass"] = failure_class
+            write_receipt(path, receipt)
+            try:
+                _capture_setup_created_evidence(main, target, entry)
+            except Exception:
+                entry["evidenceState"] = "pending"
+                entry["evidenceFailureClass"] = "identity-capture"
+            write_receipt(path, receipt)
+            try:
+                _recover_creation_entry(
+                    main,
+                    args,
+                    path,
+                    receipt,
+                    entry,
+                    archive_reason="automatic rollback after failed setup",
+                )
+            except Exception:
+                # Ownership and the bounded failure class are already durable.
+                # Never surface a setup command's exception/stdout/stderr.
+                pass
+            raise LifecycleError(
+                f"session creation failed ({failure_class}); recovery receipt retained"
+            ) from error
+    return {"branch": branch, "worktree": str(target), "createdOid": created_oid}
+
+
+def _capture_setup_created_evidence(
+    main: Path,
+    target: Path,
+    entry: dict[str, Any],
+) -> None:
+    entry.pop("evidenceFailureClass", None)
+    if entry.get("rootDevice") is not None:
+        verify_created_worktree_root(
+            main,
+            target,
+            entry["branch"],
+            expected_identity=(entry["rootDevice"], entry["rootInode"]),
+            expected_parent_identity=(
+                entry["parentDevice"], entry["parentInode"]
+            ),
+        )
+    if not target.exists() or not entry.get("artifactBaselineDigest"):
+        entry["setupCreatedFiles"] = []
+        entry["setupTrackedEvidence"] = _tracked_evidence(target) if target.exists() else None
+        entry["evidenceState"] = "complete"
+        return
+    baseline = load_artifact_baseline(target)
+    if baseline.digest != entry["artifactBaselineDigest"]:
+        raise LifecycleError("creation baseline changed before recovery journaling")
+    facts = collect_cleanup_facts(main, target, pr_state="none")
+    created = tuple(sorted(
+        set(facts.untracked_files).difference(baseline.initial_untracked_files)
+    ))
+    tracked = _tracked_evidence(target)
+    entry["setupTrackedEvidence"] = tracked
+    entry["setupCreatedPaths"] = list(created)
+    entry["setupInventoryDigest"] = _inventory_digest(tracked, created)
+    entry["evidenceState"] = "pending"
+    with verified_worktree_root(
+        target,
+        entry["rootDevice"],
+        entry["rootInode"],
+    ) as descriptor:
+        entry["setupCreatedFiles"] = [
+            contained_untracked_identity(descriptor, relative)
+            for relative in created
+        ]
+    entry["evidenceState"] = "complete"
+
+
+def _tracked_evidence(target: Path) -> dict[str, Any]:
+    paths: set[str] = set()
+    digests: dict[str, str] = {}
+    for name, cached in (("worktree", False), ("index", True)):
+        diff_command = [
+            "git", "diff", "--binary", "--full-index", "--no-renames",
+        ]
+        names_command = ["git", "diff", "--name-only", "-z", "--no-renames"]
+        if cached:
+            diff_command.insert(2, "--cached")
+            names_command.insert(2, "--cached")
+        diff = run(diff_command, cwd=target).stdout
+        names = run(names_command, cwd=target).stdout
+        values = [value for value in names.split("\0") if value]
+        if any(
+            Path(value).is_absolute() or ".." in Path(value).parts
+            for value in values
+        ):
+            raise LifecycleError("tracked recovery path is unsafe")
+        paths.update(values)
+        digests[f"{name}DiffSha256"] = sha256(
+            diff.encode("utf-8", errors="surrogateescape")
+        ).hexdigest()
+    return {"paths": sorted(paths), **digests}
+
+
+def _inventory_digest(
+    tracked: dict[str, Any],
+    untracked_paths: tuple[str, ...] | list[str],
+) -> str:
+    payload = json.dumps(
+        {"tracked": tracked, "untrackedPaths": list(untracked_paths)},
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return sha256(payload).hexdigest()
+
+
+def _tracked_evidence_at_created_oid() -> dict[str, Any]:
+    empty = sha256(b"").hexdigest()
+    return {
+        "paths": [],
+        "worktreeDiffSha256": empty,
+        "indexDiffSha256": empty,
+    }
+
+
+def _worktree_backlink_matches(main: Path, target: Path, branch: str) -> bool:
+    top = run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=target,
+        check=False,
+    )
+    common = run(
+        ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+        cwd=target,
+        check=False,
+    )
+    current = run(
+        ["git", "branch", "--show-current"],
+        cwd=target,
+        check=False,
+    )
+    return (
+        top.returncode == 0
+        and Path(top.stdout.strip()).resolve() == target.resolve()
+        and common.returncode == 0
+        and Path(common.stdout.strip()).resolve() == common_git_dir(main)
+        and current.returncode == 0
+        and current.stdout.strip() == branch
+    )
+
+
+def _archive_recovered_target(
+    path: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+    reason: str,
+) -> None:
+    entry.pop("failure", None)
+    archived = {key: value for key, value in entry.items() if key != "failure"}
+    receipt.setdefault("recoveredTargets", []).append({
+        **archived,
+        "state": "recovered",
+        "recoveryReason": reason,
+    })
+    receipt["targets"].remove(entry)
+    write_receipt(path, receipt)
+
+
+def _revalidate_creation_safety(
+    main: Path,
+    args: argparse.Namespace,
+    path: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+) -> None:
+    branch = entry["branch"]
+    expected_oid = entry["createdOid"]
+    proof_ref = validated_proof_ref(receipt, entry)
+    # The PR query is deliberately before the final receipt/claim read: a
+    # command that races either ownership input is detected before mutation.
+    if pr_state(args.gh_command, main, branch) == "open":
+        raise LifecycleError(f"open PR during creation recovery: {branch}")
+    current_path, current_receipt = read_receipt(main, args.anchor, args.owner)
+    if current_path != path or current_receipt != receipt:
+        raise LifecycleError("active claim or recovery receipt changed")
+    profile = load_profile(Path(entry["profile"]))
+    if branch in profile.protected_branches:
+        raise LifecycleError(f"protected branch during creation recovery: {branch}")
+    if resolve_ref(main, f"refs/heads/{branch}") != expected_oid:
+        raise LifecycleError(f"unexpected OID during creation recovery: {branch}")
+    if resolve_ref(main, proof_ref) != expected_oid:
+        raise LifecycleError(f"session ownership proof changed: {branch}")
+
+
+def _recover_creation_entry(
+    main: Path,
+    args: argparse.Namespace,
+    path: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+    *,
+    archive_reason: str,
+) -> None:
+    current_path, current_receipt = read_receipt(main, args.anchor, args.owner)
+    if current_path != path or current_receipt != receipt:
+        raise LifecycleError("active claim or recovery receipt changed")
+    if entry.get("state") != "recovery-pending":
+        raise LifecycleError("target is not pending creation recovery")
+
+    branch = entry["branch"]
+    target = Path(entry["worktree"])
+    proof_ref = validated_proof_ref(receipt, entry)
+
+    current_oid = resolve_ref(main, f"refs/heads/{branch}")
+    expected_oid = entry["createdOid"]
+    proof_oid = resolve_ref(main, proof_ref)
+    linked = worktree_branches(main)
+    linked_path = linked.get(branch)
+    target_present = os.path.lexists(target)
+    if entry.get("acquisitionState") == "failed":
+        if proof_oid is not None:
+            raise LifecycleError(
+                f"failed acquisition has ambiguous ownership proof: {branch}"
+            )
+        # The atomic ref transaction is the sole ownership grant. Without its
+        # proof ref, every same-name branch/path/registration is foreign and
+        # must be ignored rather than turning the receipt into a liveness trap.
+        _archive_recovered_target(path, receipt, entry, archive_reason)
+        return
+    if proof_oid is None:
+        if target_present or linked_path is not None:
+            raise LifecycleError(
+                f"session ownership proof is missing while a worktree remains: {branch}"
+            )
+        # A failed transaction may leave a foreign branch at the intended
+        # name. It is never adopted or deleted without the proof ref.
+        _archive_recovered_target(path, receipt, entry, archive_reason)
+        return
+    if proof_oid != expected_oid:
+        raise LifecycleError(f"session ownership proof changed: {branch}")
+    if current_oid is not None and current_oid != expected_oid:
+        raise LifecycleError(
+            f"unexpected OID during creation recovery: {branch}: "
+            f"expected {expected_oid}, found {current_oid}"
+        )
+    if current_oid is None and (target_present or linked_path is not None):
+        raise LifecycleError(
+            f"session ref disappeared while its worktree remains: {branch}"
+        )
+    if current_oid is None and not target_present and linked_path is None:
+        raise LifecycleError(
+            f"session ref disappeared while its ownership proof remains: {branch}"
+        )
+    if current_oid == expected_oid and not target_present and linked_path is None:
+        _revalidate_creation_safety(main, args, path, receipt, entry)
+        if not delete_owned_refs_prepared(
+            main,
+            branch,
+            proof_ref,
+            expected_oid,
+            entry["createdOid"],
+            f"refs/tags/wave-active/{args.anchor}",
+            receipt["claimOid"],
+        ):
+            raise LifecycleError(
+                f"compare-delete failed during branch-only creation recovery: {branch}"
+            )
+        _archive_recovered_target(path, receipt, entry, archive_reason)
+        return
+    if current_oid == expected_oid and target_present and linked_path is None:
+        metadata = target.lstat()
+        recorded_identity = (entry.get("rootDevice"), entry.get("rootInode"))
+        if (
+            not stat.S_ISDIR(metadata.st_mode)
+            or None in recorded_identity
+            or recorded_identity != (metadata.st_dev, metadata.st_ino)
+        ):
+            raise LifecycleError(
+                f"unregistered prepared root identity changed: {branch}"
+            )
+        with verified_worktree_root(
+            target, entry["rootDevice"], entry["rootInode"]
+        ) as descriptor:
+            if os.listdir(descriptor):
+                raise LifecycleError(
+                    f"unregistered prepared root is not empty: {branch}"
+                )
+        _revalidate_creation_safety(main, args, path, receipt, entry)
+        try:
+            os.rmdir(target)
+        except OSError as error:
+            raise LifecycleError(
+                f"unregistered prepared root changed before removal: {branch}"
+            ) from error
+        if not delete_owned_refs_prepared(
+            main,
+            branch,
+            proof_ref,
+            expected_oid,
+            entry["createdOid"],
+            f"refs/tags/wave-active/{args.anchor}",
+            receipt["claimOid"],
+        ):
+            raise LifecycleError(
+                f"compare-delete failed after prepared-root recovery: {branch}"
+            )
+        _archive_recovered_target(path, receipt, entry, archive_reason)
+        return
+    if linked_path != target.resolve():
+        raise LifecycleError(
+            f"worktree registration changed during creation recovery: {branch}"
+        )
+    if not target_present:
+        raise LifecycleError(
+            f"worktree directory is missing while Git registration remains: {branch}"
+        )
+    if target.is_symlink() or not target.is_dir():
+        raise LifecycleError(
+            f"worktree root type changed during creation recovery: {branch}"
+        )
+    metadata = target.stat()
+    recorded_identity = (entry.get("rootDevice"), entry.get("rootInode"))
+    if None not in recorded_identity and recorded_identity != (
+        metadata.st_dev, metadata.st_ino
+    ):
+        raise LifecycleError(
+            f"worktree root identity changed during creation recovery: {branch}"
+        )
+    if None in recorded_identity:
+        if (
+            not _worktree_backlink_matches(main, target, branch)
+            or collect_cleanup_facts(main, target, pr_state="none").tracked_files
+            or collect_cleanup_facts(main, target, pr_state="none").untracked_files
+        ):
+            raise LifecycleError(
+                f"worktree creation identity was not journaled before recovery: {branch}"
+            )
+        entry["rootDevice"] = metadata.st_dev
+        entry["rootInode"] = metadata.st_ino
+        recorded_identity = (metadata.st_dev, metadata.st_ino)
+        write_receipt(path, receipt)
+
+    facts = collect_cleanup_facts(main, target, pr_state="none")
+    baseline_digest = entry.get("artifactBaselineDigest")
+    if not baseline_digest:
+        if facts.tracked_files or facts.untracked_files:
+            raise LifecycleError(
+                "creation baseline is missing while worktree changes remain"
+            )
+        setup_created: tuple[str, ...] = ()
+        tracked_evidence = _tracked_evidence(target)
+    else:
+        baseline = load_artifact_baseline(target)
+        if (
+            baseline.digest != baseline_digest
+            or baseline.setup_head != expected_oid
+            or (baseline.root_device, baseline.root_inode) != recorded_identity
+        ):
+            raise LifecycleError("creation baseline changed or is incoherent")
+        initial = set(baseline.initial_untracked_files)
+        current = set(facts.untracked_files)
+        if not initial.issubset(current):
+            raise LifecycleError(
+                "creation baseline inventory changed before recovery"
+            )
+        evidence = entry.get("setupCreatedFiles")
+        tracked_evidence = entry.get("setupTrackedEvidence")
+        evidence_state = entry.get("evidenceState")
+        if evidence_state == "pending":
+            current_tracked = _tracked_evidence(target)
+            current_created = tuple(sorted(current.difference(initial)))
+            current_digest = _inventory_digest(current_tracked, current_created)
+            if not facts.tracked_files and not current_created:
+                entry["setupTrackedEvidence"] = current_tracked
+                entry["setupCreatedFiles"] = []
+                entry["setupCreatedPaths"] = []
+                entry["setupInventoryDigest"] = current_digest
+                entry["evidenceState"] = "complete"
+                entry.pop("evidenceFailureClass", None)
+                write_receipt(path, receipt)
+                evidence = []
+                tracked_evidence = current_tracked
+            elif current_digest == entry.get("setupInventoryDigest"):
+                _capture_setup_created_evidence(main, target, entry)
+                write_receipt(path, receipt)
+                evidence = entry.get("setupCreatedFiles")
+                tracked_evidence = entry.get("setupTrackedEvidence")
+            else:
+                raise LifecycleError(
+                    "creation recovery evidence is pending and inventory changed"
+                )
+        if not isinstance(evidence, list) or not all(
+            isinstance(item, dict)
+            and isinstance(item.get("path"), str)
+            and item.get("kind") in {"regular", "symlink"}
+            for item in evidence
+        ):
+            raise LifecycleError("setup-created file evidence is missing or incoherent")
+        if (
+            not isinstance(tracked_evidence, dict)
+            or not isinstance(tracked_evidence.get("paths"), list)
+        ):
+            raise LifecycleError("setup-created tracked evidence is missing or incoherent")
+        current_tracked = _tracked_evidence(target)
+        clean_tracked = _tracked_evidence_at_created_oid()
+        if current_tracked != clean_tracked and current_tracked != tracked_evidence:
+            raise LifecycleError("tracked setup changes changed after failed setup")
+        evidenced_paths = {item["path"] for item in evidence}
+        unexpected = current.difference(initial).difference(evidenced_paths)
+        if unexpected:
+            raise LifecycleError(
+                "foreign untracked files appeared after failed setup: "
+                + ", ".join(sorted(unexpected))
+            )
+        setup_created = tuple(sorted(current.intersection(evidenced_paths)))
+        if initial:
+            raise LifecycleError(
+                "pre-setup untracked files remain protected: "
+                + ", ".join(sorted(initial))
+            )
+
+    if tracked_evidence != _tracked_evidence_at_created_oid():
+        _revalidate_creation_safety(main, args, path, receipt, entry)
+        current_tracked = _tracked_evidence(target)
+        if current_tracked == tracked_evidence:
+            paths = tracked_evidence["paths"]
+            if paths:
+                _revalidate_creation_safety(main, args, path, receipt, entry)
+                restored = run(
+                    [
+                        "git", "restore", f"--source={expected_oid}",
+                        "--staged", "--worktree", "--", *paths,
+                    ],
+                    cwd=target,
+                    check=False,
+                )
+                if restored.returncode != 0:
+                    raise LifecycleError(
+                        "bounded tracked restoration failed during creation recovery"
+                    )
+        elif current_tracked != _tracked_evidence_at_created_oid():
+            raise LifecycleError("tracked setup changes changed after failed setup")
+    _revalidate_creation_safety(main, args, path, receipt, entry)
+    with verified_worktree_root(
+        target,
+        entry["rootDevice"],
+        entry["rootInode"],
+    ) as descriptor:
+        for relative in setup_created:
+            _revalidate_creation_safety(main, args, path, receipt, entry)
+            expected = next(
+                item for item in entry["setupCreatedFiles"]
+                if item["path"] == relative
+            )
+            remove_contained_untracked(descriptor, expected)
+    latest = collect_cleanup_facts(main, target, pr_state="none")
+    if latest.tracked_files or latest.untracked_files:
+        raise LifecycleError("creation recovery inventory changed before removal")
+    _revalidate_creation_safety(main, args, path, receipt, entry)
+    if not delete_owned_refs_prepared(
+        main,
+        branch,
+        proof_ref,
+        expected_oid,
+        entry["createdOid"],
+        f"refs/tags/wave-active/{args.anchor}",
+        receipt["claimOid"],
+        remove_worktree=target,
+        root_identity=(entry["rootDevice"], entry["rootInode"]),
+    ):
+        raise LifecycleError(
+            f"locked worktree/ref removal failed during creation recovery: {branch}"
+        )
+    if os.path.lexists(target) or branch in worktree_branches(main):
+        raise LifecycleError("worktree still exists after creation recovery")
+    _archive_recovered_target(path, receipt, entry, archive_reason)
+
+
+def recover_creation(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    with receipt_lock(main, args.anchor):
+        path, receipt = read_receipt(main, args.anchor, args.owner)
+        entry = next(
+            (
+                candidate for candidate in receipt["targets"]
+                if candidate.get("branch") == args.branch
+            ),
+            None,
+        )
+        if entry is None:
+            raise LifecycleError(f"no receipt target for recovery: {args.branch}")
+        if entry.get("state") not in {
+            "provisional",
+            "worktree-pending",
+            "baseline-pending",
+            "setting-up",
+            "recovery-pending",
+        }:
+            raise LifecycleError(
+                f"target is not a recoverable creation attempt: {args.branch}: "
+                f"{entry.get('state', '<missing>')}"
+            )
+        entry["state"] = "recovery-pending"
+        entry.pop("failure", None)
+        write_receipt(path, receipt)
+        _recover_creation_entry(
+            main,
+            args,
+            path,
+            receipt,
+            entry,
+            archive_reason="explicit creation recovery",
+        )
+    return {
+        "recovered": True,
+        "branch": args.branch,
+        "receipt": str(path),
+    }
+
+
+def worktree_branches(main: Path) -> dict[str, Path]:
+    output = run(["git", "worktree", "list", "--porcelain"], cwd=main).stdout
+    result: dict[str, Path] = {}
+    current: Path | None = None
+    for line in output.splitlines():
+        if line.startswith("worktree "):
+            current = Path(line.split(" ", 1)[1]).resolve()
+        elif line.startswith("branch refs/heads/") and current is not None:
+            result[line.removeprefix("branch refs/heads/")] = current
+    return result
+
+
+def lexical_worktree_branches(main: Path) -> dict[str, Path]:
+    """Return Git's registered paths without resolving a substituted symlink."""
+    output = run(["git", "worktree", "list", "--porcelain"], cwd=main).stdout
+    result: dict[str, Path] = {}
+    current: Path | None = None
+    for line in output.splitlines():
+        if line.startswith("worktree "):
+            current = Path(line.split(" ", 1)[1]).absolute()
+        elif line.startswith("branch refs/heads/") and current is not None:
+            result[line.removeprefix("branch refs/heads/")] = current
+    return result
+
+
+def prepare_target_root_nofollow(
+    main: Path,
+    target: Path,
+) -> tuple[os.stat_result, os.stat_result]:
+    """Create the lexical target through directory descriptors only."""
+    relative = target.relative_to(main.resolve())
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    descriptors: list[int] = []
+    current = os.open(main, directory_flags | no_follow)
+    try:
+        descriptors.append(current)
+        for component in relative.parts[:-1]:
+            try:
+                child = os.open(
+                    component, directory_flags | no_follow, dir_fd=current
+                )
+            except FileNotFoundError:
+                os.mkdir(component, mode=0o700, dir_fd=current)
+                child = os.open(
+                    component, directory_flags | no_follow, dir_fd=current
+                )
+            current = child
+            descriptors.append(current)
+        parent_metadata = os.fstat(current)
+        os.mkdir(relative.name, mode=0o700, dir_fd=current)
+        root_metadata = os.stat(
+            relative.name, dir_fd=current, follow_symlinks=False
+        )
+        if not stat.S_ISDIR(root_metadata.st_mode):
+            raise LifecycleError("new session worktree root is not a directory")
+        return parent_metadata, root_metadata
+    except OSError as error:
+        raise LifecycleError(
+            "new session worktree parent/root creation is unsafe"
+        ) from error
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+
+
+def verify_target_parent_nofollow(
+    main: Path,
+    target: Path,
+    expected_identity: tuple[int, int],
+) -> None:
+    relative = target.relative_to(main.resolve())
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    descriptors: list[int] = []
+    current = os.open(main, directory_flags | no_follow)
+    try:
+        descriptors.append(current)
+        for component in relative.parts[:-1]:
+            current = os.open(
+                component, directory_flags | no_follow, dir_fd=current
+            )
+            descriptors.append(current)
+        metadata = os.fstat(current)
+        if (metadata.st_dev, metadata.st_ino) != expected_identity:
+            raise LifecycleError("new session worktree parent identity changed")
+    except OSError as error:
+        raise LifecycleError(
+            "new session worktree parent identity changed"
+        ) from error
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+
+
+def verify_created_worktree_root(
+    main: Path,
+    target: Path,
+    branch: str,
+    *,
+    expected_identity: tuple[int, int] | None = None,
+    expected_parent_identity: tuple[int, int] | None = None,
+) -> os.stat_result:
+    """Bind setup to the lexical linked-worktree directory without symlink following."""
+    lexical_target = target.absolute()
+    if expected_parent_identity is not None:
+        verify_target_parent_nofollow(main, target, expected_parent_identity)
+    if lexical_worktree_branches(main).get(branch) != lexical_target:
+        raise LifecycleError("new session worktree registration is incoherent")
+    try:
+        metadata = target.lstat()
+        if not stat.S_ISDIR(metadata.st_mode):
+            raise LifecycleError("new session worktree root is not a directory")
+        with verified_worktree_root(
+            target,
+            metadata.st_dev,
+            metadata.st_ino,
+        ) as descriptor:
+            git_file = os.open(
+                ".git",
+                os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
+                dir_fd=descriptor,
+            )
+            try:
+                opened = os.fstat(git_file)
+                if not stat.S_ISREG(opened.st_mode):
+                    raise LifecycleError("new session worktree backlink is incoherent")
+                backlink = os.read(git_file, 16 * 1024).decode("utf-8").strip()
+            finally:
+                os.close(git_file)
+    except OSError as error:
+        raise LifecycleError("new session worktree root identity is incoherent") from error
+    if not backlink.startswith("gitdir: "):
+        raise LifecycleError("new session worktree backlink is incoherent")
+    git_dir = Path(backlink.removeprefix("gitdir: "))
+    common = common_git_dir(main)
+    try:
+        git_dir.relative_to(common / "worktrees")
+        git_dir_metadata = git_dir.lstat()
+        if not stat.S_ISDIR(git_dir_metadata.st_mode):
+            raise ValueError
+        recorded_backlink = (git_dir / "gitdir").read_text(encoding="utf-8").strip()
+    except (OSError, ValueError) as error:
+        raise LifecycleError("new session worktree backlink is incoherent") from error
+    if Path(recorded_backlink).absolute() != lexical_target / ".git":
+        raise LifecycleError("new session worktree backlink is incoherent")
+    identity = (metadata.st_dev, metadata.st_ino)
+    if expected_identity is not None and identity != expected_identity:
+        raise LifecycleError("new session worktree root identity changed")
+    return metadata
+
+
+def seal(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    with receipt_lock(main, args.anchor):
+        path, receipt = read_receipt(main, args.anchor, args.owner)
+        if receipt.get("state") == "sealed":
+            return receipt_report(path, receipt)
+        if receipt.get("state") != "open" or (
+            not receipt["targets"] and not receipt.get("recoveredTargets")
+        ):
+            raise LifecycleError(
+                "only an open receipt with active or recovered targets can be sealed"
+            )
+        linked = worktree_branches(main)
+        for entry in receipt["targets"]:
+            branch = entry["branch"]
+            if entry.get("state") != "active":
+                raise LifecycleError(
+                    f"session target is not ready to seal: {branch}: "
+                    f"{entry.get('state', '<missing>')}"
+                )
+            target = Path(entry["worktree"])
+            if linked.get(branch) != target.resolve():
+                raise LifecycleError(f"session worktree identity changed before seal: {branch}")
+            metadata = target.stat()
+            if (metadata.st_dev, metadata.st_ino) != (
+                entry["rootDevice"], entry["rootInode"]
+            ):
+                raise LifecycleError(f"session worktree root changed before seal: {branch}")
+            if run(["git", "status", "--porcelain"], cwd=target).stdout.strip():
+                raise LifecycleError(f"session worktree is dirty before seal: {branch}")
+            expected = resolve_ref(main, f"refs/heads/{branch}")
+            if expected is None or run(
+                ["git", "merge-base", "--is-ancestor", entry["createdOid"], expected],
+                cwd=main,
+                check=False,
+            ).returncode != 0:
+                raise LifecycleError(f"session branch moved outside its created history: {branch}")
+            proof_ref = validated_proof_ref(receipt, entry)
+            if resolve_ref(main, proof_ref) != entry["createdOid"]:
+                raise LifecycleError(f"session ownership proof changed before seal: {branch}")
+            entry["expectedOid"] = expected
+            entry["state"] = "sealed"
+        receipt["state"] = "sealed"
+        write_receipt(path, receipt)
+    return receipt_report(path, receipt)
+
+
+def commit_parents(repo: Path, commit: str) -> list[str]:
+    line = run(["git", "rev-list", "--parents", "-n", "1", commit], cwd=repo).stdout
+    return line.strip().split()[1:]
+
+
+def content_empty(repo: Path, commit: str, first_parent: str) -> bool:
+    return run(
+        ["git", "diff-tree", "--quiet", first_parent, commit],
+        cwd=repo,
+        check=False,
+    ).returncode == 0
+
+
+def patch_id(repo: Path, commit: str, first_parent: str) -> str | None:
+    diff = run(
+        [
+            "git", "diff", "--binary", "--full-index", "--no-renames",
+            first_parent, commit,
+        ],
+        cwd=repo,
+    ).stdout
+    if not diff:
+        return None
+    result = subprocess.run(
+        ["git", "patch-id", "--stable"],
+        cwd=repo,
+        input=diff,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    return result.stdout.split()[0]
+
+
+def is_ancestor(repo: Path, commit: str, target: str) -> bool:
+    return run(
+        ["git", "merge-base", "--is-ancestor", commit, target],
+        cwd=repo,
+        check=False,
+    ).returncode == 0
+
+
+def main_patch_index(repo: Path, base: str, main_oid: str) -> Counter[str]:
+    commits = run(
+        ["git", "rev-list", "--reverse", "--topo-order", f"{base}..{main_oid}"],
+        cwd=repo,
+    ).stdout.splitlines()
+    patches: Counter[str] = Counter()
+    for commit in commits:
+        parents = commit_parents(repo, commit)
+        if len(parents) != 1 or content_empty(repo, commit, parents[0]):
+            continue
+        value = patch_id(repo, commit, parents[0])
+        if value:
+            patches[value] += 1
+    return patches
+
+
+def integration_report(
+    repo: Path,
+    created_oid: str,
+    expected_oid: str,
+    main_oid: str,
+) -> dict[str, Any]:
+    if not is_ancestor(repo, created_oid, main_oid):
+        return {
+            "integration": "ambiguous",
+            "commits": [],
+            "reason": "recorded base is no longer an ancestor of canonical main",
+        }
+    commits = run(
+        [
+            "git", "rev-list", "--reverse", "--topo-order",
+            f"{created_oid}..{expected_oid}",
+        ],
+        cwd=repo,
+    ).stdout.splitlines()
+    index = main_patch_index(repo, created_oid, main_oid)
+    provisional: list[dict[str, Any]] = []
+    owned_patch_counts: Counter[str] = Counter()
+    for commit in commits:
+        parents = commit_parents(repo, commit)
+        if not parents:
+            provisional.append({"oid": commit, "status": "ambiguous", "reason": "root commit"})
+            continue
+        if content_empty(repo, commit, parents[0]):
+            provisional.append({
+                "oid": commit,
+                "status": "ambiguous",
+                "reason": "empty commit has no patch identity",
+            })
+            continue
+        if len(parents) != 1:
+            provisional.append({
+                "oid": commit,
+                "status": "ambiguous",
+                "reason": "merge commit has no unambiguous patch identity",
+            })
+            continue
+        if is_ancestor(repo, commit, main_oid):
+            provisional.append({"oid": commit, "status": "ancestry-merged"})
+            continue
+        value = patch_id(repo, commit, parents[0])
+        if value is None:
+            provisional.append({"oid": commit, "status": "ambiguous", "reason": "missing patch-id"})
+            continue
+        owned_patch_counts[value] += 1
+        provisional.append({"oid": commit, "status": "pending", "patchId": value})
+
+    for row in provisional:
+        value = row.get("patchId")
+        if row["status"] != "pending" or value is None:
+            continue
+        if owned_patch_counts[value] != 1 or index[value] > 1:
+            row["status"] = "ambiguous"
+            row["reason"] = "patch-id is not one-to-one"
+        elif index[value] == 1:
+            row["status"] = "patch-equivalent"
+        else:
+            row["status"] = "unique-patch"
+
+    statuses = {row["status"] for row in provisional}
+    if "ambiguous" in statuses:
+        integration = "ambiguous"
+    elif "unique-patch" in statuses:
+        integration = "unique-patch"
+    elif statuses and statuses <= {"ancestry-merged"}:
+        integration = "ancestry-merged"
+    else:
+        integration = "patch-equivalent"
+    return {"integration": integration, "commits": provisional}
+
+
+def assess(main: Path, args: argparse.Namespace) -> tuple[Path, dict[str, Any], dict[str, Any]]:
+    path, receipt = read_receipt(main, args.anchor, args.owner)
+    if receipt.get("state") not in {"sealed", "tearing-down", "complete"}:
+        raise LifecycleError("teardown receipt must be sealed first")
+    main_oid = resolve_commit(main, args.main)
+    if main_oid is None:
+        raise LifecycleError(f"canonical main is not resolvable: {args.main}")
+    linked = worktree_branches(main)
+    rows = []
+    for entry in receipt["targets"]:
+        branch = entry["branch"]
+        target = Path(entry["worktree"])
+        reasons: list[str] = []
+        current_oid = resolve_ref(main, f"refs/heads/{branch}")
+        proof_ref = validated_proof_ref(receipt, entry)
+        proof_oid = resolve_ref(main, proof_ref)
+        target_exists = os.path.lexists(target)
+        linked_path = linked.get(branch)
+        fully_absent = (
+            current_oid is None
+            and proof_oid is None
+            and not target_exists
+            and linked_path is None
+        )
+        if entry.get("removed"):
+            if fully_absent:
+                rows.append({
+                    "branch": branch,
+                    "worktree": str(target),
+                    "expectedOid": entry.get("expectedOid"),
+                    "currentOid": current_oid,
+                    "integration": "already-removed",
+                    "commits": [],
+                    "reasons": [],
+                    "removable": True,
+                    "scratchFiles": [],
+                    "scratchEvidence": [],
+                })
+            else:
+                rows.append({
+                    "branch": branch,
+                    "worktree": str(target),
+                    "expectedOid": entry.get("expectedOid"),
+                    "currentOid": current_oid,
+                    "integration": "ambiguous",
+                    "commits": [],
+                    "reasons": ["removed target was recreated"],
+                    "removable": False,
+                    "scratchFiles": [],
+                    "scratchEvidence": [],
+                })
+            continue
+        if (
+            fully_absent
+            and entry.get("teardownPhase") == "ref-deletion-pending"
+        ):
+            rows.append({
+                "branch": branch,
+                "worktree": str(target),
+                "expectedOid": entry.get("expectedOid"),
+                "currentOid": current_oid,
+                "integration": "already-removed",
+                "commits": [],
+                "reasons": [],
+                "removable": True,
+                "scratchFiles": [],
+                "scratchEvidence": [],
+            })
+            continue
+        if fully_absent:
+            rows.append({
+                "branch": branch,
+                "worktree": str(target),
+                "expectedOid": entry.get("expectedOid"),
+                "currentOid": current_oid,
+                "integration": "ambiguous",
+                "commits": [],
+                "reasons": ["owned target disappeared outside session teardown"],
+                "removable": False,
+                "scratchFiles": [],
+                "scratchEvidence": [],
+            })
+            continue
+        expected_oid = entry.get("expectedOid")
+        if not expected_oid or current_oid != expected_oid:
+            reasons.append(
+                f"unexpected OID: expected {expected_oid or '<unsealed>'}, "
+                f"found {current_oid or '<missing>'}"
+            )
+        if proof_oid != entry.get("createdOid"):
+            reasons.append("session ownership proof is missing or changed")
+        profile = load_profile(Path(entry["profile"]))
+        if branch in profile.protected_branches:
+            reasons.append(f"protected branch: {branch}")
+        state = pr_state(args.gh_command, main, branch)
+        if state == "open":
+            reasons.append("open PR")
+        integration = (
+            integration_report(main, entry["createdOid"], expected_oid, main_oid)
+            if expected_oid and current_oid == expected_oid
+            else {"integration": "ambiguous", "commits": []}
+        )
+        if integration["integration"] == "unique-patch":
+            reasons.append("unique patch content is not represented on canonical main")
+        elif integration["integration"] == "ambiguous":
+            reasons.append("ambiguous patch identity")
+
+        scratch: list[str] = []
+        scratch_evidence: list[dict[str, Any]] = []
+        if target_exists or linked_path is not None:
+            if not target_exists and linked_path is not None:
+                reasons.append(
+                    "worktree directory is missing while Git registration remains"
+                )
+            elif target_exists and (target.is_symlink() or not target.is_dir()):
+                reasons.append("worktree root type changed")
+            elif linked_path != target.resolve():
+                reasons.append("worktree registration no longer matches receipt")
+            elif target_exists:
+                metadata = target.stat()
+                if (metadata.st_dev, metadata.st_ino) != (
+                    entry["rootDevice"], entry["rootInode"]
+                ):
+                    reasons.append("worktree root identity changed")
+                verified_scratch: tuple[str, ...] = ()
+                try:
+                    baseline = load_artifact_baseline(target)
+                    if (
+                        baseline.digest != entry.get("artifactBaselineDigest")
+                        or baseline.setup_head != entry["createdOid"]
+                    ):
+                        raise LifecycleError(
+                            "artifact provenance baseline changed or is incoherent"
+                        )
+                    evidence = verified_landing_scratch_evidence(
+                        profile,
+                        target,
+                        expected_baseline_digest=entry["artifactBaselineDigest"],
+                    )
+                    scratch_evidence = list(evidence)
+                    verified_scratch = tuple(item["path"] for item in evidence)
+                except (LifecycleError, KeyError) as error:
+                    reasons.append(f"artifact provenance baseline stop: {error}")
+                facts = collect_cleanup_facts(
+                    main,
+                    target,
+                    merge_target=args.main,
+                    pr_state=state,
+                )
+                cleanup = classify_cleanup(
+                    profile,
+                    facts,
+                    verified_scratch_files=verified_scratch,
+                )
+                try:
+                    cleanup = bind_cleanup_scratch_evidence(
+                        profile,
+                        cleanup,
+                        scratch_evidence,
+                        require_generator_evidence=True,
+                    )
+                    scratch_evidence = list(cleanup.scratch_evidence)
+                except LifecycleError as error:
+                    reasons.append(f"scratch evidence stop: {error}")
+                reasons.extend(
+                    reason for reason in cleanup.reasons
+                    if not reason.startswith("unmerged branch:")
+                )
+                scratch = list(cleanup.scratch_files)
+        rows.append({
+            "branch": branch,
+            "worktree": str(target),
+            "expectedOid": expected_oid,
+            "currentOid": current_oid,
+            "integration": integration["integration"],
+            "commits": integration["commits"],
+            "reasons": list(dict.fromkeys(reasons)),
+            "removable": not reasons,
+            "scratchFiles": scratch,
+            "scratchEvidence": scratch_evidence,
+        })
+    report = {
+        "receipt": str(path),
+        "anchor": args.anchor,
+        "owner": args.owner,
+        "main": args.main,
+        "mainOid": main_oid,
+        "targets": rows,
+        "removable": all(row["removable"] for row in rows),
+    }
+    return path, receipt, report
+
+
+def inspect(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    return assess(main, args)[2]
+
+
+def revalidate_target(
+    main: Path,
+    args: argparse.Namespace,
+    receipt_path_value: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+    main_oid: str,
+) -> dict[str, Any]:
+    if resolve_commit(main, args.main) != main_oid:
+        raise LifecycleError("canonical main moved before target mutation")
+    current_path, current_receipt, report = assess(main, args)
+    if current_path != receipt_path_value or current_receipt != receipt:
+        raise LifecycleError("active claim or teardown receipt changed before mutation")
+    row = next(
+        (candidate for candidate in report["targets"]
+         if candidate["branch"] == entry["branch"]),
+        None,
+    )
+    if row is None:
+        raise LifecycleError("exact receipt target disappeared before mutation")
+    if not row["removable"] or row["integration"] == "already-removed":
+        detail = ", ".join(row["reasons"]) or row["integration"]
+        raise LifecycleError(
+            f"target changed before mutation: {entry['branch']}: {detail}"
+        )
+    # assess queries PR state after reading the receipt. Close that race with a
+    # final claim/receipt, profile, PR and ref/proof pass.
+    revalidate_owned_safety(
+        main, args, receipt_path_value, receipt, entry,
+        expected_oid=entry["expectedOid"],
+        error_suffix="target mutation",
+    )
+    return row
+
+
+def revalidate_owned_safety(
+    main: Path,
+    args: argparse.Namespace,
+    receipt_path_value: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+    *,
+    expected_oid: str,
+    error_suffix: str,
+) -> None:
+    branch = entry["branch"]
+    if pr_state(args.gh_command, main, branch) == "open":
+        raise LifecycleError(f"open PR before {error_suffix}: {branch}")
+    current_path, current_receipt = read_receipt(main, args.anchor, args.owner)
+    if current_path != receipt_path_value or current_receipt != receipt:
+        raise LifecycleError(
+            f"active claim or teardown receipt changed before {error_suffix}"
+        )
+    profile = load_profile(Path(entry["profile"]))
+    if branch in profile.protected_branches:
+        raise LifecycleError(f"protected branch before {error_suffix}: {branch}")
+    if resolve_ref(main, f"refs/heads/{branch}") != expected_oid:
+        raise LifecycleError(f"unexpected OID before {error_suffix}: {branch}")
+    proof_ref = validated_proof_ref(receipt, entry)
+    if resolve_ref(main, proof_ref) != entry["createdOid"]:
+        raise LifecycleError(f"session ownership proof changed before {error_suffix}: {branch}")
+
+
+def revalidate_ref_cleanup(
+    main: Path,
+    args: argparse.Namespace,
+    receipt_path_value: Path,
+    receipt: dict[str, Any],
+    entry: dict[str, Any],
+    main_oid: str,
+) -> None:
+    if resolve_commit(main, args.main) != main_oid:
+        raise LifecycleError("canonical main moved before branch cleanup")
+    branch = entry["branch"]
+    revalidate_owned_safety(
+        main, args, receipt_path_value, receipt, entry,
+        expected_oid=entry["expectedOid"],
+        error_suffix="branch cleanup",
+    )
+    target = Path(entry["worktree"])
+    linked = worktree_branches(main)
+    target_present = os.path.lexists(target)
+    if target_present:
+        metadata = target.lstat()
+        if (
+            not stat.S_ISDIR(metadata.st_mode)
+            or
+            linked.get(branch) != target.resolve()
+            or (metadata.st_dev, metadata.st_ino)
+            != (entry["rootDevice"], entry["rootInode"])
+        ):
+            raise LifecycleError(
+                f"worktree identity changed before branch cleanup: {branch}"
+            )
+    elif branch in linked:
+        raise LifecycleError(
+            f"worktree registration changed before branch cleanup: {branch}"
+        )
+    elif entry.get("teardownPhase") != "ref-deletion-pending":
+        raise LifecycleError(f"owned worktree disappeared before branch cleanup: {branch}")
+
+
+def canonical_ref(repo: Path, rev: str) -> str | None:
+    result = run(
+        ["git", "rev-parse", "--symbolic-full-name", rev],
+        cwd=repo,
+        check=False,
+    )
+    value = result.stdout.strip()
+    return value if result.returncode == 0 and value.startswith("refs/") else None
+
+
+def immutable_oid(value: str) -> bool:
+    return len(value) == 40 and all(character in "0123456789abcdef" for character in value)
+
+
+def teardown(main: Path, args: argparse.Namespace) -> dict[str, Any]:
+    with receipt_lock(main, args.anchor):
+        path, receipt, preview = assess(main, args)
+        main_ref = canonical_ref(main, args.main)
+        if main_ref is None and not immutable_oid(args.main):
+            raise LifecycleError(
+                "canonical main must be a ref or immutable full commit OID"
+            )
+        if not preview["removable"]:
+            blockers = [
+                f"{row['branch']}: {', '.join(row['reasons'])}"
+                for row in preview["targets"] if row["reasons"]
+            ]
+            raise LifecycleError("; ".join(blockers))
+        _, latest_receipt, latest = assess(main, args)
+        if latest != preview or latest_receipt != receipt:
+            raise LifecycleError("teardown inventory changed before removal")
+        if resolve_commit(main, args.main) != preview["mainOid"]:
+            raise LifecycleError("canonical main moved before teardown")
+
+        by_branch = {row["branch"]: row for row in latest["targets"]}
+        # Persist every recovery OID before the first mutation. The receipt is
+        # an audit/recovery archive even if the process stops between targets.
+        for entry in receipt["targets"]:
+            if not entry.get("removed"):
+                entry["recoveryOid"] = entry["expectedOid"]
+        receipt["state"] = "tearing-down"
+        write_receipt(path, receipt)
+
+        for entry in receipt["targets"]:
+            row = by_branch[entry["branch"]]
+            if row["integration"] == "already-removed":
+                entry["removed"] = True
+                continue
+            row = revalidate_target(
+                main,
+                args,
+                path,
+                receipt,
+                entry,
+                preview["mainOid"],
+            )
+            if (
+                row["scratchFiles"] != by_branch[entry["branch"]]["scratchFiles"]
+                or row["scratchEvidence"]
+                != by_branch[entry["branch"]]["scratchEvidence"]
+            ):
+                raise LifecycleError(
+                    f"scratch evidence changed before target mutation: "
+                    f"{entry['branch']}"
+                )
+            target = Path(entry["worktree"])
+            if os.path.lexists(target):
+                with verified_worktree_root(
+                    target,
+                    entry["rootDevice"],
+                    entry["rootInode"],
+                ) as descriptor:
+                    profile = load_profile(Path(entry["profile"]))
+                    remove_authorized_scratch(
+                        profile,
+                        descriptor,
+                        row["scratchFiles"],
+                        row["scratchEvidence"],
+                    )
+                after_scratch = revalidate_target(
+                    main,
+                    args,
+                    path,
+                    receipt,
+                    entry,
+                    preview["mainOid"],
+                )
+                if after_scratch["scratchFiles"]:
+                    raise LifecycleError(
+                        f"scratch inventory changed before worktree removal: "
+                        f"{entry['branch']}"
+                    )
+            revalidate_ref_cleanup(
+                main,
+                args,
+                path,
+                receipt,
+                entry,
+                preview["mainOid"],
+            )
+            entry["teardownPhase"] = "ref-deletion-pending"
+            write_receipt(path, receipt)
+            revalidate_ref_cleanup(
+                main,
+                args,
+                path,
+                receipt,
+                entry,
+                preview["mainOid"],
+            )
+            if not delete_owned_refs_prepared(
+                main,
+                entry["branch"],
+                entry["proofRef"],
+                entry["expectedOid"],
+                entry["createdOid"],
+                f"refs/tags/wave-active/{args.anchor}",
+                receipt["claimOid"],
+                remove_worktree=target if os.path.lexists(target) else None,
+                main_ref=main_ref,
+                main_oid=preview["mainOid"],
+                root_identity=(
+                    (entry["rootDevice"], entry["rootInode"])
+                    if os.path.lexists(target) else None
+                ),
+            ):
+                raise LifecycleError(
+                    f"locked worktree/ref cleanup stopped: {entry['branch']}"
+                )
+            entry["removed"] = True
+            entry["teardownPhase"] = "removed"
+            write_receipt(path, receipt)
+        receipt["state"] = "complete"
+        write_receipt(path, receipt)
+    result = receipt_report(path, receipt)
+    result["removed"] = True
+    return result
+
+
+def receipt_report(path: Path, receipt: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "receipt": str(path),
+        "anchor": receipt["anchor"],
+        "owner": receipt["owner"],
+        "baseOid": receipt["baseOid"],
+        "state": receipt["state"],
+        "targets": receipt["targets"],
+    }
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser()
+    commands = root.add_subparsers(dest="action", required=True)
+
+    def common(name: str) -> argparse.ArgumentParser:
+        command = commands.add_parser(name)
+        command.add_argument("--anchor", required=True)
+        command.add_argument("--owner", required=True)
+        return command
+
+    begin_parser = common("begin")
+    begin_parser.add_argument("--base", default="origin/main")
+
+    create_parser = common("create")
+    create_parser.add_argument(
+        "--profile", default="docs/agents/workflow-capabilities.json"
+    )
+    create_parser.add_argument("--base")
+    create_parser.add_argument("--gh-command", default="gh")
+    create_parser.add_argument("issue")
+    create_parser.add_argument("slug")
+    create_parser.add_argument("branch_type", nargs="?", default="feat")
+
+    recover_parser = common("recover")
+    recover_parser.add_argument("--branch", required=True)
+    recover_parser.add_argument("--gh-command", default="gh")
+
+    common("seal")
+    for name in ("inspect", "teardown"):
+        command = common(name)
+        command.add_argument("--main", default="origin/main")
+        command.add_argument("--gh-command", default="gh")
+    return root
+
+
+def main() -> int:
+    try:
+        args = parser().parse_args()
+        repo = main_worktree(Path.cwd())
+        actions = {
+            "begin": begin,
+            "create": create_target,
+            "recover": recover_creation,
+            "seal": seal,
+            "inspect": inspect,
+            "teardown": teardown,
+        }
+        result = actions[args.action](repo, args)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except LifecycleError as error:
+        print(f"STOP: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())