dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-work/scripts/unit_workspace_integration.py

@@ -0,0 +1,677 @@
+"""Canonical integration, locking, wave sequencing, and exact restoration."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import shutil
+from pathlib import Path
+
+from unit_workspace_state import *
+from unit_workspace_jobs import find_attempt, parse_diff_paths, scope_expansion_pending
+
+
+def integration_lock_path(doc: dict) -> str:
+    ident = doc["repository"]["identity_digest"] + "\0" + doc["branch"]["ref"]
+    # Anchor to the root this run actually lives under (run_dir searches both
+    # candidate roots), never the current invocation's preferred creation root:
+    # a fallback-root run must validate and release the lock it recorded.
+    run_root = os.path.dirname(run_dir(doc["run_id"]))
+    return os.path.join(run_root, ".locks", f"integration-{digest_bytes(ident.encode())}.json")
+
+
+def read_integration_lock(path: str) -> dict:
+    return read_private_json(path)
+
+
+def validated_lock_nonce(doc: dict, unit_id: str, lock: dict) -> str:
+    expected = {
+        "run_id": doc["run_id"],
+        "unit_id": unit_id,
+        "repository": doc["repository"]["identity_digest"],
+        "branch_ref": doc["branch"]["ref"],
+    }
+    if any(lock.get(k) != v for k, v in expected.items()):
+        raise Operational("BLOCKED", "integration lock identity mismatch")
+    nonce = lock.get("nonce")
+    if not isinstance(nonce, str) or not re.fullmatch(r"[0-9a-f]{48}", nonce):
+        raise TrustFailure("integration lock nonce is malformed")
+    return nonce
+
+
+def validate_lock(doc: dict, unit_id: str, token: str) -> tuple[str, dict]:
+    path = integration_lock_path(doc)
+    try:
+        lock = read_integration_lock(path)
+    except TrustFailure as exc:
+        if not os.path.lexists(path):
+            raise Operational("BLOCKED", "integration lock is missing") from exc
+        raise
+    nonce = validated_lock_nonce(doc, unit_id, lock)
+    if nonce != token:
+        raise Operational("BLOCKED", "integration lock token or identity mismatch")
+    return path, lock
+
+
+def cmd_integration_acquire(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id) as doc:
+        validate_repo(doc)
+        unit = doc["units"].get(args.unit_id)
+        plan_verification = bool(getattr(args, "plan_verification", False))
+        recover_only = bool(getattr(args, "recover_only", False))
+        allowed_states = INTEGRATABLE_STATES | {"preserved", "committed", "cleaned"}
+        if plan_verification or (recover_only and unit and unit.get("state") == "native-completed"):
+            allowed_states.add("native-completed")
+        if not unit or unit["state"] not in allowed_states:
+            raise Operational("REFUSED", "unit is not ready for integration")
+        if not plan_verification and unit["state"] != "native-completed":
+            validate_wave_order(doc, unit)
+        path = integration_lock_path(doc)
+        existing = doc.get("integration_lock")
+        if existing:
+            if not args.resume:
+                raise Operational("REFUSED", "integration claim already exists; pass --resume to recover the same claim")
+            if existing.get("phase", "held") != "held":
+                raise Operational("REFUSED", "integration claim is releasing; resume or retry release before acquisition")
+            validate_lock(doc, args.unit_id, existing["nonce"])
+            return "ACQUIRED", {"lock_token": existing["nonce"], "resumed": True, "path": path}
+        nonce = secrets.token_hex(24)
+        resumed = False
+        if recover_only:
+            lock = read_integration_lock(path)
+            nonce = validated_lock_nonce(doc, args.unit_id, lock)
+            resumed = True
+        else:
+            payload = {"run_id": args.run_id, "unit_id": args.unit_id, "nonce": nonce, "repository": doc["repository"]["identity_digest"], "branch_ref": doc["branch"]["ref"], "created_at": now_iso()}
+            try:
+                create_private(path, (json.dumps(payload, sort_keys=True) + "\n").encode())
+                test_fault("integration-lock-after-create")
+            except Operational as exc:
+                if exc.word == "INTERRUPTED":
+                    raise
+                lock = read_integration_lock(path)
+                if lock.get("run_id") == args.run_id and lock.get("unit_id") == args.unit_id:
+                    if not args.resume:
+                        raise Operational("REFUSED", "integration lock file already exists; pass --resume to recover its claim")
+                    nonce = validated_lock_nonce(doc, args.unit_id, lock)
+                    resumed = True
+                else:
+                    raise Operational("BLOCKED", "another run/unit owns canonical integration", {"owner_run": lock.get("run_id"), "owner_unit": lock.get("unit_id")})
+    with locked_manifest(args.run_id, write=True) as doc:
+        doc["integration_lock"] = {"unit_id": args.unit_id, "nonce": nonce, "path": path, "phase": "held"}
+        event(doc, "integration-lock-acquired", args.unit_id, {"resumed": resumed})
+    return "ACQUIRED", {"lock_token": nonce, "resumed": resumed, "path": path}
+
+
+def semantic_snapshot(repo: str) -> dict:
+    head = git_text(repo, "rev-parse", "HEAD")
+    head_tree = git_text(repo, "rev-parse", "HEAD^{tree}")
+    index_tree = git_text(repo, "write-tree")
+    raw = git(repo, "status", "--porcelain=v2", "-z", "--untracked-files=all")
+    worktree_index = git(repo, "diff", "--name-only", "-z")
+    return {
+        "head": head,
+        "branch_ref": git_text(repo, "symbolic-ref", "-q", "HEAD", check=False),
+        "head_tree": head_tree,
+        "index_tree": index_tree,
+        "status_sha256": digest_bytes(raw),
+        "status_empty": not bool(raw),
+        "worktree_index_empty": not bool(worktree_index),
+    }
+
+
+def expected_apply_snapshot(repo: str, pre_head: str, unit: dict) -> dict:
+    transport = unit["transport"]
+    if pre_head == transport["base"]:
+        tree = transport["tree"]
+    else:
+        # Compute the same semantic three-way result as applying the
+        # base-parented transport commit, without touching the canonical index.
+        merged = git_text(repo, "merge-tree", "--write-tree", pre_head, transport["commit"])
+        tree = merged.splitlines()[0] if merged else ""
+        if not tree:
+            raise Operational("BLOCKED", "could not derive expected canonical apply tree")
+    raw = git(repo, "diff-tree", "-r", "-M", "--name-status", "-z", pre_head, tree)
+    return {"index_tree": tree, "changed_paths": parse_diff_paths(raw)}
+
+
+def matches_expected_apply(repo: str, unit: dict, snap: dict | None = None) -> bool:
+    snap = snap or semantic_snapshot(repo)
+    pre = unit.get("integration", {}).get("pre_fold")
+    expected = unit.get("integration", {}).get("expected_apply")
+    if not pre or not expected:
+        return False
+    return (
+        snap["head"] == pre["head"]
+        and snap["index_tree"] == expected["index_tree"]
+        and snap["worktree_index_empty"]
+        and status_paths(repo) == set(expected["changed_paths"])
+    )
+
+
+def wave_members(doc: dict, unit: dict) -> list[dict]:
+    wave = unit.get("wave", {})
+    wave_id = wave.get("id")
+    if not wave_id:
+        return []
+    base = wave.get("base")
+    members = [
+        candidate for candidate in doc.get("units", {}).values()
+        if candidate.get("wave", {}).get("id") == wave_id
+    ]
+    positions = [candidate.get("wave", {}).get("position") for candidate in members]
+    if any(candidate.get("wave", {}).get("base") != base for candidate in members):
+        raise Operational("BLOCKED", "wave members do not share one recorded base")
+    if len(set(positions)) != len(positions):
+        raise Operational("BLOCKED", "wave positions are not unique")
+    return sorted(members, key=lambda candidate: candidate["wave"]["position"])
+
+
+def validate_wave_order(doc: dict, unit: dict) -> None:
+    members = wave_members(doc, unit)
+    earlier_unresolved = [
+        candidate["unit_id"] for candidate in members
+        if candidate["wave"]["position"] < unit["wave"]["position"]
+        and not (
+            candidate.get("state") in {"committed", "preserved", "cleaned"}
+            or (
+                candidate.get("state") == "native-completed"
+                and unit_accepted_commit(candidate) is not None
+            )
+        )
+    ]
+    if earlier_unresolved:
+        raise Operational(
+            "BLOCKED",
+            "earlier wave units must be committed or preserved before this fold-in",
+            {"reason": "earlier wave unit not resolved", "units": earlier_unresolved},
+        )
+
+
+def wave_member_changed_paths(candidate: dict) -> set[str] | None:
+    transport = candidate.get("transport", {})
+    if transport.get("commit"):
+        paths = transport.get("changed_paths")
+    elif candidate.get("state") == "native-completed":
+        if unit_accepted_commit(candidate) is None:
+            raise TrustFailure("native wave completion evidence is malformed")
+        completion = find_attempt(candidate).get("fallback", {}).get("completed")
+        paths = completion.get("changed_paths") if isinstance(completion, dict) else None
+    else:
+        return None
+    if not isinstance(paths, list) or any(not isinstance(path, str) for path in paths):
+        raise TrustFailure("wave member changed paths are malformed")
+    return set(paths)
+
+
+def validate_wave_collisions(
+    doc: dict,
+    unit: dict,
+    overrides: dict[str, set[str]] | None = None,
+    require_complete: bool = True,
+) -> None:
+    members = wave_members(doc, unit)
+    if not members:
+        return
+    overrides = overrides or {}
+    changed_by_unit: dict[str, set[str]] = {}
+    unterminated: list[str] = []
+    for candidate in members:
+        unit_id = candidate["unit_id"]
+        paths = overrides.get(unit_id)
+        if paths is None:
+            paths = wave_member_changed_paths(candidate)
+        if paths is None:
+            unterminated.append(unit_id)
+        else:
+            changed_by_unit[unit_id] = paths
+    if unterminated:
+        if require_complete:
+            raise Operational(
+                "BLOCKED",
+                "every wave worker must terminalize before the first fold-in",
+                {"reason": "wave not fully terminalized", "units": unterminated},
+            )
+    collisions: dict[str, list[str]] = {}
+    for index, left in enumerate(members):
+        for right in members[index + 1:]:
+            left_paths = changed_by_unit.get(left["unit_id"])
+            right_paths = changed_by_unit.get(right["unit_id"])
+            if left_paths is None or right_paths is None:
+                continue
+            overlap = sorted(left_paths & right_paths)
+            if overlap:
+                collisions[f'{left["unit_id"]}:{right["unit_id"]}'] = overlap
+    if collisions:
+        raise Operational(
+            "BLOCKED",
+            "wave transports have a changed-path collision",
+            {"reason": "changed-path collision", "collisions": collisions},
+        )
+
+
+def validate_wave_ready(doc: dict, unit: dict) -> None:
+    members = wave_members(doc, unit)
+    if not members:
+        return
+    validate_wave_order(doc, unit)
+    validate_wave_collisions(doc, unit)
+
+
+def validate_wave_advancement(members: list[dict], unit: dict, parent: str, canonical: str) -> list[str]:
+    position = unit["wave"]["position"]
+    targets = [candidate for candidate in members if candidate["wave"]["position"] > position]
+    for candidate in targets:
+        allowed = candidate["wave"].get("allowed_heads", [])
+        if canonical in allowed:
+            continue
+        if not allowed or allowed[-1] != parent:
+            raise Operational("BLOCKED", "wave advancement is not the exact recorded canonical chain")
+    return [candidate["unit_id"] for candidate in targets]
+
+
+def advance_wave_allowed_heads(members: list[dict], position: int, canonical: str) -> list[str]:
+    advanced: list[str] = []
+    for candidate in members:
+        if candidate["wave"]["position"] <= position:
+            continue
+        allowed = candidate["wave"].setdefault("allowed_heads", [])
+        if canonical not in allowed:
+            allowed.append(canonical)
+        advanced.append(candidate["unit_id"])
+    return advanced
+
+
+def validate_dependencies_ready(doc: dict, unit: dict) -> None:
+    missing: list[str] = []
+    unaccepted: list[str] = []
+    for dependency_id in unit.get("dependencies", []):
+        dependency = doc.get("units", {}).get(dependency_id)
+        if dependency is None:
+            missing.append(dependency_id)
+            continue
+        if unit_accepted_commit(dependency) is None:
+            unaccepted.append(dependency_id)
+    if missing or unaccepted:
+        raise Operational(
+            "BLOCKED",
+            "unit dependencies must have controller-accepted canonical commits before preflight",
+            {
+                "unit_id": unit["unit_id"],
+                "missing_dependencies": missing,
+                "unaccepted_dependencies": unaccepted,
+            },
+        )
+
+
+def dependency_advanced_head(doc: dict, unit: dict, head: str) -> bool:
+    dependency_commits = [
+        unit_accepted_commit(doc["units"][dependency_id])
+        for dependency_id in unit.get("dependencies", [])
+    ]
+    if any(commit is None for commit in dependency_commits):
+        return False
+    accepted_heads = {
+        commit
+        for unit_id, candidate in doc.get("units", {}).items()
+        if unit_id != unit.get("unit_id")
+        if (commit := unit_accepted_commit(candidate)) is not None
+    }
+    if head not in accepted_heads:
+        return False
+    allowed_heads = unit.get("wave", {}).get("allowed_heads", [])
+    required_ancestors = {
+        *accepted_heads,
+        *dependency_commits,
+        *allowed_heads,
+        unit.get("workspace", {}).get("base"),
+    }
+    required_ancestors.discard(None)
+    repo = doc["repository"]["toplevel"]
+    return all(
+        git_text(repo, "merge-base", commit, head, check=False) == commit
+        for commit in required_ancestors
+    )
+
+
+def validate_preflight_ancestry(doc: dict, unit: dict, heads: set[str]) -> None:
+    required = {
+        commit
+        for unit_id, candidate in doc.get("units", {}).items()
+        if unit_id != unit["unit_id"]
+        and (commit := unit_accepted_commit(candidate)) is not None
+    }
+    wave = unit.get("wave", {})
+    required.update(head for head in wave.get("allowed_heads", []) if head != wave.get("base"))
+
+    repo = doc["repository"]["toplevel"]
+    missing = {
+        head: sorted(
+            commit for commit in required
+            if git_text(repo, "merge-base", commit, head, check=False) != commit
+        )
+        for head in sorted(heads)
+    }
+    missing = {head: commits for head, commits in missing.items() if commits}
+    if missing:
+        raise Operational(
+            "BLOCKED",
+            "preflight HEAD omits controller-accepted prerequisite commits",
+            {"unit_id": unit["unit_id"], "missing_ancestry": missing},
+        )
+
+
+def cmd_preflight(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id) as doc:
+        info = validate_repo(doc)
+        unit = doc["units"].get(args.unit_id)
+        if not unit or unit["state"] not in {"integration-pending", "preserved"}:
+            raise Operational("REFUSED", "unit is not integration-pending")
+        validate_lock(doc, args.unit_id, args.lock_token)
+        validate_dependencies_ready(doc, unit)
+        if scope_expansion_pending(unit):
+            raise Operational(
+                "BLOCKED",
+                "worker requested scope expansion; inspect the retained result and transport, then resolve or re-dispatch explicitly",
+                {
+                    "unit_id": args.unit_id,
+                    "terminal_status": "scope_expansion",
+                    "transport": unit["transport"],
+                    "recovery_path": unit["recovery_path"],
+                },
+            )
+        validate_wave_ready(doc, unit)
+        allowed = set(unit["wave"].get("allowed_heads", []))
+        requested: set[str] = set()
+        if args.allowed_head:
+            requested = {git_text(info["toplevel"], "rev-parse", f"{h}^{{commit}}") for h in args.allowed_head}
+            if any(head not in allowed and not dependency_advanced_head(doc, unit, head) for head in requested):
+                raise Operational("BLOCKED", "unrecorded same-wave HEAD allowance")
+        if info["head"] not in allowed and not dependency_advanced_head(doc, unit, info["head"]):
+            raise Operational("BLOCKED", "canonical HEAD advanced outside the recorded wave")
+        validate_preflight_ancestry(doc, unit, requested | {info["head"]})
+        snap = semantic_snapshot(info["toplevel"])
+        if not snap["status_empty"] or snap["index_tree"] != snap["head_tree"]:
+            raise Operational("BLOCKED", "canonical checkout is not clean at preflight")
+        expected = expected_apply_snapshot(info["toplevel"], snap["head"], unit)
+        intent_revision = doc["revision"] + 1
+    with locked_manifest(args.run_id, write=True) as doc:
+        unit = doc["units"][args.unit_id]
+        unit["state"] = "integration-pending"
+        unit["integration"]["intent_revision"] = intent_revision
+        unit["integration"]["pre_fold"] = snap
+        unit["integration"]["expected_apply"] = expected
+        event(doc, "canonical-apply-intent", args.unit_id, {"transport": unit["transport"]["commit"], "pre_head": snap["head"]})
+    return "PREFLIGHT_OK", {"unit_id": args.unit_id, "pre_fold": snap, "transport": unit["transport"]}
+
+
+def cmd_mark_applied(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id) as doc:
+        validate_lock(doc, args.unit_id, args.lock_token)
+        unit = doc["units"].get(args.unit_id)
+        if not unit or unit["state"] not in {"integration-pending", "integrated"} or not unit["integration"].get("pre_fold"):
+            raise Operational("REFUSED", "no recorded preflight intent")
+        repo = validate_repo(doc)["toplevel"]
+        snap = semantic_snapshot(repo)
+        if snap["head"] != unit["integration"]["pre_fold"]["head"]:
+            raise Operational("BLOCKED", "canonical HEAD moved before apply was recorded")
+        if not matches_expected_apply(repo, unit, snap):
+            raise Operational("BLOCKED", "canonical state does not match the expected transport application")
+    test_fault("after-apply-observed")
+    with locked_manifest(args.run_id, write=True) as doc:
+        unit = doc["units"][args.unit_id]
+        unit["state"] = "integrated"
+        unit["integration"]["applied"] = {"at": now_iso(), "post_index_tree": snap["index_tree"], "status_sha256": snap["status_sha256"]}
+        event(doc, "transport-applied", args.unit_id, {"post_index_tree": snap["index_tree"]})
+    return "APPLIED", {"unit_id": args.unit_id, "post_index_tree": snap["index_tree"]}
+
+
+def cmd_mark_verified(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id, write=True) as doc:
+        validate_lock(doc, args.unit_id, args.lock_token)
+        unit = doc["units"].get(args.unit_id)
+        if not unit or unit["state"] not in {"integrated", "verified"}:
+            raise Operational("REFUSED", "unit is not applied")
+        repo = validate_repo(doc)["toplevel"]
+        if not matches_expected_apply(repo, unit):
+            raise Operational(
+                "BLOCKED",
+                "canonical state changed after the recorded transport application",
+                {
+                    "unit_id": args.unit_id,
+                    "reason": "canonical state no longer matches the expected transport application",
+                },
+            )
+        evidence = {"at": now_iso(), "digest": args.evidence_digest, "summary": args.summary}
+        ignored_state = getattr(args, "ignored_state", None)
+        if isinstance(ignored_state, str):
+            ignored_state = parse_json_arg(ignored_state, "ignored-state")
+        if ignored_state is not None:
+            evidence["ignored_state"] = ignored_state
+        unit["integration"]["verification"] = evidence
+        unit["state"] = "verified"
+        event(doc, "canonical-verification-passed", args.unit_id, {"digest": args.evidence_digest})
+    return "VERIFIED", {"unit_id": args.unit_id, "verification": evidence}
+
+
+def reconcile_commit(doc: dict, unit: dict) -> dict | None:
+    repo = doc["repository"]["toplevel"]
+    head = git_text(repo, "rev-parse", "HEAD")
+    parents = git_text(repo, "rev-list", "--parents", "-n", "1", head).split()
+    expected_parent = unit["integration"]["pre_fold"]["head"]
+    expected_tree = unit["integration"]["applied"]["post_index_tree"]
+    actual_tree = git_text(repo, "rev-parse", "HEAD^{tree}")
+    if parents == [head, expected_parent] and actual_tree == expected_tree and not status_paths(repo):
+        return {"commit": head, "parent": expected_parent, "tree": actual_tree, "at": now_iso()}
+    return None
+
+
+def cmd_mark_committed(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id) as doc:
+        validate_lock(doc, args.unit_id, args.lock_token)
+        unit = doc["units"].get(args.unit_id)
+        if not unit or unit["state"] not in {"verified", "committed"}:
+            raise Operational("REFUSED", "unit has not passed canonical verification")
+        commit = reconcile_commit(doc, unit)
+        if not commit:
+            raise Operational("BLOCKED", "canonical commit parent/tree/cleanliness do not match recorded integration")
+    with locked_manifest(args.run_id, write=True) as doc:
+        unit = doc["units"][args.unit_id]
+        unit["integration"]["canonical_commit"] = commit
+        unit["state"] = "committed"
+        event(doc, "canonical-commit-confirmed", args.unit_id, {"commit": commit["commit"]})
+    return "COMMITTED", {"unit_id": args.unit_id, "canonical_commit": commit}
+
+
+def cmd_wave_advance(args) -> tuple[str, dict]:
+    with locked_manifest(args.run_id) as doc:
+        info = validate_repo(doc)
+        unit = doc["units"].get(args.unit_id)
+        if not unit or unit.get("state") != "committed":
+            raise Operational("REFUSED", "only a committed wave unit can advance its siblings")
+        validate_lock(doc, args.unit_id, args.lock_token)
+        members = wave_members(doc, unit)
+        if not members:
+            raise Operational("REFUSED", "unit does not belong to a parallel wave")
+        validate_wave_ready(doc, unit)
+        canonical = git_text(info["toplevel"], "rev-parse", f"{args.canonical_commit}^{{commit}}")
+        recorded = unit.get("integration", {}).get("canonical_commit", {})
+        if recorded.get("commit") != canonical or info["head"] != canonical:
+            raise Operational("BLOCKED", "canonical wave commit does not match manifest and HEAD")
+        parent = unit.get("integration", {}).get("pre_fold", {}).get("head")
+        if recorded.get("parent") != parent:
+            raise Operational("BLOCKED", "canonical wave commit parent is not the recorded pre-fold HEAD")
+        validate_wave_advancement(members, unit, parent, canonical)
+    with locked_manifest(args.run_id, write=True) as doc:
+        unit = doc["units"][args.unit_id]
+        position = unit["wave"]["position"]
+        advanced = advance_wave_allowed_heads(wave_members(doc, unit), position, canonical)
+        event(doc, "wave-advanced", args.unit_id, {"canonical_commit": canonical, "eligible_siblings": advanced})
+    return "WAVE_ADVANCED", {"unit_id": args.unit_id, "canonical_commit": canonical, "eligible_siblings": advanced}
+
+
+def path_in_tree(repo: str, treeish: str, rel: str) -> bool:
+    out = git(repo, "ls-tree", "-z", "--full-tree", treeish, "--", rel)
+    return bool(out)
+
+
+def remove_introduced_paths(repo: str, unit: dict) -> None:
+    pre = unit["integration"]["pre_fold"]["head"]
+    base = unit["transport"]["base"]
+    commit = unit["transport"]["commit"]
+    raw = git(repo, "diff-tree", "-r", "-M", "--name-status", "-z", base, commit)
+    for rel in parse_diff_paths(raw):
+        if path_in_tree(repo, pre, rel):
+            continue
+        target = os.path.abspath(os.path.join(repo, rel))
+        if os.path.commonpath([repo, target]) != repo:
+            raise Operational("BLOCKED", "transport path escaped canonical repository")
+        if os.path.islink(target) or os.path.isfile(target):
+            os.unlink(target)
+        elif os.path.isdir(target):
+            shutil.rmtree(target)
+        parent = os.path.dirname(target)
+        while parent != repo and os.path.commonpath([repo, parent]) == repo:
+            try:
+                os.rmdir(parent)
+            except OSError:
+                break
+            parent = os.path.dirname(parent)
+
+
+def restore(run_id: str, unit_id: str, lock_token: str) -> bool:
+    with locked_manifest(run_id) as doc:
+        validate_lock(doc, unit_id, lock_token)
+        unit = doc["units"].get(unit_id)
+        if not unit or not unit["integration"].get("pre_fold"):
+            raise Operational("REFUSED", "unit has no pre-fold snapshot")
+        repo = doc["repository"]["toplevel"]
+        pre = dict(unit["integration"]["pre_fold"])
+        git_dir = git_text(repo, "rev-parse", "--path-format=absolute", "--absolute-git-dir")
+        cherry_pick_head = os.path.join(git_dir, "CHERRY_PICK_HEAD")
+        expected_conflict = False
+        if os.path.isfile(cherry_pick_head) and git_text(repo, "rev-parse", "HEAD") == pre["head"]:
+            expected_conflict = Path(cherry_pick_head).read_text().strip() == unit["transport"]["commit"]
+        current = None if expected_conflict else semantic_snapshot(repo)
+        already_exact = current == pre if current else False
+        expected_apply = matches_expected_apply(repo, unit, current) if current else False
+        partial_reset = bool(current) and (
+            unit.get("state") == "restoring"
+            and current["head"] == pre["head"]
+            and current["index_tree"] == pre["index_tree"]
+            and current["worktree_index_empty"]
+            and status_paths(repo).issubset(set(unit["integration"]["expected_apply"]["changed_paths"]))
+        )
+        if not (already_exact or expected_apply or partial_reset or expected_conflict):
+            raise Operational("BLOCKED", "canonical state is not a proven in-flight transport state; refusing destructive restoration")
+    with locked_manifest(run_id, write=True) as doc:
+        unit = doc["units"][unit_id]
+        unit["state"] = "restoring"
+        event(doc, "restore-intent", unit_id)
+    if not already_exact:
+        git(repo, "cherry-pick", "--abort", check=False)
+        git(repo, "reset", "--hard", pre["head"])
+        test_fault("restore-after-reset")
+        with locked_manifest(run_id) as doc:
+            unit = doc["units"][unit_id]
+            remove_introduced_paths(repo, unit)
+    test_fault("restore-after-path-removal")
+    actual = semantic_snapshot(repo)
+    exact = actual == pre
+    with locked_manifest(run_id, write=True) as doc:
+        unit = doc["units"][unit_id]
+        unit["integration"]["restore"] = {
+            "at": now_iso(),
+            "exact": exact,
+            "already_exact": already_exact,
+            "snapshot": actual,
+        }
+        if exact:
+            unit["state"] = "preserved"
+            event(doc, "canonical-restored", unit_id)
+        else:
+            blocker = {"at": now_iso(), "unit_id": unit_id, "reason": "exact pre-fold restoration could not be proven"}
+            doc["blockers"].append(blocker)
+            event(doc, "restore-blocked", unit_id)
+    return exact
+
+
+def cmd_restore(args) -> tuple[str, dict]:
+    exact = restore(args.run_id, args.unit_id, args.lock_token)
+    if not exact:
+        raise Operational("BLOCKED", "exact pre-fold restoration could not be proven")
+    return "PRESERVED", {"unit_id": args.unit_id, "recovery_path": os.path.join(run_dir(args.run_id), "units", args.unit_id)}
+
+
+
+
+def release_lock_is_owned(doc: dict, unit_id: str, lock_token: str, lock: dict) -> bool:
+    expected = {
+        "run_id": doc["run_id"],
+        "unit_id": unit_id,
+        "repository": doc["repository"]["identity_digest"],
+        "branch_ref": doc["branch"]["ref"],
+    }
+    if any(lock.get(key) != value for key, value in expected.items()):
+        return False
+    nonce = lock.get("nonce")
+    if not isinstance(nonce, str) or not re.fullmatch(r"[0-9a-f]{48}", nonce):
+        return False
+    return nonce == lock_token
+
+
+def integration_release(run_id: str, unit_id: str, lock_token: str) -> None:
+    with locked_manifest(run_id, write=True) as doc:
+        held = doc.get("integration_lock")
+        if not held or held.get("unit_id") != unit_id or held.get("nonce") != lock_token:
+            raise Operational("REFUSED", "integration lock token or identity mismatch")
+        unit = doc["units"].get(unit_id)
+        pre_apply = bool(
+            unit
+            and unit.get("state") == "integration-pending"
+            and not unit.get("integration", {}).get("pre_fold")
+        )
+        if not unit or (unit["state"] not in {"committed", "preserved", "cleaned", "native-completed"} and not pre_apply):
+            raise Operational("REFUSED", "integration lock releases only before preflight or after accepted completion")
+        path = held.get("path")
+        if path != integration_lock_path(doc):
+            raise Operational("BLOCKED", "manifest integration lock path changed")
+        phase = held.get("phase", "held")
+        if phase == "held":
+            validate_lock(doc, unit_id, lock_token)
+            held["phase"] = "releasing"
+            held["release_started_at"] = now_iso()
+            event(doc, "integration-lock-release-intent", unit_id)
+        elif phase != "releasing":
+            raise Operational("BLOCKED", "manifest integration claim has an unknown phase")
+    with locked_manifest(run_id, write=True) as doc:
+        held = doc.get("integration_lock")
+        if not held or held.get("unit_id") != unit_id or held.get("nonce") != lock_token or held.get("phase") != "releasing":
+            raise Operational("BLOCKED", "manifest integration claim changed")
+        if held.get("path") != path or path != integration_lock_path(doc):
+            raise Operational("BLOCKED", "manifest integration lock path changed")
+        current = None
+        try:
+            current = read_integration_lock(path)
+        except TrustFailure:
+            if os.path.lexists(path):
+                raise
+        if current is not None and release_lock_is_owned(doc, unit_id, lock_token, current):
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass
+        test_fault("integration-release-after-unlink")
+        if os.path.lexists(path):
+            current = read_integration_lock(path)
+            if release_lock_is_owned(doc, unit_id, lock_token, current):
+                raise Operational("BLOCKED", "integration lock file remained after release")
+        doc["integration_lock"] = None
+        event(doc, "integration-lock-released", unit_id)
+
+
+def cmd_integration_release(args) -> tuple[str, dict]:
+    integration_release(args.run_id, args.unit_id, args.lock_token)
+    return "RELEASED", {"unit_id": args.unit_id}