@opengsd/gsd-path 1.5.0 → 1.6.1

package/scripts/isolation.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import argparse
 import contextlib
+import functools
 import hashlib
 import io
 import json
@@ -103,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
 
 
@@ -146,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
 
 
@@ -714,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)
@@ -833,7 +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}")
-        _remove_worktree(checkout, destination, force)
+        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")
@@ -1177,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:
@@ -1193,12 +1216,20 @@ 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))
         body = member_commit_body(str(journal["task_file"]), sorted(pending), member_base, str(journal["base"]))
-        git_output(sidecar, "commit", "-q", "-m", str(journal["subject"]), "-m", body.strip())
+        # The paths and the body grow with the change set, so both go through
+        # stdin: a Windows command line holds about 32 KiB.
+        for arguments, text in (
+            (("add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"),
+             "".join(f"{path}\0" for path in sorted(pending))),
+            (("commit", "-q", "-F", "-"), _commit_message(str(journal["subject"]), body)),
+        ):
+            result = run_git(sidecar, *arguments, input=text)
+            if result.returncode != 0:
+                raise IsolationError((result.stderr or result.stdout).strip() or "git command failed")
     source = current_sha(sidecar)
     if source == member_base:
         raise IsolationError("no changes to land")
@@ -1646,6 +1677,25 @@ def committed_paths_since(repo: Path, base: str) -> Set[str]:
     )
 
 
