py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/initenv/components/project_structure/hooks_manager.py

@@ -0,0 +1,995 @@
+"""Git hooks manager utilities for project structure setup."""
+
+import hashlib
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .....utils.logging import log_debug_pair, log_info_pair
+from .....utils.root import Root, RootKind
+from .....utils.root_fallback import current_root, current_worktree
+from ...common.check_git_bash import check_git_bash_installed
+from .hook_source import HookSource, locate_hook_source
+
+#: Hooks the tool owns and keeps in sync with the vendored templates.
+#: Unknown files in .wl/hooks/ are left untouched (user's own hooks survive).
+#:
+#: Only ``pre-push`` carries a version marker among these (see
+#: :data:`_HOOK_MARKER_PREFIX`): the per-command gate's marker comparison covers
+#: that hook alone, and the other three rely on the release-time hash sync
+#: (:func:`apply_hook_sync`, called unconditionally by ``wl_dir_updater`` -- the
+#: ``sync_hooks`` compatibility entry wraps it) for body drift (#159/m2).
+KNOWN_HOOKS = frozenset(
+    {"pre-commit", "pre-push", "check_lockfile.py", "check_lockfile.sh"}
+)
+
+#: Prefix of the per-hook version marker line (``# WL-Pre-Push-Hook-Version: …``)
+#: that the cheap per-command gate reads from a hook's first 512 bytes. The gate
+#: compares the marker's *value* between the deployed hook and the vendored
+#: template, so a template whose *body* changed under an un-bumped marker is not
+#: invisible -- a prefix-only check could not see that drift (#158/B3).
+#:
+#: The prefix is ``pre-push``-specific on purpose, and only that hook carries a
+#: marker: it is the single :data:`KNOWN_HOOKS` member whose body drift the
+#: per-command gate can see. Extending the marker to the other three templates is
+#: a change to the marker protocol itself (a shared prefix, a bump rule, and
+#: every deployed copy re-syncing once), not a widening of this constant, so it
+#: was left out of #159/m2 in favour of stating the coverage.
+_HOOK_MARKER_PREFIX = "WL-Pre-Push-Hook-Version:"
+
+#: The value written to ``core.hooksPath`` is no longer a shared-config literal:
+#: it is the **absolute** deploy path carried by
+#: :attr:`HookSource.worktree_hooks_path` (ADR-0009) and written with
+#: ``git config --worktree``.
+
+#: Key in ``.wl/config.json`` holding the **sentinel** (#274, carried into the
+#: worktree scope by #276): the ``core.hooksPath`` value ``wl`` itself wrote last
+#: for *this* worktree. The value lives in the per-worktree config, which another
+#: tool or a human may also set -- and ``wl`` must not overwrite a value it did
+#: not write (wlcc ADR-0011, decision 2 / decision 4). The sentinel is what makes
+#: that distinguishable: a worktree-scoped value that is neither empty nor equal
+#: to this record belongs to somebody else.
+#:
+#: A missing key is deliberately read as "never written by ``wl``" -- the default
+#: for every ``config.json`` written before this key existed (backward
+#: compatibility). Such a worktree is not locked out: an unset worktree value is
+#: claimed, and a value equal to the path ``wl`` would write is recognised as its
+#: own, because rewriting it cannot change what anybody else asked for.
+HOOKS_PATH_SENTINEL_KEY = "core_hooks_path"
+
+#: The repository-format extension that makes a per-worktree config file
+#: (``config.worktree``) legal. It has to be set **before** ``git config
+#: --worktree`` writes anything: without it git silently treats ``--worktree`` as
+#: the shared local scope, which is exactly the cross-worktree coupling #276
+#: removes. Setting it is idempotent and one-time: :func:`_ensure_worktree_config`
+#: reads it first and only writes when it is not already true.
+_WORKTREE_CONFIG_EXTENSION = "extensions.worktreeConfig"
+
+
+def _git_top_level() -> Path | None:
+    """git's own work-tree root, or None when not inside a git work tree.
+
+    A ``WORKTREE``-kind lookup through the root module, whose git seam is the
+    ``git rev-parse --show-toplevel`` call the old git probe used.
+    Unlike the deploy root there is no fallback to spell out: the old resolver
+    also answered ``None`` when there was no work tree, and ``resolve`` reports
+    exactly that -- which is why this cannot go through ``current_root``.
+    """
+    root = current_worktree()
+    return root.path if root is not None else None
+
+
+def _is_git_work_tree() -> bool:
+    """Whether the current directory is inside a git work tree."""
+    return _git_top_level() is not None
+
+
+def _git_config_get(*scope_args: str) -> str | None:
+    """Read one ``git config`` value, returning None when unset/unreadable.
+
+    ``scope_args`` is the flag list that selects the scope under test
+    (``--worktree`` / ``--local``). Reading through git -- never by parsing
+    ``.git/config`` text -- is the #93 rule; the per-scope flags are what make
+    the *worktree* value distinguishable from the shared one (#276).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "config", *scope_args, "--get", "core.hooksPath"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    # No shape guard: the result is a real ``CompletedProcess`` here. Tests that
+    # drive this function patch ``hooks_manager.subprocess.run`` with a real one,
+    # so the #105/#106 ``getattr``/``isinstance`` defence -- which existed only
+    # because a globally patched ``subprocess.run`` could hand back something
+    # else, and which had to stay in step with the root module's git probe --
+    # has nothing left to defend against. It was removed with that probe (#123).
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _get_worktree_hooks_path() -> str | None:
+    """Read the **worktree-scoped** ``core.hooksPath``, never the effective one.
+
+    This is the only value ``wl`` may claim or repair (#276): the effective
+    answer would silently include the shared config, which ``wl`` deliberately
+    leaves untouched (ADR-0009). Before ``extensions.worktreeConfig`` is enabled
+    git answers "unset" here -- the read is harmless and the write path enables
+    the extension first.
+
+    Returns:
+        The worktree-scoped value, or None when it is unset/unreadable.
+    """
+    return _git_config_get("--worktree")
+
+
+def _get_shared_hooks_path() -> str | None:
+    """Read the **shared** (repository-wide) ``core.hooksPath``.
+
+    Used only to tell the user, in the log, that an older shared value is still
+    there as a fallback and how to remove it once nothing depends on it. Never
+    used for a decision: the shared config is not ``wl``'s to change (ADR-0009,
+    decision 2). ``--local`` is the shared repo config even in a linked
+    worktree -- it is the file every worktree reads.
+    """
+    return _git_config_get("--local")
+
+
+def _worktree_hooks_path_origin() -> str | None:
+    """Which config file supplies the *worktree-scoped* ``core.hooksPath``.
+
+    Used only for the one-line explanation printed when ``wl`` refuses to touch
+    somebody else's value (#274, carried into the worktree scope by #276) --
+    "who set it" answered by git itself through ``--show-origin``
+    (``file:.../.git/worktrees/<id>/config.worktree``, ``command line:``, …)
+    rather than guessed. Never used for a decision.
+
+    Returns:
+        The origin git reports, or None when it is unreadable. Callers word the
+        "unknown" case separately per language, so this keeps returning None.
+    """
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "config",
+                "--worktree",
+                "--show-origin",
+                "--get",
+                "core.hooksPath",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0 or not result.stdout:
+        return None
+    # ``--show-origin`` prints ``<origin>\t<value>``; only the origin is wanted
+    # here (the value was already read by _get_worktree_hooks_path).
+    origin = result.stdout.splitlines()[0].split("\t", 1)[0].strip()
+    return origin or None
+
+
+def _worktree_config_is_enabled() -> bool:
+    """Whether ``extensions.worktreeConfig`` is already on.
+
+    Read with ``--bool`` so any spelling git accepts (``true`` / ``yes`` / ``1``)
+    counts; anything unset/unreadable/invalid reads as "not enabled", which makes
+    the caller attempt the (idempotent) enable write.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "config", "--bool", "--get", _WORKTREE_CONFIG_EXTENSION],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return False
+    return result.returncode == 0 and result.stdout.strip() == "true"
+
+
+def _ensure_worktree_config() -> bool:
+    """Turn on ``extensions.worktreeConfig`` — once, idempotently.
+
+    The extension must be enabled **before** any ``git config --worktree``
+    write: without it git silently writes the *shared* local config, which is
+    exactly the cross-worktree coupling #276 removes. (Verified against
+    git 2.56: a pre-enable ``--worktree`` write landed in ``.git/config``.)
+
+    This is the one write ``wl`` makes to the shared config, and it is a
+    repository-format switch, not a ``core.hooksPath`` value: ``git`` itself
+    requires it in the common config. The read-first check keeps it a one-time
+    write.
+
+    Returns:
+        True when the extension is enabled (already or just now); False when git
+        refused the write, in which case no pointer is written either.
+    """
+    if _worktree_config_is_enabled():
+        return True
+    try:
+        subprocess.run(
+            ["git", "config", _WORKTREE_CONFIG_EXTENSION, "true"],
+            check=True,
+            capture_output=False,
+        )
+    except (subprocess.CalledProcessError, OSError) as e:
+        log_info_pair(
+            f"Warning: failed to enable {_WORKTREE_CONFIG_EXTENSION}: {e}",
+            f"警告: 启用 {_WORKTREE_CONFIG_EXTENSION} 失败: {e}",
+        )
+        return False
+    log_debug_pair(
+        f"✓ Enabled per-worktree git config ({_WORKTREE_CONFIG_EXTENSION}).",
+        f"✓ 已启用按 worktree 分离的 git 配置（{_WORKTREE_CONFIG_EXTENSION}）。",
+    )
+    return True
+
+
+def _read_hooks_path_sentinel(deploy_root: Root) -> str | None:
+    """The **worktree-scoped** ``core.hooksPath`` value ``wl`` recorded last.
+
+    ``deploy_root`` anchors the ``.wl/config.json`` this is read from -- the same
+    deploy root the pointer itself is written for, so the record and the write it
+    describes can never name different ``.wl`` directories. Because ``.wl`` is
+    per-checkout, each worktree keeps its own record of its own absolute path
+    (#274 in the worktree scope, #276).
+
+    A missing file, unreadable file, non-object JSON, or missing/non-string key
+    all answer None. That is the deliberate backward-compatibility rule for a
+    ``config.json`` written before the sentinel existed: "no record" is read as
+    "``wl`` has not recorded a claim", never as an error.
+    """
+    try:
+        with open(deploy_root.wl_dir() / "config.json", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    value = data.get(HOOKS_PATH_SENTINEL_KEY)
+    return value if isinstance(value, str) and value else None
+
+
+def _record_hooks_path_sentinel(deploy_root: Root, value: str) -> bool:
+    """Record ``value`` as the ``core.hooksPath`` value ``wl`` just wrote.
+
+    Read-modify-write of the existing ``.wl/config.json``, preserving every other
+    key: the sentinel is one field of the user's config, not a file of its own.
+
+    The file is never *created* here. ``ConfigGenerator`` owns the "materialise a
+    full default config" step, and creating a config stub before it runs would
+    make that step see an existing file and skip the defaults (#202's half-built
+    ``.wl`` shape). When there is no record to update, the write still stands --
+    the next successful write will record it, and until then the value is
+    recognised as ``wl``'s own by equality with the expected absolute path.
+
+    Returns:
+        True when the record already held ``value`` or was updated; False when
+        the config could not be read/written. A False is not fatal: the value on
+        disk is already the one ``wl`` wanted, so the worst case is that the
+        record is attempted again on the next write.
+    """
+    config_file = deploy_root.wl_dir() / "config.json"
+    try:
+        with open(config_file, encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            return False
+        if data.get(HOOKS_PATH_SENTINEL_KEY) == value:
+            return True
+        data[HOOKS_PATH_SENTINEL_KEY] = value
+        # Same serialisation as `_update_config_version` (wl_dir_updater): indent=2,
+        # raw non-ASCII, trailing newline -- one house format for this file.
+        with open(config_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        return True
+    except (OSError, json.JSONDecodeError):
+        return False
+
+
+def _main_worktree_path() -> Path | None:
+    """The main worktree's checkout path, or None when git cannot say.
+
+    ``git worktree list --porcelain`` documents the main worktree as the first
+    entry. Used only by :func:`_inherited_from_main`.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    prefix = "worktree "
+    for line in result.stdout.splitlines():
+        if line.startswith(prefix):
+            return Path(line[len(prefix) :])
+    return None
+
+
+def _same_path(left: Path, right: Path) -> bool:
+    """Whether two paths name the same directory, tolerating spelling aliases."""
+    try:
+        return left.resolve() == right.resolve()
+    except (OSError, RuntimeError):
+        return left == right
+
+
+def _inherited_from_main(current: str, deploy_root: Root) -> bool:
+    """Whether ``current`` is wl's own value **copied in by ``git worktree add``**.
+
+    Git copies the main worktree's ``config.worktree`` into every new linked
+    worktree (verified on git 2.56 by inspecting the file before any write).
+    With the extension on that copy includes our ``core.hooksPath``, so a
+    freshly created worktree starts with the MAIN checkout's absolute path and,
+    because its ``.wl`` is a fresh checkout, no local sentinel.
+
+    Treating that value as a stranger would leave the new worktree pointing at
+    another checkout's hooks forever -- the exact "wrong checkout's hooks"
+    failure #276 removes. The main worktree's sentinel is what tells the copy
+    apart from a value a human set: only an exact match is adopted, and
+    rewriting it then changes only wl's own pointer.
+
+    Quiet and cheap: called only when the value is neither unset, the local
+    sentinel, nor the expected path, i.e. never on a converged worktree.
+    """
+    main = _main_worktree_path()
+    if main is None or _same_path(main, deploy_root.path):
+        return False
+    main_sentinel = _read_hooks_path_sentinel(Root(main, RootKind.WORKTREE))
+    return main_sentinel is not None and main_sentinel == current
+
+
+def _worktree_hooks_path_is_ours(
+    current: str | None,
+    sentinel: str | None,
+    worktree_hooks_path: str,
+    deploy_root: Root,
+) -> bool:
+    """Whether the worktree-scoped ``core.hooksPath`` may be rewritten (#274/#276).
+
+    The ticket's rule, applied to the **worktree** scope: "current value is
+    empty, or equal to the sentinel". Two equality shortcuts are added, both
+    describing a value ``wl`` itself wrote and therefore unable to overwrite
+    anybody else's intent:
+
+    * ``current == worktree_hooks_path`` -- exactly what a write would produce
+      for this worktree. Allowing the write only records the claim (and repairs
+      a directory that went missing). This covers a ``config.json`` whose
+      sentinel was lost while the pointer itself is still correct.
+    * ``current == the MAIN worktree's sentinel`` -- the value ``git worktree
+      add`` copied from the main checkout's ``config.worktree`` (see
+      :func:`_inherited_from_main`). Without this, every worktree created after
+      the main checkout was claimed would start with the main checkout's path
+      and be stuck pointing at it.
+
+    Unlike the shared-value rule this replaces, there is **no** legacy-absolute
+    or ``.wl/hooks``-literal shortcut: no released ``wl`` ever wrote the
+    worktree scope, so a value there came either from somebody else or from
+    git's copy of wl's own shared-with-main setting.
+
+    Everything else -- a dangling path, a directory belonging to another tool, a
+    hand-edited value -- is a value ``wl`` did not write and must not silently
+    replace.
+    """
+    if current is None:
+        return True
+    if current == sentinel or current == worktree_hooks_path:
+        return True
+    return _inherited_from_main(current, deploy_root)
+
+
+def _hash_file(path: Path) -> str:
+    """SHA-256 of a file's bytes; empty string when unreadable."""
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return ""
+
+
+def _read_hook_marker(path: Path) -> str | None:
+    """Return the :data:`_HOOK_MARKER_PREFIX` marker *value* in ``path``'s head.
+
+    Reads at most the first 512 bytes -- the window the cheap gate has always
+    used -- and returns the text after the marker prefix (stripped), or ``None``
+    when the file is unreadable or carries no marker line. Comparing this value
+    (not merely the prefix) is what lets a template whose *body* changed under
+    an un-bumped marker trip :func:`hooks_need_sync` (#158/B3); a prefix-only
+    check could never see that drift.
+    """
+    try:
+        head = path.read_bytes()[:512].decode("utf-8", errors="replace")
+    except OSError:
+        return None
+    for line in head.splitlines():
+        if _HOOK_MARKER_PREFIX in line:
+            return line.split(_HOOK_MARKER_PREFIX, 1)[1].strip()
+    return None
+
+
+def _sync_known_hooks(
+    hooks_src: Path,
+    hooks_dest: Path,
+    *,
+    changed_files: list[str] | None = None,
+    pruned: list[str] | None = None,
+) -> bool:
+    """Copy known hooks that are missing or differ from the template.
+
+    A known hook that the template no longer ships is pruned from the
+    destination. Unknown files in hooks_dest are never touched.
+
+    ``changed_files`` / ``pruned``, when supplied, receive the names involved in
+    this same pass -- copied/updated, and removed respectively -- so
+    :func:`apply_hook_sync` can report *what* changed without a second hash
+    sweep (#161: the verdict is computed once). Both are optional so the plain
+    2-argument form keeps its "did anything change?" contract.
+
+    Returns:
+        True if any hook file changed (copied, updated, or pruned).
+    """
+    changed = False
+
+    for hook_name in KNOWN_HOOKS:
+        src = hooks_src / hook_name
+        dest = hooks_dest / hook_name
+
+        if src.exists():
+            if not dest.exists() or _hash_file(src) != _hash_file(dest):
+                shutil.copy2(src, dest)
+                dest.chmod(0o755)
+                changed = True
+                if changed_files is not None:
+                    changed_files.append(hook_name)
+        else:
+            # Template no longer ships this known hook -> prune installed copy
+            if dest.exists():
+                dest.unlink()
+                changed = True
+                if pruned is not None:
+                    pruned.append(hook_name)
+
+    return changed
+
+
+def _log_shared_fallback_note() -> None:
+    """Tell the user, once per claim, that a shared value is still around (#276).
+
+    ADR-0009 decision 2 keeps the shared ``core.hooksPath`` byte-for-byte as it
+    was: it remains the fallback for checkouts that never ran this ``wl``
+    version, and cleaning it up is the human's call. Printing the value and the
+    exact removal command here is the "cleanup lives in the log, not in a new
+    subcommand" half of that decision.
+
+    Quiet when the shared config has no value (the common case).
+    """
+    shared = _get_shared_hooks_path()
+    if shared is None:
+        return
+    log_info_pair(
+        f"The shared (repository-wide) core.hooksPath still holds {shared!r}; "
+        "wl leaves it unchanged as a fallback for checkouts that have not run "
+        "wl. This worktree's own value takes precedence here. Remove the shared "
+        "value with `git config --unset core.hooksPath` once no checkout "
+        "depends on it.",
+        f"共享 core.hooksPath 仍为 {shared!r}；wl 原样保留，作为尚未运行过 wl 的"
+        "检出的回退。本 worktree 自己的值在此处优先。待无检出依赖它时，可用 "
+        "`git config --unset core.hooksPath` 清除。",
+    )
+
+
+def _configure_git_hooks_path(worktree_hooks_path: str, deploy_root: Root) -> bool:
+    """Point **this worktree's** ``core.hooksPath`` at the wl-managed directory.
+
+    Writes ``worktree_hooks_path`` -- the locator's absolute deploy path
+    (:attr:`HookSource.worktree_hooks_path`), never a string in the shared
+    config -- with ``git config --worktree`` (ADR-0009, superseding ADR-0005).
+    Because the value lives in the per-worktree config it is removed together
+    with the worktree: deleting a linked checkout can no longer leave every
+    other checkout pointing at a directory that is gone.
+
+    The shared config is left exactly as it was, with one deliberate exception:
+    ``extensions.worktreeConfig=true`` must be set for a per-worktree config to
+    exist at all, so :func:`_ensure_worktree_config` turns it on -- read-first,
+    one time. Any pre-existing shared ``core.hooksPath`` stays as a fallback and
+    :func:`_log_shared_fallback_note` reports it with its removal command.
+
+    The write is idempotent: the same absolute path is stored every time, so a
+    worktree whose value already matches is never written again. A worktree
+    whose value is ``wl``'s own but stale -- the worktree was moved, or the
+    hooks directory vanished -- is repointed once by
+    :func:`hooks_path_is_stale`'s verdict.
+
+    The worktree-scoped value shadows any shared one for this checkout only.
+    That is intended: the shared legacy value is somebody's fallback, not this
+    worktree's pointer.
+
+    **Never overwrites a value ``wl`` did not write** (#274 in the worktree
+    scope, #276 decision 4). The current *worktree-scoped* value is read before
+    writing and passed through :func:`_worktree_hooks_path_is_ours`: empty or
+    equal to the sentinel ``wl`` recorded in ``.wl/config.json`` -> write;
+    anything else -> leave it untouched and print one line naming the value, the
+    config file that supplies it (``git config --worktree --show-origin``) and
+    how to hand the pointer to ``wl``.
+
+    ``deploy_root`` anchors the sentinel (``<deploy_root>/.wl/config.json``) --
+    each worktree records its own value under its own ``.wl``. It is required: a
+    default would let a caller write a record into a ``.wl`` other than the one
+    the pointer describes.
+
+    Returns:
+        True when the git config write succeeded; False when it was skipped
+        (not inside a git work tree), the worktree config could not be enabled,
+        git refused the write, or the value on disk belongs to somebody else.
+    """
+    # The gate is "did the WORKTREE lookup resolve to a real work tree?" --
+    # i.e. is there a checkout for git to run the hooks from at all. Outside one
+    # the deploy root is the project-root fallback, which no repository's config
+    # should be pointed at.
+    if not _is_git_work_tree():
+        # Nothing to configure (e.g. a non-git directory): stay quiet.
+        log_debug_pair(
+            "Skipping core.hooksPath configuration (not a git work tree).",
+            "跳过 core.hooksPath 配置（不在 git 工作树中）。",
+        )
+        return False
+
+    # Enable the per-worktree config *before* reading or writing it: a
+    # `--worktree` write without the extension lands in the shared config, which
+    # is precisely the defect #276 removes.
+    if not _ensure_worktree_config():
+        return False
+
+    # The ownership gate (#274/#276). Reading the current value here costs one
+    # `git config --get --worktree` -- but only on a write attempt, which is
+    # rare (a first claim, a hook-file change, or a stale path), never on the
+    # converged per-command path.
+    current = _get_worktree_hooks_path()
+    sentinel = _read_hooks_path_sentinel(deploy_root)
+    if not _worktree_hooks_path_is_ours(
+        current, sentinel, worktree_hooks_path, deploy_root
+    ):
+        origin = _worktree_hooks_path_origin()
+        # One line, English + Chinese, per the ticket: what the value is, which
+        # config file supplies it, and the explicit way to hand it to wl. That
+        # value itself is *not* unset and not modified.
+        log_info_pair(
+            f"core.hooksPath is set to {current!r} by "
+            f"{origin or 'an unknown scope'} in this worktree's config; wl does "
+            "not overwrite it. To let wl manage git hooks here, run "
+            "`git config --worktree --unset core.hooksPath` and re-run wl.",
+            f"本 worktree 的 core.hooksPath 已由 {origin or '未知作用域'} 设为 "
+            f"{current!r}；wl 不会覆盖它。若要在本 worktree 让 wl 接管钩子，请先执行 "
+            "`git config --worktree --unset core.hooksPath`，再重跑 wl。",
+        )
+        return False
+
+    try:
+        subprocess.run(
+            ["git", "config", "--worktree", "core.hooksPath", worktree_hooks_path],
+            check=True,
+            capture_output=False,
+        )
+        # Record what wl just wrote, so the next run can tell it from a value
+        # somebody else sets later. A failure to record is not a failed write:
+        # the value on disk is already wl's (see the helper's contract).
+        _record_hooks_path_sentinel(deploy_root, worktree_hooks_path)
+        _log_shared_fallback_note()
+        log_debug_pair(
+            f"✓ Configured Git to use custom hooks directory: {worktree_hooks_path}",
+            f"✓ 配置Git使用自定义钩子目录: {worktree_hooks_path}",
+        )
+        return True
+    except subprocess.CalledProcessError as e:
+        log_info_pair(
+            f"Warning: Failed to configure custom hooks directory: {e}",
+            f"警告: 配置自定义钩子目录失败: {e}",
+        )
+        return False
+    except Exception as e:
+        log_info_pair(
+            f"Warning: Failed to configure custom hooks directory: {e}",
+            f"警告: 配置自定义钩子目录失败: {e}",
+        )
+        return False
+
+
+def _log_missing_hooks_directory(source: HookSource) -> None:
+    """Log warning if the located template directory is missing (#162).
+
+    The "missing" verdict is the locator's explicit
+    :attr:`HookSource.template_missing` -- never a fallback to another
+    platform's directory.
+    """
+    if source.template_missing:
+        log_info_pair(
+            f"  Warning: Hooks template directory not found at {source.template_dir}",
+            f"  警告: 未找到hooks模板目录 {source.template_dir}",
+        )
+
+
+def hooks_path_is_stale(
+    worktree_hooks_path: str, deploy_root: Root | None = None
+) -> bool:
+    """Whether this worktree's ``core.hooksPath`` needs ``wl`` to (re)write it.
+
+    Read-only. ``worktree_hooks_path`` is the expected absolute value, supplied
+    by the caller from the locator (:attr:`HookSource.worktree_hooks_path`) so
+    the comparison side names the value exactly where the write side does
+    (#162).
+
+    **Only the worktree scope is consulted (#276).** The effective value would
+    also match a legacy shared ``core.hooksPath`` -- and writing because of it
+    is exactly what ADR-0009 forbids (the shared config is not ``wl``'s to
+    change). The read is ``git config --get --worktree core.hooksPath``, so a
+    shared value is invisible here; it stays as the fallback it always was.
+
+    **Ownership first (#274).** A worktree value that was not written by ``wl``
+    is not stale: it is somebody else's, and asking for a rewrite would ask for
+    exactly what the ticket forbids. The value counts as ``wl``'s own when it is
+    unset, equal to the sentinel recorded in ``.wl/config.json``, or equal to the
+    path ``wl`` would write -- see :func:`_worktree_hooks_path_is_ours`. Anything
+    else answers False: no write is attempted, and a pointer ``wl`` has decided
+    to leave alone is not reported as stale on every command either.
+
+    For a value that *is* ``wl``'s own, it is stale when either holds:
+
+    * the **raw** configured string is not exactly ``worktree_hooks_path``
+      (e.g. the path of the checkout before it was moved/renamed) -- repoint it
+      once;
+    * the expected directory does not exist (a first claim whose deploy has not
+      happened yet, or a moved repository).
+
+    The first test compares the raw ``git config --get --worktree`` output
+    against the expected value with **neither side normalised**. The expected
+    value is already absolute, so there is no "every run rewrites" trap: a value
+    produced by a write compares equal to itself forever, and any other spelling
+    converges in one write.
+
+    ``deploy_root`` anchors the sentinel. The sync chain passes the root it
+    already resolved; direct callers may omit it, and this single-root entry then
+    resolves exactly the one root it needs through
+    :func:`~wl_cli.utils.root_fallback.current_root` -- the same compatibility
+    pattern as :func:`hooks_need_sync` (#160).
+
+    Outside a git work tree this always reports False. Nothing can be configured
+    there, and a machine-wide ``core.hooksPath`` (from ``~/.gitconfig`` or the
+    system config) would otherwise look stale forever: reported on every ``wl``
+    run, retried on every ``wl`` run, and never repairable.
+
+    Cost: inside a git work tree this is two git subprocesses (``rev-parse
+    --show-toplevel`` and ``config --get --worktree``) plus one read of
+    ``.wl/config.json``; outside one it is a single ``rev-parse``.
+    """
+    # Also the "can we repair anything here?" guard for the branch below: a
+    # global core.hooksPath is visible via `git config --get` even outside a
+    # repository, and is not ours to fix.
+    if _git_top_level() is None:
+        return False
+
+    current = _get_worktree_hooks_path()
+    if current is None:
+        # Unclaimed: wl may claim it, and there is nothing of anybody else's to
+        # preserve.
+        return True
+
+    if deploy_root is None:
+        deploy_root = current_root(RootKind.DEPLOY)
+    sentinel = _read_hooks_path_sentinel(deploy_root)
+    if not _worktree_hooks_path_is_ours(
+        current, sentinel, worktree_hooks_path, deploy_root
+    ):
+        # Somebody else's pointer: not stale, because "stale" would authorise a
+        # write that `_configure_git_hooks_path` must refuse anyway.
+        return False
+
+    if current != worktree_hooks_path:
+        # wl's own value in another spelling (a moved/renamed worktree): one
+        # rewrite to the expected absolute path, then it matches.
+        return True
+
+    # The value is the expected path; ask whether it actually points at a
+    # directory. It is absolute, so git's work-tree-relative resolution rules do
+    # not apply -- `Path.is_dir()` is the same question git asks.
+    return not Path(worktree_hooks_path).is_dir()
+
+
+@dataclass(frozen=True)
+class HookSyncState:
+    """Hook-staleness verdict computed once by :func:`evaluate_hooks` (#161).
+
+    Replaces the old ``bool`` from ``hooks_need_sync``: :func:`apply_hook_sync`
+    consumes this value, so the ``core.hooksPath`` probe paid for here is never
+    repeated inside the sync.
+    """
+
+    #: Known hooks absent from the deployed directory (sorted).
+    missing: tuple[str, ...]
+    #: The deployed pre-push's version marker is absent or differs in *value*
+    #: from the vendored template's (#158/B3).
+    marker_stale: bool
+    #: ``core.hooksPath`` is not the wl-managed directory (see
+    #: :func:`hooks_path_is_stale`). Always known: the probe runs even when a
+    #: hook is already missing/marker-stale, so there is no ``None``/"unknown"
+    #: state for the applier to resolve.
+    path_stale: bool
+
+    @property
+    def needs_sync(self) -> bool:
+        """Whether any of the three conditions fired."""
+        return bool(self.missing) or self.marker_stale or self.path_stale
+
+
+@dataclass(frozen=True)
+class SyncReport:
+    """What :func:`apply_hook_sync` actually changed (#161).
+
+    Keeping the outcomes separate is what makes "only the path was repaired"
+    assertable through the public interface: ``path_repaired is True`` with
+    ``files_changed is False`` and ``pruned == ()``.
+
+    That is an *outcome* distinction, not a diagnosis: any file change --
+    including a prune-only pass -- also attempts to write ``core.hooksPath``
+    (see :func:`apply_hook_sync`), so ``path_repaired is True`` only means that
+    write succeeded. It does **not** mean the path was stale, and outside a git
+    work tree the write is not even attempted
+    (``_configure_git_hooks_path`` returns ``False`` and writes nothing).
+    """
+
+    #: A known hook was copied or updated from the template.
+    files_changed: bool
+    #: ``core.hooksPath`` was (re)written successfully. Attempted whenever *any*
+    #: known hook file changed (copy/update **or** a prune-only pass) as well as
+    #: when the evaluated path was stale, so ``True`` here does not imply the
+    #: path had been stale. ``_configure_git_hooks_path`` returns ``False``
+    #: outside a git work tree, where nothing is written and this stays
+    #: ``False``; see :func:`apply_hook_sync`.
+    path_repaired: bool
+    #: Known hooks removed because the template no longer ships them (sorted).
+    pruned: tuple[str, ...] = ()
+
+    @property
+    def changed(self) -> bool:
+        """Whether anything at all changed."""
+        return self.files_changed or self.path_repaired or bool(self.pruned)
+
+
+def evaluate_hooks(deploy_root: Root) -> HookSyncState:
+    """Evaluate hook staleness once, in full (#161).
+
+    Reports the three conditions the old ``hooks_need_sync`` bool collapsed:
+
+    * ``missing`` -- which of :data:`KNOWN_HOOKS` is absent from
+      ``<deploy_root>/.wl/hooks``;
+    * ``marker_stale`` -- the deployed ``pre-push``'s version marker is missing
+      or differs from the vendored template's. The comparison is on the marker
+      **value** -- the text after :data:`_HOOK_MARKER_PREFIX` -- not merely the
+      prefix's presence: a template whose body changed is expected to bump that
+      value, and the value comparison is what turns such a bump into a real
+      re-sync (#158/B3). The template's marker is consulted only once the
+      deployed hook has one; an unreadable template (e.g. an install whose
+      located ``template_dir`` is missing) keeps the old prefix-present verdict
+      rather than forcing a sync that could not repair anything;
+    * ``path_stale`` -- :func:`hooks_path_is_stale` (the *worktree-scoped*
+      value is unset, dangling, or not exactly the absolute deploy path, for a
+      value ``wl`` owns). A value somebody else set in the worktree config is
+      never stale: #274 forbids overwriting it, so reporting staleness would
+      only authorise a write the applier must refuse. Outside a git work tree
+      this is always False.
+
+    The path probe runs even when a hook is already known missing or
+    marker-stale. That is the deliberate choice recorded on #161: one git
+    subprocess buys a *complete* state, so the applier never re-probes and the
+    state never has to represent "unknown".
+
+    Coverage is deliberately narrow: of :data:`KNOWN_HOOKS` only ``pre-push``
+    carries a version marker, so the value comparison above guards that hook
+    alone. A body change to ``pre-commit`` / ``check_lockfile.py`` /
+    ``check_lockfile.sh`` under an unchanged marker is therefore invisible *to
+    this gate* -- but it is bounded, not silent: :func:`apply_hook_sync` runs
+    unconditionally on every ``wl`` release (``wl_dir_updater``) and compares
+    every known hook by hash, so such a drift survives at most one release.
+    Widening the comparison to all of :data:`KNOWN_HOOKS` means extending the
+    marker protocol to three more vendored templates (a shared prefix, a bump
+    rule, one re-sync of every deployed copy), which is a protocol change rather
+    than a docstring one; #159/m2 states the coverage instead of making it.
+
+    Cost: two 512-byte reads (deployed + template) and one path probe -- one or
+    two git subprocesses (~a few ms) -- on every ``wl`` command. No hook file is
+    hashed.
+    """
+    # One locator call supplies both directories: the deploy directory the gate
+    # inspects and the template the marker is read from (#162).
+    source = locate_hook_source(deploy_root)
+    hooks_dir = source.deploy_dir
+
+    missing = tuple(
+        hook_name
+        for hook_name in sorted(KNOWN_HOOKS)
+        if not (hooks_dir / hook_name).exists()
+    )
+
+    marker_stale = False
+    pre_push = hooks_dir / "pre-push"
+    if pre_push.exists():
+        deployed_marker = _read_hook_marker(pre_push)
+        if deployed_marker is None:
+            marker_stale = True
+        else:
+            template_marker = _read_hook_marker(source.template_dir / "pre-push")
+            if template_marker is not None and template_marker != deployed_marker:
+                marker_stale = True
+
+    # Always probed: see the docstring. This is the single call site of
+    # hooks_path_is_stale on the sync path -- apply_hook_sync consumes the value
+    # instead of asking git again (#161).
+    path_stale = hooks_path_is_stale(source.worktree_hooks_path, deploy_root)
+
+    return HookSyncState(
+        missing=missing,
+        marker_stale=marker_stale,
+        path_stale=path_stale,
+    )
+
+
+def apply_hook_sync(state: HookSyncState, deploy_root: Root) -> SyncReport:
+    """Apply an already evaluated :class:`HookSyncState` (#161).
+
+    1. Copies known hook templates from the located template directory into the
+       deploy directory when they are missing or differ from the template
+       (hash-based).
+    2. Prunes known hooks the template no longer ships.
+    3. Attempts to point **this worktree's** ``git config --worktree
+       core.hooksPath`` at :attr:`HookSource.worktree_hooks_path` (the absolute
+       ``.wl/hooks`` deploy path, ADR-0009) when the hook files changed OR
+       ``state.path_stale`` -- so a pure path fault (a moved worktree, a moved
+       repository, a hand-edited config) is repaired even though no hook file
+       changed. *Any* hook-file change counts, including a prune-only pass, so a
+       ``True`` :attr:`SyncReport.path_repaired` records a successful write, not
+       a stale-path diagnosis. Outside a git work tree
+       ``_configure_git_hooks_path`` returns ``False`` and nothing is written.
+
+       The write is additionally gated on ownership (#274 in the worktree
+       scope, #276): when the current worktree-scoped ``core.hooksPath`` was not
+       written by ``wl`` (not empty, not the sentinel in ``.wl/config.json``,
+       not the exact path wl would write), the pointer is left exactly as it is
+       and one explanatory line is logged. A file-change pass still deploys the
+       hook files in that case -- only that pointer is somebody else's to decide.
+
+    Steps 1-2 are skipped entirely when the located
+    :attr:`HookSource.template_missing` is set: a missing template directory is
+    "cannot tell", never "the template ships no hooks", and pruning on it would
+    delete every deployed known hook off a broken install. The warning is still
+    logged, and a stale ``core.hooksPath`` is still repaired.
+
+    Both directories, and the literal written to ``core.hooksPath``, come from
+    :func:`locate_hook_source` -- the single definition of where hooks come
+    from and go (#162).
+
+    It never calls :func:`hooks_path_is_stale`: the verdict is the one
+    :func:`evaluate_hooks` already paid for, which is the recomputation this
+    change removes.
+
+    The file sync always runs, even when ``state.needs_sync`` is False, for the
+    same reason the old ``sync_hooks`` did: it is the hash-based safety net that
+    catches body drift in the hooks carrying no version marker, on the release
+    path.
+    """
+    # Check for Git Bash (only runs on Windows)
+    check_git_bash_installed()
+
+    source = locate_hook_source(deploy_root)
+    source.deploy_dir.mkdir(parents=True, exist_ok=True)
+    # ``source.worktree_hooks_path`` is the same absolute deploy path in git's
+    # spelling; creating it above makes that path real before the pointer is
+    # written.
+
+    # Copy/prune known hooks (hash-aware), recording what moved in this pass.
+    copied: list[str] = []
+    pruned: list[str] = []
+    any_file_change = False
+    if source.template_missing:
+        # A missing template directory says nothing about which hooks the
+        # installation *ships*: ``_sync_known_hooks`` would read every absent
+        # ``src`` as "the template no longer ships this hook" and prune all four
+        # deployed hooks off a broken install. Warn and leave the deploy
+        # directory exactly as it is. The flag is this call's snapshot, not a
+        # fresh stat, so it cannot change between this branch and the warning
+        # just below -- but ``evaluate_hooks`` located its own, earlier, snapshot
+        # independently, so the two calls may still disagree if the template
+        # directory changed between them.
+        _log_missing_hooks_directory(source)
+    else:
+        any_file_change = _sync_known_hooks(
+            source.template_dir,
+            source.deploy_dir,
+            changed_files=copied,
+            pruned=pruned,
+        )
+
+    # (Re)configure the path when the files changed or the evaluated path was
+    # stale. ``state.path_stale`` replaces the old in-sync probe. The absolute
+    # path comes from the locator's field -- the same value the comparison side
+    # used, so write and compare cannot drift apart.
+    path_repaired = False
+    if any_file_change or state.path_stale:
+        # ``bool`` keeps the report a plain boolean even when a caller stubs
+        # the helper with a truthy object.
+        path_repaired = bool(
+            _configure_git_hooks_path(source.worktree_hooks_path, deploy_root)
+        )
+
+    return SyncReport(
+        files_changed=bool(copied),
+        path_repaired=path_repaired,
+        pruned=tuple(sorted(pruned)),
+    )
+
+
+def hooks_need_sync(deploy_root: Root | None = None) -> bool:
+    """Per-command hook staleness check, as a bool (compatibility wrapper).
+
+    Equivalent to ``evaluate_hooks(deploy_root).needs_sync`` (#161). Kept for
+    callers that only need the yes/no; code that will also sync should call
+    :func:`evaluate_hooks` once and hand the state to :func:`apply_hook_sync`.
+
+    ``deploy_root`` is threaded through as a value by the self-sync chain, which
+    no longer chdirs to the deploy root; when it is omitted the single deploy
+    root this check needs is resolved from :func:`current_root` -- once, at this
+    public entry (#160).
+    """
+    if deploy_root is None:
+        deploy_root = current_root(RootKind.DEPLOY)
+    return evaluate_hooks(deploy_root).needs_sync
+
+
+def sync_hooks(deploy_root: Root | None = None) -> bool:
+    """Sync known git hooks for the project (compatibility wrapper).
+
+    Evaluates **once** (:func:`evaluate_hooks`), applies that same state
+    (:func:`apply_hook_sync`), and returns ``report.changed`` -- so the
+    ``core.hooksPath`` probe is not repeated inside the sync (#161). The work
+    it performs:
+
+    1. Copies known hook templates from the located template directory into the
+       deploy directory when they are missing or differ from it (hash-based).
+    2. Prunes known hooks the template no longer ships.
+    3. Points this worktree's ``git config --worktree core.hooksPath`` at
+       :attr:`HookSource.worktree_hooks_path` (the absolute ``.wl/hooks``
+       deploy path, ADR-0009) when the hook files changed OR the configured path
+       is stale -- so a pure path fault (a moved worktree, a moved repository, a
+       hand-edited config) is repaired even though no hook file changed.
+
+    ``deploy_root`` is the root the hook files are deployed under, threaded in
+    as a value by the self-sync chain (which no longer chdirs to it); when it is
+    omitted the deploy root comes from :func:`current_root`, resolved once at
+    this public entry (#160).
+
+    Upgrade note (#276): the first ``wl`` run after the upgrade enables
+    ``extensions.worktreeConfig`` (once) and claims the empty worktree scope
+    with this checkout's absolute path -- two ``git config`` writes. The shared
+    config's old ``core.hooksPath`` is left untouched as a fallback; later runs
+    find the worktree value matching and write nothing.
+
+    Returns:
+        True if any hook file changed or the git hooks path was (re)configured.
+    """
+    if deploy_root is None:
+        deploy_root = current_root(RootKind.DEPLOY)
+    state = evaluate_hooks(deploy_root)
+    return apply_hook_sync(state, deploy_root).changed