claude-dev-env 8.83.1 → 8.84.0

package/docs/account-broker.md

@@ -6,7 +6,7 @@ Claude's main home is `~/.claude`. Its `claude-chain.json` file contains a `chai
 
 The optional `claude-account-order.json` file in the main home sets the Claude pick priority. It is a JSON list of account names, first choice first, such as `["claude-second", "claude"]`. An entry matches an account's name, its command, or its `claude-<name>` launcher, and `claude` names the main account. A new job goes to the first listed account with room. When no listed account has room, the broker picks the unlisted account with the most room, and it waits when no account has room. A resumed session stays on its bound account while that account has room. A listed name absent from the roster is skipped. Without the file, every job goes to the account with the most room. Edit the file to change the order; the next pick reads it.
 
-Codex uses its configured account roster. When no Codex roster is configured, the broker chooses the default Codex home.
+Codex uses its configured account roster. When no Codex roster is configured, the broker chooses the default Codex home. A new Codex job goes to an account on a Pro plan before any other account in the same tier. The plan comes from the account's meter reply, and `ALL_PRO_PLAN_TYPES` lists the Pro plans: `pro`, `prolite`, and `promax`. Among accounts of the same kind, the one with the most room wins. A Pro account below the `normal` floor still loses to any account with room in the `normal` tier.
 
 ## Commands
 

package/docs/codex-accounts.md

@@ -91,8 +91,8 @@ A window that reports no length counts as weekly.
 
 | Condition | Answer |
 |---|---|
-| One or more accounts with more than 10% left | `normal` on the account with the most room |
-| No account over 10%, one or more over 1% | `luna` on the account with the most room |
+| One or more accounts with more than 10% left | `normal` on a Pro plan account (`pro`, `prolite` and `promax`) before any other account in this tier; among accounts of the same kind, the one with the most room |
+| No account over 10%, one or more over 1% | `luna` on a Pro plan account (`pro`, `prolite` and `promax`) before any other account in this tier; among accounts of the same kind, the one with the most room |
 | An account that reports a window shorter than a week, such as the 5-hour window, with under 20% of that window left | never takes `luna` |
 | No account over 1% | `wait`, naming the next reset when known |
 | A meter read fails | The broker reads it again, up to 3 reads, waiting 1 second and then 2 seconds |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.83.1",
+    "version": "8.84.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/Sync-RepoMain.ps1

@@ -189,6 +189,35 @@ function Invoke-AdoptCopiedTree {
     return $false
 }
 