+def _stage_paths(repo: Path, mode: str, paths: Set[str]) -> None:
+    """Stage `paths` with one `git add`.
+
+    One call for each path fails when a file replaces a tracked directory: the
+    first call drops the files below the directory from the index, and then
+    their pathspecs match no file. The `./` prefix stops pathspec magic, so a
+    name such as `:!b` cannot exclude another path of the set. Git names the
+    path in its error text.
+    """
+    if not paths:
+        return
+    added = run_git(
+        repo, "add", mode, "--pathspec-from-file=-", "--pathspec-file-nul",
+        input="".join(f"./{path}\0" for path in sorted(paths)),
+    )
+    if added.returncode != 0:
+        raise IsolationError(f"could not stage the change set: {added.stderr.strip()}")
+
+
 def ignored_legacy_ledger(repo: Path) -> bool:
     """True when a verify ledger absent from HEAD is hidden by an ignore rule.
 
@@ -1661,17 +1711,25 @@ def ignored_legacy_ledger(repo: Path) -> bool:
     return run_git(repo, "check-ignore", "-q", "--no-index", "--", VERIFY_LEDGER_PATH).returncode == 0
 
 
+def _commit_message(subject: str, body: str) -> str:
+    """The message for `git commit -F -`.
+
+    A landing body lists every changed path. As a `-m` argument it can exceed
+    the Windows command-line limit, so the message goes through stdin. Like
+    `-m`, the message ends its last line.
+    """
+    message = f"{subject}\n\n{body}"
+    return message if message.endswith("\n") else message + "\n"
+
+
 def _commit_pending(
     repo: Path, pending: Set[str], subject: str, body: str, forced: Set[str] = frozenset()
 ) -> str:
     reset = run_git(repo, "reset", "-q", "HEAD")
     if reset.returncode != 0:
         raise IsolationError("could not clear the index before commit")
-    for path in sorted(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}")
+    _stage_paths(repo, "-A", pending - forced)
+    _stage_paths(repo, "-f", pending & forced)
     staged = _split_paths(
         git_output(
             repo,
@@ -1684,12 +1742,38 @@ def _commit_pending(
     )
     if staged != pending:
         raise IsolationError("staged paths do not match the uncommitted change set")
-    committed = run_git(repo, "commit", "-q", "-m", subject, "-m", body)
+    committed = run_git(repo, "commit", "-q", "-F", "-", input=_commit_message(subject, body))
     if committed.returncode != 0:
         raise IsolationError((committed.stderr or committed.stdout).strip() or "commit failed")
     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,
@@ -1703,7 +1787,7 @@ def validate_allowed_changes(
     if not landing:
         raise IsolationError("no changes to land")
     since_base = committed_paths_since(repo, base) | landing
-    unexpected = sorted(path for path in since_base if path not in allowed)
+    unexpected = undeclared_paths(repo, base, since_base, allowed)
     if unexpected:
         raise IsolationError(
             "unexpected paths: " + ", ".join(unexpected)
@@ -1737,18 +1821,15 @@ def commit_allowed_changes(
     reset = run_git(repo, "reset", "-q", "HEAD")
     if reset.returncode != 0:
         raise IsolationError("could not clear the index before landing")
-    for path in sorted(staging):
-        added = run_git(repo, "add", "-A", "--", path)
-        if added.returncode != 0:
-            raise IsolationError(f"could not stage {path}")
+    _stage_paths(repo, "-A", staging)
     staged = _split_paths(
-        git_output(repo, "diff", "--cached", "--name-only", "--relative")
+        git_output(repo, "diff", "--no-renames", "--cached", "--name-only", "--relative")
     )
     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)
-    committed = run_git(repo, "commit", "-q", "-m", subject, "-m", body)
+    committed = run_git(repo, "commit", "-q", "-F", "-", input=_commit_message(subject, body))
     if committed.returncode != 0:
         raise IsolationError(
             (committed.stderr or committed.stdout).strip() or "commit failed"
@@ -2619,7 +2700,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:
@@ -2711,6 +2792,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]]:
@@ -2944,6 +3075,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}
@@ -2951,6 +3083,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:
@@ -2977,14 +3114,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"}
@@ -3238,6 +3383,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",
@@ -3803,7 +3951,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)
 
@@ -4711,6 +4863,23 @@ def retire_unused_verify(
     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)

package/scripts/members.py

@@ -35,6 +35,8 @@ MARKER_SCHEMA = "gsd-path/member/v1"
 MARKER_KEYS = {"schema", "coordinator", "project", "name"}
 NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 FIELDS = ("Checkout", "Remote", "Integration")
+# Optional: `add` records it one time; a row without it means main.
+DEFAULT_BRANCH_FIELD = "Default branch"
 INTEGRATIONS = ("default", "direct", "pull-request")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([^/\s]+)/([^/\s]+)"
@@ -221,9 +223,10 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
         if not line.strip():
             continue
         key, separator, value = line.partition(":")
-        if not separator or key not in FIELDS or key.lower() in current:
+        field = key.lower().replace(" ", "_")
+        if not separator or key not in (*FIELDS, DEFAULT_BRANCH_FIELD) or field in current:
             raise MembersError(f"MEMBERS.md line {number}: unexpected line {line!r}")
-        current[key.lower()] = value.strip()
+        current[field] = value.strip()
     if not preamble or preamble[0] != "# Members":
         raise MembersError("MEMBERS.md format error: expected # Members")
     rest = preamble[1:]
@@ -247,17 +250,37 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
             )
         if not Path(member["checkout"]).is_absolute():
             raise MembersError(f"MEMBERS.md member {member['name']} Checkout must be absolute")
+        if not _common.valid_default_branch(default_branch(member)):
+            raise MembersError(
+                f"MEMBERS.md member {member['name']} has invalid Default branch: {member['default_branch']}"
+            )
     return members
 
 
+def default_branch(member: dict[str, str]) -> str:
+    """The default branch a MEMBERS.md row records; a row without the field means main."""
+    return member.get("default_branch", "main")
+
+
+def member_default_branch(coordinator: Path, name: str) -> str:
+    """The default branch MEMBERS.md records for the member `name`."""
+    for member in read_members(coordinator):
+        if member["name"] == name:
+            return default_branch(member)
+    raise MembersError(f"member {name} is not in MEMBERS.md")
+
+
 def check_member(
     coordinator: Path,
     coordinator_name: str,
     checkout: Path,
-    recorded_remote: Optional[str] = None,
+    recorded: Optional[dict[str, str]] = None,
     refuse_reserved_refs: bool = True,
-) -> str:
-    """Refuse a checkout that cannot join; return its origin URL."""
+) -> tuple[str, str]:
+    """Refuse a checkout that cannot join; return its origin URL and default branch.
+
+    `recorded` is the member's MEMBERS.md row. Without it (`add`), the default
+    branch is the local origin/HEAD, read this one time; an unset ref means main."""
     if checkout.is_symlink() or not checkout.is_dir():
         raise MembersError(f"member checkout is not a real directory: {checkout}")
     checkout = checkout.resolve()
@@ -279,12 +302,21 @@ def check_member(
     remote = _git(checkout, "config", "--get", "remote.origin.url")
     if not GITHUB_REMOTE_RE.fullmatch(remote):
         raise MembersError(f"member requires a GitHub.com origin: {remote}")
-    if recorded_remote is not None and remote != recorded_remote:
-        raise MembersError(f"member origin changed: {recorded_remote} -> {remote}")
-    default = _common.run_git(checkout, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
-    if default.returncode != 0 or default.stdout.strip() != "origin/main":
-        raise MembersError(f"member remote default must be main: {checkout}")
-    require_origin_main(checkout)
+    if recorded is not None and remote != recorded["remote"]:
+        raise MembersError(f"member origin changed: {recorded['remote']} -> {remote}")
+    live = _common.origin_default_branch(checkout)
+    default = live if recorded is None else default_branch(recorded)
+    if live != default:
+        raise MembersError(
+            f"member remote default must be {default}, got {live}: {checkout}; "
+            "run `git remote set-head origin --auto` when the local origin/HEAD is stale"
+        )
+    if not _common.valid_default_branch(default):
+        raise MembersError(
+            f"member default branch {default!r} cannot be recorded in MEMBERS.md: it is a "
+            "GSD Path reserved name or it has a character that the file cannot hold"
+        )
+    require_origin_branch(checkout, default)
     member_state = checkout / ".project" / "STATE.md"
     if member_state.exists() or member_state.is_symlink():
         if member_state.is_symlink() or not member_state.is_file():
@@ -303,7 +335,7 @@ def check_member(
         colliding = [ref for ref in refs if ref.startswith(prefixes)]
         if colliding:
             raise MembersError("member refs collide with coordinator names: " + ", ".join(colliding))
-    return remote
+    return remote, default
 
 
 MEMBER_CLOSE_SCHEMA = "gsd-path/member-close/v1"
@@ -338,12 +370,14 @@ def write_member_close(common: Path, archive_name: str, rows: list[dict]) -> Non
     _common.atomic_write(path, json.dumps({"schema": MEMBER_CLOSE_SCHEMA, "members": rows}, indent=2) + "\n")
 
 
-def require_origin_main(checkout: Path) -> None:
+def require_origin_branch(checkout: Path, branch: str) -> str:
+    """The commit of the member's fetched default branch `branch`."""
     baseline = _common.run_git(
-        checkout, "rev-parse", "--verify", "--quiet", "refs/remotes/origin/main^{commit}"
+        checkout, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{branch}^{{commit}}"
     )
     if baseline.returncode != 0:
-        raise MembersError("member requires refs/remotes/origin/main; run git fetch origin")
+        raise MembersError(f"member requires refs/remotes/origin/{branch}; run git fetch origin")
+    return baseline.stdout.strip()
 
 
 def member_ref_prefixes(project: str) -> tuple[str, ...]:
@@ -405,7 +439,8 @@ def _task_members(coordinator: Path) -> set[str]:
 
 def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
     """At build start, lock the members tasks name (MEMBERS.md order) and create
-    each member's bound branch at its origin/main. None when no task names a member."""
+    each member's bound branch at its recorded default branch on origin. None when
+    no task names a member."""
     root, state = _coordinator(coordinator)
     named = _task_members(root)
     lock_path = root / LOCK_PATH
@@ -444,8 +479,8 @@ def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
         remote = _git(checkout, "config", "--get", "remote.origin.url")
         if remote != member["remote"]:
             raise MembersError(f"member origin changed: {member['remote']} -> {remote}")
-        require_origin_main(checkout)
-        base = _git(checkout, "rev-parse", "refs/remotes/origin/main^{commit}")
+        default = default_branch(member)
+        base = require_origin_branch(checkout, default)
         existing = _common.run_git(checkout, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
         if existing.returncode == 0:
             tip = existing.stdout.strip()
@@ -458,7 +493,7 @@ def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
             elif _common.run_git(checkout, "merge-base", "--is-ancestor", tip, base).returncode == 0:
                 base = tip
             else:
-                raise MembersError(f"member {member['name']} branch {branch} has commits not on origin/main")
+                raise MembersError(f"member {member['name']} branch {branch} has commits not on origin/{default}")
         else:
             missing.append((checkout, base))
         entries.append({"name": member["name"], "branch": branch, "base": base})
@@ -475,6 +510,8 @@ def render(members: Sequence[dict[str, str]]) -> str:
         f"Checkout: {member['checkout']}\n"
         f"Remote: {member['remote']}\n"
         f"Integration: {member['integration']}\n"
+        # A row that never had the field keeps none, so old rows are not rewritten.
+        + (f"{DEFAULT_BRANCH_FIELD}: {member['default_branch']}\n" if "default_branch" in member else "")
         for member in members
     ]
     return "\n".join([HEADER, *sections])
@@ -488,7 +525,7 @@ def add_member(repo: Path, name: str, checkout: Path, integration: str) -> list[
         raise MembersError(f"invalid member name: {name!r}")
     members = read_members(root)
     resolved = checkout.resolve()
-    remote = check_member(root, state.project, checkout)
+    remote, default = check_member(root, state.project, checkout)
     common = Path(_git(resolved, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve()
     identity = _remote_identity(remote)
     for member in members:
@@ -499,7 +536,8 @@ def add_member(repo: Path, name: str, checkout: Path, integration: str) -> list[
             raise MembersError(f"member already recorded: {member['name']}")
     _refuse_foreign_marker(resolved, root, state.project, name)
     members.append(
-        {"name": name, "checkout": str(resolved), "remote": remote, "integration": integration}
+        {"name": name, "checkout": str(resolved), "remote": remote, "integration": integration,
+         "default_branch": default}
     )
     _write_marker(resolved, root, state.project, name)
     _common.atomic_write(root / ".project" / MEMBERS_FILE, render(members))
@@ -560,8 +598,9 @@ def create_member(repo: Path, name: str, checkout: Path, integration: str, githu
         _common.atomic_write(journal, json.dumps(recorded, indent=2, sort_keys=True) + "\n")
     listed = [member for member in read_members(root) if member["name"] == name]
     if listed:
-        if (len(listed) != 1 or listed[0] != {"name": name, "checkout": str(resolved), "remote": url,
-                                            "integration": integration}
+        if (len(listed) != 1 or {**listed[0], "default_branch": default_branch(listed[0])} != {
+                    "name": name, "checkout": str(resolved), "remote": url,
+                    "integration": integration, "default_branch": "main"}
                 or member_role(resolved) != {"coordinator": root, "project": state.project, "name": name}):
             raise MembersError(f"member already recorded with a different checkout or marker: {name}")
         journal.unlink()
@@ -610,6 +649,10 @@ def create_member(repo: Path, name: str, checkout: Path, integration: str, githu
         cloned = _common.run_git(resolved.parent, "clone", "-q", url, str(resolved))
         if cloned.returncode != 0:
             raise MembersError(f"could not clone {url}: {(cloned.stderr or cloned.stdout).strip()}")
+    # ponytail: --create stays main-only, because a new repository uses main;
+    # `add` joins an existing repository with any default branch.
+    if _common.origin_default_branch(resolved) != "main":
+        raise MembersError(f"member remote default must be main: {resolved}")
     recorded["step"] = "join"
     _common.atomic_write(journal, json.dumps(recorded, indent=2, sort_keys=True) + "\n")
     joined = add_member(root, name, resolved, integration)
@@ -622,7 +665,7 @@ def validate_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"], refuse_reserved_refs=False)
+        check_member(root, state.project, checkout, member, refuse_reserved_refs=False)
         try:
             role = member_role(checkout)
         except MembersError as error:
@@ -641,7 +684,7 @@ def repair_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"], refuse_reserved_refs=False)
+        check_member(root, state.project, checkout, member, refuse_reserved_refs=False)
         _refuse_foreign_marker(checkout.resolve(), root, state.project, member["name"])
     for member in members:
         checkout = Path(member["checkout"]).resolve()

package/scripts/migrate_core.py

@@ -10,6 +10,8 @@ import shutil
 import stat
 import sys
 
+import _common
+
 
 def hook_inventory(settings):
     if settings.is_symlink() or not settings.is_file():

package/scripts/model_policy.py

@@ -196,16 +196,27 @@ def task_settings(path):
 
 def native_record(args):
     """The parent owns lifecycle; release requires its recorded terminal-result receipt."""
+    # A relative path would resolve against cwd, which may be the immutable runtime store.
+    if not args.record.is_absolute():
+        raise PolicyError(f'--record must be an absolute path: {args.record}')
     record = args.record.resolve()
+    missing = f'release requires an existing record and terminal-result evidence: {record}'
+    # Check before log_lock creates the record directory and its lock file.
+    if args.action == 'release' and not record.exists():
+        raise PolicyError(missing)
     with log_lock({'log': str(record)}):
         data = read_json(record) if record.exists() else None
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
                     'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
         if data is not None and data.get('identity') != identity:
-            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+            recorded = data.get('identity')
+            recorded = recorded if isinstance(recorded, dict) else {}
+            differing = ', '.join(f'{field}: {value}, record has {recorded.get(field)}'
+                                  for field, value in identity.items() if recorded.get(field) != value)
+            raise PolicyError(f'record belongs to another assignment or milestone/track/cycle ({differing})')
         if args.action == 'release':
             if data is None or not args.terminal_result:
-                raise PolicyError('release requires an existing record and terminal-result evidence')
+                raise PolicyError(missing)
             data.update(active=False, terminal_result=args.terminal_result)
         else:
             if args.capabilities is None: