@opengsd/gsd-path 1.3.1 → 1.4.0

package/scripts/install.py

@@ -2,15 +2,18 @@
 """Install GSD Path skills for supported coding agents."""
 
 import argparse
+import difflib
 import errno
 import hashlib
 import json
 import os
 import re
+import shlex
 import shutil
 import subprocess
 import sys
 import tempfile
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable, Iterable, List, Mapping, Optional, Sequence, Tuple, Union
@@ -45,6 +48,10 @@ LOCAL_ROOTS = local_roots_for_manifest(sync_skill_resources.RESOURCE_MANIFEST)
 SKILL_NAMES = skill_names_for_manifest(sync_skill_resources.RESOURCE_MANIFEST)
 SKILL_ALIASES = dict(sync_skill_resources.RESOURCE_MANIFEST["skill_aliases"])
 ROUTER_ALIASES = dict(sync_skill_resources.RESOURCE_MANIFEST["router_aliases"])
+LOCAL_EDITS_NOTE = (
+    "; local edits inside these skills are not carried forward "
+    "(see UPDATE.md#local-additions)"
+)
 CLAUDE_BRIDGE = "@../AGENTS.md\n@../WORKFLOW.md\n"
 HOOKS_DIRECTORY = ".gsd-path"
 GUARD_SCRIPTS = ("guard_hook.py", "git_guard.py")
@@ -56,6 +63,21 @@ PROJECT_STATUS_MARKER = "gsd-path project status launcher"
 INSTALL_LOCK_NAME = ".gsd-path-install-lock"
 INSTALL_LOCK_OWNER = "owner.json"
 INSTALL_LOCK_SCHEMA = "gsd-path/install-lock/v2"
+AGENTS_BEGIN = "<!-- gsd-path:begin -->"
+AGENTS_END = "<!-- gsd-path:end -->"
+# Codex default project_doc_max_bytes; it silently cuts the rest of AGENTS.md.
+CODEX_DOC_LIMIT = 32768
+# sha256 of each released whole-file AGENTS.md (v1.0.0, v1.1.0, v1.2.0-v1.3.1).
+RELEASED_AGENTS = frozenset(
+    {
+        "dfc969299e10c4430742c66c273436136a813d75e332cecf9403f94c904b330b",
+        "3a5c4ed62f397725acce962a7fdfafd5a3296f0a784acafc55454b5304a4eb7c",
+        "831de61d4b4b624319930162d45ac88c49cc13ca22894f37733ba68e6503f972",
+    }
+)
+LEGACY_AGENTS_TITLE = "# AGENTS.md — Operating Rules for the GSD Path Pipeline"
+# Every released whole-file AGENTS.md carries this marker.
+LEGACY_AGENTS_MARKER = "<!-- gsd-path/plain-prompt-reentry/v1 -->"
 PROJECT_CONTRACTS = (
     ("AGENTS.md", "## Plain-prompt re-entry"),
     ("WORKFLOW.md", "### Plain-prompt re-entry"),
@@ -231,19 +253,149 @@ GIT_HOOKS = (
     ("pre-push", pre_push_hook),
 )
 GIT_HOOK_NAMES = tuple(name for name, _ in GIT_HOOKS)
+MEMBER_HOOK_MARKER = "gsd-path member guard"
+CHAINED_HOOK_SUFFIX = ".gsd-path-chained"
+
+
+def member_hook(interpreter: str, name: str) -> str:
+    """A member hook finds its coordinator through the member marker, so a
+    moved coordinator needs only `members.py repair`, then runs any chained hook."""
+    guard = f'{interpreter} "$coordinator/{HOOKS_DIRECTORY}/git_guard.py" {name} "$@"'
+    lines = [
+        "#!/bin/sh",
+        f"# {MEMBER_HOOK_MARKER}: runs the coordinator's git_guard.py named by this",
+        "# repository's member marker, then any chained hook.",
+        "common=$(git rev-parse --path-format=absolute --git-common-dir) || exit 1",
+        f"coordinator=$({interpreter} -c 'import json, sys; print(json.load(open(sys.argv[1]))[\"coordinator\"])' "
+        '"$common/gsd-path/member.json") || {',
+        '  echo "gsd-path guard: member marker is unreadable; run members.py repair --repo <coordinator>" >&2',
+        "  exit 1",
+        "}",
+        f'chained="$(dirname "$0")/{name}{CHAINED_HOOK_SUFFIX}"',
+    ]
+    if name == "pre-push":
+        # Git gives pre-push its ref updates on stdin; both hooks need them.
+        lines += [
+            "input=$(cat)",
+            '[ -n "$input" ] && input="$input\n"',
+            f'printf %s "$input" | {guard} || exit 1',
+            'if [ -x "$chained" ]; then printf %s "$input" | exec "$chained" "$@"; fi',
+        ]
+    else:
+        lines += [f"{guard} || exit 1", 'if [ -x "$chained" ]; then exec "$chained" "$@"; fi']
+    return "\n".join(lines) + "\n"
+
+
+def install_member_hooks(coordinator: Path, member: Path, dry_run: bool = False) -> List[str]:
+    """Install git hooks that hold a member repo to its coordinator's guard.
+
+    Unmanaged hooks are kept as `<hook>.gsd-path-chained` and run after the
+    guard passes; the member's own single-repo Path hooks are replaced.
+    """
+    _validate_project_git_root(member)
+    # Imported here so other installer commands keep their small import closure.
+    try:
+        from . import members
+    except ImportError:
+        import members
+    try:
+        role = members.member_role(member)
+    except members.MembersError as error:
+        raise InstallerError(str(error)) from error
+    if role is None or not _same_path(Path(role["coordinator"]), coordinator):
+        raise InstallerError(f"{member} is not a member of {coordinator}; run members.py add first")
+    guard = coordinator / HOOKS_DIRECTORY / "git_guard.py"
+    if guard.is_symlink() or not _is_managed_guard_script(guard):
+        raise InstallerError(f"coordinator guard is not installed: {guard}")
+    hooks_dir = _resolve_git_hooks_path(member)
+    if hooks_dir is None:
+        raise InstallerError(f"cannot resolve the git hooks directory of {member}")
+    common = Path(subprocess.run(
+        ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+        cwd=os.fspath(member), capture_output=True, encoding="utf-8", errors="replace", check=True,
+    ).stdout.strip()).resolve()
+    resolved = hooks_dir.resolve()
+    worktree_output = subprocess.run(
+        ["git", "worktree", "list", "--porcelain", "-z"],
+        cwd=os.fspath(member), capture_output=True, check=True,
+    ).stdout
+    worktrees = [
+        Path(os.fsdecode(field[len(b"worktree "):])).resolve()
+        for field in worktree_output.split(b"\0") if field.startswith(b"worktree ")
+    ]
+    if not worktrees or (
+        any(resolved.is_relative_to(root) for root in worktrees)
+        and not resolved.is_relative_to(common)
+    ):
+        raise InstallerError(
+            f"git hooks path is inside the member worktree: {hooks_dir}; "
+            "point core.hooksPath outside the worktree or unset it"
+        )
+    interpreter = _required_python_runtime("--member-of")
+    plan = []
+    for name in GIT_HOOK_NAMES:
+        hook, chained = hooks_dir / name, hooks_dir / f"{name}{CHAINED_HOOK_SUFFIX}"
+        if hook.is_symlink() or chained.is_symlink():
+            raise InstallerError(f"refusing a symlinked git hook: {hook}")
+        if _lexists(hook) and not hook.is_file():
+            raise InstallerError(f"git hook is not a regular file: {hook}")
+        text = hook.read_text(encoding="utf-8", errors="replace") if hook.is_file() else None
+        chain = (
+            text is not None
+            and MEMBER_HOOK_MARKER not in text
+            and not _is_managed_git_hook_content(text)
+        )
+        if chain and _lexists(chained):
+            raise InstallerError(f"cannot chain {hook}: {chained} already exists")
+        plan.append((name, hook, chained, chain))
+    lines = []
+    for name, hook, chained, chain in plan:
+        note = " (keeps the existing hook as a chained hook)" if chain else ""
+        lines.append(f"member hook: {hook}{note}" + (" (dry run)" if dry_run else ""))
+    if dry_run:
+        return lines
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    staged = []
+    try:
+        for name, _, _, _ in plan:
+            temporary = hooks_dir / f".{name}.gsd-path-tmp"
+            # O_EXCL already refuses any existing name; O_NOFOLLOW (absent on
+            # Windows) adds defense in depth where it exists.
+            flags = (os.O_WRONLY | os.O_CREAT | os.O_EXCL
+                     | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0))
+            fd = os.open(temporary, flags, 0o755)
+            staged.append(temporary)
+            with os.fdopen(fd, "wb") as output:
+                if hasattr(os, "fchmod"):  # Windows before 3.13; Git for Windows needs no exec bit.
+                    os.fchmod(output.fileno(), 0o755)
+                output.write(member_hook(interpreter, name).encode("utf-8"))
+        for name, hook, chained, chain in plan:
+            if chain:
+                os.replace(hook, chained)
+            os.replace(hooks_dir / f".{name}.gsd-path-tmp", hook)
+    finally:
+        for temporary in staged:
+            temporary.unlink(missing_ok=True)
+    return lines
+
+
+# Every interpreter a managed hook may be pinned to; each is a command prefix.
+INTERPRETER_CANDIDATES = ("python3", "python", "py -3")
 
 
 def _detect_python_interpreter() -> Optional[str]:
-    """Probe for a runnable interpreter (python3, then python).
+    """Probe for a runnable interpreter (python3, then python, then py -3).
 
     Emitted hooks must never hard-code an interpreter that does not exist on
-    this machine (python3 is typically absent on Windows).
+    this machine (python3 is typically absent on Windows, and python.org
+    installs may put only the py launcher on PATH). The result is a command
+    prefix; split it before spawning.
     """
-    for candidate in ("python3", "python"):
+    for candidate in INTERPRETER_CANDIDATES:
         try:
             result = subprocess.run(
                 [
-                    candidate,
+                    *candidate.split(),
                     "-B",
                     "-c",
                     "import sys; raise SystemExit(sys.version_info < (3, 9))",
@@ -277,7 +429,7 @@ def _resolve_git_hooks_path(project: "Path") -> Optional["Path"]:
             ["git", "rev-parse", "--show-toplevel", "--git-path", "hooks"],
             cwd=os.fspath(project),
             capture_output=True,
-            text=True,
+            encoding="utf-8", errors="replace",
             check=False,
         )
     except OSError:
@@ -534,7 +686,7 @@ def _stamp_installed_versions(staged_root: Path, version: Optional[str]) -> None
     if not version:
         return
     for name in {"gsd-path", *ROUTER_ALIASES}:
-        (staged_root / name / "VERSION").write_text(f"{version}\n", encoding="utf-8")
+        (staged_root / name / "VERSION").write_bytes(f"{version}\n".encode("utf-8"))
 
 
 def _lexists(path: Path) -> bool:
@@ -670,7 +822,7 @@ def stage_target(source_root: Path, target: str, staged_root: Path) -> None:
         encoding="utf-8"
     )
     for dispatch in sorted(staged_root.glob("*/references/dispatch.md")):
-        dispatch.write_text(adapter, encoding="utf-8")
+        dispatch.write_bytes(adapter.encode("utf-8"))
     if target == "cursor":
         shutil.copy2(
             source_root / "platforms" / "cursor" / "agent.md",
@@ -687,9 +839,8 @@ def stage_target(source_root: Path, target: str, staged_root: Path) -> None:
         path_invocation = "path" if target == "opencode" else "/path"
         for name in SKILL_NAMES:
             entrypoint = staged_root / name / "SKILL.md"
-            entrypoint.write_text(
-                _augment_frontmatter(entrypoint.read_text(encoding="utf-8"), target),
-                encoding="utf-8",
+            entrypoint.write_bytes(
+                _augment_frontmatter(entrypoint.read_text(encoding="utf-8"), target).encode("utf-8"),
             )
         for markdown in sorted(staged_root.rglob("*.md")):
             content = markdown.read_text(encoding="utf-8")
@@ -698,7 +849,7 @@ def stage_target(source_root: Path, target: str, staged_root: Path) -> None:
                 if target == SHARED_AGENT_PROFILE
                 else content.replace("$gsd-path", invocation).replace("$path", path_invocation)
             )
-            markdown.write_text(transformed, encoding="utf-8")
+            markdown.write_bytes(transformed.encode("utf-8"))
 
 
 def _missing_directories(path: Path) -> List[Path]:
@@ -735,7 +886,7 @@ def _process_identity(pid: int) -> Optional[str]:
     else:
         command = ["ps", "-o", "lstart=", "-p", str(pid)]
     try:
-        result = subprocess.run(command, capture_output=True, text=True, check=False)
+        result = subprocess.run(command, capture_output=True, encoding="utf-8", errors="replace", check=False)
     except OSError:
         return None
     value = result.stdout.strip()
@@ -743,11 +894,39 @@ def _process_identity(pid: int) -> Optional[str]:
 
 
 def _process_alive(pid: int) -> bool:
+    """Whether pid names a running process, without signalling it.
+
+    Windows os.kill(pid, 0) sends CTRL_C_EVENT, so Windows asks the kernel.
+    status_runtime and install carry verbatim copies (they cannot import this
+    module); tests/test_common_platform.py keeps them identical.
+    """
+    if pid <= 0:
+        return False
+    if os.name != "nt":
+        try:
+            os.kill(pid, 0)
+        except OSError as error:
+            return error.errno == errno.EPERM
+        return True
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.OpenProcess.argtypes = (wintypes.DWORD, wintypes.BOOL, wintypes.DWORD)
+    kernel32.GetExitCodeProcess.argtypes = (wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD))
+    kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
+    handle = kernel32.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
+    if not handle:
+        # ERROR_ACCESS_DENIED: a protected process exists but refuses the query.
+        return ctypes.get_last_error() == 5
     try:
-        os.kill(pid, 0)
-    except OSError as error:
-        return error.errno == errno.EPERM
-    return True
+        code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+            return True
+        return code.value == 259  # STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
 
 
 def _stale_install_lock_snapshot(lock: Path) -> Tuple[os.stat_result, bytes]:
@@ -784,6 +963,31 @@ def _stale_install_lock_snapshot(lock: Path) -> Tuple[os.stat_result, bytes]:
     return observed, owner_bytes
 
 
+# Access denied and sharing violation: on Windows a scanner or indexer that
+# briefly opens a freshly written file blocks moving it or its directory.
+_WINDOWS_BUSY_ERRORS = (5, 32)
+_MOVE_ATTEMPTS = 20
+
+
+def _move_retrying(move: Callable[[Path, Path], object], source: Path, destination: Path) -> None:
+    """Run ``move``, retried on Windows while another process briefly holds ``source``."""
+    if os.name != "nt":
+        move(source, destination)
+        return
+    for attempt in range(_MOVE_ATTEMPTS):
+        try:
+            move(source, destination)
+            return
+        except PermissionError as error:
+            # A directory moved onto an existing directory also reports access
+            # denied; that is not transient, so never retry it.
+            if (getattr(error, "winerror", None) not in _WINDOWS_BUSY_ERRORS
+                    or os.path.isdir(destination)
+                    or attempt == _MOVE_ATTEMPTS - 1):
+                raise
+            time.sleep(min(0.01 * 2 ** attempt, 0.25))
+
+
 def _recover_stale_install_lock(lock: Path, quarantine: Path) -> Optional[Path]:
     legacy_quarantine = lock.with_name(f"{lock.name}.stale")
     if not _lexists(lock):
@@ -839,19 +1043,18 @@ def _create_install_lock(lock: Path) -> None:
     quarantine = None
     published = False
     try:
-        (staging / INSTALL_LOCK_OWNER).write_text(
-            json.dumps(
+        (staging / INSTALL_LOCK_OWNER).write_bytes(
+            (json.dumps(
                 {
                     "schema": INSTALL_LOCK_SCHEMA,
                     "pid": os.getpid(),
                     "identity": identity,
                 }
             )
-            + "\n",
-            encoding="utf-8",
+            + "\n").encode("utf-8"),
         )
         quarantine = _recover_stale_install_lock(lock, recovery)
-        staging.rename(lock)
+        _move_retrying(Path.rename, staging, lock)
         published = True
         if quarantine is not None:
             shutil.rmtree(quarantine)
@@ -926,7 +1129,7 @@ def _backup_existing(
         for entry, backup_name in existing:
             stored = transaction.backup / backup_name
             transaction.moved.append((entry, stored))
-            os.replace(entry, stored)
+            _move_retrying(os.replace, entry, stored)
 
 
 def _reserve_directory(path: Path) -> None:
@@ -987,7 +1190,7 @@ def _rollback_target(transaction: TargetTransaction) -> None:
         _remove_path(destination)
     for original, stored in reversed(transaction.moved):
         if _lexists(stored):
-            os.replace(stored, original)
+            _move_retrying(os.replace, stored, original)
     if transaction.backup is not None:
         try:
             transaction.backup.rmdir()
@@ -1082,7 +1285,8 @@ def _update_replacement(
     project: Path, destination: Path, hooks_dir: Optional[Path]
 ) -> Optional[Callable[[Path], bool]]:
     """--update replaces managed runtime, guard, and git hook files in place
