@gitkraken/core-gitlens 0.5.113 → 0.5.115

package/docs/integrations.md

@@ -113,28 +113,34 @@ provider before calling the token backend; never reuse an id discovered under a
 Every read returns `ProviderResult<T>` (`items` + `warnings` + `fetchFailed?`), and every paged read extends
 it with `page` + `hasMore` + `cursor?`. **No read throws for a provider-side failure** — see §6.
 
-| Method                       | Returns                   | Scope                                                                                 |
-| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------- |
-| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups; issue-tracker resources (Jira sites, …).                  |
-| `listProjects`               | `ProviderOrganization`    | The project tier: Azure DevOps, and issue-tracker projects.                           |
-| `listRepos`                  | `ProviderRepositoryShape` | Repos of an `org`, or account-wide user-affiliated repos when `org` is omitted.       |
-| `listPullRequestsPage`       | `PullRequestShape`        | With `repos`: those repos' PRs. Without: the user's PRs account-wide.                 |
-| `searchPullRequestsPage`     | `PullRequestShape`        | PRs involving the user that match structured criteria, optionally repo/org-scoped.    |
-| `countPullRequests`          | `PullRequestCountResult`  | How many PRs match each scope, fetching none of them. See §5.1.                       |
-| `listIssuesPage`             | `IssueShape`              | Same split, for a **git host**'s issues.                                              |
-| `searchIssuesPage`           | `IssueShape`              | Issues matching structured criteria over a repo/org scope — **no** `@me` binding.     |
-| `countIssues`                | `IssueCountResult`        | How many match each scope, fetching none of them. See §5.1.                           |
-| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira / Linear / Trello (issues live under resource → project).                        |
-| `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                     |
-| `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                |
-| `broadenIssues`              | `ProviderBroadenResult`   | Per-org fan-out: list the org's repos, then read their issues unfiltered by assignee. |
-| `resolveRepository`          | `ResolveRepositoryResult` | Remote URL → canonical provider identity (the `gk repo resolve` equivalent).          |
-| `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                      |
+| Method                       | Returns                   | Scope                                                                                   |
+| ---------------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
+| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups; issue-tracker resources (Jira sites, …).                    |
+| `listProjects`               | `ProviderOrganization`    | The project tier: Azure DevOps, and issue-tracker projects.                             |
+| `listRepos`                  | `ProviderRepositoryShape` | Repos of an `org`, or account-wide user-affiliated repos when `org` is omitted.         |
+| `listPullRequestsPage`       | `PullRequestShape`        | With `repos`: those repos' PRs. Without: the user's PRs account-wide.                   |
+| `searchPullRequestsPage`     | `PullRequestShape`        | PRs involving the user that match structured criteria, optionally repo/org-scoped.      |
+| `countPullRequests`          | `PullRequestCountResult`  | How many PRs match each scope, fetching none of them. See §5.1.                         |
+| `listIssuesPage`             | `IssueShape`              | Same split, for a **git host**'s issues.                                                |
+| `searchIssuesPage`           | `IssueShape`              | Issues matching structured criteria over a repo/org scope — **no** `@me` binding.       |
+| `countIssues`                | `IssueCountResult`        | How many match each scope, fetching none of them. See §5.1.                             |
+| `getIssuesBatch`             | `IssueBatchResult`        | Resolves N `(owner, repo, number)` coordinates in one request; an absence is proven.    |
+| `getTrackerIssue`            | `TrackerIssueResult`      | Resolves ONE tracker issue by key within a resource; an absence is proven. Jira/Linear. |
+| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira / Linear / Trello (issues live under resource → project).                          |
+| `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                       |
+| `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                  |
+| `broadenIssues`              | `ProviderBroadenResult`   | Per-org fan-out for every visible issue, unfiltered by assignee.                        |
+| `resolveRepository`          | `ResolveRepositoryResult` | Remote URL → canonical provider identity (the `gk repo resolve` equivalent).            |
+| `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                        |
 
 A provider that cannot serve a surface says so explicitly — a warning explaining that the operation is
 unsupported plus `fetchFailed`, never a silent empty page. That distinction is the whole point of the result
 shape: an empty `items` with no warning means "this account genuinely has nothing".
 
