agentHost: distinguish a detached HEAD from a failed git probe

Addresses PR review feedback: keying the repair off a missing `branchName`
alone also matched a detached HEAD, which reports no branch by design.
Those sessions would have refreshed git state on every evaluation --
a periodic git call and log noise that could never produce a branch.

`parseGitStatusV2` already recognises `(detached)`; it now reports that as
`isDetachedHead` so the distinction survives into persisted session git
state, and a shared `needsSessionGitStateRefresh` predicate keeps the
Agent Merge and subscribe-time call sites in agreement about which states
are worth recomputing.

The controller additionally caps the repair at one attempt per runtime, so
any other checkout that cannot report a branch costs a single git call
rather than one per backstop, and logs a warning when a refresh still
yields no branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: benibenj

src/vs/platform/agentHost/common/state/sessionState.ts

@@ -1366,6 +1366,12 @@ export interface ISessionGitState {
 	readonly hasGitHubRemote?: boolean;
 	/** Current branch name. */
 	readonly branchName?: string;
+	/**
+	 * Whether `HEAD` is detached, which is why {@link branchName} is absent.
+	 * Distinguishes a legitimately branch-less checkout from git state left
+	 * behind by a probe that failed before it could resolve the branch.
+	 */
+	readonly isDetachedHead?: boolean;
 	/** Base branch the work targets (e.g. `main`). */
 	readonly baseBranchName?: string;
 	/** Upstream tracking branch (e.g. `origin/feature`). */
@@ -1581,6 +1587,7 @@ export function readSessionGitState(meta: SessionMeta | undefined): ISessionGitS
 	const result: {
 		hasGitHubRemote?: boolean;
 		branchName?: string;
+		isDetachedHead?: boolean;
 		baseBranchName?: string;
 		upstreamBranchName?: string;
 		incomingChanges?: number;
@@ -1593,6 +1600,7 @@ export function readSessionGitState(meta: SessionMeta | undefined): ISessionGitS
 	} = {};
 	if (typeof raw['hasGitHubRemote'] === 'boolean') { result.hasGitHubRemote = raw['hasGitHubRemote']; }
 	if (typeof raw['branchName'] === 'string') { result.branchName = raw['branchName']; }
+	if (typeof raw['isDetachedHead'] === 'boolean') { result.isDetachedHead = raw['isDetachedHead']; }
 	if (typeof raw['baseBranchName'] === 'string') { result.baseBranchName = raw['baseBranchName']; }
 	if (typeof raw['upstreamBranchName'] === 'string') { result.upstreamBranchName = raw['upstreamBranchName']; }
 	if (typeof raw['incomingChanges'] === 'number') { result.incomingChanges = raw['incomingChanges']; }
@@ -1605,6 +1613,23 @@ export function readSessionGitState(meta: SessionMeta | undefined): ISessionGitS
 	return result;
 }
 
+/**
+ * Whether a session's git state should be recomputed because it does not
+ * describe a usable checkout.
+ *
+ * A state that was never computed obviously qualifies. So does one that is
+ * missing its branch without a detached `HEAD` to explain it: `git status` is
+ * the only probe that reports the branch, so such a state is the residue of a
+ * probe that failed, and consumers that key off the branch (Agent Merge binds
+ * its pull request that way) stay stranded until it is recomputed. A detached
+ * `HEAD` is a legitimate branch-less checkout and must not be mistaken for it,
+ * or every caller would refresh in a loop against a repository that will never
+ * report a branch.
+ */
+export function needsSessionGitStateRefresh(gitState: ISessionGitState | undefined): boolean {
+	return gitState === undefined || (gitState.branchName === undefined && !gitState.isDetachedHead);
+}
+
 /**
  * Returns a new {@link SessionMeta} with the git-state payload set to
  * `gitState`, or with the git slot removed if `gitState` is `undefined`.

src/vs/platform/agentHost/node/agentHostGitService.ts

@@ -994,6 +994,7 @@ export class AgentHostGitService implements IAgentHostGitService {
 		const result: ISessionGitState = {
 			hasGitHubRemote,
 			branchName: status.branchName,
+			isDetachedHead: status.isDetachedHead,
 			baseBranchName,
 			upstreamBranchName: status.upstreamBranchName,
 			incomingChanges: status.incomingChanges,
@@ -1526,6 +1527,7 @@ export function parseGitDiffRawNumstat(output: string, repositoryRoot: URI, sess
  */
 export function parseGitStatusV2(output: string | undefined): {
 	branchName?: string;
+	isDetachedHead?: boolean;
 	upstreamBranchName?: string;
 	outgoingChanges?: number;
 	incomingChanges?: number;
@@ -1535,6 +1537,7 @@ export function parseGitStatusV2(output: string | undefined): {
 		return {};
 	}
 	let branchName: string | undefined;
+	let isDetachedHead: boolean | undefined;
 	let upstreamBranchName: string | undefined;
 	let outgoingChanges: number | undefined;
 	let incomingChanges: number | undefined;
@@ -1544,8 +1547,11 @@ export function parseGitStatusV2(output: string | undefined): {
 		if (!line) { continue; }
 		if (line.startsWith('# branch.head ')) {
 			const head = line.substring('# branch.head '.length).trim();
-			// `(detached)` is what git emits for a detached HEAD. Treat as no branch.
-			branchName = head === '(detached)' ? undefined : head;
+			// `(detached)` is what git emits for a detached HEAD. Treat as no
+			// branch, but report why so consumers can tell an intentionally
+			// branch-less checkout from a status probe that never ran.
+			isDetachedHead = head === '(detached)' ? true : undefined;
+			branchName = isDetachedHead ? undefined : head;
 		} else if (line.startsWith('# branch.upstream ')) {
 			upstreamBranchName = line.substring('# branch.upstream '.length).trim();
 		} else if (line.startsWith('# branch.ab ')) {
@@ -1558,7 +1564,7 @@ export function parseGitStatusV2(output: string | undefined): {
 			uncommittedChanges++;
 		}
 	}
-	return { branchName, upstreamBranchName, outgoingChanges, incomingChanges, uncommittedChanges };
+	return { branchName, isDetachedHead, upstreamBranchName, outgoingChanges, incomingChanges, uncommittedChanges };
 }
 
 /** Exported for tests. */

src/vs/platform/agentHost/node/agentMergeController.ts

@@ -21,7 +21,7 @@ import { deriveGitHubEndpoints } from '../common/githubEndpoints.js';
 import { SessionConfigKey } from '../common/sessionConfigKeys.js';
 import { ActionType } from '../common/state/protocol/common/actions.js';
 import { AuthRequiredReason } from '../common/state/sessionActions.js';
-import { getSessionRelatedPullRequestUrls, isAhpChatChannel, isSessionStatusArchived, parseRequiredSessionUriFromChatUri, readSessionGitHubState, readSessionGitState, SessionLifecycle, TurnState } from '../common/state/sessionState.js';
+import { getSessionRelatedPullRequestUrls, isAhpChatChannel, isSessionStatusArchived, needsSessionGitStateRefresh, parseRequiredSessionUriFromChatUri, readSessionGitHubState, readSessionGitState, SessionLifecycle, TurnState } from '../common/state/sessionState.js';
 import { IAgentConfigurationService } from './agentConfigurationService.js';
 import { IAgentHostGitHubEndpointService } from './agentHostGitHubEndpointService.js';
 import { AgentHostStateManager, IAgentHostStateManager } from './agentHostStateManager.js';
@@ -47,6 +47,13 @@ class AgentMergeRuntime extends Disposable {
 	readonly evaluationScheduler: RunOnceScheduler;
 	readonly backstopScheduler: RunOnceScheduler;
 	ref: PullRequestRef | undefined;
+	/**
+	 * Whether this runtime already tried to recompute git state that reported
+	 * no usable branch. Caps that repair at one git call per runtime so a
+	 * checkout that can never report a branch does not spawn one on every
+	 * backstop.
+	 */
+	didRefreshForMissingBranch = false;
 
 	constructor(
 		readonly session: string,
@@ -483,7 +490,7 @@ export class AgentMergeController extends Disposable {
 
 	/**
 	 * Resolves the branch Agent Merge should act on, repairing session git
-	 * state that is missing it.
+	 * state that does not report one.
 	 *
 	 * A failed git probe can leave persisted git state without a branch. The
 	 * refresh that would repair it normally rides along with a client watching
@@ -492,12 +499,21 @@ export class AgentMergeController extends Disposable {
 	 * — binding the pull request, subscribing to it, acting on its feedback —
 	 * is gated on the branch, so without this the session idles on the backstop
 	 * indefinitely and Agent Merge silently never runs.
+	 *
+	 * A detached `HEAD` is excluded: it reports no branch by design, so
+	 * refreshing would never produce one. The attempt is capped at once per
+	 * runtime regardless, so any other checkout that cannot report a branch
+	 * costs a single git call rather than one per backstop.
 	 */
 	private async _resolveCurrentBranch(session: string, runtime: AgentMergeRuntime, state: NonNullable<ReturnType<AgentHostStateManager['getSessionState']>>): Promise<string | undefined> {
-		const branchName = readSessionGitState(state._meta)?.branchName;
-		if (branchName) {
-			return branchName;
+		const gitState = readSessionGitState(state._meta);
+		if (gitState?.branchName) {
+			return gitState.branchName;
+		}
+		if (runtime.didRefreshForMissingBranch || !needsSessionGitStateRefresh(gitState)) {
+			return undefined;
 		}
+		runtime.didRefreshForMissingBranch = true;
 		this._logService.debug(`[AgentMergeController] Refreshing git state because the session reports no branch: session=${session}`);
 		await this._gitStateService.refreshSessionGitState(session, state.workingDirectories?.[0] ? URI.parse(state.workingDirectories[0]) : undefined);
 		if (!this._isCurrentRuntime(session, runtime)) {
@@ -506,6 +522,8 @@ export class AgentMergeController extends Disposable {
 		const refreshed = readSessionGitState(this._stateManager.getSessionState(session)?._meta)?.branchName;
 		if (refreshed) {
 			this._logService.info(`[AgentMergeController] Recovered the session branch after refreshing git state: session=${session}`);
+		} else {
+			this._logService.warn(`[AgentMergeController] Session still reports no branch after refreshing git state: session=${session}`);
 		}
 		return refreshed;
 	}

src/vs/platform/agentHost/node/agentService.ts

@@ -37,7 +37,7 @@ import type { InvokeChangesetOperationParams, InvokeChangesetOperationResult } f
 import { AhpErrorCodes, AHP_SESSION_NOT_FOUND, ContentEncoding, JSON_RPC_INTERNAL_ERROR, ProtocolError, ResourceChangeType, ResourceType, ResourceWriteMode, type CreateResourceWatchParams, type CreateResourceWatchResult, type DirectoryEntry, type ResourceCopyParams, type ResourceCopyResult, type ResourceDeleteParams, type ResourceDeleteResult, type ResourceListResult, type ResourceMkdirParams, type ResourceMkdirResult, type ResourceMoveParams, type ResourceMoveResult, type ResourceReadResult, type ResourceResolveParams, type ResourceResolveResult, type ResourceWatchState, type ResourceWriteParams, type ResourceWriteResult, type IStateSnapshot } from '../common/state/sessionProtocol.js';
 import { ChangesSummary, ChatInteractivity, ChatOriginKind, MessageAttachmentKind, type Annotation, type AnnotationEntry, type AnnotationsState, type ChatOrigin, type Customization, type Message, type MessageAttachment, type MessageResourceAttachment } from '../common/state/protocol/state.js';
 import type { ChatPendingMessageSetAction, ChatTurnStartedAction, SessionConfigChangedAction } from '../common/state/protocol/actions.js';
-import { ISessionGitHubState, ISessionGitState, MessageKind, ResponsePartKind, SESSION_META_GITHUB_KEY, SESSION_META_GIT_KEY, SESSION_META_MULTI_ROOT_KEY, SESSION_META_SOURCE_CONTROL_KEY, AH_META_ORCHESTRATION_DB_KEY, readSessionSpawnDepth, parseSessionOrchestration, withSessionSpawnDepth, withSessionOrchestration, SessionLifecycle, SessionStatus, ToolCallStatus, ToolResultContentType, AH_META_WORKSPACELESS_DB_KEY, AH_META_IS_ARCHIVED_DB_KEY, AH_META_IS_DONE_DB_KEY, AH_META_IS_READ_DB_KEY, buildChatUri, buildDefaultChatUri, buildResourceWatchChannelUri, buildSubagentChatUri, buildSubagentSessionUriPrefix, hostBuildInfoFromProduct, isAhpChatChannel, isDefaultChatUri, isSubagentChatUri, isSubagentSession, parseChatUri, parseDefaultChatUri, parseRequiredSessionUriFromChatUri, parseResourceWatchChannelUri, parseSessionMultiRootMetadata, parseSubagentSessionUri, readSessionExternal, readSessionGitHubState, readSessionGitState, readSessionMultiRootMetadata, readSessionSourceControlState, readSessionWorkspaceless, withSessionExternal, withSessionGitHubState, withSessionGitState, withSessionMultiRootMetadata, withSessionSourceControlState, withSessionStatusFlag, withSessionWorkspaceless, withSessionFolderPickerDecision, readSessionFolderPickerDecision, parseSessionFolderPickerDecision, SESSION_META_FOLDER_PICKER_KEY, readSessionEhcliAdoptable, type ISessionSourceControlState, type SessionConfigState, type SessionSummary, type ToolResultSubagentContent, type Turn, type UsageInfo, chatStorageUri, hasReportedUsage } from '../common/state/sessionState.js';
+import { ISessionGitHubState, ISessionGitState, MessageKind, ResponsePartKind, SESSION_META_GITHUB_KEY, SESSION_META_GIT_KEY, SESSION_META_MULTI_ROOT_KEY, SESSION_META_SOURCE_CONTROL_KEY, AH_META_ORCHESTRATION_DB_KEY, readSessionSpawnDepth, parseSessionOrchestration, withSessionSpawnDepth, withSessionOrchestration, SessionLifecycle, SessionStatus, ToolCallStatus, ToolResultContentType, AH_META_WORKSPACELESS_DB_KEY, AH_META_IS_ARCHIVED_DB_KEY, AH_META_IS_DONE_DB_KEY, AH_META_IS_READ_DB_KEY, buildChatUri, buildDefaultChatUri, buildResourceWatchChannelUri, buildSubagentChatUri, buildSubagentSessionUriPrefix, hostBuildInfoFromProduct, isAhpChatChannel, isDefaultChatUri, isSubagentChatUri, isSubagentSession, needsSessionGitStateRefresh, parseChatUri, parseDefaultChatUri, parseRequiredSessionUriFromChatUri, parseResourceWatchChannelUri, parseSessionMultiRootMetadata, parseSubagentSessionUri, readSessionExternal, readSessionGitHubState, readSessionGitState, readSessionMultiRootMetadata, readSessionSourceControlState, readSessionWorkspaceless, withSessionExternal, withSessionGitHubState, withSessionGitState, withSessionMultiRootMetadata, withSessionSourceControlState, withSessionStatusFlag, withSessionWorkspaceless, withSessionFolderPickerDecision, readSessionFolderPickerDecision, parseSessionFolderPickerDecision, SESSION_META_FOLDER_PICKER_KEY, readSessionEhcliAdoptable, type ISessionSourceControlState, type SessionConfigState, type SessionSummary, type ToolResultSubagentContent, type Turn, type UsageInfo, chatStorageUri, hasReportedUsage } from '../common/state/sessionState.js';
 import { readToolCallMeta } from '../common/meta/agentToolCallMeta.js';
 import { readEphemeralSessionMeta, withEphemeralSessionMeta } from '../common/meta/agentEphemeralSessionMeta.js';
 import { readChatSurfaceMeta, withChatSurfaceMeta } from '../common/meta/agentChatSurfaceMeta.js';
@@ -3842,11 +3842,12 @@ export class AgentService extends Disposable implements IAgentService {
 			// restore path that normally calls `_attachGitState` is skipped — so
 			// trigger it lazily here for the first subscriber. `_attachGitState`
 			// is async and updates `_meta.git` once ready, which clients see via
-			// the normal state-update stream. A state without a branch is treated
-			// as missing too: a failed git probe can persist one, and it would
-			// otherwise mask the very repair this lazy refresh exists to perform.
+			// the normal state-update stream. State that does not describe a
+			// usable checkout counts as missing too: a failed probe can persist
+			// a branch-less remnant, and it would otherwise mask the very
+			// repair this lazy refresh exists to perform.
 			const sessionState = this._stateManager.getSessionState(resourceStr);
-			if (!isAhpChatChannel(resourceStr) && sessionState && readSessionGitState(sessionState._meta)?.branchName === undefined) {
+			if (!isAhpChatChannel(resourceStr) && sessionState && needsSessionGitStateRefresh(readSessionGitState(sessionState._meta))) {
 				const workingDirectory = sessionState.workingDirectories?.[0]
 					? URI.parse(sessionState.workingDirectories[0])
 					: undefined;

src/vs/platform/agentHost/test/node/agentHostGitService.test.ts

@@ -9,6 +9,7 @@ import { formatGitError, getRemoteTrackingRef, GitCheckoutProgressParser, isRetr
 import { buildGitBlobUri } from '../../node/gitDiffContent.js';
 import { URI } from '../../../../base/common/uri.js';
 import { EMPTY_TREE_OBJECT, getBranchCompletions, resolveDiffBaseBranchName } from '../../common/agentHostGitService.js';
+import { needsSessionGitStateRefresh } from '../../common/state/sessionState.js';
 
 suite('AgentHostGitService', () => {
 	ensureNoDisposablesAreLeakedInTestSuite();
@@ -104,6 +105,7 @@ suite('AgentHostGitService', () => {
 			].join('\n');
 			assert.deepStrictEqual(parseGitStatusV2(out), {
 				branchName: 'main',
+				isDetachedHead: undefined,
 				upstreamBranchName: 'origin/main',
 				outgoingChanges: 0,
 				incomingChanges: 0,
@@ -123,6 +125,7 @@ suite('AgentHostGitService', () => {
 			].join('\n');
 			assert.deepStrictEqual(parseGitStatusV2(out), {
 				branchName: 'feature',
+				isDetachedHead: undefined,
 				upstreamBranchName: 'origin/feature',
 				outgoingChanges: 3,
 				incomingChanges: 2,
@@ -137,6 +140,7 @@ suite('AgentHostGitService', () => {
 			].join('\n');
 			assert.deepStrictEqual(parseGitStatusV2(out), {
 				branchName: undefined,
+				isDetachedHead: true,
 				upstreamBranchName: undefined,
 				outgoingChanges: undefined,
 				incomingChanges: undefined,
@@ -149,6 +153,24 @@ suite('AgentHostGitService', () => {
 		});
 	});
 
+	suite('needsSessionGitStateRefresh', () => {
+		test('separates a branch-less probe failure from a detached HEAD', () => {
+			assert.deepStrictEqual({
+				neverComputed: needsSessionGitStateRefresh(undefined),
+				// The residue of a failed `git status`, as persisted before the
+				// probe learned to withhold state it could not compute.
+				probeFailureRemnant: needsSessionGitStateRefresh({ baseBranchName: 'main' }),
+				detachedHead: needsSessionGitStateRefresh({ isDetachedHead: true, baseBranchName: 'main' }),
+				onABranch: needsSessionGitStateRefresh({ branchName: 'feature', baseBranchName: 'main' }),
+			}, {
+				neverComputed: true,
+				probeFailureRemnant: true,
+				detachedHead: false,
+				onABranch: false,
+			});
+		});
+	});
+
 	suite('parseHasGitHubRemote', () => {
 		test('detects ssh github remote', () => {
 			assert.strictEqual(parseHasGitHubRemote('origin\tgit@github.com:owner/repo.git (fetch)\n'), true);