@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/gsd-path-plan/scripts/isolation.py

@@ -11,10 +11,12 @@ from __future__ import annotations
 
 import argparse
 import contextlib
+import functools
 import hashlib
 import io
 import json
 import shlex
+import shutil
 import os
 import re
 import stat
@@ -27,11 +29,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,
@@ -107,6 +104,10 @@ class IsolationError(RuntimeError):
     """Raised when isolation, landing, or retirement cannot proceed."""
 
 
+class RemovalError(IsolationError):
+    """Raised when the removal of a sidecar worktree fails."""
+
+
 run_git = _common.run_git
 
 
@@ -150,7 +151,10 @@ def require_commit(repo: Path, value: str) -> str:
 
 def require_full_sha(value: str) -> str:
     if not re.fullmatch(r"[0-9a-f]{40}", value):
-        raise IsolationError(f"base must be a full 40-character SHA: {value}")
+        raise IsolationError(
+            f"base must be a full 40-character SHA: {value}; "
+            "resolve a ref or a short SHA with git rev-parse first"
+        )
     return value
 
 
@@ -176,6 +180,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 +449,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 +492,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,
@@ -647,6 +722,18 @@ def member_checkout(coordinator: Path, member: str) -> Tuple[Path, str]:
     return checkout, str(role["project"])
 
 
+def member_default_branch(coordinator: Path, member: str) -> str:
+    """The default branch that MEMBERS.md records for a member; a row without it means main."""
+    try:
+        import members
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import members
+    try:
+        return members.member_default_branch(require_directory(coordinator, "coordinator"), member)
+    except members.MembersError as error:
+        raise IsolationError(str(error)) from error
+
+
 def member_bound_checkout(coordinator: Path, member: str) -> Dict[str, object]:
     """Path's own checkout of a locked member's bound branch, outside the team's checkout."""
     checkout, _, entry = _member_context(coordinator, member)
@@ -758,7 +845,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 +853,10 @@ 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")
+        try:
+            _remove_worktree(checkout, destination, force)
+        except IsolationError as error:
+            raise RemovalError(str(error)) from error
     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 +864,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 +1025,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 +1141,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:
@@ -1126,7 +1200,7 @@ def _prove_member_commit(
                              parent, commit).splitlines())
     if not changed:
         return "commit changes nothing"
-    undeclared = sorted(changed - allowed)
+    undeclared = undeclared_paths(repo, parent, changed, allowed)
     if undeclared:
         return "undeclared paths: " + ", ".join(undeclared)
     if git_output(repo, "log", "-1", "--format=%s", commit) != subject:
@@ -1142,7 +1216,7 @@ def _commit_member_source(sidecar: Path, journal: Dict[str, object], allowed: Se
     if pending:
         if current_sha(sidecar) != member_base:
             raise IsolationError("dirty member source HEAD must equal the member base")
-        undeclared = sorted(pending - allowed)
+        undeclared = undeclared_paths(sidecar, member_base, pending, allowed)
         if undeclared:
             raise IsolationError("undeclared paths: " + ", ".join(undeclared))
         git_output(sidecar, "add", "-A", "--", *sorted(pending))
@@ -1411,8 +1485,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 +1519,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 +1609,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",
 })
 
