@opengsd/gsd-path 1.4.0 → 1.5.0

package/skills/gsd-path-forensics/scripts/_common.py

@@ -65,6 +65,49 @@ VERIFY_RESULTS = ("pass", "fail")
 VERIFY_LEDGER_SCHEMA = "gsd-path/verify-ledger/v2"
 VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
 
+REVIEW_BULLET_HEADING_PATTERN = re.compile(r"^#{2,3} ")
+REVIEW_BULLET_FIELD_LABEL_PATTERN = re.compile(r"^- \*\*[^*]+\*\*:")
+
+
+def review_bullet_field_label_pattern(field: str) -> re.Pattern[str]:
+    return re.compile(rf"^- \*\*{re.escape(field)}\*\*:[ \t]*(.*)$")
+
+
+def _review_bullet_field_value(lines: Sequence[str], index: int, inline: str) -> str:
+    if inline:
+        return inline
+    collected: list[str] = []
+    for line in lines[index + 1 :]:
+        if REVIEW_BULLET_FIELD_LABEL_PATTERN.match(line) or REVIEW_BULLET_HEADING_PATTERN.match(
+            line
+        ):
+            break
+        if line and not line[0].isspace():
+            break
+        stripped = line.strip()
+        if stripped:
+            collected.append(stripped)
+    return "\n".join(collected)
+
+
+def find_review_bullet_field_values(lines: Sequence[str], field: str) -> list[str]:
+    pattern = review_bullet_field_label_pattern(field)
+    values: list[str] = []
+    for index, line in enumerate(lines):
+        match = pattern.fullmatch(line)
+        if match is None:
+            continue
+        values.append(_review_bullet_field_value(lines, index, match.group(1)))
+    return values
+
+
+def parse_review_bullet_field(lines: Sequence[str], field: str) -> str:
+    """Parse one `- **Field**:` review bullet, including indented continuations."""
+    values = find_review_bullet_field_values(lines, field)
+    if len(values) != 1:
+        raise ValueError(field)
+    return values[0]
+
 
 # Sample paths the pipeline must commit. A product rule such as an unanchored
 # `build/` would otherwise drop them silently from every commit.
@@ -150,6 +193,11 @@ def verify_ledger_entries(path: Path) -> list:
     return parse_verify_ledger(path.read_text(encoding="utf-8"))
 
 
+def read_user_text(path: Path) -> str:
+    """Read a user-edited text file with CRLF normalized to LF."""
+    return path.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
+
+
 def parse_verify_ledger(text: str) -> list:
     entries = []
     for number, line in enumerate(text.splitlines(), start=1):
@@ -204,7 +252,43 @@ def run_command(
 def run_git(
     repo: Path, *arguments: str, input: Optional[str] = None
 ) -> subprocess.CompletedProcess[str]:
-    return _run_exact(("git", "-C", str(repo), *arguments), input=input)
+    return _run_exact(git_command(repo, *arguments), input=input)
+
+
+def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
+    """Git argv for repo, including WSL drvfs workarounds when needed."""
+    return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)
+
+
+def git_drvfs_config_flags(repo: Path) -> tuple[str, ...]:
+    """Disable index preload on 9p/drvfs mounts where git commit races on index.lock (#207)."""
+    if os.name != "posix":
+        return ()
+    try:
+        root = repo.resolve()
+        mounts = Path("/proc/mounts").read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ()
+    best = ""
+    fstype = ""
+    for line in mounts:
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        mount_point, mount_type = parts[1], parts[2]
+        if mount_type not in {"9p", "drvfs"}:
+            continue
+        if root == Path(mount_point) or root.is_relative_to(mount_point):
+            if len(mount_point) >= len(best):
+                best, fstype = mount_point, mount_type
+    if not fstype:
+        return ()
+    return ("-c", "core.preloadindex=false", "-c", "index.threads=1")
+
+
+def git_index_lock_retryable(stderr: str) -> bool:
+    text = stderr.casefold()
+    return "index.lock" in text and "file exists" in text
 
 
 # OS files that are never pipeline artifacts when git ignores them.
@@ -227,6 +311,70 @@ def git_visible_entries(directory: Path) -> set:
     return {path.split("/", 1)[0] for path in result.stdout.split("\0") if path}
 
 
