@gitkraken/core-gitlens 0.7.1 → 0.8.0

package/docs/integrations.md

@@ -113,42 +113,87 @@ 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 / Bitbucket DC projects; 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 where the provider can count. 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 (Cloud + Data Center) / Linear. |
-| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira (Cloud + Data Center) / 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.                                                                                |
+| Method                       | Returns                   | Scope                                                                                        |
+| ---------------------------- | ------------------------- | -------------------------------------------------------------------------------------------- |
+| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups / Bitbucket DC projects; 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 where the provider can count. 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 issues by coordinate or tracker identifier; an absence is proven.                 |
+| `getPullRequestsBatch`       | `PullRequestBatchResult`  | Resolves N PRs by `(owner, repo, number)`, in any state; an absence is proven.               |
+| `getPullRequestsForBranches` | `PullRequestBranchResult` | Each branch's PRs, in any state and fork-aware; an empty list is a proven none.              |
+| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira (Cloud + Data Center) / 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).                 |
+| `getCurrentAccount`          | `CurrentAccountResult`    | Who a git host connection is signed in as; trackers refuse.                                  |
+| `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 every supported tracker. Jira Cloud 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, and neither
-does Jira Data Center, whose browser link is built from the connection's own base URL.
-
-For Jira Data Center `resourceId` is the host — the instance's single resource, as `listOrgs` reports it — and the
-read takes the `domain` its siblings take to select the instance. Unlike them it never falls back to the primary
-connection: a self-managed tracker requires a `domain` or a `connectionId` with a configured host, and is refused
-(warning + `fetchFailed`) otherwise. Two self-hosted instances routinely share project and issue keys, and this
-read's `issue: undefined` is a proven absence a caller may cache, so an answer from whichever host happens to be
-primary would be cached under a key that names a different instance. For the same reason a `resourceId` that names
-a different host than the one the read resolves to is refused rather than read.
+`getIssuesBatch` takes the target form its provider addresses an issue by: `{ key, owner, repo, number, project? }` on
+GitHub/GHE, GitLab and Azure DevOps, and `{ key, resourceId, resourceUrl?, identifier }` on Jira (Cloud and Data
+Center) and Linear; a call carrying the other form is refused whole. GitHub/GHE resolve up to 25 coordinates per
+request; GitLab, Azure DevOps and the trackers cost one request per target. Azure DevOps requires `project` and
+ignores `repo`, since work items belong to the project. Rows take the repository-scoped `listIssuesPage` conversion,
+except that an Azure DevOps row has no `project`, which only the account-wide read fills from project discovery. What
+counts as a proven absence is per host. On GitLab it is a null project or issue, and a miss costs a second request to
+confirm it, since provider-apis reports a reply carrying only GraphQL errors the same way; a 404 or an empty response
+fails the target. On Azure DevOps it is Azure's own 404 body naming the work item (`WorkItemUnauthorizedAccessException`,
+which Azure also uses for a work item this connection cannot read) or the project
+(`ProjectDoesNotExistWithNameException`); an HTML 404, a 410 or any other `typeKey` fails the target. Bitbucket and
+Bitbucket DC have no issues and refuse. A tracker target's `resourceId` is trusted, so the read performs no resource
+discovery. Jira Cloud also requires `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. Linear does not need it, and neither does
+Jira Data Center, whose browser link is built from the connection's own base URL. A key asked of several resources is
+one call, with one target per resource.
+
+For Jira Data Center a target's `resourceId` is the host — the instance's single resource, as `listOrgs` reports it —
+and the call takes the `domain` its siblings take to select the instance. Unlike them it never falls back to the
+primary connection: a self-managed tracker requires a `domain` or a `connectionId` with a configured host, and the
+whole call is refused (warning + `fetchFailed`) otherwise. Two self-hosted instances routinely share project and
+issue keys, and this read's `issue: undefined` is a proven absence a caller may cache, so an answer from whichever
+host happens to be primary would be cached under a key that names a different instance. For the same reason, a call
+in which any target's `resourceId` names a different host than the one the read resolves to is refused whole rather
+than read.
+
+`getPullRequestsBatch` is the pull request counterpart of `getIssuesBatch`, with the same absence/failure contract,
+and it serves every git host. Azure DevOps also requires `project` on each target. GitHub/GHE resolve up to 25
+targets per request; every other host costs one request per target, and GitLab a second one to confirm a miss. A
+target GitHub refuses on its own, e.g. in an org enforcing SAML SSO the token isn't authorized for, fails only that
+target. Its rows carry the same fields as the list reads' rows, except on Bitbucket Cloud — which has no single pull
+request read in provider-apis, so those rows come from GitLens' own REST read and lack `commentsCount`, `isDraft`
+and the clone URLs. On GitLab, a miss the confirming read then contradicts fails the target rather than answering
+with the confirming read's own, differently-identified row. It is uncached and bypasses the
+host's `IntegrationCacheProvider.getPullRequest`, so the caller owns caching the answer.
+
+`getPullRequestsForBranches` answers "which pull requests have this branch as their head" without the user's
+relationship to them, so unlike the sweeps it finds a teammate's pull request from the user's branch. A target names
+the repository the pull requests are opened against, the branch's short name and, for a branch in a fork,
+`headOwner`; one equal to the target's owner means the base repository. A pull request matches only when its head
+repository is that base repository or that fork, so a `main` never claims every fork's `main`. The match is on the
+head branch name in every state, so a merged pull request whose branch was deleted is still found. Each target
+returns up to 10, most recently updated first. An empty list without `truncated` is a proven none, a missing base
+repository included; `truncated` means more may match than were returned. GitHub/GHE answer up to 25 targets per
+request, and every other host costs one request per target. GitLab and Azure DevOps, where that request only finds
+the matching numbers, then resolve each match (typically 0–1 per branch) through `getPullRequestsBatch`'s own read,
+so their rows are exactly its rows; a match that read can't check fails its whole branch. Rows carry the list reads'
+fields on GitHub/GHE and Bitbucket DC and the by-id read's on Bitbucket Cloud. Bitbucket DC and Azure DevOps refuse a
+`headOwner` naming another owner, since neither can find a fork by its owner. It is uncached and bypasses
+`IntegrationCacheProvider.getPullRequestForBranch`.
+
+`getCurrentAccount` answers who a git host connection is signed in as. It returns a single `account?` rather
+than `items`, and `account` is never absent without a warning: no session, a failed request, or an issue tracker,
+which has only a per-resource account and refuses (see §8). It goes through the host-supplied
+`IntegrationManagerCacheProvider.getCurrentAccount` cache rather than adding a second one.
 
 ## 5. Paging
 
