From 74c45bac7ffacfa65fe8d0351f114ef64e43a266 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 10 Jul 2026 00:16:53 -0700
Subject: [PATCH] docs(worktrees): explain create fetch maintenance scope

---
 src/main/ipc/worktree-remote.ts  | 1 +
 src/main/runtime/orca-runtime.ts | 1 +
 2 files changed, 2 insertions(+)

diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 6217a3338da..43ef357eed6 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -478,6 +478,7 @@ async function refreshRemoteTrackingBaseForWorktreeCreate(
     getSshWorktreeCreateBaseFetchKey(repo, base),
     getSshWorktreeCreateRemoteQueueKey(repo, base.remote),
     () =>
+      // Why: the exact-base refresh gates create; unrelated repo housekeeping must not extend it.
       provider.fetchRemoteTrackingRef(repo.path, base.remote, base.branch, base.ref, {
         skipAutoMaintenance: true
       })
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index c7e55378c2f..fc8ede96bae 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -14621,6 +14621,7 @@ export class OrcaRuntimeService {
       if (this.getFreshFetchCompletedAt(key) !== null) {
         return { ok: true }
       }
+      // Why: this exact refresh gates worktree create; ordinary fetches still own maintenance.
       return gitExecFileAsync(
         [
           ...GIT_FETCH_SKIP_AUTO_MAINTENANCE_CONFIG_ARGS,