+function Get-RunLockName {
+    $lockPath = [System.IO.Path]::TrimEndingDirectorySeparator([System.IO.Path]::GetFullPath($RepoPath))
+    $resolveLinkTarget = [System.IO.Directory].GetMethod('ResolveLinkTarget', [type[]]([string], [bool]))
+    if ((Test-Path -LiteralPath $lockPath) -and ($null -ne $resolveLinkTarget)) {
+        $finalTarget = [System.IO.Directory]::ResolveLinkTarget($lockPath, $true)
+        if ($null -ne $finalTarget) {
+            $lockPath = [System.IO.Path]::TrimEndingDirectorySeparator($finalTarget.FullName)
+        }
+    }
+    $pathBytes = [System.Text.Encoding]::UTF8.GetBytes($lockPath.ToLowerInvariant())
+    $pathHash = [System.Convert]::ToHexString([System.Security.Cryptography.SHA256]::HashData($pathBytes))
+    return "Global\SyncRepoMain-$pathHash"
+}
+
+$runLock = [System.Threading.Mutex]::new($false, (Get-RunLockName))
+try {
+    $hasRunLock = $runLock.WaitOne(0)
+}
+catch [System.Threading.AbandonedMutexException] {
+    $hasRunLock = $true
+}
+if (-not $hasRunLock) {
+    Write-SyncLog -Level 'SKIP' -Message "another sync of $RepoPath is still running"
+    exit 3
+}
+
+$env:GIT_TERMINAL_PROMPT = '0'
+$env:GCM_INTERACTIVE = 'never'
+
 try {
     if (-not (Test-Path -LiteralPath $RepoPath)) {
         Write-SyncLog -Level 'ERROR' -Message "repo path missing: $RepoPath"
@@ -212,7 +241,7 @@ try {
         exit 3
     }
 
-    $null = Invoke-GitOrExit -Arguments @('fetch', $Remote, $Branch) `
+    $null = Invoke-GitOrExit -Arguments @('-c', 'http.lowSpeedLimit=1000', '-c', 'http.lowSpeedTime=60', 'fetch', $Remote, $Branch) `
         -FailureMessage "fetch $Remote $Branch failed" -FailureExitCode 1
 
     $tipOutput = Invoke-GitOrExit -Arguments @('rev-parse', $Branch, "$Remote/$Branch") `

package/scripts/account_broker_support.py

@@ -315,6 +315,7 @@ def read_codex_account_meters(account: Account) -> Meters:
         short_window.resets_at if short_window else None,
         FULL_PERCENT - weekly_window.used_percent if weekly_window else None,
         weekly_window.resets_at if weekly_window else None,
+        usage.plan_type,
     )
 
 
@@ -500,6 +501,7 @@ def _meter_payload(meters: Meters | None) -> dict[str, object] | None:
         "session_resets_at": utc_time_text(meters.session_resets_at),
         "weekly_percent_left": meters.weekly_percent_left,
         "weekly_resets_at": utc_time_text(meters.weekly_resets_at),
+        "plan_type": meters.plan_type,
     }
 
 
@@ -509,7 +511,14 @@ def _meters_from_payload(raw_meters: object) -> Meters | None:
     all_percentages = (raw_meters.get("session_percent_left"), raw_meters.get("weekly_percent_left"))
     if any(each_percent is not None and not isinstance(each_percent, (int, float)) for each_percent in all_percentages):
         return None
-    return Meters(all_percentages[0], parse_utc_time(raw_meters.get("session_resets_at")), all_percentages[1], parse_utc_time(raw_meters.get("weekly_resets_at")))
+    plan_type = raw_meters.get("plan_type")
+    return Meters(
+        all_percentages[0],
+        parse_utc_time(raw_meters.get("session_resets_at")),
+        all_percentages[1],
+        parse_utc_time(raw_meters.get("weekly_resets_at")),
+        plan_type if isinstance(plan_type, str) else None,
+    )
 
 
 def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict[str, object], now: datetime) -> tuple[Reading, bool]:

package/scripts/codex_account_meters.py

@@ -4,10 +4,13 @@
 Codex reports usage through ``codex app-server`` and the JSON-RPC method
 ``account/rateLimits/read``. The reply names up to two windows, a short one
 (5 hours) and a weekly one. The account broker counts the account's room as
-the smaller of the two::
+the smaller of the two. The reply also names the account's plan, such as
+``pro`` or ``team``::
 
     5-hour window 30% used, week 85% used  -> 15% left
     week window only, 40% used             -> 60% left
+    planType "promax"                      -> plan_type "promax"
+    no planType                            -> plan_type None
     no window, error reply, no reply       -> CodexMeterUnreadError
 
 Every read failure raises ``CodexMeterUnreadError``. A missing Codex
@@ -92,9 +95,10 @@ class UsageWindow:
 
 @dataclass(frozen=True)
 class CodexAccountMeters:
-    """One account's windows, with its tightest short window and its tightest weekly window."""
+    """One account's windows and plan, with its tightest short window and its tightest weekly window."""
 
     all_windows: tuple[UsageWindow, ...]
+    plan_type: str | None = None
 
     @property
     def short_window(self) -> UsageWindow | None:
@@ -176,14 +180,16 @@ def parse_rate_limits_reply(reply_text: str) -> CodexAccountMeters:
     ::
 
         {"id": 2, "result": {"rateLimits": {"primary": {"usedPercent": 30, ...},
-                                            "secondary": {"usedPercent": 85, ...}}}}
-        -> CodexAccountMeters with two windows, 15% left
+                                            "secondary": {"usedPercent": 85, ...},
+                                            "planType": "promax"}}}
+        -> CodexAccountMeters with two windows, 15% left, plan_type "promax"
+        the same reply without "planType" -> plan_type None
 
     Args:
         reply_text: One line the ``codex app-server`` process wrote.
 
     Returns:
-        The windows the reply carries.
+        The windows and the plan type the reply carries.
 
     Raises:
         CodexMeterUnreadError: The line is no reply, an error reply, or names
@@ -197,7 +203,8 @@ def parse_rate_limits_reply(reply_text: str) -> CodexAccountMeters:
     )
     if not all_windows:
         raise CodexMeterUnreadError("rate-limit reply names no usage window")
-    return CodexAccountMeters(all_windows=all_windows)
+    plan_type = rate_limits.get("planType")
+    return CodexAccountMeters(all_windows=all_windows, plan_type=plan_type if isinstance(plan_type, str) else None)
 
 
 def request_messages() -> list[dict[str, object]]:

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -20,6 +20,7 @@ from dev_env_scripts_constants.claude_account_constants import (
     SECOND_WEEKLY_USED_CEILING_PERCENT,
 )
 from dev_env_scripts_constants.codex_account_constants import (
+    ALL_PRO_PLAN_TYPES,
     CODEX_HOME_ENVIRONMENT_VARIABLE,
     LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
     LUNA_TIER_STOP_PERCENT_LEFT,
@@ -193,6 +194,7 @@ class Meters:
     session_resets_at: datetime | None
     weekly_percent_left: float | None
     weekly_resets_at: datetime | None
+    plan_type: str | None = None
 
     @property
     def tightest_percent_left(self) -> float | None:
@@ -313,10 +315,11 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
     return max(all_known_resets, default=None)
 
 
-def _rank_key(reading: Reading) -> tuple[bool, int, float]:
+def _rank_key(reading: Reading) -> tuple[bool, int, bool, float]:
     room = reading.meters.tightest_percent_left if reading.meters else None
     priority = reading.account.priority
-    return (priority is None, priority or 0, -(room if room is not None else -1.0))
+    is_pro_plan = reading.meters is not None and reading.meters.plan_type in ALL_PRO_PLAN_TYPES
+    return (priority is None, priority or 0, not is_pro_plan, -(room if room is not None else -1.0))
 
 
 def _main_has_room(meters: Meters | None) -> bool:

package/scripts/dev_env_scripts_constants/codex_account_constants.py

@@ -99,6 +99,9 @@ LUNA_TIER_STOP_PERCENT_LEFT: float = 1.0
 LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT: float = 20.0
 """An account with a window shorter than a week runs Luna only with this much of it left."""
 
+ALL_PRO_PLAN_TYPES: frozenset[str] = frozenset({"pro", "prolite", "promax"})
+"""Plan types of a personal Codex Pro subscription. The broker tries these accounts first."""
+
 WEEKLY_WINDOW_MINUTES: int = 10080
 """Length of the weekly window. Any shorter window is a short window, such as 5 hours."""
 

package/scripts/dev_env_scripts_constants/test_codex_account_constants.py

@@ -86,9 +86,14 @@ def test_tier_bars_match_the_documented_table() -> None:
     normal_bar = documented_percent(constants.NORMAL_TIER_MINIMUM_PERCENT_LEFT)
     luna_stop = documented_percent(constants.LUNA_TIER_STOP_PERCENT_LEFT)
     luna_short_window_floor = documented_percent(constants.LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT)
+    pro_plans = documented_list(sorted(constants.ALL_PRO_PLAN_TYPES))
+    pro_preference = (
+        f"on a Pro plan account ({pro_plans}) before any other account in this tier; "
+        "among accounts of the same kind, the one with the most room"
+    )
     all_expected_rows = [
-        f"| One or more accounts with more than {normal_bar} left | `{constants.TIER_NORMAL}` on the account with the most room |",
-        f"| No account over {normal_bar}, one or more over {luna_stop} | `{constants.TIER_LUNA}` on the account with the most room |",
+        f"| One or more accounts with more than {normal_bar} left | `{constants.TIER_NORMAL}` {pro_preference} |",
+        f"| No account over {normal_bar}, one or more over {luna_stop} | `{constants.TIER_LUNA}` {pro_preference} |",
         f"| An account that reports a window shorter than a week, such as the 5-hour window, with under {luna_short_window_floor} of that window left | never takes `{constants.TIER_LUNA}` |",
         f"| No account over {luna_stop} | `{constants.TIER_WAIT}`, naming the next reset when known |",
     ]

package/scripts/test_account_broker.py

@@ -58,12 +58,14 @@ def _meters(
     *,
     short_reset: datetime | None = None,
     weekly_reset: datetime | None = None,
+    plan_type: str | None = None,
 ) -> Meters:
     return Meters(
         short_left,
         short_reset or NOW + timedelta(hours=5),
         weekly_left,
         weekly_reset or NOW + timedelta(days=3),
+        plan_type,
     )
 
 
@@ -125,6 +127,30 @@ def test_should_put_unread_accounts_after_readable_accounts() -> None:
     assert decision.account == readings[1].account
 
 
+def test_should_pick_a_pro_plan_account_over_a_roomier_team_account() -> None:
+    readings = (
+        Reading(_account("team-mel"), _meters(90, 85, plan_type="team")),
+        Reading(_account("personal"), _meters(40, 30, plan_type="promax")),
+    )
+
+    decision = choose_from_readings(Product.CODEX, readings, now=NOW)
+
+    assert decision.account == readings[1].account
+    assert decision.tier == "normal"
+
+
+def test_should_pick_a_team_account_in_the_normal_tier_over_a_pro_plan_account_below_the_floor() -> None:
+    readings = (
+        Reading(_account("personal"), _meters(50, 8, plan_type="pro")),
+        Reading(_account("team-jon"), _meters(40, 30, plan_type="team")),
+    )
+
+    decision = choose_from_readings(Product.CODEX, readings, now=NOW)
+
+    assert decision.account == readings[1].account
+    assert decision.tier == "normal"
+
+
 def test_should_keep_list_order_when_tighter_windows_tie() -> None:
     readings = (
         Reading(_account("first"), _meters(40, 60)),

package/scripts/test_account_broker_support.py

@@ -192,7 +192,8 @@ def test_should_read_codex_meters_through_injected_reader(
             UsageWindow(300, 20.0, short_reset),
             UsageWindow(10080, 30.0, None),
             UsageWindow(None, 50.0, unknown_length_reset),
-        )
+        ),
+        plan_type="promax",
     )
     monkeypatch.setattr(support.codex_account_meters, "resolve_codex_path", lambda _: tmp_path / "codex")
     monkeypatch.setattr(support.codex_account_meters, "read_codex_meters", lambda *_: usage)
@@ -203,6 +204,19 @@ def test_should_read_codex_meters_through_injected_reader(
     assert meters.session_resets_at == short_reset
     assert meters.weekly_percent_left == 50.0
     assert meters.weekly_resets_at == unknown_length_reset
+    assert meters.plan_type == "promax"
+
+
+def test_should_keep_the_plan_through_the_cached_meter_payload() -> None:
+    meters = Meters(80.0, None, 70.0, None, "pro")
+
+    assert support._meters_from_payload(support._meter_payload(meters)) == meters
+
+
+def test_should_load_a_cached_meter_payload_saved_without_a_plan() -> None:
+    old_payload = {"session_percent_left": 80.0, "session_resets_at": None, "weekly_percent_left": 70.0, "weekly_resets_at": None}
+
+    assert support._meters_from_payload(old_payload) == Meters(80.0, None, 70.0, None, None)
 
 
 def _codex_meter_reads(

package/scripts/test_codex_account_meters.py

@@ -65,6 +65,16 @@ class TestParseRateLimitsReply:
         )
         assert [each.used_percent for each in meters.all_windows] == [40.0]
 
+    def should_read_the_plan_type_beside_the_windows(self) -> None:
+        meters = parse_rate_limits_reply(
+            reply_line({"primary": {"usedPercent": 40}, "planType": "promax"})
+        )
+        assert meters.plan_type == "promax"
+
+    def should_read_a_reply_without_a_plan_type(self) -> None:
+        meters = parse_rate_limits_reply(reply_line({"primary": {"usedPercent": 40}}))
+        assert meters.plan_type is None
+
     def should_clamp_used_percent_past_full(self) -> None:
         meters = parse_rate_limits_reply(reply_line({"primary": {"usedPercent": 130}}))
         assert [each.used_percent for each in meters.all_windows] == [100.0]

package/scripts/tests/Sync-RepoMain.Tests.ps1

@@ -105,4 +105,29 @@ Describe 'Sync-RepoMain' {
         [System.IO.File]::ReadAllText((Join-Path $fixture.MirrorPath 'added.txt')) | Should -Be "local only`n"
         [System.IO.File]::ReadAllText((Join-Path $fixture.MirrorPath 'tracked.txt')) | Should -Be "new`n"
     }
+
+    It 'skips without fetching while another sync of the same repo holds the run lock' {
+        $fixture = New-MirrorBehindRemote -Name 'lock-held'
+        $lockPath = [System.IO.Path]::TrimEndingDirectorySeparator([System.IO.Path]::GetFullPath($fixture.MirrorPath))
+        $pathBytes = [System.Text.Encoding]::UTF8.GetBytes($lockPath.ToLowerInvariant())
+        $lockName = 'Global\SyncRepoMain-' + [System.Convert]::ToHexString([System.Security.Cryptography.SHA256]::HashData($pathBytes))
+        $readyPath = Join-Path $TestDrive 'lock-ready'
+        $holderCommand = "`$lock = [System.Threading.Mutex]::new(`$true, '$lockName'); Set-Content -LiteralPath '$readyPath' -Value ready; Start-Sleep -Seconds 30"
+        $holder = Start-Process pwsh -ArgumentList '-NoProfile', '-Command', $holderCommand -PassThru
+        try {
+            $deadline = (Get-Date).AddSeconds(20)
+            while (-not (Test-Path -LiteralPath $readyPath) -and (Get-Date) -lt $deadline) {
+                Start-Sleep -Milliseconds 200
+            }
+
+            $exitCode = Invoke-SyncScript -Fixture $fixture
+        }
+        finally {
+            Stop-Process -Id $holder.Id -Force -ErrorAction SilentlyContinue
+        }
+
+        $exitCode | Should -Be 3
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('rev-parse', 'HEAD')) | Should -Be $fixture.OldTip
+        (Get-Content -LiteralPath $fixture.LogPath -Raw) | Should -Match 'still running'
+    }
 }