@@ -361,7 +406,7 @@ prove from structured errors:
 
 | `kind`          | Meaning                                                                                                                                         | Reasonable response                                                                         |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection.                                                        |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection. A scoped one is narrower: see `scope` below.           |
 | `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                                                                   | Back off and retry; keep the last snapshot.                                                 |
 | `not-found`     | 404/410/422 on the requested scope.                                                                                                             | Drop that scope; don't reconnect.                                                           |
 | `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                                                                          | Re-resolve the target or re-authenticate.                                                   |
@@ -373,6 +418,95 @@ Conversely, `other` is intentionally not a complete failure taxonomy. Treat `mes
 text rather than a stable protocol; use `fetchFailed`, `page.truncated`, and `page.allPages` for completeness
 and keep unknown failures conservative.
 
+### `scope` — which part of the read failed
+
+A fan-out read records a failure against the organization, project or repository it happened in.
+`ProviderWarning.scope` forwards that attribution (`resourceId`, `projectId`, `repositoryId`, whichever the
+provider reported), so a consumer can tell "one organization refused this token" from "the connection's token
+is dead" without parsing `message`:
+
+```ts
+if (warning.kind === 'auth' && warning.scope == null) {
+	promptToReconnect(warning.providerId, warning.connectionId);
+} else if (warning.kind === 'auth') {
+	// One organization/project/repository refused the credential, e.g. an Azure DevOps organization with
+	// third-party OAuth access disabled, one in another Entra tenant, or a Conditional Access policy.
+	// Reconnecting cannot fix that, so mark only that scope unavailable and keep the others.
+	markScopeUnavailable(warning.providerId, warning.connectionId, warning.scope);
+}
+```
+
+`kind` and `isAuth` do not change with it: a scoped 401 is still an authentication failure, and `scope` says
+how far it reaches. **Its absence means account-wide or unattributed**, so a consumer that ignores the field
+keeps its existing behavior. It is set only on warnings derived from a structured scope failure, and names at
+least one ID when present; a failure attributed to nothing below the provider carries none. A warning built
+from a caught exception never carries one, even when that call targeted a single organization, and an omission
+keeps its attribution in `omission.scope` instead. The batch reads (`getIssuesBatch`, `getPullRequestsBatch`,
+`getPullRequestsForBranches`) are the exception: a refused target's warning names the scope its target names —
+the Azure DevOps organization and project, the repository on other git hosts, or the tracker's resource.
+
+A scoped `auth` failure also means **the credential itself was accepted**. A dead token can come back as
+nothing but scoped refusals wherever a read reaches its scopes without an uncached request to the connection
+first: discovery served from a per-token cache (Azure DevOps, Bitbucket and Jira Cloud cache the account, its
+organizations, workspaces or sites, and their projects), or an SDK fan-out across the requested repositories
+(Bitbucket Data Center). So when a read's only auth failures are scoped, those providers confirm the credential
+with one uncached check before reporting them; a batch read does so only when every target was refused, since a
+target that answered already proved the credential. A refused credential fails the whole read instead: an
+unscoped `auth` warning, `fetchFailed`, no results served from the cache, and the usual connection recovery.
+A refusal the provider pins on the credential itself, like Bitbucket's or Jira Cloud's for a token missing the
+OAuth scopes the read needs, is published unscoped too, once for the connection, because a reconnect
+(consenting to them again) is what fixes it; the scopes that answered keep their results.
+
+The promise holds for a read that carries no unscoped `auth` warning of its own: one that does already asks for a
+reconnect, and its other scoped refusals are not checked. Two cases stay scoped even then. A check that could not
+complete or was denied (a network error, a throttle, a `403`, Bitbucket Data Center refusing a credential it
+authenticated, or a Bitbucket Data Center project access token, whose user the check cannot find) proves nothing,
+so the warnings are published unconfirmed and carry no `cause`, and the next read checks again: a credential the
+check can never confirm, like a project access token, costs one check on every read that has scoped refusals. And a
+credential confirmed within the last minute is not checked again, so a scope that keeps refusing it costs at most
+one extra check a minute, and a revocation can take up to a minute to surface as a connection failure.
+
+`scope.resourceId` is the resource as the read addressed it: its id on most reads, its name on the few that
+address it by name (Azure DevOps' repo-scoped reads, Bitbucket's workspace reads). Match it against both
+`ProviderOrganization.id` and `name`.
+
+Warnings also dedup on `scope` and `cause`, so failures of two scopes stay two warnings.
+
+### `cause` — why a sound credential was refused
+
+A scoped `auth` warning can also say **why** the scope refused, so a consumer recommends the fix instead of a
+reconnect. `ProviderWarning.cause` carries a closed `reason` to switch on (also exported as
+`ProviderWarningCauseReason`), the provider's own `code` when it reports one, and a `remedyUrl` when this layer
+can address the setting behind the refusal. `message` says the same in prose.
+
+```ts
+switch (warning.cause?.reason) {
+	case 'oauth-app-not-allowed':
+		// An admin enables the org's third-party OAuth policy at `remedyUrl`, or the user connects with a PAT.
+		suggestAllowingOAuthApps(warning.scope, warning.cause.remedyUrl);
+		break;
+	case 'access-denied':
+		suggestRequestingAccess(warning.scope);
+		break;
+	case 'conditional-access':
+		suggestAskingTheTenantAdmin(warning.scope);
+		break;
+}
+```
+
+| `cause.reason`          | Means                                                                                    | Fixed by                                                                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oauth-app-not-allowed` | The organization does not let third-party OAuth apps in.                                 | An organization admin enabling **Third-party application access via OAuth** (Azure DevOps; off by default for new organizations), or a PAT, which the policy does not govern. |
+| `access-denied`         | The account has no access to that organization or project (not a member, no permission). | Someone who administers it granting access.                                                                                                                                   |
+| `conditional-access`    | A Microsoft Entra Conditional Access policy blocked the request (`VS403463`).            | The tenant admin exempting the request.                                                                                                                                       |
+
+It is set **only on a scoped `auth` warning whose credential was confirmed** (see `scope` above), because until
+then these refusals look exactly like a dead credential: Azure DevOps answers a third-party OAuth app its
+organization disallows with the same bare `401` it gives an expired token. Only Azure DevOps names causes today,
+from answers captured against the live service. **Its absence proves nothing**: a refusal this layer cannot name
+still carries the provider's own explanation, when it gave one, in `message`, e.g. an organization that only
+allowlists global personal access tokens.
+
 ### `omission` — succeeded, but withheld results
 
 `other` covers two facts with **opposite remedies**: a request that failed, and a request that succeeded while