-    and keeps everything else (AGENTS.md, WORKFLOW.md, CLAUDE.md). Returns
+    and keeps everything else (WORKFLOW.md, CLAUDE.md); AGENTS.md has its own
+    block merge. Returns
     the managed-file check for a replaceable destination, or None for a
     kept one."""
     parent = project / HOOKS_DIRECTORY
@@ -1143,6 +1347,7 @@ def _project_result(
     ):
         replaceable = (
             destination in mergers
+            or destination == project / "AGENTS.md"
             or _update_replacement(project, destination, hooks_dir) is not None
         )
         bucket = kept if _lexists(destination) and not replaceable else refreshed
@@ -1155,13 +1360,140 @@ def _project_result(
 
 
 def _existing_contract_error(destination: Path) -> "InstallerError":
-    return InstallerError(
+    message = (
         f"project contract already exists: {destination} — the installer never "
-        "overwrites project files. Run --update --project PATH to refresh managed "
+        "overwrites project files."
+    )
+    document = destination.name in ("AGENTS.md", "WORKFLOW.md") or (
+        destination.name == "CLAUDE.md" and destination.parent.name == ".claude"
+    )
+    if document:
+        aside = destination.with_name(f"{destination.stem}.pre-path{destination.suffix}")
+        if _lexists(aside):
+            message += (
+                f" First install: {aside} already exists; move the contract to an "
+                f"unused name, rerun, then merge its rules into the new {destination.name}."
+            )
+        else:
+            message += (
+                f" First install: move it aside with `mv {shlex.quote(str(destination))} "
+                f"{shlex.quote(str(aside))}`, rerun, then merge its rules into the new "
+                f"{destination.name}."
+            )
+        message += " Already a GSD Path project:"
+    return InstallerError(
+        f"{message} Run --update --project PATH to refresh managed "
         "runtime files; merge template changes manually (see UPDATE.md)."
     )
 
 
+def _agents_block(template: str) -> str:
+    return f"{AGENTS_BEGIN}\n{template.rstrip(chr(10))}\n{AGENTS_END}\n"
+
+
+def _split_agents(text: str, destination: Path) -> Optional[Tuple[str, str]]:
+    """Owner text (before, after) around Path's block, or None without markers.
+    Markers count only as whole lines; inline mentions are owner text."""
+    begins = [m.start() for m in re.finditer(rf"(?m)^{re.escape(AGENTS_BEGIN)}\r?$", text)]
+    ends = list(re.finditer(rf"(?m)^{re.escape(AGENTS_END)}\r?(?:\n|$)", text))
+    if not begins and not ends:
+        return None
+    if len(begins) != 1 or len(ends) != 1 or ends[0].start() < begins[0]:
+        begins, ends = len(begins), len(ends)
+        raise InstallerError(
+            f"{destination} needs exactly one {AGENTS_BEGIN} line followed by one "
+            f"{AGENTS_END} line; found {begins} begin and {ends} end markers. "
+            "Fix the markers by hand, then rerun."
+        )
+    return text[:begins[0]], text[ends[0].end():]
+
+
+def _read_agents(destination: Path) -> Optional[bytes]:
+    if not _lexists(destination):
+        return None
+    try:
+        return destination.read_bytes()
+    except OSError as error:
+        raise InstallerError(f"cannot read {destination}: {error}") from error
+
+
+def _merged_agents(
+    source_root: Path, destination: Path, raw: Optional[bytes] = None
+) -> bytes:
+    """AGENTS.md with Path's block inserted or replaced; owner text kept as is.
+    raw is the current file (None when absent); read from disk when omitted."""
+    template = (source_root / "AGENTS.md").read_text(encoding="utf-8")
+    block = _agents_block(template)
+    if raw is None:
+        raw = _read_agents(destination)
+    if raw is not None:
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise InstallerError(f"cannot read {destination}: {error}") from error
+        parts = _split_agents(text, destination)
+        if parts is not None:
+            merged = parts[0] + block + parts[1]
+        elif hashlib.sha256(raw).hexdigest() in RELEASED_AGENTS:
+            merged = block  # One-time migration of an unedited whole-file install.
+        elif LEGACY_AGENTS_TITLE in text or re.search(
+            rf"(?m)^{re.escape(LEGACY_AGENTS_MARKER)}\r?$", text
+        ):
+            diff = "".join(
+                difflib.unified_diff(
+                    template.splitlines(keepends=True),
+                    text.splitlines(keepends=True),
+                    "AGENTS.md (current GSD Path contract)",
+                    str(destination),
+                )
+            )
+            raise InstallerError(
+                f"{destination} is an edited whole-file GSD Path contract; Path cannot "
+                "tell its text from your edits. Migrate by hand: 1) keep your own "
+                f"rules from the diff below; 2) move the file aside with `mv "
+                f"{shlex.quote(str(destination))} "
+                f"{shlex.quote(str(destination.with_name('AGENTS.pre-path.md')))}`; "
+                "3) rerun; 4) add your rules after the "
+                f"{AGENTS_END} line.\n{diff}"
+            )
+        else:
+            merged = block + "\n" + text  # Block first: Codex cuts the tail.
+    else:
+        merged = block
+    data = merged.encode("utf-8")
+    if len(data) > CODEX_DOC_LIMIT:
+        aside = destination.with_name("AGENTS.pre-path.md")
+        raise InstallerError(
+            f"{destination} would be {len(data)} bytes (existing file {len(raw or b'')} "
+            f"bytes, GSD Path block {len(block.encode('utf-8'))} bytes). Codex reads "
+            f"only the first {CODEX_DOC_LIMIT} bytes and silently cuts the rest. "
+            f"Move it aside with `mv {shlex.quote(str(destination))} "
+            f"{shlex.quote(str(aside))}`, rerun, then add back only the rules that fit."
+        )
+    return data
+
+
+def _apply_agents(
+    source_root: Path, destination: Path, transaction: "ProjectTransaction"
+) -> None:
+    original = _read_agents(destination)
+    merged = _merged_agents(source_root, destination, original)
+    if original is None:
+        try:
+            with destination.open("xb") as output:
+                transaction.copied.append(destination)
+                output.write(merged)
+        except FileExistsError as error:
+            raise _existing_contract_error(destination) from error
+        return
+    if original != merged:
+        if _read_agents(destination) != original:
+            raise InstallerError(f"{destination} changed during install; rerun")
+        mode = destination.stat().st_mode & 0o777
+        _atomic_write(destination, merged, mode)
+        transaction.replaced.append((destination, original, mode))
+
+
 def _validate_project_git_root(project: Path) -> None:
     probe = project
     while not _lexists(probe):
@@ -1171,7 +1503,7 @@ def _validate_project_git_root(project: Path) -> None:
             ["git", "rev-parse", "--show-toplevel"],
             cwd=probe,
             capture_output=True,
-            text=True,
+            encoding="utf-8", errors="replace",
             check=False,
             env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
         )
@@ -1186,6 +1518,90 @@ def _validate_project_git_root(project: Path) -> None:
         raise InstallerError(f"project path is not the Git worktree root: {project}")
 
 
+GIT_ATTRIBUTES_BEGIN = "# gsd-path:begin"
+GIT_ATTRIBUTES_END = "# gsd-path:end"
+# Pipeline state is compared and hashed byte for byte. Git for Windows installs
+# with core.autocrlf=true, which would check .project files out as CRLF in
+# every worktree; this local rule keeps them LF without touching product files.
+GIT_ATTRIBUTES_BLOCK = (
+    f"{GIT_ATTRIBUTES_BEGIN}\n/.project/** text eol=lf\n{GIT_ATTRIBUTES_END}\n"
+)
+
+
+def _git_attributes_path(project: Path) -> Optional[Path]:
+    """The repository's local attributes file, shared by every worktree.
+
+    `--git-path info/attributes` resolves to the common git directory, so
+    managed worktrees see the same rule. None when git cannot resolve it.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel", "--git-path", "info/attributes"],
+            cwd=os.fspath(project), capture_output=True,
+            encoding="utf-8", errors="replace", check=False,
+        )
+    except OSError:
+        return None
+    lines = [line for line in result.stdout.splitlines() if line]
+    if result.returncode != 0 or len(lines) != 2 or not _same_path(Path(lines[0]), project):
+        return None
+    return Path(os.path.abspath(os.path.join(os.fspath(project), lines[1])))
+
+
+def _merged_git_attributes(raw: Optional[bytes], destination: Path) -> bytes:
+    """The attributes file with Path's block inserted or replaced; other lines kept."""
+    if raw is None:
+        return GIT_ATTRIBUTES_BLOCK.encode("utf-8")
+    text = raw.decode("utf-8", "surrogateescape")
+    lines = text.splitlines(keepends=True)
+    begins = [i for i, line in enumerate(lines) if line.rstrip("\r\n") == GIT_ATTRIBUTES_BEGIN]
+    ends = [i for i, line in enumerate(lines) if line.rstrip("\r\n") == GIT_ATTRIBUTES_END]
+    if not begins and not ends:
+        separator = "" if not text or text.endswith("\n") else "\n"
+        merged = text + separator + GIT_ATTRIBUTES_BLOCK
+    elif len(begins) != 1 or len(ends) != 1 or ends[0] < begins[0]:
+        raise InstallerError(
+            f"{destination} needs exactly one {GIT_ATTRIBUTES_BEGIN} line followed by "
+            f"one {GIT_ATTRIBUTES_END} line; fix the markers by hand, then rerun"
+        )
+    else:
+        merged = "".join(lines[:begins[0]]) + GIT_ATTRIBUTES_BLOCK + "".join(lines[ends[0] + 1:])
+    return merged.encode("utf-8", "surrogateescape")
+
+
+def _read_git_attributes(destination: Path) -> Optional[bytes]:
+    if not _lexists(destination):
+        return None
+    if destination.is_symlink() or not destination.is_file():
+        raise InstallerError(f"unsafe git attributes file: {destination}")
+    try:
+        return destination.read_bytes()
+    except OSError as error:
+        raise InstallerError(f"cannot read {destination}: {error}") from error
+
+
+def _apply_git_attributes(project: Path, transaction: "ProjectTransaction") -> None:
+    destination = _git_attributes_path(project)
+    if destination is None:
+        return
+    original = _read_git_attributes(destination)
+    merged = _merged_git_attributes(original, destination)
+    if original == merged:
+        return
+    _create_directory(destination.parent, transaction.created_directories)
+    if original is None:
+        try:
+            with destination.open("xb") as output:
+                transaction.copied.append(destination)
+                output.write(merged)
+        except FileExistsError as error:
+            raise InstallerError(f"{destination} changed during install; rerun") from error
+        return
+    mode = destination.stat().st_mode & 0o777
+    _atomic_write(destination, merged, mode)
+    transaction.replaced.append((destination, original, mode))
+
+
 def _validate_project(
     source_root: Path,
     project: Path,
@@ -1232,11 +1648,18 @@ def _validate_project(
         runtime_store.prepare(source_root, project, dry_run=True)
     except (OSError, ValueError) as error:
         raise InstallerError(str(error)) from error
+    attributes = _git_attributes_path(project)
+    if attributes is not None:
+        _merged_git_attributes(_read_git_attributes(attributes), attributes)
     mergers = _native_settings_mergers(project, selected, hooks)
     for destination, _, _, _ in _project_destinations(
         project, selected, hooks, interpreter, hooks_dir
     ):
-        if _lexists(destination):
+        if destination == project / "AGENTS.md":
+            if destination.is_symlink():
+                raise _existing_contract_error(destination)
+            _merged_agents(source_root, destination)
+        elif _lexists(destination):
             merge = mergers.get(destination)
             managed = (
                 _update_replacement(project, destination, hooks_dir) if update else None
@@ -1265,7 +1688,10 @@ def _apply_project(
     interpreter: str,
     hooks_dir: Optional[Path],
     update: bool = False,
+    contracts: bool = True,
 ) -> None:
+    """contracts=False (hook refresh) creates a missing AGENTS.md but never
+    rewrites an existing one."""
     try:
         pin = runtime_store.prepare(source_root, project)
     except (OSError, ValueError) as error:
@@ -1278,6 +1704,11 @@ def _apply_project(
         if destination.name == "runtime.json" and destination.parent == project / HOOKS_DIRECTORY:
             content = runtime_store.pin_text(pin)
         _create_directory(destination.parent, transaction.created_directories)
+        if destination == project / "AGENTS.md" and (
+            contracts or not _lexists(destination)
+        ):
+            _apply_agents(source_root, destination, transaction)
+            continue
         merge = mergers.get(destination)
         if _lexists(destination) and not destination.is_symlink():
             replaceable = (
@@ -1320,6 +1751,7 @@ def _apply_project(
             if created:
                 _remove_path(destination)
             raise
+    _apply_git_attributes(project, transaction)
 
 
 def _rollback_project(transaction: ProjectTransaction) -> None:
@@ -1411,7 +1843,7 @@ def _atomic_write(
             with os.fdopen(descriptor, "wb") as output:
                 output.write(content)
         else:
-            with os.fdopen(descriptor, "w", encoding="utf-8") as output:
+            with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as output:
                 output.write(content)
         if mode is not None:
             temporary.chmod(mode)
@@ -1448,7 +1880,7 @@ def _is_managed_hook_entry(entry) -> bool:
 def _is_guard_command(command: str) -> bool:
     normalized = command.replace("\\", "/")
     match = re.fullmatch(
-        r"(?:python3|python)\s+(?:\"([^\"\r\n]+)\"|'([^'\r\n]+)'|(\S+))",
+        r"(?:python3|python|py\s+-3)\s+(?:\"([^\"\r\n]+)\"|'([^'\r\n]+)'|(\S+))",
         normalized,
     )
     if match is None:
@@ -1761,7 +2193,7 @@ def refresh_hooks(
             _validate_hooks_refresh(source_root, project, full, hooks_dir, selected, True)
             transaction = ProjectTransaction()
             try:
-                _apply_project(source_root, project, selected, full, transaction, interpreter, hooks_dir, update=True)
+                _apply_project(source_root, project, selected, full, transaction, interpreter, hooks_dir, update=True, contracts=False)
             except BaseException:
                 _rollback_project(transaction)
                 raise
@@ -1777,7 +2209,7 @@ def refresh_hooks(
                     refresh_targets.append(target)
         transaction = ProjectTransaction()
         try:
-            _apply_project(source_root, project, refresh_targets, True, transaction, interpreter, hooks_dir, update=True)
+            _apply_project(source_root, project, refresh_targets, True, transaction, interpreter, hooks_dir, update=True, contracts=False)
         except BaseException:
             _rollback_project(transaction)
             raise
@@ -1940,10 +2372,10 @@ def _validated_project_state(source_root: Path, project: Path) -> dict:
     interpreter = _required_python_runtime("--doctor")
     try:
         result = subprocess.run(
-            [interpreter, "-B", str(validator), "validate", "--repo", str(project)],
+            [*interpreter.split(), "-B", str(validator), "validate", "--repo", str(project)],
             cwd=project,
             capture_output=True,
-            text=True,
+            encoding="utf-8", errors="replace",
             check=False,
         )
     except OSError as error:
@@ -1981,10 +2413,10 @@ def _validate_project_runtime_status(source_root: Path, project: Path) -> None:
     environment["GIT_OPTIONAL_LOCKS"] = "0"
     try:
         result = subprocess.run(
-            [interpreter, "-B", str(runtime), "status", "--repo", str(project)],
+            [*interpreter.split(), "-B", str(runtime), "status", "--repo", str(project)],
             cwd=project,
             capture_output=True,
-            text=True,
+            encoding="utf-8", errors="replace",
             check=False,
             env=environment,
         )
@@ -2148,9 +2580,13 @@ def _valid_status_branch(value: object) -> Optional[re.Match[str]]:
 
 def _is_executable(path: Path) -> bool:
     try:
-        return bool(path.stat().st_mode & 0o111)
+        status = path.stat()
     except OSError:
         return False
+    if os.name == "nt":
+        # Windows has no exec bit; Git for Windows runs any regular hook file.
+        return path.is_file()
+    return bool(status.st_mode & 0o111)
 
 
 def _native_guard_contract(
@@ -2165,6 +2601,32 @@ def _native_guard_contract(
     return None
 
 
+def _windows_path_warnings() -> List[str]:
+    """Settings that deep managed-worktree paths need past 260 characters."""
+    import winreg
+
+    warnings = []
+    try:
+        with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE,
+                            r"SYSTEM\CurrentControlSet\Control\FileSystem") as key:
+            enabled = winreg.QueryValueEx(key, "LongPathsEnabled")[0] == 1
+    except OSError:
+        enabled = False
+    if not enabled:
+        warnings.append("windows: long paths are disabled (LongPathsEnabled=0); files deep in "
+                        "managed worktrees may exceed 260 characters")
+    try:
+        result = subprocess.run(["git", "config", "--get", "core.longpaths"], capture_output=True,
+                                encoding="utf-8", errors="replace", check=False)
+    except OSError:
+        # Without git on PATH there is no git setting to advise on.
+        return warnings
+    if result.stdout.strip().lower() != "true":
+        warnings.append("windows: git core.longpaths is not true; run "
+                        "`git config --global core.longpaths true`")
+    return warnings
+
+
 def doctor(
     source_root: Path,
     targets: Sequence[str],
@@ -2186,6 +2648,9 @@ def doctor(
     version = _read_package_version(source_root / "package.json")
     if version is None:
         push("fail", "package: version cannot be read")
+    if os.name == "nt":
+        for text in _windows_path_warnings():
+            push("warn", text)
     seen: List[Tuple[str, Path]] = []
     installed_targets = set()
     for target in targets:
@@ -2235,6 +2700,29 @@ def doctor(
     if project is None:
         return findings
 
+    attributes = _git_attributes_path(project)
+    if attributes is not None:
+        try:
+            current = _read_git_attributes(attributes)
+            if current is None or _merged_git_attributes(current, attributes) != current:
+                push("warn", f"git: {attributes} lacks the GSD Path LF rule for .project — "
+                             f'run --update --project "{project}"')
+            else:
+                push("ok", "git: .project is checked out LF in every worktree")
+        except InstallerError as error:
+            push("fail", f"git: {error}")
+        crlf = sorted(
+            path.relative_to(project).as_posix()
+            for path in (project / ".project").rglob("*")
+            if path.is_file() and not path.is_symlink() and b"\r\n" in path.read_bytes()
+        ) if (project / ".project").is_dir() else []
+        if crlf:
+            # git checkout skips files it considers clean, so delete them first.
+            push("warn", f"git: {len(crlf)} .project file(s) were checked out as CRLF "
+                         f"(first: {crlf[0]}); with the LF rule in place and changes "
+                         "committed, run `git ls-files -z .project | xargs -0 rm -f && "
+                         "git checkout -- .project` to restore LF")
+
     for name, heading in PROJECT_CONTRACTS:
         contract = project / name
         if contract.is_symlink():
@@ -2249,6 +2737,26 @@ def doctor(
         canonical = read_project_file(source_root / name, f"package: {name}")
         if canonical is None:
             continue
+        if name == "AGENTS.md":
+            text = content.decode("utf-8", errors="replace")
+            try:
+                parts = _split_agents(text, contract)
+            except InstallerError as error:
+                push("fail", f"project: {error}")
+                continue
+            if parts is None:
+                push("fail", f'project: AGENTS.md has no GSD Path block — run --update --project "{project}"')
+            elif _agents_block(canonical.decode("utf-8", errors="replace")) not in text:
+                push("fail", f'project: AGENTS.md block is stale — run --update --project "{project}"')
+            elif len(content) > CODEX_DOC_LIMIT:
+                push(
+                    "fail",
+                    f"project: AGENTS.md is {len(content)} bytes; Codex reads only "
+                    f"the first {CODEX_DOC_LIMIT} — reduce the file to keep all rules visible",
+                )
+            else:
+                push("ok", "project: AGENTS.md block present")
+            continue
         installed_section = _contract_section(
             content.decode("utf-8", errors="replace"), heading
         )
@@ -2442,7 +2950,7 @@ def doctor(
             try:
                 parsed = json.loads(settings.read_text(encoding="utf-8"))
                 entries = parsed.get("hooks", {}).get(event)
-                variants = [entry(candidate) for candidate in ("python3", "python")]
+                variants = [entry(candidate) for candidate in INTERPRETER_CANDIDATES]
                 current = isinstance(entries, list) and any(
                     candidate in variants for candidate in entries
                 )
@@ -2488,7 +2996,7 @@ def doctor(
                             push("warn", f"hooks: {label} is not a managed GSD Path git hook")
                         elif not any(
                             hook_text == generator(candidate)
-                            for candidate in ("python3", "python")
+                            for candidate in INTERPRETER_CANDIDATES
                         ):
                             push("warn", f"hooks: {label} is stale — run --hooks-refresh-full")
                         elif not _is_executable(hook_path):
@@ -2715,7 +3223,7 @@ def install(
                     results.append(
                         "codex-legacy: backed up "
                         f"{len(legacy_transaction.moved)} entries to "
-                        f"{legacy_transaction.backup}"
+                        f"{legacy_transaction.backup}{LOCAL_EDITS_NOTE}"
                     )
             for index, plan in enumerate(deployments):
                 transaction = TargetTransaction(plan.root)
@@ -2726,7 +3234,7 @@ def install(
                     results.append(
                         f"{'+'.join(plan.targets)}: backed up "
                         f"{len(transaction.moved)} entries "
-                        f"to {transaction.backup}"
+                        f"to {transaction.backup}{LOCAL_EDITS_NOTE}"
                     )
             if project is not None:
                 result_line = _project_result(
@@ -2778,6 +3286,7 @@ def parser() -> argparse.ArgumentParser:
     argument_parser.add_argument("--local", action="store_true")
     argument_parser.add_argument("--dry-run", action="store_true")
     argument_parser.add_argument("--project", type=Path)
+    argument_parser.add_argument("--member-of", type=Path)
     argument_parser.add_argument("--doctor", action="store_true")
     runtime_actions = argument_parser.add_mutually_exclusive_group()
     for action in ("restore", "upgrade", "migrate"):
@@ -2845,6 +3354,18 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         except (InstallerError, OSError, ValueError) as error:
             print(f"error: {error}", file=sys.stderr)
             return 1
+    if arguments.member_of is not None:
+        if project is None:
+            argument_parser.error("--member-of requires --project")
+        try:
+            for line in install_member_hooks(
+                absolute_path(arguments.member_of), project, arguments.dry_run
+            ):
+                print(line)
+            return 0
+        except (InstallerError, OSError, subprocess.CalledProcessError) as error:
+            print(f"error: {error}", file=sys.stderr)
+            return 1
     if arguments.doctor:
         named = [target for target in TARGETS if getattr(arguments, target)]
         selected = named if named and not arguments.all_targets else list(TARGETS)