@opengsd/gsd-path 1.4.0 → 1.5.0

package/scripts/isolation.py

@@ -15,6 +15,7 @@ import hashlib
 import io
 import json
 import shlex
+import shutil
 import os
 import re
 import stat
@@ -27,11 +28,6 @@ import tempfile
 from pathlib import Path, PurePosixPath
 from typing import Dict, Iterator, Optional, Sequence, Set, Tuple
 
-if sys.platform == "win32":
-    import msvcrt
-else:
-    import fcntl
-
 if __package__:
     from .pipeline_git import (
         attest_commit_body,
@@ -176,6 +172,12 @@ def sidecar_root(primary: Path, kind: str, name: str, *, pin: bool = False) -> P
         raise IsolationError(str(error)) from error
 
 
+def release_workspace_quietly(primary: Path) -> None:
+    """Best-effort placement hygiene after a sidecar retires; never blocks landing."""
+    with contextlib.suppress(ValueError, OSError):
+        worktree_paths.release_workspace(primary)
+
+
 def validate_task_id(task_id: str) -> str:
     if not TASK_ID_RE.fullmatch(task_id):
         raise IsolationError(f"invalid task id: {task_id}")
@@ -439,8 +441,9 @@ def collect_artifact_recoveries(primary: Path) -> list[Dict[str, object]]:
 
 
 def _git_file(repo: Path, revision: str, path: str) -> bytes:
+    git_path = PurePosixPath(path.replace("\\", "/")).as_posix()
     result = subprocess.run(
-        ("git", "-C", str(repo), "show", f"{revision}:{path}"),
+        ("git", "-C", str(repo), "show", f"{revision}:{git_path}"),
         capture_output=True,
         check=False,
     )
@@ -481,6 +484,70 @@ def _same_directory(path: Path, expected: os.stat_result) -> bool:
     return stat.S_ISDIR(current.st_mode) and os.path.samestat(current, expected)
 
 
+def _long_path(absolute: str) -> str:
+    if absolute.startswith("\\\\?\\"):
+        return absolute
+    if absolute.startswith("\\\\"):
+        return "\\\\?\\UNC\\" + absolute[2:]
+    return "\\\\?\\" + absolute
+
+
+def _force_rmtree(path: Path) -> None:
+    """Delete a sidecar tree directly, tolerating read-only files and long paths."""
+    def _writable(function, target, _error):
+        os.chmod(target, stat.S_IWRITE)
+        function(target)
+
+    # The \\?\ prefix sidesteps Windows MAX_PATH on deep sidecar trees.
+    target = Path(_long_path(os.path.abspath(path))) if os.name == "nt" else path
+    try:
+        shutil.rmtree(target, onerror=_writable)
+    except OSError as error:
+        raise IsolationError(f"could not delete {path}: {error}") from error
+
+
+def _remove_worktree(primary: Path, destination: Path, force: bool) -> None:
+    """Remove a sidecar worktree, tolerating populated submodules and locked trees.
+
+    git refuses to remove worktrees whose submodules were ever initialized, and
+    forced removal can still fail deleting deep trees (Windows "Directory not
+    empty"). A dirty sidecar keeps git's refusal unless `force`, so forced
+    retries only run for a provably clean tree. The direct-delete fallback runs
+    only for git's tree-deletion failures, so any other git error leaves the
+    sidecar intact for diagnosis.
+    """
+    tree_delete_failure = ("failed to delete", "directory not empty", "permission denied")
+
+    def failure(*flags: str) -> str:
+        result = run_git(primary, "worktree", "remove", *flags, str(destination))
+        return (result.stderr or result.stdout).strip() if result.returncode else ""
+
+    detail = failure("--force") if force else failure()
+    if not detail:
+        return
+    if not force and destination.is_dir():
+        status = run_git(
+            destination, "status", "--porcelain", "--untracked-files=all"
+        )
+        if status.returncode != 0 or status.stdout.strip():
+            raise IsolationError(detail or "git worktree remove failed")
+        run_git(destination, "submodule", "deinit", "--all", "--force")
+        detail = failure("--force")
+        if not detail:
+            return
+    if destination.is_dir() and any(
+        marker in detail.lower() for marker in tree_delete_failure
+    ):
+        _force_rmtree(destination)
+        detail = failure("--force")
+    if detail and not destination.is_dir():
+        pruned = run_git(primary, "worktree", "prune")
+        if pruned.returncode == 0:
+            detail = ""
+    if detail or destination.is_dir() or destination.resolve() in _registered_worktrees(primary):
+        raise IsolationError(detail or "git worktree remove failed")
+
+
 def _cleanup_reserved_worktree(
     primary: Path,
     branch: str,
@@ -758,7 +825,7 @@ def retire_member_task(
         raise IsolationError(f"member task branch {ref} has unlanded commits")
     destination = sidecar_root(checkout, "task", name)
     copy_rejected = None
-    if force:
+    if force and task_file:
         rejected, copy_rejected = _rejected_member_attempt_error(coordinator, member, task_id, task_file, destination)
         if rejected:
             raise IsolationError(rejected)
@@ -766,9 +833,7 @@ def retire_member_task(
     if destination.resolve() in registered:
         if registered[destination.resolve()] != ref:
             raise IsolationError(f"member task sidecar is on another branch: {destination}")
-        removed = run_git(checkout, "worktree", "remove", *(("--force",) if force else ()), str(destination))
-        if removed.returncode != 0:
-            raise IsolationError((removed.stderr or removed.stdout).strip() or "git worktree remove failed")
+        _remove_worktree(checkout, destination, force)
     authorization = run_git(checkout, "update-ref", "-d", member_task_authorization_ref(project, task_id))
     if authorization.returncode != 0:
         raise IsolationError((authorization.stderr or authorization.stdout).strip() or "git update-ref failed")
@@ -776,6 +841,7 @@ def retire_member_task(
         deleted = run_git(checkout, "update-ref", "-d", ref, tip.stdout.strip())
         if deleted.returncode != 0:
             raise IsolationError((deleted.stderr or deleted.stdout).strip() or "git update-ref failed")
+    release_workspace_quietly(checkout)
     return copy_rejected
 
 
@@ -936,9 +1002,11 @@ def activate_member_task(
     created = run_git(checkout, "update-ref", ref, member_base, "0" * 40)
     if created.returncode != 0 and run_git(checkout, "rev-parse", "--verify", "--quiet", ref).stdout.strip() != member_base:
         raise IsolationError("could not record member task authorization")
-    return {"agent": agent, "base": resolved_base, "copy": str(copy), "member": member,
+    result = {"agent": agent, "base": resolved_base, "copy": str(copy), "member": member,
             "member_base": member_base, "status": "in-progress", "task_branch": branch,
             "task_file": task_file, "worktree": str(sidecar)}
+    _write_native_member_dispatch_record(coordinator, result)
+    return result
 
 
 def retained_member_task(
@@ -1050,25 +1118,8 @@ def _member_journal_path(coordinator: Path, task_id: str) -> Path:
 @contextlib.contextmanager
 def _member_landing_lock(coordinator: Path) -> Iterator[None]:
     path = common_git_dir(coordinator).joinpath(*MEMBER_LANDING_DIR, ".lock")
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("a+b") as handle:
-        if sys.platform == "win32":
-            handle.seek(0, os.SEEK_END)
-            if handle.tell() == 0:
-                handle.write(b"\0")
-                handle.flush()
-            handle.seek(0)
-            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
-        else:
-            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
-        try:
-            yield
-        finally:
-            if sys.platform == "win32":
-                handle.seek(0)
-                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
-            else:
-                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+    with _common.exclusive_lock(path):
+        yield
 
 
 def _require_member_coordinator_branch(coordinator: Path) -> None:
@@ -1411,8 +1462,9 @@ def retire_member_verify(created: Dict[str, Dict[str, str]]) -> None:
     """Remove the member siblings of a coordinator verify sidecar; they hold no output."""
     for record in reversed(list(created.values())):
         checkout, destination, branch = _member_verify_sidecar(record)
-        git_output(checkout, "worktree", "remove", "--force", str(destination))
+        _remove_worktree(checkout, destination, True)
         git_output(checkout, "branch", "-D", branch)
+        release_workspace_quietly(checkout)
 
 
 def check_member_verify(created: Dict[str, Dict[str, str]]) -> None:
@@ -1444,6 +1496,89 @@ def clean_verify(primary: Path, worktree: Path, base: str, branch: str) -> Dict[
     return {"worktree": str(worktree), "branch": branch, "base": expected, "removed": removed}
 
 
+def ensure_verify_sidecar(primary: Path, base: str, branch: str) -> Dict[str, object]:
+    """Return the named verify sidecar, recreating it when it is missing.
+
+    Finish needs the sidecar prepare-task created. A deleted sidecar must be
+    rebuildable from the recorded base without a clean primary: the serial
+    task's own product changes are exactly the tree finish reproduces next,
+    so this must not reuse isolate_verify's clean-tree gate.
+    """
+    primary = require_directory(primary, "primary worktree")
+    if worktree_root(primary) != primary:
+        raise IsolationError(f"primary is not its Git root: {primary}")
+    resolved_base = require_commit(primary, require_full_sha(base))
+    if not branch.startswith(VERIFY_BRANCH_PREFIX):
+        raise IsolationError("verify sidecar reproduction requires a verify branch")
+    destination = _sidecar_path_for_branch(primary, branch)
+    ref = f"refs/heads/{branch}"
+    registered = _registered_worktrees(primary)
+    if destination.is_symlink() or (destination.exists() and not destination.is_dir()):
+        raise IsolationError(f"worktree path already exists: {destination}")
+    if destination.is_dir():
+        try:
+            # A leftover empty directory (a half-deleted sidecar) clears;
+            # anything non-empty must be the sidecar itself.
+            destination.rmdir()
+        except OSError:
+            try:
+                same = (
+                    worktree_root(destination) == destination
+                    and destination.resolve() in registered
+                    and registered[destination.resolve()] == ref
+                    and common_git_dir(destination) == common_git_dir(primary)
+                )
+            except IsolationError:
+                same = False
+            if not same:
+                raise IsolationError(
+                    f"verify sidecar ownership changed: {destination}"
+                ) from None
+            if (
+                require_attached(destination) != branch
+                or current_sha(destination) != resolved_base
+            ):
+                raise IsolationError(f"verify sidecar HEAD changed: {destination}")
+            return {
+                "base": resolved_base,
+                "branch": branch,
+                "kind": "verify",
+                "mode": "sidecar",
+                "worktree": str(destination),
+            }
+    if destination.resolve() in registered:
+        cleared = run_git(primary, "worktree", "remove", str(destination))
+        if cleared.returncode != 0:
+            run_git(primary, "worktree", "prune")
+            if destination.resolve() in _registered_worktrees(primary):
+                raise IsolationError(
+                    (cleared.stderr or cleared.stdout).strip()
+                    or "could not clear stale worktree registration"
+                )
+    existing = run_git(primary, "show-ref", "--verify", "--quiet", ref)
+    if existing.returncode == 0:
+        deleted = run_git(primary, "update-ref", "-d", ref)
+        if deleted.returncode != 0:
+            raise IsolationError(
+                (deleted.stderr or deleted.stdout).strip() or "git update-ref failed"
+            )
+    create_named_worktree(primary, branch, destination, resolved_base)
+    return {
+        "base": resolved_base,
+        "branch": branch,
+        "kind": "verify",
+        "mode": "sidecar",
+        "worktree": str(destination),
+    }
+
+
+def reproduce_verify_sidecar(sidecar_path: Path, tree: str) -> None:
+    """Copy the primary's current task tree into the verify sidecar (clean_verify's inverse)."""
+    git_output(sidecar_path, "read-tree", "-u", "--reset", tree)
+    if git_output(sidecar_path, "write-tree") != tree:
+        raise IsolationError("sidecar reproduction differs from the primary task diff")
+
+
 def _split_paths(block: str) -> Set[str]:
     return {line.strip() for line in block.splitlines() if line.strip()}
 
@@ -1451,7 +1586,7 @@ def _split_paths(block: str) -> Set[str]:
 # Top-level .project entries the pipeline owns; ship checks filter other entries by Git visibility.
 PROJECT_ENTRIES = frozenset({
     "STATE.md", "LESSONS.md", "REPOSITORY.md", "MEMBERS.md", "CHARTER.md", "ROADMAP.md",
-    "SYNTHESIS.md",
+    "SYNTHESIS.md", "config.json", "model-policy.json",
     "intent", "research", "plan", "tasks", "review", "build", "discuss", "archive", "next",
 })
 
@@ -1556,14 +1691,24 @@ def _commit_pending(
 
 
 def validate_allowed_changes(
-    repo: Path, base: str, pending: Set[str], allowed: Set[str]
+    repo: Path,
+    base: str,
+    pending: Set[str],
+    allowed: Set[str],
+    tolerated: Set[str] = frozenset(),
 ) -> None:
-    if not pending:
+    # Tolerated paths (primary bookkeeping) may stay uncommitted; the next
+    # `.project` checkpoint commits them.
+    landing = pending - tolerated
+    if not landing:
         raise IsolationError("no changes to land")
-    since_base = committed_paths_since(repo, base) | pending
+    since_base = committed_paths_since(repo, base) | landing
     unexpected = sorted(path for path in since_base if path not in allowed)
     if unexpected:
-        raise IsolationError("unexpected paths: " + ", ".join(unexpected))
+        raise IsolationError(
+            "unexpected paths: " + ", ".join(unexpected)
+            + "; landing allows only the task file and its declared files"
+        )
 def _clean_blob_oid(repo: Path, path: str, text: str, *, write: bool) -> str:
     arguments = ["hash-object"]
     if write:
@@ -1583,21 +1728,23 @@ def commit_allowed_changes(
     subject: str,
     allowed: Set[str],
     body: str,
+    tolerated: Set[str] = frozenset(),
 ) -> tuple[str, str, Dict[str, Optional[tuple[str, str]]]]:
     require_attached(repo)
     pending = uncommitted_paths(repo)
-    validate_allowed_changes(repo, base, pending, allowed)
+    validate_allowed_changes(repo, base, pending, allowed, tolerated)
+    staging = pending - tolerated
     reset = run_git(repo, "reset", "-q", "HEAD")
     if reset.returncode != 0:
         raise IsolationError("could not clear the index before landing")
-    for path in sorted(pending):
+    for path in sorted(staging):
         added = run_git(repo, "add", "-A", "--", path)
         if added.returncode != 0:
             raise IsolationError(f"could not stage {path}")
     staged = _split_paths(
         git_output(repo, "diff", "--cached", "--name-only", "--relative")
     )
-    if staged != pending:
+    if staged != staging:
         raise IsolationError("staged paths do not match the uncommitted change set")
     verified_tree = git_output(repo, "write-tree")
     verified_delta = _tree_delta(repo, base, verified_tree)
@@ -1743,6 +1890,17 @@ def activate_task(
     if task_branch is None:
         if branch.startswith(TASK_BRANCH_PREFIX):
             raise IsolationError("parallel task activation requires --task-branch")
+        live = [
+            path
+            for path, ref in _registered_worktrees(worktree).items()
+            if ref == f"refs/heads/{task_branch_name(task_id)}"
+            and path != worktree
+        ]
+        if live:
+            raise IsolationError(
+                "task has an active parallel worktree; serial activation in "
+                f"another worktree is refused (activate {live[0]} with --task-branch)"
+            )
     elif task_branch != task_branch_name(task_id) or branch != task_branch:
         raise IsolationError("task activation branch does not match the task worktree")
     normalized_task = relative_posix(task_file)
@@ -1773,7 +1931,7 @@ def activate_task(
             if existing.returncode != 0 or existing.stdout.strip() != resolved_base:
                 _replace_regular_file(task_path, text.encode("utf-8"), mode)
                 raise IsolationError("could not record task worktree authorization")
-    return {
+    result = {
         "agent": agent,
         "base": resolved_base,
         "status": "in-progress",
@@ -1781,6 +1939,30 @@ def activate_task(
         "task_file": normalized_task,
         "worktree": str(worktree),
     }
+    _write_native_dispatch_record(worktree, result)
+    return result
+
+
+def _write_native_dispatch_record(worktree: Path, activation: Dict[str, object]) -> None:
+    try:
+        if __package__:
+            from . import dispatch_driver
+        else:
+            import dispatch_driver
+    except ImportError:
+        return
+    dispatch_driver.record_native_activation(worktree, activation)
+
+
+def _write_native_member_dispatch_record(coordinator: Path, activation: Dict[str, object]) -> None:
+    try:
+        if __package__:
+            from . import dispatch_driver
+        else:
+            import dispatch_driver
+    except ImportError:
+        return
+    dispatch_driver.record_native_member_activation(coordinator, activation)
 
 
 def deactivate_task(
@@ -1899,6 +2081,59 @@ def stamp_task_landed(task_path: Path, base: str) -> None:
     )
 
 
+def block_serial_task(
+    primary: Path, task_file: str, task_id: str, base: str
+) -> Dict[str, str]:
+    """Record an explicit blocked result on its still-active serial task."""
+    primary = require_directory(primary, "primary worktree")
+    if worktree_root(primary) != primary:
+        raise IsolationError(f"primary is not its Git root: {primary}")
+    normalized_task = relative_posix(task_file)
+    if not normalized_task.startswith(".project/tasks/"):
+        raise IsolationError("serial task file must stay under .project/tasks/")
+    task_id = validate_task_id(task_id)
+    expected_base = require_commit(primary, require_full_sha(base))
+    task_path = _real_file(primary, normalized_task, "serial task file")
+    text, mode = _read_task_text(task_path)
+    fields, error = task_frontmatter(text)
+    if error or fields is None:
+        raise IsolationError(error or "serial task frontmatter is unreadable")
+    if fields.get("id") != task_id:
+        raise IsolationError("serial task id changed before blocked result")
+    if fields.get("status") not in {"in-progress", "blocked"}:
+        raise IsolationError("serial task is no longer active")
+    if fields.get("base") != expected_base:
+        raise IsolationError("serial task base changed before blocked result")
+    if fields.get("task_branch") != "null":
+        raise IsolationError("serial task records a task branch")
+    recorded_worktree = fields.get("worktree")
+    if not isinstance(recorded_worktree, str) or Path(recorded_worktree).resolve() != primary:
+        raise IsolationError("serial task worktree changed before blocked result")
+
+    if fields.get("status") == "blocked":
+        return {"task_id": task_id, "task_file": normalized_task,
+                "base": expected_base, "status": "blocked"}
+
+    head, body = split_frontmatter(text)
+    replaced = False
+    lines = []
+    for line in head:
+        if _frontmatter_key(line) == "status":
+            if replaced:
+                raise IsolationError("serial task frontmatter repeats status")
+            replaced = True
+            lines.append("status: blocked")
+        else:
+            lines.append(line)
+    if not replaced:
+        raise IsolationError("serial task frontmatter is missing status")
+    _replace_regular_file(
+        task_path, ("---\n" + "\n".join(lines) + "\n---\n" + body).encode("utf-8"), mode
+    )
+    return {"task_id": task_id, "task_file": normalized_task,
+            "base": expected_base, "status": "blocked"}
+
+
 def _restore_landing_state(
     worktree: Path, task_path: Path, task_bytes: bytes, task_mode: int, index_tree: str
 ) -> None:
@@ -1933,7 +2168,12 @@ def _restore_rejected_commit(
 
 
 def _stamp_and_commit(
-    worktree: Path, base: str, subject: str, task_file: str, allowed: Set[str]
+    worktree: Path,
+    base: str,
+    subject: str,
+    task_file: str,
+    allowed: Set[str],
+    tolerated: Set[str] = frozenset(),
 ) -> tuple[str, Dict[str, Optional[tuple[str, str]]]]:
     task_path = worktree / task_file
     task_text, task_mode = _read_task_text(task_path)
@@ -1954,14 +2194,14 @@ def _stamp_and_commit(
     pending = uncommitted_paths(worktree)
     if stamped != task_bytes:
         pending.add(task_file)
-    validate_allowed_changes(worktree, base, pending, allowed)
+    validate_allowed_changes(worktree, base, pending, allowed, tolerated)
     original_head = current_sha(worktree)
     index_tree = git_output(worktree, "write-tree")
     try:
         _replace_regular_file(task_path, stamped, task_mode)
-        body = task_commit_body(task_file, uncommitted_paths(worktree), base)
+        body = task_commit_body(task_file, uncommitted_paths(worktree) - tolerated, base)
         commit, verified_tree, verified_delta = commit_allowed_changes(
-            worktree, base, subject, allowed, body
+            worktree, base, subject, allowed, body, tolerated
         )
         proof_error = _landing_commit_proof_error(
             worktree,
@@ -2039,6 +2279,7 @@ def land(
             subject,
             relative_posix(task_file),
             allowed,
+            BOOKKEEPING_PATHS,
         )
         return {
             "bound_branch": bound,
@@ -2333,7 +2574,7 @@ def _landing_retry_error(
     if task_file not in pending:
         return "interrupted landing does not retain the task change"
     try:
-        validate_allowed_changes(repo, base, pending, contract_paths)
+        validate_allowed_changes(repo, base, pending, contract_paths, BOOKKEEPING_PATHS)
     except IsolationError as validation_error:
         return str(validation_error)
     return None
@@ -2556,6 +2797,40 @@ def _resume_task_error(
     return _retained_task_contract_error(current_text, isolate_text)
 
 
+def _serial_bookkeeping_error(primary: Path, base: str, head: str) -> Optional[str]:
+    """Prove that serial task history advanced only through linear .project commits."""
+    if base == head:
+        return None
+    if run_git(primary, "merge-base", "--is-ancestor", base, head).returncode != 0:
+        return "recorded base is not an ancestor of the current branch"
+    commits = git_output(
+        primary, "rev-list", "--first-parent", "--reverse", f"{base}..{head}"
+    ).splitlines()
+    previous = base
+    for commit in commits:
+        parents = git_output(primary, "rev-list", "--parents", "-n", "1", commit).split()
+        if len(parents) != 2 or parents[1] != previous:
+            return "history contains an unproven merge or commit sequence"
+        paths = git_output(
+            primary,
+            "diff-tree",
+            "--no-commit-id",
+            "--name-only",
+            "-r",
+            "--no-renames",
+            previous,
+            commit,
+        ).splitlines()
+        if not paths:
+            return "history contains an empty commit"
+        if any(path != ".project" and not path.startswith(".project/") for path in paths):
+            return "history contains changes outside .project"
+        previous = commit
+    if previous != head:
+        return "history does not prove a first-parent path from the recorded base"
+    return None
+
+
 MEMBER_RECORD_RE = re.compile(
     r"Task: (?P<task>\S+)\nBase: (?P<base>[0-9a-f]{40})\n"
     r"Member: (?P<member>\S+) (?P<landing>[0-9a-f]{40}) (?P<member_base>[0-9a-f]{40})"
@@ -2845,8 +3120,12 @@ def _recover_task(
                 )
             except IsolationError as error:
                 return result("block", reason=f"{status} task has invalid base: {error}")
-            if head != base:
-                return result("block", reason=f"{status} serial task advanced past its base")
+            advance_error = _serial_bookkeeping_error(primary, base, head)
+            if advance_error:
+                return result(
+                    "block",
+                    reason=f"{status} serial task advanced past its base: {advance_error}",
+                )
             primary_worktree, primary_error = _worktree_report(primary, primary, bound)
             if primary_error:
                 return result("block", reason=primary_error)
@@ -2860,6 +3139,15 @@ def _recover_task(
                 str(primary),
                 "null",
             )
+            if head != base and resume_error is None:
+                return result(
+                    "reconcile",
+                    base=base,
+                    reason=(
+                        "serial task advanced through .project bookkeeping; reconcile the "
+                        "attempt and any retained Verify sidecar before resetting it to pending"
+                    ),
+                )
         if resume_error:
             return result("block", reason=resume_error)
         return result("resume", base=base)
@@ -2888,8 +3176,12 @@ def _recover_task(
         if serial_retained:
             if str(fields.get("task_branch", "")) != "null":
                 return result("block", reason=f"{status} serial task records a task branch")
-            if run_git(primary, "merge-base", "--is-ancestor", base, head).returncode != 0:
-                return result("block", reason=f"{status} serial task base is not an ancestor")
+            advance_error = _serial_bookkeeping_error(primary, base, head)
+            if advance_error:
+                return result(
+                    "block",
+                    reason=f"{status} serial task advanced past its base: {advance_error}",
+                )
             primary_worktree, primary_error = _worktree_report(primary, primary, bound)
             if primary_error:
                 return result("block", reason=primary_error)
@@ -4321,6 +4613,7 @@ def retire(
                             or f"could not delete {branch}"
                         )
                 branch_retired = True
+        release_workspace_quietly(primary)
         return {
             "bound_branch": bound,
             "branch": branch,
@@ -4354,22 +4647,13 @@ def retire(
             raise IsolationError(
                 "worktree is dirty; pass --force only from the retry-retirement path"
             )
-    remove = run_git(
-        primary,
-        "worktree",
-        "remove",
-        *(("--force",) if force else ()),
-        str(resolved_worktree),
-    )
-    if remove.returncode != 0:
-        raise IsolationError(
-            (remove.stderr or remove.stdout).strip() or "git worktree remove failed"
-        )
+    _remove_worktree(primary, resolved_worktree, force)
     deleted = run_git(primary, "branch", "-D", retire_branch)
     if deleted.returncode != 0:
         raise IsolationError(
             (deleted.stderr or deleted.stdout).strip() or f"could not delete {retire_branch}"
         )
+    release_workspace_quietly(primary)
     return {
         "bound_branch": bound,
         "branch": retire_branch,
@@ -4379,6 +4663,54 @@ def retire(
     }
 
 
+def retire_unused_verify(
+    primary: Path, worktree: Path, base: str, branch: str
+) -> Dict[str, object]:
+    """Retire a Verify sidecar only when it is provably untouched since creation."""
+    primary = require_directory(primary, "primary worktree")
+    if worktree_root(primary) != primary:
+        raise IsolationError(f"primary is not its Git root: {primary}")
+    if not branch.startswith(VERIFY_BRANCH_PREFIX):
+        raise IsolationError("unused Verify retirement requires a verify branch")
+    expected = _sidecar_path_for_branch(primary, branch)
+    resolved_worktree = worktree.resolve()
+    if resolved_worktree != expected:
+        raise IsolationError("unused Verify path differs from its branch")
+    expected_base = require_commit(primary, require_full_sha(base))
+
+    if os.path.lexists(worktree):
+        if worktree.is_symlink() or not worktree.is_dir() or worktree.resolve() != worktree:
+            raise IsolationError(f"unused Verify path is not an owned worktree: {worktree}")
+        if worktree_root(worktree) != worktree:
+            raise IsolationError(f"unused Verify path is not its Git root: {worktree}")
+        if common_git_dir(primary) != common_git_dir(worktree):
+            raise IsolationError("unused Verify sidecar belongs to another repository")
+        if require_attached(worktree) != branch:
+            raise IsolationError("unused Verify sidecar branch changed")
+        if current_sha(worktree) != expected_base:
+            raise IsolationError("unused Verify sidecar HEAD changed; preserving it")
+        dirty = git_output(
+            worktree,
+            "status",
+            "--porcelain",
+            "--untracked-files=all",
+            "--ignored=matching",
+        )
+        if dirty:
+            raise IsolationError("unused Verify sidecar has uncommitted files; preserving it")
+    else:
+        branch_head = run_git(
+            primary, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"
+        )
+        if branch_head.returncode == 0 and branch_head.stdout.strip() != expected_base:
+            raise IsolationError("unused Verify branch HEAD changed; preserving it")
+        for registered_path, registered_branch in _registered_worktrees(primary).items():
+            if registered_branch == f"refs/heads/{branch}" and registered_path != expected:
+                raise IsolationError("unused Verify branch is checked out at another path")
+
+    return retire(primary, expected, branch, False)
+
+
 def parser() -> argparse.ArgumentParser:
     argument_parser = argparse.ArgumentParser(description=__doc__)
     subparsers = argument_parser.add_subparsers(dest="command", required=True)