@@ -583,12 +717,14 @@ Derived from the provider models and `providersMetadata`. ✓ supported · ✗ r
 | Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      —      |   —    |   —    |
 | `searchIssuesPage`           |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
 | `countIssues`                |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
-| `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
-| `getTrackerIssue`            |      ✗       |          ✗           |     ✗     |      ✗       |            ✗            |      ✓      |   ✓    |   ✗    |
+| `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      ✓      |   ✓    |   ✗    |
+| `getPullRequestsBatch`       |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+| `getPullRequestsForBranches` |      ✓       |          ✓           |     ✓     |      ✓¹      |           ✓¹            |      ✗      |   ✗    |   ✗    |
 | Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |      ✓      |   ✓    |   ✓    |
 | `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |      ✓      |   ✓    |   ✓    |
 | `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      ✗      |   ✗    |   ✗    |
 | `resolveRepository`          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
+| `getCurrentAccount`          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
 
 Bitbucket Data Center exposes its projects through `listOrgs`: both `id` and `name` are the project key.
 Pass that key as `org` to `listRepos` to select a project, or omit `org` to enumerate all accessible repositories,
@@ -601,11 +737,15 @@ HTTPS links are rebuilt from the configured URL and an SSH link, whose host and
 
 Jira Data Center inherits Jira Cloud's row. Its reads are addressed per host, so `domain` selects the instance and
 every read below is scoped to that one connection; a paged read that omits it gets the primary configured host,