@@ -1536,7 +1694,7 @@ def _commit_pending(
         mode = "-f" if path in forced else "-A"
         added = run_git(repo, "add", mode, "--", path)
         if added.returncode != 0:
-            raise IsolationError(f"could not stage {path}")
+            raise IsolationError(f"could not stage {path}: {added.stderr.strip()}")
     staged = _split_paths(
         git_output(
             repo,
@@ -1555,15 +1713,51 @@ def _commit_pending(
     return current_sha(repo)
 
 
+def undeclared_paths(
+    repo: Path, base: str, paths: Set[str], declared: Set[str]
+) -> list[str]:
+    """Return the sorted paths that the declared entries do not cover.
+
+    An entry covers itself and, as a declared directory, the files below it.
+    An entry that is a file at `base` covers only itself: the task-brief lint
+    rejects a path below a base file.
+    """
+
+    @functools.lru_cache(maxsize=None)
+    def directory(entry: str) -> bool:
+        kind = run_git(repo, "cat-file", "-t", f"{base}:{entry}")
+        return kind.returncode != 0 or kind.stdout.strip() == "tree"
+
+    return sorted(
+        path
+        for path in paths
+        if path not in declared
+        and not any(
+            str(parent) in declared and directory(str(parent))
+            for parent in list(PurePosixPath(path).parents)[:-1]
+        )
+    )
+
+
 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
-    unexpected = sorted(path for path in since_base if path not in allowed)
+    since_base = committed_paths_since(repo, base) | landing
+    unexpected = undeclared_paths(repo, base, since_base, 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 +1777,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}")
+            raise IsolationError(f"could not stage {path}: {added.stderr.strip()}")
     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 +1939,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 +1980,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 +1988,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 +2130,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 +2217,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 +2243,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 +2328,7 @@ def land(
             subject,
             relative_posix(task_file),
             allowed,
+            BOOKKEEPING_PATHS,
         )
         return {
             "bound_branch": bound,
@@ -2333,7 +2623,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
@@ -2378,7 +2668,7 @@ def _prove_task_commit(
     )
     if task_file not in changed:
         return None, "commit does not touch the task file"
-    stray = sorted(changed - contract_paths)
+    stray = undeclared_paths(repo, base, changed, contract_paths)
     if stray:
         return None, f"commit touches undeclared paths: {', '.join(stray)}"
     if landing_error:
@@ -2470,6 +2760,56 @@ def _task_branch_proof_error(
     return None
 
 
+def only_missing_files(worktree: Path) -> bool:
+    """True when the only difference of a worktree from its HEAD is tracked files that are missing.
+
+    An untracked or a gitignored file is content that Git does not have, so it makes this False.
+    """
+    status = run_git(worktree, "status", "--porcelain", "--untracked-files=all", "--ignored=matching")
+    lines = status.stdout.splitlines()
+    return status.returncode == 0 and bool(lines) and all(line.startswith(" D") for line in lines)
+
+
+def holds_only_landed_files(repo: Path, path: Path, commits: Sequence[str]) -> bool:
+    """True when `path` is a directory, not a usable worktree, that holds only files of `commits`.
+
+    Each file must be the same blob at the same path in one of the commits, so the removal of
+    the directory loses nothing that Git does not have. A check that cannot be done is False.
+    """
+
+    def unreadable(error: OSError) -> None:
+        raise error
+
+    try:
+        if path.is_symlink() or not path.is_dir() or path.resolve() != path:
+            return False
+        root = run_git(path, "rev-parse", "--show-toplevel")
+        if root.returncode == 0 and Path(root.stdout.strip()).resolve() == path:
+            return False
+        files = []
+        for folder, folders, names in os.walk(path, onerror=unreadable):
+            if any(os.path.islink(os.path.join(folder, name)) for name in folders):
+                return False
+            files += [os.path.join(folder, name) for name in names]
+        # What a removal left of the worktree link is not content.
+        files = [name for name in files if name != str(path / ".git")]
+        if not all(stat.S_ISREG(os.lstat(name).st_mode) for name in files):
+            return False
+        known = {
+            entry.split(" ", 2)[2]
+            for commit in commits
+            for entry in git_text(repo, "ls-tree", "-r", "-z", commit).split("\0")
+            if entry
+        }
+        hashed = run_git(repo, "hash-object", "--stdin-paths", input="".join(f"{name}\n" for name in files))
+    except (OSError, IsolationError):
+        return False
+    hashes = hashed.stdout.split()
+    return hashed.returncode == 0 and len(hashes) == len(files) and all(
+        f"{sha}\t{Path(name).relative_to(path).as_posix()}" in known for sha, name in zip(hashes, files)
+    )
+
+
 def _worktree_report(
     primary: Path, path: Path, expected_branch: str
 ) -> tuple[Optional[Dict[str, object]], Optional[str]]:
@@ -2556,6 +2896,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})"
@@ -2669,6 +3043,7 @@ def _recover_task(
     head: str,
     bound: str,
     canonical_task_file: Optional[str] = None,
+    inspect_isolate: bool = True,
 ) -> Dict[str, object]:
     task_file = canonical_task_file or relative_posix(str(path.relative_to(primary)))
     report: Dict[str, object] = {"task": task_file}
@@ -2676,6 +3051,11 @@ def _recover_task(
     def result(verdict: str, **extra: object) -> Dict[str, object]:
         return {**report, "verdict": verdict, **extra}
 
+    def leftover(commit: object, base: object) -> Dict[str, object]:
+        # The landing is proven, so this block names only what is left to remove.
+        return result("block", reason=f"task landed at {commit}; remove its leftover isolate: {sidecar}",
+                      commit=commit, base=base, leftover=str(sidecar))
+
     try:
         task_text, _ = _read_task_text(path)
     except IsolationError as error:
@@ -2702,14 +3082,22 @@ def _recover_task(
         return result(**_prove_member_task(primary, task_file, fields, subject, history))
     task_branch = task_branch_name(task_id)
     branch_exists = task_branch in branches
-    worktree, worktree_error = _worktree_report(
-        primary, sidecar_root(primary, "task", task_id), task_branch
+    sidecar = sidecar_root(primary, "task", task_id)
+    worktree, worktree_error = (
+        _worktree_report(primary, sidecar, task_branch) if inspect_isolate else (None, None)
     )
     report["worktree"] = worktree
     report["task_branch"] = task_branch if branch_exists else None
     report["rejected"] = []
 
     if worktree_error:
+        landed = _recover_task(
+            primary, path, history, branches, head, bound, canonical_task_file, False
+        ) if status == "done" else {}
+        if landed.get("verdict") == "recovered" and holds_only_landed_files(
+            primary, sidecar, [str(landed["commit"]), *([task_branch] if branch_exists else [])]
+        ):
+            return leftover(landed["commit"], landed["base"])
         return result("block", reason=worktree_error)
 
     valid_statuses = {"pending", "in-progress", "done", "failed", "blocked"}
@@ -2845,8 +3233,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 +3252,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 +3289,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)
@@ -2946,6 +3351,9 @@ def _recover_task(
             if branch_error:
                 return result("block", reason=branch_error)
         if worktree is not None and not bool(worktree["clean"]):
+            if only_missing_files(sidecar):
+                # Only landed files are missing: a removal stopped part way, and nothing unknown is there.
+                return leftover(commit, base)
             return result(
                 "block",
                 reason="proven task retains a dirty worktree",
@@ -3511,7 +3919,11 @@ def _attest_body_fields(body: str) -> tuple[Dict[str, str], list[str]]:
 
 
 def _attested_changes(repo: Path, base: str, head: str, declared: Set[str]) -> list[str]:
-    """Declared paths that changed between base and head, matched literally like land."""
+    """Declared paths that changed between base and head, matched literally.
+
+    Land also accepts files below a declared directory. Attestation does not:
+    a recorded attestation body must stay provable.
+    """
     changed = set(git_output(repo, "diff", "--name-only", base, head).splitlines())
     return sorted(changed & declared)
 
@@ -4321,6 +4733,7 @@ def retire(
                             or f"could not delete {branch}"
                         )
                 branch_retired = True
+        release_workspace_quietly(primary)
         return {
             "bound_branch": bound,
             "branch": branch,
@@ -4354,22 +4767,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 +4783,71 @@ 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 retire_stale_verify(primary: Path, worktree: Path, branch: str) -> Dict[str, object]:
+    """Retire the Verify sidecar of an earlier prepare-task only when it is proven untouched.
+
+    The reflog of its branch is the record of its creation base. It must hold only the
+    creation, at a commit of the bound branch; `retire_unused_verify` then proves the checkout.
+    """
+    try:
+        created = git_output(primary, "reflog", "show", "--format=%H", f"refs/heads/{branch}").split()
+        if len(created) != 1:
+            raise IsolationError("its branch moved after its creation, or has no record of its creation")
+        if run_git(primary, "merge-base", "--is-ancestor", created[0], "HEAD").returncode != 0:
+            raise IsolationError("its branch is not at a commit of the bound branch")
+        return retire_unused_verify(primary, worktree, created[0], branch)
+    except IsolationError as error:
+        raise IsolationError(f"Verify sidecar {worktree} is kept: {error}") from error
+
+
 def parser() -> argparse.ArgumentParser:
     argument_parser = argparse.ArgumentParser(description=__doc__)
     subparsers = argument_parser.add_subparsers(dest="command", required=True)