+RUNTIME_PIN_PATH = ".gsd-path/runtime.json"
+RUNTIME_PIN_ALLOWANCE = (
+    "only runtime-pin commits (.gsd-path/runtime.json) may follow the reviewed HEAD"
+)
+
+
+def reviewed_head_covers(repo: Path, reviewed: str, head: str) -> bool:
+    """True when a review of `reviewed` still covers `head`.
+
+    That is the same commit, or `reviewed` is an ancestor of `head` and every
+    commit on the first-parent path in ``reviewed..head`` is a non-merge commit
+    whose only change is ``.gsd-path/runtime.json``. An empty commit does not
+    qualify. Any other path, any merge commit, an unresolvable SHA, or a
+    non-ancestor returns False.
+    """
+    if not reviewed or not head:
+        return False
+    resolved_repo = Path(repo)
+    resolved: List[str] = []
+    for value in (reviewed, head):
+        result = run_git(
+            resolved_repo, "rev-parse", "--verify", "--quiet", f"{value}^{{commit}}"
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return False
+        resolved.append(result.stdout.strip())
+    reviewed_sha, head_sha = resolved
+    if reviewed_sha == head_sha:
+        return True
+    if (
+        run_git(resolved_repo, "merge-base", "--is-ancestor", reviewed_sha, head_sha).returncode
+        != 0
+    ):
+        return False
+    listing = run_git(
+        resolved_repo,
+        "rev-list",
+        "--first-parent",
+        "--parents",
+        f"{reviewed_sha}..{head_sha}",
+    )
+    if listing.returncode != 0:
+        return False
+    for line in listing.stdout.splitlines():
+        fields = line.split()
+        if len(fields) != 2:
+            return False
+        commit_sha, parent_sha = fields[0], fields[1]
+        changed = run_git(
+            resolved_repo,
+            "diff",
+            "--name-only",
+            "--no-renames",
+            "--no-ext-diff",
+            parent_sha,
+            commit_sha,
+        )
+        if changed.returncode != 0:
+            return False
+        if {path for path in changed.stdout.splitlines() if path} != {RUNTIME_PIN_PATH}:
+            return False
+    return True
+
+
 def atomic_replace(path: Path, temporary_path: Path, content: str) -> None:
     temporary_path.parent.mkdir(parents=True, exist_ok=True)
     descriptor = None

package/skills/gsd-path-forensics/scripts/loop_run.py

@@ -514,16 +514,28 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
     """Run one spec command; a hung command counts as failed (exit None).
 
     POSIX runs /bin/sh as shell=True did; Windows runs Git for Windows bash, not
-    cmd.exe. A timeout kills the whole process group, so a grandchild cannot
-    keep the output pipes open.
+    cmd.exe. A timeout kills the whole process group when possible; if output
+    pipes stay open, drain them with a short grace timeout and then close them.
     """
     argv = _common.bash_argv(command) if os.name == "nt" else ["/bin/sh", "-c", command]
     process = _common.popen_group(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdout = b""
+    stderr = b""
     try:
         stdout, stderr = process.communicate(timeout=timeout)
-    except subprocess.TimeoutExpired:
+    except subprocess.TimeoutExpired as expired:
         _common.kill_tree(process)
-        stdout, stderr = process.communicate()
+        try:
+            stdout, stderr = process.communicate(timeout=5)
+        except subprocess.TimeoutExpired as drained:
+            stdout = drained.stdout or expired.stdout or b""
+            stderr = drained.stderr or expired.stderr or b""
+            if process.stdout:
+                process.stdout.close()
+            if process.stderr:
+                process.stderr.close()
+            process.kill()
+            process.wait(timeout=5)
         output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")
         return None, f"{output}\ntimed out at the admitted wall-clock deadline"
     return process.returncode, (stdout + stderr).decode("utf-8", errors="replace")

package/skills/gsd-path-forensics/scripts/path_config.py

@@ -13,7 +13,7 @@ sys.dont_write_bytecode = True
 ROLES = ('coder', 'reviewer', 'review_panel', 'skeptic', 'inspect_codebase',
          'inspect_docs', 'docs_audit', 'research', 'decide', 'roadmap', 'plan', 'plan_patch')
 HOSTS = ('codex', 'claude', 'grok', 'opencode', 'copilot', 'qwen', 'antigravity',
-         'cursor', 'zed', 'kiro', 'kimi')
+         'cursor', 'zed', 'kiro', 'kimi', 'muse')
 
 
 def sibling(name):
@@ -73,8 +73,8 @@ def validate_value(key, value):
     if not isinstance(value, str) or not value or value != value.strip():
         raise ValueError(f'{key} requires a nonempty string')
     if key == 'integration':
-        if value not in ('direct', 'pull-request'):
-            raise ValueError('integration must be direct or pull-request')
+        if value not in ('direct', 'pull-request', 'external-landing'):
+            raise ValueError('integration must be direct, pull-request, or external-landing')
     elif key == 'review_panel':
         if any(char.isspace() for char in value):
             raise ValueError('use off, detected, or comma-separated families without spaces')

package/skills/gsd-path-forensics/scripts/pipeline_undo.py

@@ -17,6 +17,7 @@ import os
 import re
 import shutil
 import sys
+from datetime import date
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -106,6 +107,16 @@ KINDS = ("checkpoint", "task", "member-task", "uncommitted-archive", "lookahead"
 PROMOTION_PREFIX = "router: promote lookahead milestone "
 ABANDON_PREFIX = "build: abandon milestone "
 INTEGRATE_PREFIX = "integrate: "
+SHIP_LOG_ONLY_LINE = re.compile(
+    r"- (?P<date>\d{4}-\d{2}-\d{2}) — ship — (?P<event>[^\r\n]+)\n\Z"
+)
+SHIPMENT_RECORD_LINE = re.compile(
+    r"- (?P<date>\d{4}-\d{2}-\d{2}) — shipped — (?P<event>[^\r\n]+)\n\Z"
+)
+SHIPMENT_EVENTS = {
+    "archive preflight passed; shipment recorded",
+    "archive preflight passed; shipment recorded; program complete",
+}
 
 
 class UndoError(RuntimeError):
@@ -375,6 +386,80 @@ def pending_transaction(repo: Path) -> Optional[dict[str, object]]:
         raise UndoError(str(error)) from error
 
 
+def _valid_state_event_line(line: str, phase: str) -> bool:
+    pattern = SHIP_LOG_ONLY_LINE if phase == "ship" else SHIPMENT_RECORD_LINE
+    match = pattern.fullmatch(line)
+    if match is None:
+        return False
+    try:
+        event_date = date.fromisoformat(match.group("date"))
+    except ValueError:
+        return False
+    event = match.group("event")
+    return event_date.isoformat() == match.group("date") and event == " ".join(event.split())
+
+
+def _owned_ship_log_events(
+    prepared_state: str,
+    current_state: str,
+    phase: object,
+    status: object,
+) -> Optional[str]:
+    """Return only ship log lines appended around a helper-owned archive event.
+
+    The prepared text must remain byte-for-byte unchanged. For shipped/done,
+    record-shipment changes only phase and status before appending its one
+    generated shipment event, so validate that exact prefix and event shape.
+    """
+    if (phase, status) == ("ship", "active"):
+        if current_state == prepared_state:
+            return ""
+        if not current_state.startswith(prepared_state):
+            return None
+        suffix = current_state[len(prepared_state):]
+        separator = "" if prepared_state.endswith("\n") else "\n"
+        if separator:
+            if not suffix.startswith(separator):
+                return None
+            suffix = suffix[len(separator):]
+        lines = suffix.splitlines(keepends=True)
+        if not lines or "".join(lines) != suffix:
+            return None
+        if not all(_valid_state_event_line(line, "ship") for line in lines):
+            return None
+        return separator + suffix
+
+    if (phase, status) != ("shipped", "done"):
+        return None
+    try:
+        shipped_prefix = pipeline_state._set_frontmatter(
+            prepared_state,
+            {"phase": "shipped", "status": "done"},
+        )
+    except PipelineStateError:
+        return None
+    if not current_state.startswith(shipped_prefix):
+        return None
+    suffix = current_state[len(shipped_prefix):]
+    separator = "" if shipped_prefix.endswith("\n") else "\n"
+    if separator:
+        if not suffix.startswith(separator):
+            return None
+        suffix = suffix[len(separator):]
+    lines = suffix.splitlines(keepends=True)
+    if not lines or "".join(lines) != suffix:
+        return None
+    shipment_event = lines[-1]
+    if not _valid_state_event_line(shipment_event, "shipped"):
+        return None
+    if SHIPMENT_RECORD_LINE.fullmatch(shipment_event).group("event") not in SHIPMENT_EVENTS:
+        return None
+    ship_events = lines[:-1]
+    if not all(_valid_state_event_line(line, "ship") for line in ship_events):
+        return None
+    return separator + "".join(ship_events) if ship_events else ""
+
+
 def _archive_metadata_error(
     repo: Path,
     state_fields: dict[str, object],
@@ -420,8 +505,13 @@ def _archive_metadata_error(
         if final_review.exists() or gap_reviews:
             reviewed_head, _ = archive_milestone.parse_final_review(archive_path)
             archive_milestone.validate_gap_reviews(archive_path, reviewed_head)
-            if reviewed_head != _optional_rev(repo, "HEAD"):
-                return "archive undo final review does not match current HEAD"
+            if not archive_milestone.reviewed_head_covers(
+                repo, reviewed_head, _optional_rev(repo, "HEAD")
+            ):
+                return (
+                    "archive undo final review does not match current HEAD; "
+                    f"{archive_milestone._common.RUNTIME_PIN_ALLOWANCE}"
+                )
             expected_inventory.add("review/FINAL.md")
             expected_inventory.update(
                 path.relative_to(archive_path).as_posix() for path in gap_reviews
@@ -476,10 +566,14 @@ def _archive_metadata_error(
         "archive",
         configured,
     )
-    current_state = (repo / ".project" / "STATE.md").read_text(encoding="utf-8")
+    current_state = (repo / ".project" / "STATE.md").read_bytes().decode("utf-8")
     phase = state_fields.get("phase")
     status = state_fields.get("status")
+    ship_events = _owned_ship_log_events(prepared_state, current_state, phase, status)
     if (phase, status) == ("ship", "active"):
+        if ship_events is None:
+            return "archive undo found unowned STATE.md changes"
+        prepared_state += ship_events
         if current_state != prepared_state:
             return "archive undo found unowned STATE.md changes"
         if ".project/ROADMAP.md" in dirty:
@@ -487,14 +581,13 @@ def _archive_metadata_error(
         return None
     if (phase, status) != ("shipped", "done"):
         return "archive undo requires ship/active or shipped/done"
+    if ship_events is None:
+        return "archive undo found unowned shipment STATE.md changes"
+    prepared_state += ship_events
 
     prepared = _state_from_text(prepared_state, "prepared archive STATE.md")
-    events = (
-        "archive preflight passed; shipment recorded",
-        "archive preflight passed; shipment recorded; program complete",
-    )
     rendered_states = []
-    for event in events:
+    for event in SHIPMENT_EVENTS:
         try:
             _, _, rendered = _render_transition(
                 prepared,

package/skills/gsd-path-forensics/scripts/worktree_paths.py

@@ -22,6 +22,27 @@ else:
         from scripts import _common
 
 
+def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    try:
+        if __package__:
+            from . import pipeline_git as pg
+        else:
+            from scripts import pipeline_git as pg
+    except ImportError:
+        try:
+            import pipeline_git as pg
+        except ImportError:
+            pg = None
+    if pg is not None:
+        return pg.worktree_list_porcelain(primary)
+    try:
+        output = _git(primary, "worktree", "list", "--porcelain", "-z")
+        return output, True
+    except ValueError:
+        output = _git(primary, "worktree", "list", "--porcelain")
+        return output, False
+
+
 def _git(primary: Path, *args: str) -> str:
     result = _common.run_git(primary, *args)
     if result.returncode:
@@ -82,6 +103,33 @@ def _workspace(primary: Path, pin: bool) -> Path:
     return workspace
 
 
+def release_workspace(primary: Path) -> bool:
+    """Forget the pinned placement receipt once no linked worktrees remain.
+
+    Lets GSD_PATH_WORKTREE_ROOT (or a new default) apply again at the next
+    milestone's first allocation. Returns True when a receipt was removed;
+    any remaining linked worktree (including one only still registered) keeps
+    the pin.
+    """
+    primary = primary.resolve()
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    receipt = common / "gsd-path" / "workspaces" / f"{_identity(primary)}.json"
+    if not receipt.is_file():
+        return False
+    output, nul_separated = _worktree_list_porcelain(primary)
+    records = output.split("\0\0") if nul_separated else [
+        block for block in output.strip().split("\n\n") if block.strip()
+    ]
+    for record in records:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        for field in fields:
+            if field.startswith("worktree ") and Path(field[len("worktree "):]).resolve() != primary:
+                return False
+    receipt.unlink()
+    return True
+
+
 def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
     primary = primary.resolve()
     if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
@@ -91,9 +139,13 @@ def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) ->
     legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
               if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
     branch = f"refs/heads/gsd-path-{kind}/{name}"
-    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    output, nul_separated = _worktree_list_porcelain(primary)
+    if nul_separated:
+        records = output.split("\0\0")
+    else:
+        records = [block for block in output.strip().split("\n\n") if block.strip()]
     for record in records:
-        fields = record.split("\0")
+        fields = record.split("\0") if nul_separated else record.splitlines()
         # Compare as paths: git prints forward slashes on Windows.
         worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
         if legacy in worktrees and f"branch {branch}" in fields:

package/skills/gsd-path-inspect/references/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

package/skills/gsd-path-inspect/references/docs-auditor.md

@@ -59,6 +59,11 @@ actually does. Read-only: change nothing outside your single output file.
 5. **Classify remediation** for every non-verified claim: `fix-doc`,
    `fix-code`, or `NEEDS-USER` when the right side of the conflict is not
    yours to decide.
+   Number queue rows with unique, strictly increasing positive integers; they
+   need not be contiguous. A row that persists from the prior audit keeps its
+   number. A new row takes a number greater than every prior queue number and
+   every `## User rulings` Queue #. Never reuse a retired number: a ruling
+   stays bound to the item it was made for.
 
 ## Rules
 

package/skills/gsd-path-inspect/scripts/_common.py

@@ -65,6 +65,49 @@ VERIFY_RESULTS = ("pass", "fail")
 VERIFY_LEDGER_SCHEMA = "gsd-path/verify-ledger/v2"
 VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
 
+REVIEW_BULLET_HEADING_PATTERN = re.compile(r"^#{2,3} ")
+REVIEW_BULLET_FIELD_LABEL_PATTERN = re.compile(r"^- \*\*[^*]+\*\*:")
+
+
+def review_bullet_field_label_pattern(field: str) -> re.Pattern[str]:
+    return re.compile(rf"^- \*\*{re.escape(field)}\*\*:[ \t]*(.*)$")
+
+
+def _review_bullet_field_value(lines: Sequence[str], index: int, inline: str) -> str:
+    if inline:
+        return inline
+    collected: list[str] = []
+    for line in lines[index + 1 :]:
+        if REVIEW_BULLET_FIELD_LABEL_PATTERN.match(line) or REVIEW_BULLET_HEADING_PATTERN.match(
+            line
+        ):
+            break
+        if line and not line[0].isspace():
+            break
+        stripped = line.strip()
+        if stripped:
+            collected.append(stripped)
+    return "\n".join(collected)
+
+
+def find_review_bullet_field_values(lines: Sequence[str], field: str) -> list[str]:
+    pattern = review_bullet_field_label_pattern(field)
+    values: list[str] = []
+    for index, line in enumerate(lines):
+        match = pattern.fullmatch(line)
+        if match is None:
+            continue
+        values.append(_review_bullet_field_value(lines, index, match.group(1)))
+    return values
+
+
+def parse_review_bullet_field(lines: Sequence[str], field: str) -> str:
+    """Parse one `- **Field**:` review bullet, including indented continuations."""
+    values = find_review_bullet_field_values(lines, field)
+    if len(values) != 1:
+        raise ValueError(field)
+    return values[0]
+
 
 # Sample paths the pipeline must commit. A product rule such as an unanchored
 # `build/` would otherwise drop them silently from every commit.
@@ -150,6 +193,11 @@ def verify_ledger_entries(path: Path) -> list:
     return parse_verify_ledger(path.read_text(encoding="utf-8"))
 
 
+def read_user_text(path: Path) -> str:
+    """Read a user-edited text file with CRLF normalized to LF."""
+    return path.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
+
+
 def parse_verify_ledger(text: str) -> list:
     entries = []
     for number, line in enumerate(text.splitlines(), start=1):
@@ -204,7 +252,43 @@ def run_command(
 def run_git(
     repo: Path, *arguments: str, input: Optional[str] = None
 ) -> subprocess.CompletedProcess[str]:
-    return _run_exact(("git", "-C", str(repo), *arguments), input=input)
+    return _run_exact(git_command(repo, *arguments), input=input)
+
+
+def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
+    """Git argv for repo, including WSL drvfs workarounds when needed."""
+    return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)
+
+
+def git_drvfs_config_flags(repo: Path) -> tuple[str, ...]:
+    """Disable index preload on 9p/drvfs mounts where git commit races on index.lock (#207)."""
+    if os.name != "posix":
+        return ()
+    try:
+        root = repo.resolve()
+        mounts = Path("/proc/mounts").read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ()
+    best = ""
+    fstype = ""
+    for line in mounts:
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        mount_point, mount_type = parts[1], parts[2]
+        if mount_type not in {"9p", "drvfs"}:
+            continue
+        if root == Path(mount_point) or root.is_relative_to(mount_point):
+            if len(mount_point) >= len(best):
+                best, fstype = mount_point, mount_type
+    if not fstype:
+        return ()
+    return ("-c", "core.preloadindex=false", "-c", "index.threads=1")
+
+
+def git_index_lock_retryable(stderr: str) -> bool:
+    text = stderr.casefold()
+    return "index.lock" in text and "file exists" in text
 
 
 # OS files that are never pipeline artifacts when git ignores them.
@@ -227,6 +311,70 @@ def git_visible_entries(directory: Path) -> set:
     return {path.split("/", 1)[0] for path in result.stdout.split("\0") if path}
 
 
+RUNTIME_PIN_PATH = ".gsd-path/runtime.json"
+RUNTIME_PIN_ALLOWANCE = (
+    "only runtime-pin commits (.gsd-path/runtime.json) may follow the reviewed HEAD"
+)
+
+
+def reviewed_head_covers(repo: Path, reviewed: str, head: str) -> bool:
+    """True when a review of `reviewed` still covers `head`.
+
+    That is the same commit, or `reviewed` is an ancestor of `head` and every
+    commit on the first-parent path in ``reviewed..head`` is a non-merge commit
+    whose only change is ``.gsd-path/runtime.json``. An empty commit does not
+    qualify. Any other path, any merge commit, an unresolvable SHA, or a
+    non-ancestor returns False.
+    """
+    if not reviewed or not head:
+        return False
+    resolved_repo = Path(repo)
+    resolved: List[str] = []
+    for value in (reviewed, head):
+        result = run_git(
+            resolved_repo, "rev-parse", "--verify", "--quiet", f"{value}^{{commit}}"
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return False
+        resolved.append(result.stdout.strip())
+    reviewed_sha, head_sha = resolved
+    if reviewed_sha == head_sha:
+        return True
+    if (
+        run_git(resolved_repo, "merge-base", "--is-ancestor", reviewed_sha, head_sha).returncode
+        != 0
+    ):
+        return False
+    listing = run_git(
+        resolved_repo,
+        "rev-list",
+        "--first-parent",
+        "--parents",
+        f"{reviewed_sha}..{head_sha}",
+    )
+    if listing.returncode != 0:
+        return False
+    for line in listing.stdout.splitlines():
+        fields = line.split()
+        if len(fields) != 2:
+            return False
+        commit_sha, parent_sha = fields[0], fields[1]
+        changed = run_git(
+            resolved_repo,
+            "diff",
+            "--name-only",
+            "--no-renames",
+            "--no-ext-diff",
+            parent_sha,
+            commit_sha,
+        )
+        if changed.returncode != 0:
+            return False
+        if {path for path in changed.stdout.splitlines() if path} != {RUNTIME_PIN_PATH}:
+            return False
+    return True
+
+
 def atomic_replace(path: Path, temporary_path: Path, content: str) -> None:
     temporary_path.parent.mkdir(parents=True, exist_ok=True)
     descriptor = None