-while `getTrackerIssue` refuses instead (see §4). `listOrgs` returns exactly one resource — the
+while `getIssuesBatch` refuses instead (see §4). `listOrgs` returns exactly one resource — the
 instance itself, synthesized from the configured host rather than fetched — and its projects carry the display name
 as `key`, because `/rest/api/2/project` reports no project key; reads address the project by id regardless. No
 autolinks are registered for the same reason: an autolink prefix has to be the project key.
 
+¹ Branches in the base repository only: a target whose `headOwner` names another owner is refused, since Bitbucket DC
+finds a branch's pull requests only through the repository the branch lives in, and an Azure DevOps fork shares its
+organization.
+
 Repo-scoped PR filters: GitHub/GHE `Author, Assignee, ReviewRequested, Mention` · GitLab `Author, Assignee,
 ReviewRequested` · Bitbucket + Bitbucket DC `Author, ReviewRequested` · Azure `Author, Assignee,
 ReviewRequested`.

package/docs/kepler-git-write-api-parity.md

@@ -0,0 +1,239 @@
+# Kepler git write-API parity
+
+Decision record for the git WRITE-path gaps Kepler hit while routing every one of its git calls through
+`@gitkraken/core-gitlens` (gitkraken/kepler, branch `kepler/migrate-raw-git-spawns`). It is the sibling of
+[`kepler-read-api-parity.md`](./kepler-read-api-parity.md), which covers provider reads; this one covers the
+`git` sub-providers and the raw-command escape hatch.
+
+The shape of the problem: Kepler drives three libraries (`@gitkraken/sync-tools`, `conflict-tools`,
+`compose-tools`) that take a `{ exec }` git port plus optional typed ops, and know nothing of core; the host
+supplies a typed op only where a core call serves it exactly. Kepler also has its own worktree, branch and
+sync services. After the migration every command runs through core's executor, so it already shares the queue, environment, binary
+resolution and logging. What it could NOT do is use a typed sub-provider method for a set of commands core had
+no method for, or had one whose contract did not fit. Each such site stayed on `provider.git.run` with a
+comment naming the missing API. This document is the list of those APIs, what was added for each, and what was
+deliberately left alone.
+
+Verdict legend: **added** (a typed method now exists) · **extended** (an existing method gained the missing
+option) · **deferred** (left on the raw escape hatch on purpose, with the reason).
+
+## 1. Compare-and-swap ref updates — added
+
+`refs.updateReference` ran `git update-ref <ref> <sha>` and swallowed every failure (logged, resolved
+`undefined`), and there was no delete form. `@gitkraken/sync-tools` (0.4.0) publishes, applies and discards a
+sync result itself (`applyPublishedSync`, `discardPublishedSync`), and every ref move in that flow is a
+compare-and-swap: the real branch advances only if nothing else moved it since the library last read it. The
+library asks its host for that through a typed `updateRef(ref, sha, { previousSha, mustNotExist, remove })`
+op, and git's own `update-ref <ref> <new> <old>` is what makes it atomic. A writer that cannot refuse is a
+clobber, so without this a host could only serve the op through the raw escape hatch.
+
+- `updateReference(repoPath, ref, sha, options?: { expected?: string | 'absent' }, cancellation?)` now passes
+  the old value to git when `expected` is a sha, and the empty old value when it is `'absent'` (create only if
+  the ref does not exist yet). It THROWS a typed `ReferenceUpdateError` — reasons `conflict` (the ref moved,
+  or exists when it must not), `invalidRef`, `invalidObject`, `notFound` — instead of swallowing.
+- `deleteReference(repoPath, ref, options?: { expected?: string }, cancellation?)` runs
+  `update-ref -d --no-deref <ref> [<expected>]` with the same error — `--no-deref` so a symbolic ref is itself
+  deleted rather than the ref it points to — and refuses `HEAD` (`checkedOut`). `update-ref -d` has none of
+  `git branch -d`'s guards or cleanup, so for a local branch (`refs/heads/<name>`) `deleteReference` supplies
+  them: it refuses a branch checked out in any worktree (`checkedOut`, read from `git worktree list`, not the
+  cached list), and removes the `branch.<name>` config section and GitLens's per-branch metadata with the ref.
+  Only `git branch -d`'s merged check is left out, since a compare-and-swap caller has already decided.
+- Both fire the cache and repository hooks a branch, remote-tracking, tag or `HEAD` move fires; a ref in another
+  namespace (`refs/kepler/...`) announces nothing, since nothing core caches can observe it and an `unknown`
+  change would make a host refresh everything.
+
+The sync-tools op maps onto these one-to-one:
+
+| `updateRef` option | core call                                                        |
+| ------------------ | ---------------------------------------------------------------- |
+| `previousSha`      | `updateReference(repoPath, ref, sha, { expected: previousSha })` |
+| `mustNotExist`     | `updateReference(repoPath, ref, sha, { expected: 'absent' })`    |
+| `remove`           | `deleteReference(repoPath, ref, { expected: previousSha })`      |
+| none               | `updateReference(repoPath, ref, sha)`                            |
+
+`'absent'` against an existing ref rejects as `conflict` and leaves the ref where it was. Deleting a ref that
+is already gone rejects as `notFound` when `expected` is given (the caller named a value it expected to
+remove), and resolves when it is not.
+
+The library reads any rejection as the ref's answer, so the host must tell a cancellation apart from a
+refusal. A cancelled call rejects with core's `CancellationError` (`name === 'CancellationError'`), never a
+`ReferenceUpdateError`, and that includes a signal already aborted when the call is made; a host adapting to
+a library that expects `AbortError` maps it by name. A cancel that lands while git is running says nothing
+about whether the ref moved, so re-read it before acting on the outcome.
+
+**Breaking:** a caller that relied on a failed `updateReference` resolving silently now gets a rejection. No
+caller in this repository did.
+
+## 2. Who clears after a write, and telling core about a raw one — changed / added
+
+A typed mutator announces its write through `hooks.cache.onReset`, and core used to clear nothing itself on
+that path: each host's handler was expected to forward to `Cache.clearCaches`. Two things followed. A host
+with no handler kept serving pre-write reads after every typed write. And `clearCaches` only soft-invalidates
+a shared entry that is still in flight, so even a wired host could hand a caller that arrived after the write
+a read that started before it; GitLens also dropped the executor's pending commands on every reset, Kepler did
+not.
+
+A consumer that mutates through `provider.git.run` (a rebase driven by a library, a `clean`, a ref bookkeeping
+write) had nothing to call at all, and typed reads served the pre-mutation answer until a file watcher caught
+up, or forever with no watcher. Kepler classified verbs itself and called `clearCaches` after each one. The
+sharpest case: it fetches PR heads through a raw `fetch` (it needs a per-process credential environment the
+typed fetch cannot carry), and a typed `refs.validateReference` right after it served the pre-fetch tip for up
+to 60s. `clearCaches` fixed that read but fired none of the host's hooks, so nothing else in the host learned
+the refs moved.
+
+- The provider wraps `onReset` when it is constructed. On every reset it hard-evicts its own caches for those
+  types (`Cache.evictCaches`, so a later caller never joins pre-write work), drops pending commands, then calls
+  the host's handler. Clears driven by a file watcher reach `clearCaches` directly and keep sharing in-flight
+  reads, which is what stops a burst of file events from spawning duplicate reads. A host's handler now only
+  has host-side state to update; forwarding to `clearCaches` as well is redundant but harmless.
+- `provider.notifyChanged(repoPath, changes: RepositoryChange[], options?: { cache?: CachedGitTypes[] | 'all' })`
+  fires the same `cache.onReset` (all types by default) and `repository.onChanged` a typed write would, so a
+  raw mutation gets exactly the same treatment, host listeners included.
+
+## 3. Worktree administration — added / extended
+
+- `worktrees.pruneWorktrees(repoPath, options?: { expire? })` — `git worktree prune`. Kepler prunes
+  after a directory it removed by hand, and before reusing a path git still lists. Like `deleteWorktree`, it
+  unregisters each worktree it removed from the cache.
+- `worktrees.lockWorktree(repoPath, path, options?: { reason? })` — `git worktree lock --reason`. The reason
+  is how Kepler marks a worktree as task-owned; only `unlockWorktree` existed.
+- `worktrees.createWorktree(repoPath, path, options?, runOptions?)` and
+  `deleteWorktree(repoPath, path, options?, runOptions?)` — gained run options. A large worktree's checkout or
+  removal legitimately outlasts the default per-command timeout, and a caller may need to cancel either. A
+  cancelled call rejects as `CancellationError`, not a worktree error. The thrown `WorktreeDeleteError` keeps git's
+  raw output reachable on `original`, which is what a platform-specific retry classifier needs.
+
+## 4. `git clean`, and the staging sub-provider's missing hooks — added / fixed
+
+- `staging.clean(repoPath, options?: { paths?, directories?, force?, ignored? })` — the only way to
+  discard untracked files; `ops.restore` cannot.
+- Every staging mutation (`stageFile(s)`, `stageDirectory`, `stageAll`, `unstage*`, `removeFile(s)`, `clean`)
+  now fires `onReset('status', 'diff', 'tracking')` and the index change, except when it targets a temporary
+  index, which is not the repository's. Before this, a consumer that staged a conflict resolution through the
+  typed API and then read `getConflictingFiles()` could be answered from the index as it stood before the
+  stage.
+
+## 5. Upstream and hooks config keys — added
+
+Kepler writes `branch.<name>.remote` / `branch.<name>.merge` (to set an upstream whose remote ref does not
+exist yet, which `--set-upstream-to` refuses) and reads `core.hooksPath`. All three are now documented members
+of `GitConfigKeys`, so `config.getConfig` / `setConfig` serve them with the usual cache. Writing either
+upstream key also resets the cached branch list, which reports the upstream.
+
+## 6. `git pull --ff-only` — extended
+
+`ops.pull` gained `fastForward: 'only'`, spelled as `ops.merge` spells it. Kepler advances a local base branch
+before forking a task worktree from it, and must not create a merge commit or start a rebase in a checkout it
+does not own. A refused fast-forward is a `PullError` with the new `noFastForward` reason (the name
+`FetchError` already uses); before this it fell through to `other`. A base branch checked out nowhere has no
+working tree to pull into, so it is advanced by fetching `<upstream>:<branch>`, which git refuses unless it
+fast-forwards; without the option that path only fetches. That fetch runs without `--update-head-ok`: "checked
+out nowhere" comes from the cached worktree list, so git's own refusal is what keeps a branch that is in fact
+checked out from moving. A branch with no upstream is `PullError` reason `noUpstream`, on this path and for a
+checked-out pull alike. `merge`'s `true` / `false` are not offered: a pull configured to rebase ignores `--ff`
+/ `--no-ff`.
+
+## 7. A commit from a tree with several parents and an author — added
+
+A compose or stack engine writes merge commits and replays commits with their original author, which the
+single-parent, identity-less `commits.createUnreachableCommitFromTree` could not.
+
+- `commits.createCommitFromTree(repoPath, tree, { parents, message, author?, committer?, sign?, source? })` runs
+  `commit-tree` with the message on stdin and the identity in the per-call environment, returning the sha.
+  With `sign` it reports a signing failure as `SigningError` and fires the signing hooks.
+- It is the only path that writes a commit object. `createUnreachableCommitFromTree` is removed, and the patch
+  sub-provider's commits (`createUnreachableCommitForPatch`, `createUnreachableCommitsFromPatches`,
+  `createEmptyInitialCommit`) go through it with unchanged results.
+
+## 8. `git init` — added
+
+`GitProvider.clone` existed; `init(path, options?: { defaultBranch?, bare? })` did not. Kepler creates a
+repository for a folder the user adds.
+
+## 9. Forced ref reads — added
+
+After a change core neither made nor was told about (another process moving a branch, a raw `fetch` the
+consumer has not reported yet), an ordinary read can answer from cache until its TTL runs out. `notifyChanged`
+is the fix when the consumer made the change; `force` is for a read that must be current regardless.
+
+- `refs.validateReference(repoPath, ref, { relativePath?, force? }, cancellation?)`,
+  `refs.getReference(repoPath, ref, { force? }, cancellation?)`,
+  `branches.getBranch(repoPath, name?, { force? }, cancellation?)` and
+  `revision.resolveRevision(repoPath, ref, pathOrUri?, { force? })`. A forced read drops its cache entry before
+  reading, so it neither returns the cached answer nor joins a read already in flight (a fresh entry gets a
+  fresh cancellation aggregate, whose id is part of the executor's dedup key), and it stores the fresh answer
+  for later unforced reads. `getStatus({ force })` and `getPausedOperationStatus({ force })` are the precedent.
+- `getBranch({ force })` evicts the whole branch cascade first: branch lists, ref tips, merge bases, commit
+  counts and resolved revisions, the set a branch move clears, since each can be derived from a ref that moved.
+  `getReference({ force })` forces its validation and branch lookup; tags are not forced.
+- `validateReference`'s `relativePath` moved into the options object, and `getBranch` / `getReference` take
+  options before `cancellation`, matching `getStatus`.
+
+## Overlaps with existing APIs, and how each was settled
+
+- **Refs containing a sha.** `branches.getBranchesWithCommits(repoPath, [sha], undefined, { all, mode })` and
+  `tags.getTagsWithCommit` already answer it, so `getRefTips` did not gain `--contains` / `--points-at`
+  filters. Kepler's one use (is a sha on any other local or remote branch) is `getBranchesWithCommits`.
+- **Config keys.** Added to the documented union rather than served by a separate untyped
+  `getConfigValue` / `setConfigValue`, which would have been a second way to read every key.
+- **Commit objects.** `createCommitFromTree` replaced `createUnreachableCommitFromTree` and the patch
+  sub-provider's own `commit-tree` calls, rather than sitting beside them.
+- **Deleting refs.** `deleteReference` stays beside `branches.deleteLocalBranch` and `tags.deleteTag` on
+  purpose. `deleteLocalBranch` keeps `git branch -d`'s merged check, which the delete flow's force-retry relies
+  on, and takes several names; `deleteTag` reports a `TagError` the UI renders. `deleteReference` is the
+  compare-and-swap form for any namespace, and shares the branch cleanup with `deleteLocalBranch`.
+- **Clearing caches.** `evictCaches` stays beside `clearCaches`: a write hard-evicts, a watcher clear keeps
+  sharing in-flight reads (see the decisions below).
+
+## Deferred, deliberately
+
+- **Index and object plumbing** (`read-tree`, `write-tree`, `update-index --index-info`, `mktree`,
+  `hash-object -w --stdin`, `cat-file -p`). The libraries drive these through `exec` with a scratch
+  `GIT_INDEX_FILE` and parse the results themselves; a typed surface would re-encode the same argv with more
+  room to drift. Revisit when a second consumer needs them.
+- **A reflog read filtered by message.** Kepler reads `git reflog <branch> --grep-reflog='branch: Created from'`
+  to recover a branch's creation point. `getIncomingActivity` walks `HEAD`'s reflog for a different purpose;
+  bolting a grep onto it would change its paging. Worth its own method on `branches` once the base-branch
+  inference core already does privately is unified with it.
+- **Generic `for-each-ref` with a caller-supplied format.** The `RefRecord` shape is private on purpose.
+- **A typed `worktree remove` for every consumer.** Kept the raw form where a consumer classifies platform
+  failures from stderr; §3's `original` makes the typed form usable for that too.
+
+## Bridging core into the tools libraries
+
+The libraries take their own port and know nothing of core, so a host serving one through core reshapes what
+core rejects with:
+
+- **Cancellation.** Core rejects with `CancellationError` (`name === 'CancellationError'`); a library that
+  expects `AbortError` gets it mapped by name.
+- **"Git answered no" versus a structural failure.** sync-tools tells them apart by whether `err.code` is a
+  number, and compose-tools reads `err.stderr`: the shape of Node's `execFile` error. Core's `GitError`
+  carries `stderr` but reports the exit as `exitCode`, which is a number or numeric string for a real exit and
+  an errno string (`'ENOENT'`) when git never started. A typed method's own error, such as
+  `ReferenceUpdateError`, keeps that `GitError` on `original`.
+
+## Decisions worth recording, because each closes off a plausible-looking alternative
+
+- `updateReference` throws rather than gaining an `errors: 'throw'` option. A ref writer whose failures are
+  invisible by default is the bug, not a mode.
+- `'absent'` rather than `expected: ''`. The empty old value is git's encoding of "must not exist"; a caller
+  spelling it as an empty string reads like a mistake, and an argv filter that drops empty strings would turn
+  a create into an unconditional overwrite.
+- New config keys join `GitConfigKeys` rather than widening it to `string` or adding an untyped read. The
+  union's value is that every listed key is documented; an escape hatch would keep the autocomplete and lose
+  the guarantee.
+- `deleteReference` gives a branch `git branch -d`'s guard and cleanup rather than refusing branches. A
+  compare-and-swap delete of a branch is legitimate (sync-tools' port contract exercises one), and refusing it
+  would push the caller back to a raw `update-ref -d` that orphans the same state.
+- A write hard-evicts while a watcher clear keeps sharing in-flight reads, rather than one policy for both. A
+  write is a known point after which an older read is wrong; a watcher tick has no such ordering, and sharing
+  the in-flight read is what keeps a burst of file events from multiplying git processes.
+- `notifyChanged` on the provider rather than an option on `git.run`. The executor has no context and no
+  hooks; the provider does. A consumer that runs a raw mutation knows what it changed.
+- Staging hooks skip the temporary-index case rather than firing unconditionally. A scratch index is not the
+  repository's; announcing an index change for it would invalidate status for nothing.
+
+**Kepler-side follow-up**, once a core release carries these: serve sync-tools' `updateRef` op through
+`updateReference` / `deleteReference` (mapping in §1), delete the review ref with `deleteReference`, drop the
+verb classifier in `core-git-port.ts` in favour of `notifyChanged`, and retire the remaining
+`TODO(core-gitlens)` residuals.