@gitkraken/core-gitlens 0.3.1 → 0.4.100

package/src/git/errors.ts

@@ -1,6 +1,37 @@
 import { pluralize } from '../utils/string.js';
 import type { GitPausedOperationStatus } from './models/pausedOperationStatus.js';
 
+/**
+ * stderr patterns git emits that are EXPECTED rather than exceptional — an empty repo, a path that doesn't
+ * exist at a revision, a branch with no upstream. The exec layer matches these to decide a command "warned"
+ * rather than failed.
+ *
+ * Matching one does NOT mean the empty output is a valid answer: `noCommits` on a fresh repo genuinely means
+ * "no commits", while `notARepository` means the read never happened. Callers must branch on which key
+ * matched — see `GitRunCompletion`. Pure patterns with no environment dependency, so this lives here rather
+ * than in the CLI provider, where the shared run contract couldn't reference it.
+ */
+export const GitWarnings = {
+	notARepository: /Not a git repository/i,
+	outsideRepository: /is outside repository/i,
+	noPath: /no such path/i,
+	noCommits: /does not have any commits/i,
+	notFound: /Path '.*?' does not exist in/i,
+	foundButNotInRevision: /Path '.*?' exists on disk, but not in/i,
+	headNotABranch: /HEAD does not point to a branch/i,
+	noUpstream: /no upstream configured for branch '(.*?)'/i,
+	unknownRevision:
+		/ambiguous argument '.*?': unknown revision or path not in the working tree|not stored as a remote-tracking branch/i,
+	mustRunInWorkTree: /this operation must be run in a work tree/i,
+	patchWithConflicts: /Applied patch to '.*?' with conflicts/i,
+	noRemoteRepositorySpecified: /No remote repository specified\./i,
+	remoteConnectionError: /Could not read from remote repository/i,
+	notAGitCommand: /'.+' is not a git command/i,
+	tipBehind: /tip of your current branch is behind/i,
+} as const;
+
+export type GitWarningKey = keyof typeof GitWarnings;
+
 export interface GitCommandContext {
 	readonly repoPath: string;
 	readonly args: readonly (string | undefined)[];
@@ -925,9 +956,11 @@ export class WorktreeCreateError extends GitCommandError<WorktreeCreateErrorDeta
 	}
 }
 
-export type WorktreeDeleteErrorReason = 'defaultWorkingTree' | 'directoryNotEmpty' | 'uncommittedChanges';
+export type WorktreeDeleteErrorReason = 'defaultWorkingTree' | 'directoryNotEmpty' | 'locked' | 'uncommittedChanges';
 interface WorktreeDeleteErrorDetails {
 	reason?: WorktreeDeleteErrorReason;
+	/** The reason the worktree was locked, when known and provided by the locker */
+	lockReason?: string;
 	gitCommand?: GitCommandContext;
 }
 
@@ -951,6 +984,8 @@ export class WorktreeDeleteError extends GitCommandError<WorktreeDeleteErrorDeta
 				return 'Cannot delete worktree because it is the default working tree';
 			case 'directoryNotEmpty':
 				return 'Unable to delete worktree because the directory is not empty';
+			case 'locked':
+				return 'Unable to delete worktree because it is locked';
 			case 'uncommittedChanges':
 				return 'Unable to delete worktree because there are uncommitted changes';
 			default:

package/src/git/models/commit.ts

@@ -479,7 +479,7 @@ export class GitCommit implements GitRevisionReference {
 	}
 
 	protected getChangedValue<T>(change: T | null | undefined, original: T | undefined): T | undefined {
-		return change === undefined ? original : change === null ? undefined : change;
+		return change === undefined ? original : (change ?? undefined);
 	}
 
 	@memoize({ resolver: (...args) => `${args[0]}|${args[1]}` })

package/src/git/models/graph.ts

@@ -28,6 +28,8 @@ export interface GitGraphRowHead {
 	 *  Producers MUST set this whenever they set `worktree`; do not read it from GitLens code,
 	 *  read `worktree.id` instead. */
 	worktreeId?: string;
+	/** True when this head is the repository's default branch. */
+	isDefault?: boolean;
 }
 
 export interface GitGraphRowRemoteHead {
@@ -38,6 +40,9 @@ export interface GitGraphRowRemoteHead {
 	avatarUrl?: string;
 	context?: string | object;
 	current?: boolean;
+	/** True when this remote ref IS the repository's default branch and no local branch tracks it (no
+	 *  local checkout) — so the default-branch tier still applies for remote-only defaults. */
+	isDefault?: boolean;
 	hostingServiceType?: GkProviderId;
 }
 
@@ -61,6 +66,9 @@ export interface GitGraphRowTag {
  * the first merge commit, so a plain (non-`--rebase-merges`) interactive rebase can safely rewrite it;
  * gates squash/drop/reword/modify. Strictly narrower than `+current` (reachable-from-HEAD includes a
  * merge's other-parent ancestry, which is NOT safely rewriteable).
+ * Bit 5: unpulled/behind-the-upstream — the exact mirror of bit 3: on HEAD's upstream tip but NOT on HEAD
+ * (i.e. `HEAD..@{u}`). Drives the graph's read-only unpulled indicator; it has no `webviewItem` segment
+ * (no command gates on it). Mutually exclusive with `Unpublished` by construction.
  * (`+HEAD` derives from `row.heads[].isCurrentHead`; contributor `+current` from `row.isCurrentUser`.)
  */
 export const enum GitGraphRowContextFlags {
@@ -70,6 +78,7 @@ export const enum GitGraphRowContextFlags {
 	HasChildren = 1 << 2,
 	Unpublished = 1 << 3,
 	RewriteableFromHead = 1 << 4,
+	Unpulled = 1 << 5,
 }
 
 /**
@@ -167,6 +176,36 @@ export interface GitGraph {
 	/** SHAs reachable from HEAD (for enrichment: marking commits on the current branch) */
 	readonly reachableFromHEAD?: ReadonlySet<string>;
 
+	/**
+	 * Ref tips as of this walk: canonical refname (`refs/heads/…`, `refs/remotes/…`, `refs/tags/…`) →
+	 * PEELED tip sha (annotated tags map to the commit their badge sits on). Captured so the host can seed
+	 * the NEXT rebuild's {@link GraphIncrementalSeed.tips} — the map the R6b fast path diffs against to find
+	 * the structural changes that force a full fallback. The CLI provider populates it on both paths (full
+	 * walk + fast path); the GitHub provider leaves it undefined.
+	 */
+	readonly refTips?: ReadonlyMap<string, string>;
+
+	/**
+	 * Fingerprint of every SIDE INPUT row construction embeds into row decorations as of this walk —
+	 * default branch, per-branch upstreams, HEAD's upstream, remote urls/providers, worktree assignments,
+	 * and the current user. These can all change WITHOUT moving any ref tip (`git remote set-head`,
+	 * `branch --set-upstream-to`, `worktree add`, remote/user config edits), and the R6b fast path reuses
+	 * prior rows wholesale (only flags/reachability are re-derived) — so it must compare this against the
+	 * seed's and fall back to a full walk on ANY change. The CLI provider populates it on both paths; the
+	 * GitHub provider leaves it undefined.
+	 */
+	readonly decorationFingerprint?: string;
+
+	/**
+	 * Whether the repo was a SHALLOW clone (a `$GIT_DIR/shallow` file was present) as of this walk. Captured
+	 * so the host can seed the NEXT rebuild's {@link GraphIncrementalSeed.shallow}: an un-shallow (or
+	 * re-shallow) while the graph is closed passes every ref-tip gate — the branch tips don't move — yet
+	 * changes what history exists BELOW the loaded window, so a stale-false `hasMore` would hide the newly
+	 * deepened commits. The R6b fast path falls back on any change. The CLI provider populates it on both
+	 * paths (full walk + fast path); the GitHub provider leaves it undefined.
+	 */
+	readonly shallow?: boolean;
+
 	/**
 	 * SHAs on the first-parent chain from HEAD up to (excluding) the first merge commit — i.e. the
 	 * commits a plain interactive rebase can safely rewrite. Empty when HEAD itself is a merge. Used by
@@ -238,6 +277,114 @@ export interface GitGraph {
 
 export type GitGraphRowsStats = Map<string, GitGraphRowStats>;
 
+/**
+ * Seed for the R6b incremental head-walk fast path. Carries the prior generation's walk artifacts so a
+ * repo-change rebuild can walk ONLY the changed head region, stitch the cached tail, and re-derive
+ * flags/reachability in memory — instead of re-walking every loaded row.
+ *
+ * R6a status: the Node provider ACCEPTS this option but IGNORES it, falling through to the full ordered
+ * walk (so a seeded rebuild is byte-equivalent to an unseeded one). It is threaded now purely so the
+ * equivalence harness can pin the shape and R6b can light up the fast path without an interface change.
+ * The GitHub provider ignores it structurally (it never lists the option).
+ */
+export interface GraphIncrementalSeed {
+	/**
+	 * Prior generation's emitted rows, in walk order. R6b stitches the unchanged tail from these once the
+	 * streamed head region CONVERGES with them (K consecutive shas aligned at a stable offset), and reads
+	 * their parent lists to re-derive reachability/flags in memory (no git) over the stitched window.
+	 */
+	readonly rows: readonly GitGraphRow[];
+	/**
+	 * Ref tips as of the prior walk: canonical refname (e.g. `refs/heads/main`, `refs/remotes/origin/main`,
+	 * `refs/tags/v1`) → tip sha. R6b enumerates the new commits via `git log --all --not <these shas>`
+	 * (cheap, exact) and diffs this map against the current tips to detect the structural changes that force
+	 * a full fallback: any ref DELETION (key gone) or a NON-fast-forward move (old tip not an ancestor of the
+	 * new tip).
+	 */
+	readonly tips: ReadonlyMap<string, string>;
+	/**
+	 * Ordering the prior rows were walked in. The convergence + date-boundary reasoning R6b relies on is only
+	 * sound for `date` order in v1; a seed whose ordering is `author-date`/`topo`, or that disagrees with the
+	 * current walk's ordering, is discarded (full fallback).
+	 */
+	readonly ordering: 'date' | 'author-date' | 'topo';
+	/**
+	 * Prior generation's reachability table, to CONTINUE (same role as the sub-provider's `reachabilitySeed`)
+	 * so rows retained across the rebuild keep stable {@link GitGraphRowContexts.reachabilityIndex} values and
+	 * only appended entries ship. R6b decides whether the stitched window extends this builder or needs a
+	 * fresh generation; see `createReachabilityTableBuilder`.
+	 */
+	readonly reachability?: GraphReachabilityTable;
+	/**
+	 * Prior generation's per-sha stats (immutable per sha), so the deferred stats query recomputes only the
+	 * new shas — same role as `rowsStatsSeed`.
+	 */
+	readonly rowsStats?: GitGraphRowsStats;
+	/**
+	 * Whether the prior generation had more rows below its loaded window (`paging.hasMore`). The fast path
+	 * can only reconstruct rows the seed carries; when the seed was a partial (paged) load and no new commit
+	 * pushes the window past its limit, `hasMore` must still be reported so the caller keeps paging. Absent ⇒
+	 * treated as `false` (the seed loaded the full history).
+	 */
+	readonly hasMore?: boolean;
+	/**
+	 * The `graph.onlyFollowFirstParent` setting the prior rows were walked under. When first-parent is on the
+	 * emitted rows carry sliced (first-parent-only) parents, which the in-memory re-derivation can't expand
+	 * back to the full parent set the walk propagates reachability through — so a seed built under (or a
+	 * current config of) first-parent forces a full fallback. Absent ⇒ treated as `false`.
+	 */
+	readonly onlyFollowFirstParent?: boolean;
+	/**
+	 * Whether the repo was a SHALLOW clone when the prior rows were walked. R6b falls back to a full walk on
+	 * ANY change vs. the current state (shallow→unshallowed, unshallowed→shallow): an un-shallow deepens
+	 * history below the loaded window while every branch tip stays put, so the cached tail / stale-false
+	 * `hasMore` would hide the newly deepened commits. Absent ⇒ treated as `false` (not shallow).
+	 */
+	readonly shallow?: boolean;
+	/**
+	 * {@link GitGraph.decorationFingerprint} of the prior walk. R6b falls back to a full walk on ANY change:
+	 * reused rows keep their embedded decorations (upstream/worktree/default/remote/user metadata), so a
+	 * metadata-only change — one that moves no ref tip — would otherwise ship stale pills indefinitely.
+	 * Absent (e.g. an old persisted snapshot) ⇒ never matches ⇒ safe full fallback.
+	 */
+	readonly decorationFingerprint?: string;
+}
+
+/**
+ * Which path a seeded {@link GitGraphSubProvider.getGraph} call took: the R6b incremental head-walk fast
+ * path, or a full ordered walk (with the gate/boundary `reason` that forced it). Reported via the
+ * `onIncrementalResult` option so the host can log it and the equivalence harness can assert it. Purely
+ * observational — it never changes the returned graph.
+ */
+export interface IncrementalGraphOutcome {
+	readonly path: 'fast' | 'fallback';
+	readonly reason?: IncrementalGraphFallbackReason;
+	/** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */
+	readonly added?: number;
+}
+
+export type IncrementalGraphFallbackReason =
+	| 'no-row-processor'
+	| 'ordering-not-date'
+	| 'rev-outside-seed'
+	| 'first-parent'
+	| 'limit-exceeds-seed'
+	| 'ref-deleted'
+	| 'ref-non-fast-forward'
+	| 'replace-refs-changed'
+	| 'shallow-changed'
+	| 'stash-changed'
+	| 'stash-window-conflict'
+	| 'date-boundary'
+	// A decoration side input changed without moving any ref tip (default branch, an upstream, a worktree
+	// assignment, a remote's url/provider, the current user) — reused rows would keep stale embedded
+	// decorations, so the walk must rebuild them. See `GitGraph.decorationFingerprint`.
+	| 'metadata-changed'
+	// The fast path threw (spawn/arg limits on huge ref sets, queue overflow, transient git errors) —
+	// never an eligibility gate. The fast path must never fail where the full walk it accelerates
+	// would succeed, so any unexpected error degrades to the full walk (cancellation still propagates).
+	| 'error';
+
 /**
  * Processes a single graph row — mutates the row in place.
  *

package/src/git/models/graphSession.ts

@@ -0,0 +1,205 @@
+import type {
+	GitGraph,
+	GitGraphRow,
+	GitGraphRowStats,
+	GraphReachabilityTable,
+	IncrementalGraphFallbackReason,
+} from './graph.js';
+
+/**
+ * A provider-owned, stateful graph window for a single repo. It is the canonical accumulated window and
+ * the single builder of the incremental rebuild seed — the host no longer mirrors loaded rows, stamps
+ * ref tips, or hand-assembles the {@link GraphIncrementalSeed}; the session owns its own walk shape and
+ * cannot be handed a lying seed.
+ *
+ * R7a is a behavior-neutral ownership move: {@link refresh} is a facade over the provider's existing
+ * `getGraph` incremental machinery (it internally builds the seed from the accumulated window, tips, and
+ * prior artifacts, with the same shape gating), {@link more} delegates to the prior result's `more()`,
+ * and {@link current} mirrors today's `GitGraph` result shape so the publisher/wire semantics stay
+ * byte-identical. R7b (refresh-result-driven channel marking) and R7c (restart persistence) extend this
+ * without breaking — {@link refresh} returns a result object, never a bare `GitGraph`.
+ */
+export interface GitGraphSession {
+	readonly repoPath: string;
+
+	/** Canonical accumulated window (the FULL loaded rows, never page-scoped after pagination). */
+	readonly window: readonly GitGraphRow[];
+
+	/**
+	 * Last-operation view mirroring today's `GitGraph` result shape: page-scoped `rows` after a
+	 * {@link more}, the full window after a {@link refresh}. Keeps the publisher's `getRows`/`getPaging`
+	 * and every graph-level read (`branches`, `remotes`, `stashes`, `ids`, `avatars`, `rowsStats`, …)
+	 * exactly as they read `_graph` today.
+	 */
+	readonly current: GitGraph;
+
+	/**
+	 * Re-walk the repo, accumulating the fresh full window. Internally seeds the incremental head-walk
+	 * fast path from the prior window/tips/artifacts (same shape gating as the host did) and falls back
+	 * to a full walk on any structural change; the result surfaces which path ran so a later stage can
+	 * mark channels precisely.
+	 */
+	refresh(options?: GitGraphSessionRefreshOptions, cancellation?: AbortSignal): Promise<GitGraphSessionRefreshResult>;
+
+	/**
+	 * Page more rows into the window (accumulates; `current` becomes the page view). Returns `false` when
+	 * there was nothing to add or a concurrent {@link refresh} superseded the page.
+	 */
+	more(limit?: number, targetId?: string, cancellation?: AbortSignal): Promise<boolean>;
+
+	/**
+	 * Snapshot the canonical window for restart persistence, or `undefined` when there's nothing worth
+	 * persisting — an empty window, or a provider without an incremental restore path (e.g. GitHub, which
+	 * stamps no ref tips for the restore's tip-diff gate). The host writes this into the repo's own git dir
+	 * (`<commonGitDir>/gitlens/graph/` — a repo-derived cache, like git's commit-graph file) on an idle
+	 * debounce / dispose; a later {@link GitGraphSubProvider.openGraphSession} `restore` reconstructs +
+	 * refreshes it. Never trusted over git — restore always re-refreshes (see {@link GitGraphSessionSnapshot}).
+	 */
+	serialize(): GitGraphSessionSnapshot | undefined;
+
+	dispose(): void;
+}
+
+/**
+ * Schema version for {@link GitGraphSessionSnapshot}. Bump on ANY shape change (field add/remove/rename or a
+ * semantics change): a restore whose snapshot version doesn't match this EXACTLY is discarded (a normal
+ * initial walk), so an old-shaped cache written by a prior extension version can never be misread.
+ */
+export const graphSessionSnapshotVersion = 3;
+
+/**
+ * Restart-persistence snapshot of a {@link GitGraphSession}'s canonical window — everything a restore needs
+ * to reconstruct the session's prior generation as an R6 incremental SEED, so a cold open on an unchanged
+ * repo is ≈ deserialize + one enumeration instead of a full walk.
+ *
+ * NEVER trusted over git: on restore the session reconstructs this as its window/tips/builders WITHOUT any
+ * git, then IMMEDIATELY {@link GitGraphSession.refresh | refreshes} — the same enumeration + tip-diff + FF +
+ * stash gates reconcile a stale snapshot (fast when unchanged, a full walk on any structural change), and any
+ * parse/validation failure discards it entirely for a normal initial walk.
+ *
+ * Rows are persisted as-is: they're already the JSON-safe wire shapes (strings/numbers/plain objects — the
+ * graph's Maps live at the graph level, not on rows, and the transient per-row `reachability` is stripped
+ * before a row is emitted). Maps are persisted as entry arrays.
+ */
+export interface GitGraphSessionSnapshot {
+	/** Must equal {@link graphSessionSnapshotVersion}; any mismatch discards the snapshot. */
+	readonly v: number;
+	readonly repoPath: string;
+	/** Walk shape the window was produced under (`${ordering}|${onlyFollowFirstParent}`). A restore is
+	 *  discarded when this disagrees with the current config's shape — the cached rows can't be reused. */
+	readonly buildShape: string;
+	readonly ordering: 'date' | 'author-date' | 'topo';
+	readonly onlyFollowFirstParent: boolean;
+	/** The persisted window rows, in walk order — a TOP slice capped at a bounded row count (see the host
+	 *  store); a longer window persists its top slice with {@link hasMore} forced true so the bottom re-pages. */
+	readonly rows: GitGraphRow[];
+	/** Ref tips as of the persisted walk: `[canonical refname, peeled tip sha]` entries — the map the restore
+	 *  refresh diffs against current git to find the structural changes that force a full fallback. */
+	readonly refTips: [string, string][];
+	/** {@link GitGraph.decorationFingerprint} as of the persisted walk — the restore refresh diffs it against
+	 *  current git so a metadata-only change while closed (upstream/default/worktree/remote/user) still forces
+	 *  the full fallback that rebuilds row decorations. Absent ⇒ never matches ⇒ safe full fallback. */
+	readonly decorationFingerprint?: string;
+	/** Shared reachability table for the window (the primary reachability representation — rows carry only a
+	 *  `contexts.reachabilityIndex` into its `sets`). The restore refresh CONTINUES it (stable indices). */
+	readonly reachability?: GraphReachabilityTable;
+	/** Per-sha immutable stats `[sha, stats]` entries for the persisted rows (present only when stats were
+	 *  included in the walk). */
+	readonly rowsStats?: [string, GitGraphRowStats][];
+	/** Downstreams `[upstream name, tracking branch names]` entries (for the refresh's change diffing). */
+	readonly downstreams: [string, string[]][];
+	/** Whether the persisted window had more rows below it — genuinely paged OR truncated by the cap. */
+	readonly hasMore: boolean;
+	/** Whether the persisted walk included per-row stats. */
+	readonly includesStats: boolean;
+	/** Whether the repo was a shallow clone when the window was walked. The restore refresh diffs this
+	 *  against current git — an un-shallow (or re-shallow) while closed forces a full fallback. */
+	readonly shallow: boolean;
+}
+
+/** Why a restore discarded its snapshot (reported via {@link GraphSessionRestoreResult.reason}). */
+export type GraphSessionRestoreDiscardReason =
+	| 'schema'
+	| 'repo-path'
+	| 'shape'
+	| 'empty'
+	| 'tips'
+	| 'rows'
+	| 'reachability'
+	| 'downstreams'
+	| 'rowsStats'
+	// A throw past structural validation (e.g. the restore refresh's enumerate chokes on a garbage rev).
+	| 'corrupt';
+
+/**
+ * Outcome of a restore attempt, reported via the {@link GitGraphSubProvider.openGraphSession} `onRestore`
+ * callback so the host can emit its single, assertable INFO line. `restored` is true only when the snapshot
+ * validated and seeded the (always-run) refresh — `refresh` then carries that refresh's path so the host can
+ * distinguish `→ refresh fast (+M)` from `→ refresh full (<reason>)`.
+ */
+export interface GraphSessionRestoreResult {
+	readonly restored: boolean;
+	/** Present when `!restored`: why the snapshot was discarded; the host logs `miss (<reason>)`. */
+	readonly reason?: GraphSessionRestoreDiscardReason;
+	/** Present when `restored`: how many window rows the snapshot carried. */
+	readonly rows?: number;
+	/** Present when `restored`: the post-restore refresh outcome (a restore ALWAYS refreshes to current truth). */
+	readonly refresh?: GitGraphSessionRefreshResult;
+}
+
+export interface GitGraphSessionRefreshOptions {
+	/** Rebuild anchor / find target — the loaded window's bottom sha (pins the walk's bottom boundary),
+	 *  or a selection/centering hint. Mirrors the `rev` the host passed to `getGraph` today. */
+	rev?: string;
+	limit?: number;
+	include?: { stats?: boolean };
+	/**
+	 * Force a FULL walk (skip the incremental seed) so every row's decorations — including the
+	 * host-serialized webview-item contexts reused rows otherwise keep — are rebuilt from fresh inputs.
+	 * For host-known invalidations the provider can't observe (pinned-ref changes, integration
+	 * connections); rare events, so the full-walk cost is acceptable.
+	 */
+	rebuild?: boolean;
+}
+
+/**
+ * Outcome of a {@link GitGraphSession.refresh}. `path` is `'fast'` only when the incremental head-walk
+ * fast path ran; a seeded fallback and an unseeded full walk both report `'full'` — a seeded fallback
+ * additionally carries `reason` (an unseeded full walk carries none), so a consumer can distinguish the
+ * two exactly as the host's `[graph] incremental walk` log did (log on `'fast'` or a `reason`, silent
+ * otherwise).
+ */
+export interface GitGraphSessionRefreshResult {
+	readonly path: 'fast' | 'full';
+	/** Present only on a SEEDED refresh that fell back to the full walk — the gate/boundary that forced it. */
+	readonly reason?: IncrementalGraphFallbackReason;
+	/** Fast path only: how many NEW commit rows the incremental enumeration added at the head. */
+	readonly added?: number;
+	/**
+	 * Which rows-plane channels this refresh actually changed, so the host marks the publisher precisely
+	 * instead of dirtying all six on every refresh. Filled by BOTH paths: the full path reports every
+	 * channel changed (a fresh walk replaces all); the fast path derives each honestly from its own work.
+	 * Correctness rule: a false negative is data loss, so a channel is reported `false` only when it
+	 * PROVABLY didn't change — never merely when uncertain. Excludes `refsMetadata`, which the session
+	 * doesn't produce (the host marks it via its own dedicated enrichment path).
+	 */
+	readonly changed: GitGraphSessionChangedChannels;
+}
+
+/** Per-channel change flags a {@link GitGraphSession.refresh} reports (see {@link GitGraphSessionRefreshResult.changed}). */
+export interface GitGraphSessionChangedChannels {
+	/** The loaded rows window — always `true` on a refresh (a head-walk reshapes it; the publisher's ledger
+	 *  diff derives the precise splice, including reused-row flag/reachability-index changes). */
+	readonly rows: boolean;
+	/** The shared reachability table grew (new dictionary/set entries appended) or started a new generation. */
+	readonly reachability: boolean;
+	/** New commit shas were introduced whose stats will be (re)queried. */
+	readonly rowsStats: boolean;
+	/** Full fallbacks that rewrite parents (unshallow / replace-ref change) recompute stats whose
+	 *  values may differ for already-shipped shas — the host must resend, not just append. */
+	readonly rowsStatsRecomputed?: boolean;
+	/** New avatar emails appeared in the map (value replacements ride the host's dedicated avatar path). */
+	readonly avatars: boolean;
+	/** The downstreams map (upstream name → tracking branch names) changed. */
+	readonly downstreams: boolean;
+}

package/src/git/models/issue.ts

@@ -4,6 +4,9 @@ import type { IssueOrPullRequest, IssueOrPullRequestState } from './issueOrPullR
 import type { ProviderReference } from './remoteProvider.js';
 import type { RepositoryIdentityDescriptor } from './repositoryIdentities.js';
 
+/** Selects which issue states a read should include. `all` covers open + closed. */
+export type IssueStateFilter = 'open' | 'closed' | 'all';
+
 export interface IssueShape extends IssueOrPullRequest {
 	author: IssueMember;
 	assignees: IssueMember[];
@@ -11,6 +14,7 @@ export interface IssueShape extends IssueOrPullRequest {
 	labels?: IssueLabel[];
 	body?: string;
 	project?: IssueProject;
+	issueType?: string;
 }
 
 @loggable(i => i.id)
@@ -37,6 +41,7 @@ export class Issue implements IssueShape {
 		public readonly body?: string,
 		public readonly project?: IssueProject,
 		public readonly number?: string,
+		public readonly issueType?: string,
 	) {}
 
 	static is(issue: unknown): issue is Issue {
@@ -60,7 +65,13 @@ export interface IssueLabel {
 
 export interface IssueMember {
 	id: string;
-	name: string;
+	/**
+	 * Absent when the provider exposes no display name for the member. Optional on purpose: a fallback string
+	 * invented here (`'unknown'`, `''`) can't be told apart from a real name downstream, so it can't be undone by a
+	 * consumer that needs to render something else — or nothing at all, as when the member feeds an AI prompt.
+	 * Each consumer picks its own presentation.
+	 */
+	name?: string;
 	avatarUrl?: string;
 	url?: string;
 }

package/src/git/models/pullRequest.ts

@@ -11,6 +11,13 @@ export type { PullRequestState };
 
 export interface PullRequestShape extends IssueOrPullRequest {
 	readonly author: PullRequestMember;
+	readonly body?: string;
+	/**
+	 * Canonical base-repository identity returned by the provider. Some providers
+	 * scope pull-request ids to a repository, so consumers must not have to infer
+	 * identity from optional refs or URLs.
+	 */
+	readonly repository?: IssueRepository;
 	readonly mergedDate?: Date;
 	readonly refs?: PullRequestRefs;
 	readonly isDraft?: boolean;
@@ -21,6 +28,8 @@ export interface PullRequestShape extends IssueOrPullRequest {
 	readonly reviewRequests?: PullRequestReviewer[];
 	readonly assignees?: PullRequestMember[];
 	readonly project?: IssueProject;
+	readonly number?: number;
+	readonly authoredByMe?: boolean;
 }
 
 @loggable(i => i.id)
@@ -56,6 +65,9 @@ export class PullRequest implements PullRequestShape {
 		public readonly statusCheckRollupState?: PullRequestStatusCheckRollupState,
 		public readonly project?: IssueProject,
 		public readonly version?: number,
+		public readonly body?: string,
+		public readonly number?: number,
+		public readonly authoredByMe?: boolean,
 	) {}
 
 	get closed(): boolean {
@@ -127,11 +139,19 @@ export interface PullRequestComparisonRefs {
 
 export interface PullRequestMember {
 	id: string;
-	name: string;
+	/**
+	 * Absent when the provider exposes no display name for the member — same contract as `IssueMember.name`: a
+	 * fallback invented here can't be told apart from a real name downstream, so each consumer picks its own
+	 * presentation.
+	 */
+	name?: string;
 	avatarUrl?: string;
 	url?: string;
 }
 
+/** Selects which pull request states a read should include. `all` covers open + closed + merged. */
+export type PullRequestStateFilter = 'open' | 'closed' | 'merged' | 'all';
+
 export interface PullRequestRef {
 	owner: string;
 	repo: string;
@@ -139,6 +159,12 @@ export interface PullRequestRef {
 	sha: string;
 	exists: boolean;
 	url: string;
+	/** HTTPS clone URL of the ref's repository, when the provider exposes it. */
+	cloneHttps?: string;
+	/** SSH clone URL of the ref's repository, when the provider exposes it. */
+	cloneSsh?: string;
+	/** Best-effort flag: whether the ref's repository is a fork. `undefined` when the provider can't tell. */
+	isFork?: boolean;
 }
 
 export interface PullRequestRefs {

package/src/git/models/repository.ts

@@ -74,6 +74,27 @@ export const repositoryChanges = exhaustiveArray<RepositoryChange>()([
 	'lastFetched',
 ]);
 
+/**
+ * The only changes {@link Repository.fireChange} accepts with `force` — delivered straight to the repository's
+ * emitter, bypassing the watch session, so they still arrive while it's suspended or when there's no watch handle
+ * at all (a repo being opened, or closed, or a virtual repo that never had one).
+ *
+ * These have nothing intrinsic in common — being forced IS the shared property, which is why this is keyed off
+ * `force` rather than some category of change.
+ *
+ * It's the partition consumers need: everything NOT listed here goes through the session, which does its
+ * pre-notification work (e.g. advancing a cache's status clock) exactly once, before it notifies anyone. Nothing
+ * runs upstream of a forced change, so a consumer bridging repository changes into a cache must handle these
+ * itself. Forcing a change that isn't listed is a compile error — and consumers gate on this same array, so
+ * listing one wires it up for free.
+ */
+export const forcedRepositoryChanges = [
+	'opened',
+	'closed',
+	'lastFetched',
+] as const satisfies readonly RepositoryChange[];
+export type ForcedRepositoryChange = (typeof forcedRepositoryChanges)[number];
+
 export interface RepositoryInit {
 	readonly id: string;
 	readonly path: string;
@@ -318,7 +339,9 @@ export class Repository {
 	}
 
 	protected fireChange(...changes: RepositoryChange[]): void;
-	protected fireChange(change: RepositoryChange, force: boolean): void;
+	/** Force-fire: delivered straight to the emitter, bypassing the watch session — see
+	 *  {@link forcedRepositoryChanges}, which is the only set this accepts. */
+	protected fireChange(change: ForcedRepositoryChange, force: true): void;
 	@trace()
 	protected fireChange(...args: RepositoryChange[] | [RepositoryChange, boolean]): void {
 		const lastArg = args.at(-1);

package/src/git/models/resourceDescriptor.ts

@@ -9,3 +9,20 @@ export type RepositoryDescriptor = ResourceDescriptor & {
 	owner: string;
 	name: string;
 };
+
+/**
+ * A normalized read scope that unifies the three provider scoping representations (repo-level
+ * `ProviderReposInput`, per-provider `PagingMode`, and org/project `ResourceDescriptor`s). Consumers pass
+ * this single shape; the integration resolves it to the provider-appropriate inputs. At least one field
+ * should be set:
+ * - `org`: GitHub login / Bitbucket workspace / Azure organization / GitLab namespace
+ * - `project`: Azure project / Jira project key
+ * - `resourceId`: Jira/Azure resource id
+ * - `repos`: explicit repositories to scope to
+ */
+export type ProviderScope = {
+	org?: string;
+	project?: string;
+	resourceId?: string;
+	repos?: RepositoryDescriptor[];
+};

package/src/git/models/signature.ts

@@ -27,3 +27,19 @@ export interface ValidationResult {
 	valid: boolean;
 	error?: string;
 }
+
+export interface SshPublicKey {
+	/** The SSH key type, e.g. `ssh-ed25519`, `ssh-rsa`, `ecdsa-sha2-nistp256`. */
+	keyType: string;
+	/** The base64-encoded public-key blob, as it appears after the key type in an `allowed_signers`/`.pub` entry. */
+	keyData: string;
+}
+
+export interface SshSignedCommit {
+	/** The signer's full SSH public key, extracted from the commit's SSH signature. */
+	key: SshPublicKey;
+	/** The committer's name from the commit object (the signing identity). */
+	name: string | undefined;
+	/** The committer's raw email from the commit object — the principal Git verifies the signature against. */
+	email: string | undefined;
+}