+`getTrackerIssue` takes `resourceId` for both supported trackers. Jira also takes `resourceUrl`, the site URL
+returned by `listOrgs`; the REST response only supplies an API `self` link, so the caller provides the already-known
+site identity rather than making this point read perform resource discovery. Linear does not need it.
+
 ## 5. Paging
 
 Two mechanisms live behind one shape, and they are **not** interchangeable:
@@ -330,7 +336,9 @@ on it without parsing `message`:
 if (warning.omission != null) {
 	// The read SUCCEEDED — message it as incompleteness, not failure.
 	// Whether anything would fetch the rest is a separate question; see `recovery` below.
-	if (warning.omission.recovery !== 'none') offerLoadMore(warning.omission);
+	// Switch on the VALUE. `!== 'none'` is not "fetchable": `narrow-scope` is not.
+	if (warning.omission.recovery === 'page-budget') offerLoadMore(warning.omission);
+	else if (warning.omission.recovery === 'narrow-scope') suggestNarrowingTheScope(warning.omission);
 }
 ```
 
@@ -360,19 +368,22 @@ mid-read left an unread tail too, but a retry may complete it — that one carri
 a provider that gave no usable cursor are the same kind, but only the first can be fetched. Gate a "load more"
 affordance on `recovery`, never on `kind`:
 
-| `omission.recovery` | Means                                                          | What a consumer does                                                       |
-| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `none`              | Nothing you can call returns the missing items.                | Say the results are capped. Do not offer to fetch more.                    |
-| `page-budget`       | Re-run the same read with a higher `maxPages` (sweep options). | Offer it — but note it re-reads from the start, so make it user-initiated. |
+| `omission.recovery` | Means                                                                                    | What a consumer does                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `none`              | Nothing you can call returns the missing items.                                          | Say the results are capped. Do not offer to fetch more.                    |
+| `page-budget`       | Re-run the same read with a higher `maxPages` (sweep options).                           | Offer it — but note it re-reads from the start, so make it user-initiated. |
+| `narrow-scope`      | A smaller server-side scope can avoid the backstop; no budget or retry reaches the rest. | Suggest narrowing the scope. Do **not** offer to fetch more.               |
 
 `recovery` is **required** — unlike `limit`, `totalCount` and `scope`, it is never absent. An absent value
 would be indistinguishable from `none` while actually meaning "this producer didn't say", which is the
 ambiguity `omission` exists to remove.
 
 It is also **conservative**: it names only what a producer can prove, so `none` means "not known to be
-recoverable", not "proven unrecoverable". Today only a sweep that spent its own page budget reports
-`page-budget`; everything else — every provider cap, every exhausted internal budget, and every omission
-derived from SDK metadata — is `none`. A `scope` does not change that. It attributes where results were
+recoverable", not "proven unrecoverable". Only a sweep that spent its own page budget reports `page-budget`, and
+only a broad Jira project query that provably stopped at its own page backstop reports `narrow-scope`.
+Already-scoped Jira reads and Linear reads use `none` when they emit an omission because changing the public
+scope cannot make those provider requests narrower. Other caps and exhausted budgets also use `none`; a stalled
+cursor or failed page may instead be a failure with no omission. A `scope` does not change that. It attributes where results were
 withheld, and the SDK reports the same scoped shape both for a scope it merely sampled and for one whose
 cursor stalled, so re-reading it is not something this layer can promise.
 
@@ -523,8 +534,10 @@ Derived from the provider models and `providersMetadata`. ✓ supported · ✗ r
 | `countPullRequests`          |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
 | Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
 | Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
-| `searchIssuesPage`           |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
-| `countIssues`                |      ✓       |          ✗           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| `searchIssuesPage`           |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| `countIssues`                |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| `getTrackerIssue`            |      ✗       |          ✗           |     ✗     |      ✗       |            ✗            |  ✓   |   ✓    |   ✗    |
 | Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |  ✓   |   ✓    |   ✓    |
 | `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |  ✓   |   ✓    |   ✓    |
 | `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  ✗   |   ✗    |   ✗    |
@@ -604,12 +617,14 @@ free text have no equivalent on either.
   recovered. `hasMore` reports only untouched forward progress. A cursor can therefore remain with
   `hasMore: false`; reusing it is an explicit manual retry of failed work, not a normal paging loop.
 
-**`broadenIssues` vs `searchIssuesPage`.** If you already know your repository set, prefer
-`searchIssuesPage({ repos })`: `broadenIssues` has to discover each org's repositories first (a paged drain)
-and then reads their issues through the SDK path with the recovery walk, so it costs strictly more for the
-same answer. It remains the read for "fan out across these orgs, whatever repos they turn out to contain",
-with per-provider attribution (`broadenedProviderIds` / `failedProviderIds` / `incompleteProviderIds`) that
-the single-provider search doesn't produce.
+**`broadenIssues` vs `searchIssuesPage`.** `broadenIssues` now reads each org through the org-scoped
+filtered search where the provider declares one (GitHub/GHE), so it no longer discovers repositories first
+and no longer routes through the SDK read's recovery walk — one request per page, per org. A provider with
+no filtered search (Azure DevOps, GitLab) still takes the repository drain, since refusing the org would be
+worse. It remains the read for "fan out across these orgs, whatever repos they turn out to contain", with
+per-provider attribution (`broadenedProviderIds` / `failedProviderIds` / `incompleteProviderIds`) that the
+single-provider search doesn't produce; reach for `searchIssuesPage` when you want ONE scope with an order
+you control.
 
 If you do migrate: broaden means **all visible** — it drops the assignee constraint entirely, so unassigned
 issues are included. The equivalent is therefore an **omitted** `relationships`, **not**

package/docs/kepler-read-api-parity.md

@@ -168,11 +168,32 @@ searches, so the reported count is the **largest** of them (the total `searchPul
 via `Math.max` over facets), not their sum, and `exceedsProviderLimit` compares that max against the per-search
 ceiling. GitHub/GHE only, matching `searchPullRequestsPage`.
 
-**Not done, deliberately:** `broadenIssues` was left as-is rather than reimplemented on top of this. It is a
-multi-provider, multi-org fan-out with its own result type and per-org cursor bundle, so only its inner
-per-org read could be swapped; and its "all visible" breadth maps to an OMITTED relationship set, not to
-`any-assignee`, which excludes unassigned issues. See the note in `reads/broaden.ts` and
+**Since done:** `broadenIssues`' inner per-org read WAS swapped onto the filtered search (#5804). Only that
+inner read changed — the fan-out keeps its own result type, per-org cursor bundle and per-provider
+attribution — and its "all visible" breadth maps to an OMITTED relationship set, not to `any-assignee`,
+which excludes unassigned issues. A provider that declares no filtered search keeps the repository drain.
+See the note in `reads/broaden.ts` and
 [`integrations.md` §9](./integrations.md#9-per-provider-behavior-worth-designing-around).
 
+**Batch issue resolution (#5802).** `getIssuesBatch` resolves N `(owner, repo, number)` coordinates in one
+request, for the identity question a search cannot answer: "which issue does this branch name reference".
+It aliases the point read rather than a search, so there is no result ceiling and no ordering — and an
+absent slot is a PROVEN absence rather than "not found within a page budget", which is what lets a consumer
+CACHE a miss. A target whose chunk failed is not returned at all, so the two stay distinguishable; caching a
+failure as an absence is the bug that distinction prevents. GitHub/GHE only, matching `countIssues`.
+
+**Tracker issue resolution by key (#5810).** `getTrackerIssue` is the same identity read for an issue TRACKER,
+which `getIssuesBatch` cannot serve: its target is `(owner, repo, number)`, and a tracker issue is addressed by
+`(resourceId, ABC-123)` — no owner, no repo, and an identifier that is not a number. It answers in one request
+where the only published tracker surface (`listIssueTrackerIssuesPage`) needs a scoped page-walk that cannot
+prove absence without draining the whole scope. Same absence/failure contract as the batch read, and the same
+reason it matters: a tracker miss is the common outcome and was never cacheable.
+
+`resourceId` is required and trusted, so the read performs no resource discovery. Jira also requires
+`resourceUrl`, obtained alongside the resource ID, because the issue response's `self` is an API endpoint rather
+than a browser link; supplying both retains the one-request contract. Linear needs only the resource ID. Jira and
+Linear only; Trello refuses because its single-issue read can fall back to a capped board scan for a numeric
+identifier, where a "not found" result cannot be distinguished from a card beyond the cap.
+
 **Kepler-side follow-up:** `ProviderScopeFilter` carries a single `repo?: string` today and needs the criteria
 set; the `provider-data` adapter then routes "All visible" to `searchIssuesPage` + `countIssues`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gitkraken/core-gitlens",
   "description": "GitLens core — shared Git / AI / GitHub primitives for internal GitKraken consumption",
-  "version": "0.5.113",
+  "version": "0.5.115",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "engines": {
-    "node": ">= 22.12.0"
+    "node": ">= 24"
   },
   "type": "module",
   "sideEffects": false,
@@ -83,6 +83,10 @@
       "types": "./dist/git/features.d.ts",
       "default": "./dist/git/features.js"
     },
+    "./git/gitHealth.js": {
+      "types": "./dist/git/gitHealth.d.ts",
+      "default": "./dist/git/gitHealth.js"
+    },
     "./git/models/*.js": {
       "types": "./dist/git/models/*.d.ts",
       "default": "./dist/git/models/*.js"
@@ -131,6 +135,10 @@
       "types": "./dist/ipc/ipcServer.d.ts",
       "default": "./dist/ipc/ipcServer.js"
     },
+    "./plus/agents/agentCapabilities.js": {
+      "types": "./dist/plus/agents/agentCapabilities.d.ts",
+      "default": "./dist/plus/agents/agentCapabilities.js"
+    },
     "./plus/agents/providers/*.js": {
       "types": "./dist/plus/agents/providers/*.d.ts",
       "default": "./dist/plus/agents/providers/*.js"
@@ -228,9 +236,9 @@
     }
   },
   "dependencies": {
-    "@gitkraken/provider-apis": "0.57.0",
+    "@gitkraken/provider-apis": "0.58.0",
     "@octokit/graphql": "9.0.4",
-    "@octokit/request": "10.0.13",
+    "@octokit/request": "10.0.14",
     "@octokit/request-error": "7.1.1",
     "@octokit/types": "17.0.0",
     "fast-string-truncated-width": "3.0.3",

package/src/git/cache.ts

@@ -7,6 +7,7 @@ import { normalizePath } from '../utils/path.js';
 import type { PromiseOrValue } from '../utils/promise.js';
 import type { CacheController } from '../utils/promiseCache.js';
 import { PromiseCache, PromiseMap, RepoPromiseCacheMap } from '../utils/promiseCache.js';
+import type { ResourceUsage } from '../utils/resourceUsage.js';
 import type { Uri } from '../utils/uri.js';
 import type { ProgressiveGitBlame } from './models/blame.js';
 import type { BranchMetadata, GitBranch } from './models/branch.js';
@@ -82,6 +83,24 @@ export type ConflictDetectionCacheKey =
  */
 const baseBranchNameTTL = 5 * 60 * 1000; // 5 minutes
 
+/**
+ * Completed blame graphs retain several objects and substrings per line. Keep normal files hot, but let large
+ * documents be owned by their active tracked-document snapshot instead of retaining a second long-lived owner.
+ */
+const maxCachedBlameLines = 5000;
+
+export async function shouldEvictBlameCacheEntry(progressive: ProgressiveGitBlame | undefined): Promise<boolean> {
+	if (progressive == null) return false;
+
+	try {
+		const blame = await progressive.completed;
+		return blame.lines.length > maxCachedBlameLines;
+	} catch {
+		// The provider factory resolves as soon as streaming starts, so a later stream failure must also be retried.
+		return true;
+	}
+}
+
 /**
  * gkConfig keys that participate in the `branchOverviews` cache's mergeTarget/mergeBase lineage.
  * Capture group 1 is the ref name (which may itself contain `.`/`/`).
@@ -266,6 +285,23 @@ export class Cache implements Disposable {
 		this.reset();
 	}
 
+	/** Resource usage retained by instantiated sub-caches and their bookkeeping maps. */
+	getResourceUsage(): ResourceUsage {
+		const usage: ResourceUsage = {};
+		for (const [name, cache] of Object.entries(this._caches)) {
+			if (cache != null) {
+				usage[`cache.${name}.entries.count`] =
+					cache instanceof RepoPromiseCacheMap ? cache.entryCount : cache.size;
+			}
+		}
+		usage['cache.commonPathRegistry.entries.count'] = this._commonPathRegistry.size;
+		usage['cache.worktreesByCommonPath.entries.count'] = this._worktreesByCommonPath.size;
+		usage['cache.statusGenerations.entries.count'] = this._statusGenerations.size;
+		usage['cache.closeGenerations.entries.count'] = this._closeGenerations.size;
+		usage['cache.gkConfigMergeSnapshots.entries.count'] = this._gkConfigMergeSnapshots.size;
+		return usage;
+	}
+
 	get bestRemotes(): PromiseMap<RepoPath, GitRemote<RemoteProvider>[]> {
 		return (this._caches.bestRemotes ??= new PromiseMap<RepoPath, GitRemote<RemoteProvider>[]>());
 	}

package/src/git/context.ts

@@ -76,6 +76,11 @@ export interface GitServiceConfig {
 
 	/** Graph-specific configuration defaults. */
 	readonly graph?: {
+		/** Whether to keep git's commit-graph file up to date in the background after graph loads —
+		 *  written when missing, periodically refreshed to cover new commits (accelerates ordered
+		 *  history walks — the graph's initial load). Fed from the master switch
+		 *  (`gitlens.gitOptimizations.enabled`); `false` disables the background write. */
+		readonly writeCommitGraph?: boolean;
 		/** Graph commit ordering (falls back to `commits.ordering` or `'date'`). */
 		readonly commitOrdering?: 'date' | 'author-date' | 'topo';
 		/** Whether to only follow first parent in graph. */
@@ -86,6 +91,12 @@ export interface GitServiceConfig {
 		readonly maxSearchItems?: number;
 	};
 
+	/** Auto-tier git-optimization (maintenance) preferences. */
+	readonly maintenance?: {
+		/** Master switch for the auto-tier optimizations (maps to `gitlens.gitOptimizations.enabled`). Defaults to `true`. */
+		readonly enabled?: boolean;
+	};
+
 	/** Force-push preferences. */
 	readonly push?: {
 		/** Whether to use `--force-with-lease` instead of a plain `--force` when force-pushing. Defaults to `true`. */

package/src/git/errors.ts

@@ -68,12 +68,18 @@ export abstract class GitCommandError<Details extends { gitCommand?: GitCommandC
 	}
 }
 
+export type GitSearchErrorReason = 'invalidPattern' | 'invalidRef';
+
 export class GitSearchError extends Error {
 	static is(ex: unknown): ex is GitSearchError {
 		return ex instanceof GitSearchError;
 	}
 
-	constructor(public readonly original: Error) {
+	constructor(
+		public readonly original: Error,
+		public readonly reason?: GitSearchErrorReason,
+		public readonly detail?: string,
+	) {
 		super(original.message);
 
 		Error.captureStackTrace?.(this, new.target);
@@ -451,6 +457,7 @@ export class PausedOperationAbortError extends GitCommandError<PausedOperationAb
 export type PausedOperationContinueErrorReason =
 	| 'conflicts'
 	| 'emptyCommit'
+	| 'messageEditFailed'
 	| 'nothingToContinue'
 	| 'uncommittedChanges'
 	| 'unmergedFiles'
@@ -483,6 +490,8 @@ export class PausedOperationContinueError extends GitCommandError<PausedOperatio
 				return `Cannot ${details.skip ? 'skip' : 'continue'} the ${details.operation.type} operation as there are unresolved conflicts`;
 			case 'emptyCommit':
 				return `Cannot ${details.skip ? 'skip' : 'continue'} the ${details.operation.type} operation as the previous commit is empty`;
+			case 'messageEditFailed':
+				return `Cannot ${details.skip ? 'skip' : 'continue'} the ${details.operation.type} operation as a commit message needs to be edited and the editor could not be opened`;
 			case 'nothingToContinue':
 				return `Cannot ${details.skip ? 'skip' : 'continue'} the ${details.operation.type} operation as there is no ${details.operation.type} in progress`;
 			case 'uncommittedChanges':
@@ -868,6 +877,7 @@ export type TagErrorReason =
 	| 'notFound'
 	| 'permissionDenied'
 	| 'remoteRejected'
+	| 'tagConflict'
 	| 'other';
 interface TagErrorDetails {
 	reason?: TagErrorReason;
@@ -906,6 +916,8 @@ export class TagError extends GitCommandError<TagErrorDetails> {
 				return `${baseMessage} because you don't have permission to push to this remote repository.`;
 			case 'remoteRejected':
 				return `${baseMessage} because the remote repository rejected the push.`;
+			case 'tagConflict':
+				return `${baseMessage} because the remote already has a tag with that name. Use force to overwrite it.`;
 			default:
 				return baseMessage;
 		}

package/src/git/features.ts

@@ -1,19 +1,32 @@
 // GitFeature's must start with `git:` to be recognized in all usages
 export type GitFeatures =
 	| 'git:checkout:pathspec-from-file'
+	| 'git:commit-graph'
+	| 'git:commit-graph:changed-paths'
 	| 'git:for-each-ref:worktreePath'
+	| 'git:fsmonitor'
+	| 'git:fsmonitor:linux'
 	| 'git:ignoreRevsFile'
+	| 'git:index:skipHash'
+	| 'git:maintenance'
+	| 'git:maintenance:pack-refs'
+	| 'git:maintenance:start'
+	| 'git:maintenance:start:systemd'
+	| 'git:manyFiles'
 	| 'git:merge-tree'
 	| 'git:merge-tree:write-tree'
 	| 'git:push:force-if-includes'
+	| 'git:rebase:autosquash'
 	| 'git:rev-parse:end-of-options'
 	| 'git:signing:ssh'
 	| 'git:signing:x509'
+	| 'git:sparse-index'
 	| 'git:stash:push:pathspecs'
 	| 'git:stash:push:staged'
 	| 'git:stash:push:stdin'
 	| 'git:status:find-renames'
 	| 'git:status:porcelain-v2'
+	| 'git:untrackedCache'
 	| 'git:worktrees';
 
 type ExtractPrefix<T> = T extends `${infer Prefix}:${infer Rest}`
@@ -30,18 +43,56 @@ export type FilteredGitFeatures<T extends GitFeatureOrPrefix> = T extends GitFea
 export const gitMinimumVersion = '2.7.2';
 export const gitFeaturesByVersion = new Map<GitFeatures, string>([
 	['git:checkout:pathspec-from-file', '2.26'],
+	// 2.24 is when git READS the commit-graph file by default (core.commitGraph on); writing it for
+	// older gits would be dead weight.
+	['git:commit-graph', '2.24'],
+	// Changed-path Bloom filters (`--changed-paths`), the v2 filter format — pre-2.31 shipped Bloom filters
+	// with real correctness bugs (bad results for merge commits), so 2.31 is the safe floor to write them.
+	['git:commit-graph:changed-paths', '2.31'],
 	['git:for-each-ref:worktreePath', '2.23'],
+	// `core.fsmonitor=true` selects the built-in FSMonitor daemon (accepting a bool rather than only a
+	// hook path). This 2.37 floor is the Windows + macOS one.
+	['git:fsmonitor', '2.37'],
+	// Linux got its own FSMonitor backend (inotify) only in 2.55, hence a separate floor. Note the backend
+	// places a watch on EVERY directory, so a large repo can exhaust `fs.inotify.max_user_watches` and the
+	// daemon fails at runtime even on a new enough git — the apply path must still probe, not just gate.
+	['git:fsmonitor:linux', '2.55'],
 	['git:ignoreRevsFile', '2.23'],
+	// `index.skipHash` (skip the trailing index checksum for faster writes); part of `feature.manyFiles`.
+	['git:index:skipHash', '2.40'],
+	// `git maintenance run --task=…`. The `maintenance` builtin + `commit-graph`/`gc` tasks are 2.29, but
+	// the loose-objects + incremental-repack tasks the auto tier uses landed in 2.30 (and `core.multiPackIndex`
+	// is default-on from 2.30, so no separate midx config write is needed) — 2.30 is the safe floor.
+	['git:maintenance', '2.30'],
+	// The pack-refs maintenance task landed one release after the maintenance builtin.
+	['git:maintenance:pack-refs', '2.31'],
+	// `git maintenance start` — the subcommands exist from 2.30 (cron only); launchctl (macOS) + schtasks
+	// (Windows) scheduling arrived in 2.31, so 2.31 is the cross-platform-safe floor.
+	['git:maintenance:start', '2.31'],
+	// `git maintenance start` systemd-timer scheduling. On Linux, 2.31–2.33 is cron-only and modern distros
+	// often ship without cron (scheduling then silently fails); the systemd fallback arrived in 2.34.
+	['git:maintenance:start:systemd', '2.34'],
+	// `feature.manyFiles` umbrella (index v4 + untracked cache + skipHash where available).
+	['git:manyFiles', '2.24'],
 	['git:merge-tree', '2.33'],
 	['git:merge-tree:write-tree', '2.38'],
 	['git:push:force-if-includes', '2.30.0'],
+	// `--autosquash` WITHOUT `-i` (folding `fixup!`/`squash!` commits into a plain/automatic rebase).
+	// Interactive rebases support autosquash on every git version GitLens supports, so this floor only
+	// gates the non-interactive path.
+	['git:rebase:autosquash', '2.44'],
 	['git:rev-parse:end-of-options', '2.30'],
 	['git:signing:ssh', '2.34.0'],
 	['git:signing:x509', '2.19.0'],
+	// Sparse-index support debuted earlier, but 2.33 shipped a corruption fix and 2.34 broadened command
+	// support. Use 2.34 as the conservative floor before offering a repository mutation.
+	['git:sparse-index', '2.34'],
 	['git:stash:push:pathspecs', '2.13.2'],
 	['git:stash:push:staged', '2.35.0'],
 	['git:stash:push:stdin', '2.30.0'],
 	['git:status:find-renames', '2.18'],
 	['git:status:porcelain-v2', '2.11'],
+	// `core.untrackedCache=true` (repo-local cache of untracked-file scans — the auto-tier config lever).
+	['git:untrackedCache', '2.8'],
 	['git:worktrees', '2.17.0'],
 ]);