package/scripts/tests/test_sync_repo_main_run_lock.py

@@ -0,0 +1,168 @@
+"""Specifications for Sync-RepoMain skipping while another run of the same repo is live."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+_SCRIPT_PATH = Path(__file__).resolve().parents[1] / "Sync-RepoMain.ps1"
+_PWSH = shutil.which("pwsh") or "pwsh"
+_SKIPPED_EXIT_CODE = 3
+_SUCCESS_EXIT_CODE = 0
+_LOCK_READY_TIMEOUT_SECONDS = 20
+
+
+def _git(repository_path: Path, *arguments: str) -> str:
+    completed = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repository_path),
+            "-c",
+            "user.name=tester",
+            "-c",
+            "user.email=tester@example.com",
+            *arguments,
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def _mirror_one_commit_behind(root_path: Path) -> Path:
+    remote_path = root_path / "remote.git"
+    author_path = root_path / "author"
+    mirror_path = root_path / "mirror"
+    remote_path.mkdir()
+    author_path.mkdir()
+    _git(remote_path, "init", "-q", "--bare", "-b", "main")
+    _git(author_path, "init", "-q", "-b", "main")
+    (author_path / "tracked.txt").write_text("old\n", encoding="utf-8")
+    _git(author_path, "add", "-A")
+    _git(author_path, "commit", "-q", "-m", "first")
+    _git(author_path, "remote", "add", "origin", str(remote_path))
+    _git(author_path, "push", "-q", "origin", "main")
+    subprocess.run(
+        ["git", "clone", "-q", str(remote_path), str(mirror_path)], check=True
+    )
+    (author_path / "tracked.txt").write_text("new\n", encoding="utf-8")
+    _git(author_path, "commit", "-q", "-am", "second")
+    _git(author_path, "push", "-q", "origin", "main")
+    return mirror_path
+
+
+def _run_lock_name(mirror_path: Path) -> str:
+    normalized_path = os.path.normpath(str(mirror_path)).lower()
+    path_digest = hashlib.sha256(normalized_path.encode("utf-8")).hexdigest().upper()
+    return f"Global\\SyncRepoMain-{path_digest}"
+
+
+def _run_sync(mirror_path: Path, log_path: Path, repo_path: str | None = None) -> int:
+    argument_path = str(mirror_path) if repo_path is None else repo_path
+    completed = subprocess.run(
+        [
+            _PWSH,
+            "-NoProfile",
+            "-File",
+            str(_SCRIPT_PATH),
+            "-RepoPath",
+            argument_path,
+            "-LogPath",
+            str(log_path),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    return completed.returncode
+
+
+def test_should_skip_without_fetching_while_another_run_holds_the_lock(
+    tmp_path: Path,
+) -> None:
+    mirror_path = _mirror_one_commit_behind(tmp_path)
+    old_tip = _git(mirror_path, "rev-parse", "HEAD")
+    log_path = tmp_path / "sync.log"
+    ready_path = tmp_path / "lock-ready"
+    holder_command = (
+        f"$lock = [System.Threading.Mutex]::new($true, '{_run_lock_name(mirror_path)}'); "
+        f"Set-Content -LiteralPath '{ready_path}' -Value ready; Start-Sleep -Seconds 30"
+    )
+    holder = subprocess.Popen([_PWSH, "-NoProfile", "-Command", holder_command])
+    try:
+        deadline = time.monotonic() + _LOCK_READY_TIMEOUT_SECONDS
+        while not ready_path.exists() and time.monotonic() < deadline:
+            time.sleep(0.2)
+        held_exit_code = _run_sync(mirror_path, log_path)
+    finally:
+        holder.kill()
+        holder.wait()
+
+    assert held_exit_code == _SKIPPED_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") == old_tip
+    assert "still running" in log_path.read_text(encoding="utf-8")
+
+    assert _run_sync(mirror_path, log_path) == _SUCCESS_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") != old_tip
+
+
+def test_should_skip_a_second_spelling_of_the_same_repo(tmp_path: Path) -> None:
+    mirror_path = _mirror_one_commit_behind(tmp_path)
+    old_tip = _git(mirror_path, "rev-parse", "HEAD")
+    ready_path = tmp_path / "lock-ready"
+    holder_command = (
+        f"$lock = [System.Threading.Mutex]::new($true, '{_run_lock_name(mirror_path)}'); "
+        f"Set-Content -LiteralPath '{ready_path}' -Value ready; Start-Sleep -Seconds 30"
+    )
+    holder = subprocess.Popen([_PWSH, "-NoProfile", "-Command", holder_command])
+    try:
+        deadline = time.monotonic() + _LOCK_READY_TIMEOUT_SECONDS
+        while not ready_path.exists() and time.monotonic() < deadline:
+            time.sleep(0.2)
+        assert ready_path.exists()
+        spellings = (
+            f"{mirror_path}{os.sep}",
+            os.path.join(str(mirror_path), "."),
+        )
+        for spelling in spellings:
+            spelling_log = tmp_path / "spelling.log"
+            spelling_log.unlink(missing_ok=True)
+            exit_code = _run_sync(mirror_path, spelling_log, repo_path=spelling)
+            assert exit_code == _SKIPPED_EXIT_CODE
+            assert _git(mirror_path, "rev-parse", "HEAD") == old_tip
+            assert "still running" in spelling_log.read_text(encoding="utf-8")
+    finally:
+        holder.kill()
+        holder.wait()
+
+
+def test_should_skip_when_the_repo_path_is_a_symlink(tmp_path: Path) -> None:
+    mirror_path = _mirror_one_commit_behind(tmp_path)
+    old_tip = _git(mirror_path, "rev-parse", "HEAD")
+    link_path = tmp_path / "mirror-link"
+    os.symlink(mirror_path, link_path, target_is_directory=True)
+    log_path = tmp_path / "sync.log"
+    ready_path = tmp_path / "lock-ready"
+    holder_command = (
+        f"$lock = [System.Threading.Mutex]::new($true, '{_run_lock_name(mirror_path)}'); "
+        f"Set-Content -LiteralPath '{ready_path}' -Value ready; Start-Sleep -Seconds 30"
+    )
+    holder = subprocess.Popen([_PWSH, "-NoProfile", "-Command", holder_command])
+    try:
+        deadline = time.monotonic() + _LOCK_READY_TIMEOUT_SECONDS
+        while not ready_path.exists() and time.monotonic() < deadline:
+            time.sleep(0.2)
+        assert ready_path.exists()
+        exit_code = _run_sync(mirror_path, log_path, repo_path=str(link_path))
+    finally:
+        holder.kill()
+        holder.wait()
+
+    assert exit_code == _SKIPPED_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") == old_tip
+    assert "still running" in log_path.read_text(encoding="utf-8")