From 14d54eeff389602c32ff8f42380e1632474feb1e Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 11:09:45 -0800
Subject: [PATCH 01/13] Fix createSourceFromState to use resolvedRef for VCS
 sources

Updated the createSourceFromState function to override the ref in the
config with meta.resolvedRef when available for GitHub, GitLab, and
BitBucket sources.

This ensures that listFiles and readFile operations use the exact
commit SHA that was indexed, rather than the branch name that may
have moved since indexing.

Agent-Id: agent-ac8ae6ab-1e3e-43f0-99fb-bdad5a5fb83d
---
 src/clients/multi-index-runner.ts | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/clients/multi-index-runner.ts b/src/clients/multi-index-runner.ts
index f15027f..752328a 100644
--- a/src/clients/multi-index-runner.ts
+++ b/src/clients/multi-index-runner.ts
@@ -43,13 +43,22 @@ async function createSourceFromState(state: IndexStateSearchOnly): Promise<Sourc
   const meta = state.source;
   if (meta.type === "github") {
     const { GitHubSource } = await import("../sources/github.js");
-    return new GitHubSource(meta.config);
+    return new GitHubSource({
+      ...meta.config,
+      ref: meta.resolvedRef ?? meta.config.ref,
+    });
   } else if (meta.type === "gitlab") {
     const { GitLabSource } = await import("../sources/gitlab.js");
-    return new GitLabSource(meta.config);
+    return new GitLabSource({
+      ...meta.config,
+      ref: meta.resolvedRef ?? meta.config.ref,
+    });
   } else if (meta.type === "bitbucket") {
     const { BitBucketSource } = await import("../sources/bitbucket.js");
-    return new BitBucketSource(meta.config);
+    return new BitBucketSource({
+      ...meta.config,
+      ref: meta.resolvedRef ?? meta.config.ref,
+    });
   } else if (meta.type === "website") {
     const { WebsiteSource } = await import("../sources/website.js");
     return new WebsiteSource(meta.config);

From 99cced44479e4d27b61f1b044c118f3f52f29959 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 11:10:16 -0800
Subject: [PATCH 02/13] Add tests for resolvedRef usage in
 createSourceFromState

Add tests to verify that createSourceFromState correctly uses
resolvedRef from state metadata when creating source instances:

- Test that GitHub source receives resolvedRef as ref when present
- Test that GitLab source receives resolvedRef as ref when present
- Test that BitBucket source receives resolvedRef as ref when present
- Test that original config.ref is used when resolvedRef is missing
- Test that website sources work correctly without resolvedRef

Uses vi.mock to mock the source constructors and verify they receive
the correct ref parameter.

Agent-Id: agent-cb10d5cd-ffb8-488e-81b3-914f1aeda05a
---
 src/clients/multi-index-runner.test.ts | 223 +++++++++++++++++++++++++
 1 file changed, 223 insertions(+)
 create mode 100644 src/clients/multi-index-runner.test.ts

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
new file mode 100644
index 0000000..947fd2e
--- /dev/null
+++ b/src/clients/multi-index-runner.test.ts
@@ -0,0 +1,223 @@
+/**
+ * Tests for MultiIndexRunner
+ * 
+ * These tests verify that createSourceFromState correctly uses resolvedRef
+ * from state metadata when creating source instances.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { IndexStateSearchOnly, SourceMetadata } from "../core/types.js";
+import type { IndexStoreReader } from "../stores/types.js";
+
+// Mock the source modules
+vi.mock("../sources/github.js", () => ({
+  GitHubSource: vi.fn().mockImplementation((config) => ({
+    type: "github" as const,
+    config,
+    listFiles: vi.fn().mockResolvedValue([]),
+    readFile: vi.fn().mockResolvedValue(""),
+    fetchAll: vi.fn(),
+    fetchChanges: vi.fn(),
+    getMetadata: vi.fn().mockResolvedValue({
+      type: "github",
+      config,
+      syncedAt: new Date().toISOString(),
+    }),
+  })),
+}));
+
+vi.mock("../sources/gitlab.js", () => ({
+  GitLabSource: vi.fn().mockImplementation((config) => ({
+    type: "gitlab" as const,
+    config,
+    listFiles: vi.fn().mockResolvedValue([]),
+    readFile: vi.fn().mockResolvedValue(""),
+    fetchAll: vi.fn(),
+    fetchChanges: vi.fn(),
+    getMetadata: vi.fn().mockResolvedValue({
+      type: "gitlab",
+      config,
+      syncedAt: new Date().toISOString(),
+    }),
+  })),
+}));
+
+vi.mock("../sources/bitbucket.js", () => ({
+  BitBucketSource: vi.fn().mockImplementation((config) => ({
+    type: "bitbucket" as const,
+    config,
+    listFiles: vi.fn().mockResolvedValue([]),
+    readFile: vi.fn().mockResolvedValue(""),
+    fetchAll: vi.fn(),
+    fetchChanges: vi.fn(),
+    getMetadata: vi.fn().mockResolvedValue({
+      type: "bitbucket",
+      config,
+      syncedAt: new Date().toISOString(),
+    }),
+  })),
+}));
+
+vi.mock("../sources/website.js", () => ({
+  WebsiteSource: vi.fn().mockImplementation((config) => ({
+    type: "website" as const,
+    config,
+    listFiles: vi.fn().mockResolvedValue([]),
+    readFile: vi.fn().mockResolvedValue(""),
+    fetchAll: vi.fn(),
+    fetchChanges: vi.fn(),
+    getMetadata: vi.fn().mockResolvedValue({
+      type: "website",
+      config,
+      syncedAt: new Date().toISOString(),
+    }),
+  })),
+}));
+
+// Import after mocking
+import { MultiIndexRunner } from "./multi-index-runner.js";
+import { GitHubSource } from "../sources/github.js";
+import { GitLabSource } from "../sources/gitlab.js";
+import { BitBucketSource } from "../sources/bitbucket.js";
+import { WebsiteSource } from "../sources/website.js";
+
+// Create mock state with specific source metadata
+const createMockState = (source: SourceMetadata): IndexStateSearchOnly => ({
+  version: 1,
+  contextState: {
+    version: 1,
+  } as any,
+  source,
+});
+
+// Create mock store
+const createMockStore = (stateMap: Map<string, IndexStateSearchOnly>): IndexStoreReader => ({
+  loadState: vi.fn().mockImplementation(async (name: string) => stateMap.get(name) ?? null),
+  loadSearch: vi.fn().mockImplementation(async (name: string) => stateMap.get(name) ?? null),
+  list: vi.fn().mockResolvedValue(Array.from(stateMap.keys())),
+});
+
+describe("MultiIndexRunner", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("createSourceFromState via getClient", () => {
+    it("uses resolvedRef for GitHub source when present", async () => {
+      const state = createMockState({
+        type: "github",
+        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
+        resolvedRef: "abc123sha",
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(GitHubSource).toHaveBeenCalledWith({
+        owner: "test-owner",
+        repo: "test-repo",
+        ref: "abc123sha",
+      });
+    });
+
+    it("uses resolvedRef for GitLab source when present", async () => {
+      const state = createMockState({
+        type: "gitlab",
+        config: { projectId: "group/project", ref: "main" },
+        resolvedRef: "def456sha",
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(GitLabSource).toHaveBeenCalledWith({
+        projectId: "group/project",
+        ref: "def456sha",
+      });
+    });
+
+    it("uses resolvedRef for BitBucket source when present", async () => {
+      const state = createMockState({
+        type: "bitbucket",
+        config: { workspace: "my-workspace", repo: "my-repo", ref: "develop" },
+        resolvedRef: "ghi789sha",
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(BitBucketSource).toHaveBeenCalledWith({
+        workspace: "my-workspace",
+        repo: "my-repo",
+        ref: "ghi789sha",
+      });
+    });
+
+    it("uses original config.ref when resolvedRef is missing for GitHub", async () => {
+      const state = createMockState({
+        type: "github",
+        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
+        // No resolvedRef
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(GitHubSource).toHaveBeenCalledWith({
+        owner: "test-owner",
+        repo: "test-repo",
+        ref: "main",
+      });
+    });
+
+    it("uses original config.ref when resolvedRef is undefined for GitLab", async () => {
+      const state = createMockState({
+        type: "gitlab",
+        config: { projectId: "group/project", ref: "develop" },
+        resolvedRef: undefined,
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(GitLabSource).toHaveBeenCalledWith({
+        projectId: "group/project",
+        ref: "develop",
+      });
+    });
+
+    it("website source works correctly without resolvedRef", async () => {
+      const state = createMockState({
+        type: "website",
+        config: { url: "https://example.com", maxDepth: 2 },
+        syncedAt: new Date().toISOString(),
+      });
+      const stateMap = new Map([["test-index", state]]);
+      const store = createMockStore(stateMap);
+
+      const runner = await MultiIndexRunner.create({ store });
+      await runner.getClient("test-index");
+
+      expect(WebsiteSource).toHaveBeenCalledWith({
+        url: "https://example.com",
+        maxDepth: 2,
+      });
+    });
+  });
+});
+

From 1ec9f174188d983fe77ad023f80baafaf7336a53 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 11:19:41 -0800
Subject: [PATCH 03/13] Fix multi-index-runner tests to skip when SDK
 unavailable

The tests require the Augment SDK which needs API credentials.
Following the pattern used in other test files (mcp-server.test.ts,
search-client.test.ts), skip the tests when the SDK fails to load
or when API credentials are not available.

Agent-Id: agent-83532e9b-da56-46ec-a480-58d2ec43c946
---
 src/clients/multi-index-runner.test.ts | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
index 947fd2e..a490463 100644
--- a/src/clients/multi-index-runner.test.ts
+++ b/src/clients/multi-index-runner.test.ts
@@ -74,8 +74,17 @@ vi.mock("../sources/website.js", () => ({
   })),
 }));
 
-// Import after mocking
-import { MultiIndexRunner } from "./multi-index-runner.js";
+// Try to import SDK-dependent modules
+let MultiIndexRunner: typeof import("./multi-index-runner.js").MultiIndexRunner;
+let sdkLoadError: Error | null = null;
+
+try {
+  const mod = await import("./multi-index-runner.js");
+  MultiIndexRunner = mod.MultiIndexRunner;
+} catch (e) {
+  sdkLoadError = e as Error;
+}
+
 import { GitHubSource } from "../sources/github.js";
 import { GitLabSource } from "../sources/gitlab.js";
 import { BitBucketSource } from "../sources/bitbucket.js";
@@ -97,7 +106,12 @@ const createMockStore = (stateMap: Map<string, IndexStateSearchOnly>): IndexStor
   list: vi.fn().mockResolvedValue(Array.from(stateMap.keys())),
 });
 
-describe("MultiIndexRunner", () => {
+// Check if API credentials are available for tests
+const hasApiCredentials = !!(
+  process.env.AUGMENT_API_TOKEN && process.env.AUGMENT_API_URL
+);
+
+describe.skipIf(sdkLoadError !== null || !hasApiCredentials)("MultiIndexRunner", () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -220,4 +234,3 @@ describe("MultiIndexRunner", () => {
     });
   });
 });
-

From 32f4382e6bf3ecac778aac1e23cf87ecd2483749 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 12:13:31 -0800
Subject: [PATCH 04/13] Refactor tests to directly test createSourceFromState

- Export createSourceFromState for testing
- Rewrite tests to call the function directly instead of going through MultiIndexRunner
- Tests now run as unit tests without requiring API credentials
- Added test for unknown source type error handling
---
 src/clients/multi-index-runner.test.ts | 189 +++++++++----------------
 src/clients/multi-index-runner.ts      |  11 +-
 2 files changed, 77 insertions(+), 123 deletions(-)

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
index a490463..8f092eb 100644
--- a/src/clients/multi-index-runner.test.ts
+++ b/src/clients/multi-index-runner.test.ts
@@ -1,28 +1,21 @@
 /**
- * Tests for MultiIndexRunner
- * 
+ * Tests for createSourceFromState
+ *
  * These tests verify that createSourceFromState correctly uses resolvedRef
  * from state metadata when creating source instances.
+ *
+ * The tests mock the source modules to capture what config gets passed
+ * to the constructors, without needing API credentials.
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import type { IndexStateSearchOnly, SourceMetadata } from "../core/types.js";
-import type { IndexStoreReader } from "../stores/types.js";
 
-// Mock the source modules
+// Mock the source modules to capture constructor calls
 vi.mock("../sources/github.js", () => ({
   GitHubSource: vi.fn().mockImplementation((config) => ({
     type: "github" as const,
     config,
-    listFiles: vi.fn().mockResolvedValue([]),
-    readFile: vi.fn().mockResolvedValue(""),
-    fetchAll: vi.fn(),
-    fetchChanges: vi.fn(),
-    getMetadata: vi.fn().mockResolvedValue({
-      type: "github",
-      config,
-      syncedAt: new Date().toISOString(),
-    }),
   })),
 }));
 
@@ -30,15 +23,6 @@ vi.mock("../sources/gitlab.js", () => ({
   GitLabSource: vi.fn().mockImplementation((config) => ({
     type: "gitlab" as const,
     config,
-    listFiles: vi.fn().mockResolvedValue([]),
-    readFile: vi.fn().mockResolvedValue(""),
-    fetchAll: vi.fn(),
-    fetchChanges: vi.fn(),
-    getMetadata: vi.fn().mockResolvedValue({
-      type: "gitlab",
-      config,
-      syncedAt: new Date().toISOString(),
-    }),
   })),
 }));
 
@@ -46,15 +30,6 @@ vi.mock("../sources/bitbucket.js", () => ({
   BitBucketSource: vi.fn().mockImplementation((config) => ({
     type: "bitbucket" as const,
     config,
-    listFiles: vi.fn().mockResolvedValue([]),
-    readFile: vi.fn().mockResolvedValue(""),
-    fetchAll: vi.fn(),
-    fetchChanges: vi.fn(),
-    getMetadata: vi.fn().mockResolvedValue({
-      type: "bitbucket",
-      config,
-      syncedAt: new Date().toISOString(),
-    }),
   })),
 }));
 
@@ -62,29 +37,11 @@ vi.mock("../sources/website.js", () => ({
   WebsiteSource: vi.fn().mockImplementation((config) => ({
     type: "website" as const,
     config,
-    listFiles: vi.fn().mockResolvedValue([]),
-    readFile: vi.fn().mockResolvedValue(""),
-    fetchAll: vi.fn(),
-    fetchChanges: vi.fn(),
-    getMetadata: vi.fn().mockResolvedValue({
-      type: "website",
-      config,
-      syncedAt: new Date().toISOString(),
-    }),
   })),
 }));
 
-// Try to import SDK-dependent modules
-let MultiIndexRunner: typeof import("./multi-index-runner.js").MultiIndexRunner;
-let sdkLoadError: Error | null = null;
-
-try {
-  const mod = await import("./multi-index-runner.js");
-  MultiIndexRunner = mod.MultiIndexRunner;
-} catch (e) {
-  sdkLoadError = e as Error;
-}
-
+// Import the function under test and mocked sources
+import { createSourceFromState } from "./multi-index-runner.js";
 import { GitHubSource } from "../sources/github.js";
 import { GitLabSource } from "../sources/gitlab.js";
 import { BitBucketSource } from "../sources/bitbucket.js";
@@ -99,36 +56,21 @@ const createMockState = (source: SourceMetadata): IndexStateSearchOnly => ({
   source,
 });
 
-// Create mock store
-const createMockStore = (stateMap: Map<string, IndexStateSearchOnly>): IndexStoreReader => ({
-  loadState: vi.fn().mockImplementation(async (name: string) => stateMap.get(name) ?? null),
-  loadSearch: vi.fn().mockImplementation(async (name: string) => stateMap.get(name) ?? null),
-  list: vi.fn().mockResolvedValue(Array.from(stateMap.keys())),
-});
-
-// Check if API credentials are available for tests
-const hasApiCredentials = !!(
-  process.env.AUGMENT_API_TOKEN && process.env.AUGMENT_API_URL
-);
-
-describe.skipIf(sdkLoadError !== null || !hasApiCredentials)("MultiIndexRunner", () => {
+describe("createSourceFromState", () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  describe("createSourceFromState via getClient", () => {
-    it("uses resolvedRef for GitHub source when present", async () => {
+  describe("GitHub source", () => {
+    it("uses resolvedRef when present", async () => {
       const state = createMockState({
         type: "github",
         config: { owner: "test-owner", repo: "test-repo", ref: "main" },
         resolvedRef: "abc123sha",
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
       expect(GitHubSource).toHaveBeenCalledWith({
         owner: "test-owner",
@@ -137,95 +79,86 @@ describe.skipIf(sdkLoadError !== null || !hasApiCredentials)("MultiIndexRunner",
       });
     });
 
-    it("uses resolvedRef for GitLab source when present", async () => {
+    it("uses config.ref when resolvedRef is missing", async () => {
       const state = createMockState({
-        type: "gitlab",
-        config: { projectId: "group/project", ref: "main" },
-        resolvedRef: "def456sha",
+        type: "github",
+        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
+        // No resolvedRef
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
-      expect(GitLabSource).toHaveBeenCalledWith({
-        projectId: "group/project",
-        ref: "def456sha",
+      expect(GitHubSource).toHaveBeenCalledWith({
+        owner: "test-owner",
+        repo: "test-repo",
+        ref: "main",
       });
     });
+  });
 
-    it("uses resolvedRef for BitBucket source when present", async () => {
+  describe("GitLab source", () => {
+    it("uses resolvedRef when present", async () => {
       const state = createMockState({
-        type: "bitbucket",
-        config: { workspace: "my-workspace", repo: "my-repo", ref: "develop" },
-        resolvedRef: "ghi789sha",
+        type: "gitlab",
+        config: { projectId: "group/project", ref: "main" },
+        resolvedRef: "def456sha",
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
-      expect(BitBucketSource).toHaveBeenCalledWith({
-        workspace: "my-workspace",
-        repo: "my-repo",
-        ref: "ghi789sha",
+      expect(GitLabSource).toHaveBeenCalledWith({
+        projectId: "group/project",
+        ref: "def456sha",
       });
     });
 
-    it("uses original config.ref when resolvedRef is missing for GitHub", async () => {
+    it("uses config.ref when resolvedRef is undefined", async () => {
       const state = createMockState({
-        type: "github",
-        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
-        // No resolvedRef
+        type: "gitlab",
+        config: { projectId: "group/project", ref: "develop" },
+        resolvedRef: undefined,
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
-      expect(GitHubSource).toHaveBeenCalledWith({
-        owner: "test-owner",
-        repo: "test-repo",
-        ref: "main",
+      expect(GitLabSource).toHaveBeenCalledWith({
+        projectId: "group/project",
+        ref: "develop",
       });
     });
+  });
 
-    it("uses original config.ref when resolvedRef is undefined for GitLab", async () => {
+  describe("BitBucket source", () => {
+    it("uses resolvedRef when present", async () => {
       const state = createMockState({
-        type: "gitlab",
-        config: { projectId: "group/project", ref: "develop" },
-        resolvedRef: undefined,
+        type: "bitbucket",
+        config: { workspace: "my-workspace", repo: "my-repo", ref: "develop" },
+        resolvedRef: "ghi789sha",
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
-      expect(GitLabSource).toHaveBeenCalledWith({
-        projectId: "group/project",
-        ref: "develop",
+      expect(BitBucketSource).toHaveBeenCalledWith({
+        workspace: "my-workspace",
+        repo: "my-repo",
+        ref: "ghi789sha",
       });
     });
+  });
 
-    it("website source works correctly without resolvedRef", async () => {
+  describe("Website source", () => {
+    it("works correctly without resolvedRef", async () => {
       const state = createMockState({
         type: "website",
         config: { url: "https://example.com", maxDepth: 2 },
         syncedAt: new Date().toISOString(),
       });
-      const stateMap = new Map([["test-index", state]]);
-      const store = createMockStore(stateMap);
 
-      const runner = await MultiIndexRunner.create({ store });
-      await runner.getClient("test-index");
+      await createSourceFromState(state);
 
       expect(WebsiteSource).toHaveBeenCalledWith({
         url: "https://example.com",
@@ -233,4 +166,18 @@ describe.skipIf(sdkLoadError !== null || !hasApiCredentials)("MultiIndexRunner",
       });
     });
   });
+
+  describe("unknown source type", () => {
+    it("throws error for unknown source type", async () => {
+      const state = createMockState({
+        type: "unknown" as any,
+        config: {},
+        syncedAt: new Date().toISOString(),
+      });
+
+      await expect(createSourceFromState(state)).rejects.toThrow(
+        "Unknown source type: unknown"
+      );
+    });
+  });
 });
diff --git a/src/clients/multi-index-runner.ts b/src/clients/multi-index-runner.ts
index 752328a..40c64c6 100644
--- a/src/clients/multi-index-runner.ts
+++ b/src/clients/multi-index-runner.ts
@@ -38,8 +38,15 @@ export interface MultiIndexRunnerConfig {
   searchOnly?: boolean;
 }
 
-/** Create a Source from index state metadata */
-async function createSourceFromState(state: IndexStateSearchOnly): Promise<Source> {
+/**
+ * Create a Source from index state metadata.
+ *
+ * For VCS sources (GitHub, GitLab, BitBucket), uses `resolvedRef` (the indexed commit SHA)
+ * if available, falling back to `config.ref` (branch name) if not.
+ *
+ * @internal Exported for testing
+ */
+export async function createSourceFromState(state: IndexStateSearchOnly): Promise<Source> {
   const meta = state.source;
   if (meta.type === "github") {
     const { GitHubSource } = await import("../sources/github.js");

From 940e3c9d25c0849114b8348014c678660a41b0be Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 12:16:05 -0800
Subject: [PATCH 05/13] Fix TypeScript error in test for unknown source type

---
 src/clients/multi-index-runner.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
index 8f092eb..2fcb480 100644
--- a/src/clients/multi-index-runner.test.ts
+++ b/src/clients/multi-index-runner.test.ts
@@ -171,7 +171,7 @@ describe("createSourceFromState", () => {
     it("throws error for unknown source type", async () => {
       const state = createMockState({
         type: "unknown" as any,
-        config: {},
+        config: {} as any,
         syncedAt: new Date().toISOString(),
       });
 

From 2ae8d6ddbee69ef017161565e296a3c9c1247ec1 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 12:30:33 -0800
Subject: [PATCH 06/13] Add comment explaining resolvedRef usage in
 createSourceFromState

Agent-Id: agent-2c5b2cfc-9cfd-4602-83db-8b2c64a1f8b7
---
 src/clients/multi-index-runner.ts | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/clients/multi-index-runner.ts b/src/clients/multi-index-runner.ts
index 40c64c6..d4a6fa1 100644
--- a/src/clients/multi-index-runner.ts
+++ b/src/clients/multi-index-runner.ts
@@ -44,27 +44,41 @@ export interface MultiIndexRunnerConfig {
  * For VCS sources (GitHub, GitLab, BitBucket), uses `resolvedRef` (the indexed commit SHA)
  * if available, falling back to `config.ref` (branch name) if not.
  *
+ * **Why resolvedRef matters:**
+ * - `resolvedRef` is the exact commit SHA that was indexed for search
+ * - Using it ensures `listFiles` and `readFile` return content from the same commit
+ *   that was indexed, so file operations match search results
+ * - If we used `config.ref` (branch name), the branch might have moved since indexing,
+ *   causing file operations to return different content than what search indexed
+ *
  * @internal Exported for testing
  */
 export async function createSourceFromState(state: IndexStateSearchOnly): Promise<Source> {
   const meta = state.source;
+
+  // Helper to get the ref for VCS sources.
+  // Uses resolvedRef (indexed commit SHA) to ensure file operations match search results.
+  // Falls back to config.ref for backwards compatibility with older indexes.
+  const getRef = (configRef: string | undefined, resolvedRef: string | undefined) =>
+    resolvedRef ?? configRef;
+
   if (meta.type === "github") {
     const { GitHubSource } = await import("../sources/github.js");
     return new GitHubSource({
       ...meta.config,
-      ref: meta.resolvedRef ?? meta.config.ref,
+      ref: getRef(meta.config.ref, meta.resolvedRef),
     });
   } else if (meta.type === "gitlab") {
     const { GitLabSource } = await import("../sources/gitlab.js");
     return new GitLabSource({
       ...meta.config,
-      ref: meta.resolvedRef ?? meta.config.ref,
+      ref: getRef(meta.config.ref, meta.resolvedRef),
     });
   } else if (meta.type === "bitbucket") {
     const { BitBucketSource } = await import("../sources/bitbucket.js");
     return new BitBucketSource({
       ...meta.config,
-      ref: meta.resolvedRef ?? meta.config.ref,
+      ref: getRef(meta.config.ref, meta.resolvedRef),
     });
   } else if (meta.type === "website") {
     const { WebsiteSource } = await import("../sources/website.js");

From e0f6d75567ab2c997f3424aac24b079f9c1709fc Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 12:58:00 -0800
Subject: [PATCH 07/13] Simplify createSourceFromState tests by removing
 redundant provider tests

All VCS sources (GitHub, GitLab, BitBucket) use identical getRef() logic,
so testing each provider separately was redundant. Reduced from 7 tests
to 4 tests while maintaining the same effective coverage:

- Uses resolvedRef when present (tests shared VCS logic)
- Falls back to config.ref when resolvedRef missing (tests shared VCS logic)
- Website source works without resolvedRef (different code path)
- Throws error for unknown source type (error handling)
---
 src/clients/multi-index-runner.test.ts | 147 ++++++++-----------------
 1 file changed, 45 insertions(+), 102 deletions(-)

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
index 2fcb480..7eea87b 100644
--- a/src/clients/multi-index-runner.test.ts
+++ b/src/clients/multi-index-runner.test.ts
@@ -43,8 +43,6 @@ vi.mock("../sources/website.js", () => ({
 // Import the function under test and mocked sources
 import { createSourceFromState } from "./multi-index-runner.js";
 import { GitHubSource } from "../sources/github.js";
-import { GitLabSource } from "../sources/gitlab.js";
-import { BitBucketSource } from "../sources/bitbucket.js";
 import { WebsiteSource } from "../sources/website.js";
 
 // Create mock state with specific source metadata
@@ -61,123 +59,68 @@ describe("createSourceFromState", () => {
     vi.clearAllMocks();
   });
 
-  describe("GitHub source", () => {
-    it("uses resolvedRef when present", async () => {
-      const state = createMockState({
-        type: "github",
-        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
-        resolvedRef: "abc123sha",
-        syncedAt: new Date().toISOString(),
-      });
-
-      await createSourceFromState(state);
-
-      expect(GitHubSource).toHaveBeenCalledWith({
-        owner: "test-owner",
-        repo: "test-repo",
-        ref: "abc123sha",
-      });
+  // All VCS sources (GitHub, GitLab, BitBucket) use the same getRef() logic:
+  // resolvedRef ?? config.ref
+  // We test this once with GitHub as the representative case.
+
+  it("uses resolvedRef when present", async () => {
+    const state = createMockState({
+      type: "github",
+      config: { owner: "test-owner", repo: "test-repo", ref: "main" },
+      resolvedRef: "abc123sha",
+      syncedAt: new Date().toISOString(),
     });
 
-    it("uses config.ref when resolvedRef is missing", async () => {
-      const state = createMockState({
-        type: "github",
-        config: { owner: "test-owner", repo: "test-repo", ref: "main" },
-        // No resolvedRef
-        syncedAt: new Date().toISOString(),
-      });
-
-      await createSourceFromState(state);
-
-      expect(GitHubSource).toHaveBeenCalledWith({
-        owner: "test-owner",
-        repo: "test-repo",
-        ref: "main",
-      });
+    await createSourceFromState(state);
+
+    expect(GitHubSource).toHaveBeenCalledWith({
+      owner: "test-owner",
+      repo: "test-repo",
+      ref: "abc123sha",
     });
   });
 
-  describe("GitLab source", () => {
-    it("uses resolvedRef when present", async () => {
-      const state = createMockState({
-        type: "gitlab",
-        config: { projectId: "group/project", ref: "main" },
-        resolvedRef: "def456sha",
-        syncedAt: new Date().toISOString(),
-      });
-
-      await createSourceFromState(state);
-
-      expect(GitLabSource).toHaveBeenCalledWith({
-        projectId: "group/project",
-        ref: "def456sha",
-      });
+  it("falls back to config.ref when resolvedRef is missing", async () => {
+    const state = createMockState({
+      type: "github",
+      config: { owner: "test-owner", repo: "test-repo", ref: "main" },
+      // No resolvedRef
+      syncedAt: new Date().toISOString(),
     });
 
-    it("uses config.ref when resolvedRef is undefined", async () => {
-      const state = createMockState({
-        type: "gitlab",
-        config: { projectId: "group/project", ref: "develop" },
-        resolvedRef: undefined,
-        syncedAt: new Date().toISOString(),
-      });
-
-      await createSourceFromState(state);
+    await createSourceFromState(state);
 
-      expect(GitLabSource).toHaveBeenCalledWith({
-        projectId: "group/project",
-        ref: "develop",
-      });
+    expect(GitHubSource).toHaveBeenCalledWith({
+      owner: "test-owner",
+      repo: "test-repo",
+      ref: "main",
     });
   });
 
-  describe("BitBucket source", () => {
-    it("uses resolvedRef when present", async () => {
-      const state = createMockState({
-        type: "bitbucket",
-        config: { workspace: "my-workspace", repo: "my-repo", ref: "develop" },
-        resolvedRef: "ghi789sha",
-        syncedAt: new Date().toISOString(),
-      });
-
-      await createSourceFromState(state);
-
-      expect(BitBucketSource).toHaveBeenCalledWith({
-        workspace: "my-workspace",
-        repo: "my-repo",
-        ref: "ghi789sha",
-      });
+  it("website source works without resolvedRef", async () => {
+    const state = createMockState({
+      type: "website",
+      config: { url: "https://example.com", maxDepth: 2 },
+      syncedAt: new Date().toISOString(),
     });
-  });
-
-  describe("Website source", () => {
-    it("works correctly without resolvedRef", async () => {
-      const state = createMockState({
-        type: "website",
-        config: { url: "https://example.com", maxDepth: 2 },
-        syncedAt: new Date().toISOString(),
-      });
 
-      await createSourceFromState(state);
+    await createSourceFromState(state);
 
-      expect(WebsiteSource).toHaveBeenCalledWith({
-        url: "https://example.com",
-        maxDepth: 2,
-      });
+    expect(WebsiteSource).toHaveBeenCalledWith({
+      url: "https://example.com",
+      maxDepth: 2,
     });
   });
 
-  describe("unknown source type", () => {
-    it("throws error for unknown source type", async () => {
-      const state = createMockState({
-        type: "unknown" as any,
-        config: {} as any,
-        syncedAt: new Date().toISOString(),
-      });
-
-      await expect(createSourceFromState(state)).rejects.toThrow(
-        "Unknown source type: unknown"
-      );
+  it("throws error for unknown source type", async () => {
+    const state = createMockState({
+      type: "unknown" as any,
+      config: {} as any,
+      syncedAt: new Date().toISOString(),
     });
+
+    await expect(createSourceFromState(state)).rejects.toThrow(
+      "Unknown source type: unknown"
+    );
   });
 });

From d9656c4527d19a4aae509f75ab7abc65e8622d7c Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:00:10 -0800
Subject: [PATCH 08/13] Add integration tests for resolvedRef handling

Created test/resolved-ref.test.ts that verifies GitHubSource operations
(listFiles, readFile) use the exact commit SHA provided as ref, ensuring
file operations return content from the indexed commit.

Test cases:
- listFiles works with commit SHA refs
- readFile returns content from specific commit SHA
- Different commit SHAs return different file content
- getMetadata returns correct resolvedRef

Uses octocat/Hello-World repository with known commits that have
slightly different README content to prove ref handling works correctly.

Agent-Id: agent-d2d9f141-b65f-43fe-82b7-9bc2962f9f5e
---
 test/README.md            |   1 +
 test/resolved-ref.test.ts | 241 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 242 insertions(+)
 create mode 100644 test/resolved-ref.test.ts

diff --git a/test/README.md b/test/README.md
index a62db8a..2c59707 100644
--- a/test/README.md
+++ b/test/README.md
@@ -36,6 +36,7 @@ This directory contains integration tests that require real credentials and make
 |------|-------------|
 | `augment-provider.ts` | Tests the Augment provider SDK integration (credentials, model, API calls, tool calling) |
 | `cli-agent.ts` | Tests the built `ctxc` CLI binary end-to-end (indexes augmentcode/auggie, then runs agent) |
+| `resolved-ref.test.ts` | Tests that GitHubSource operations use the exact commit SHA provided as ref (honors resolvedRef) |
 
 ## Note
 
diff --git a/test/resolved-ref.test.ts b/test/resolved-ref.test.ts
new file mode 100644
index 0000000..f149f7a
--- /dev/null
+++ b/test/resolved-ref.test.ts
@@ -0,0 +1,241 @@
+/**
+ * Integration tests for resolvedRef handling in GitHubSource.
+ *
+ * These tests verify that when a specific commit SHA is provided as ref,
+ * the listFiles and readFile operations use that exact commit, not the
+ * latest commit on a branch.
+ *
+ * This validates the fix in createSourceFromState() that ensures file
+ * operations use resolvedRef (the indexed commit SHA) instead of config.ref
+ * (the branch name).
+ *
+ * Prerequisites:
+ * - GITHUB_TOKEN environment variable set
+ *
+ * Usage:
+ *   npx tsx test/resolved-ref.test.ts
+ */
+
+import { GitHubSource } from "../src/sources/github.js";
+
+// Skip if no GitHub token
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
+if (!GITHUB_TOKEN) {
+  console.log("⏭️  Skipping: GITHUB_TOKEN not set");
+  process.exit(0);
+}
+
+// Known commits from octocat/Hello-World repository
+// These are stable and won't change
+const OLDEST_COMMIT = "553c2077f0edc3d5dc5d17262f6aa498e69d6f8e";
+const NEWEST_COMMIT = "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d";
+
+// Expected content at specific commits (base64 decoded):
+// OLDEST_COMMIT README: "Hello World!" (no trailing newline)
+// NEWEST_COMMIT README: "Hello World!\n" (with trailing newline)
+const OLDEST_COMMIT_README_CONTENT = "Hello World!";
+const NEWEST_COMMIT_README_CONTENT = "Hello World!\n";
+
+interface TestResult {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+
+const results: TestResult[] = [];
+
+function test(name: string, passed: boolean, message?: string) {
+  results.push({ name, passed, message });
+  console.log(`${passed ? "✓" : "✗"} ${name}`);
+  if (message && !passed) {
+    console.log(`  ${message}`);
+  }
+}
+
+async function testListFilesHonorsRef() {
+  console.log("\n📁 Testing listFiles honors ref...\n");
+
+  // Test 1: listFiles with oldest commit should work
+  try {
+    const source = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: OLDEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const files = await source.listFiles();
+    const hasReadme = files.some((f) => f.path === "README");
+
+    test(
+      "listFiles with commit SHA returns files",
+      files.length > 0 && hasReadme,
+      `Expected README in files, got: ${JSON.stringify(files.map((f) => f.path))}`
+    );
+  } catch (error) {
+    test("listFiles with commit SHA returns files", false, String(error));
+  }
+
+  // Test 2: listFiles with newest commit should also work
+  try {
+    const source = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: NEWEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const files = await source.listFiles();
+    const hasReadme = files.some((f) => f.path === "README");
+
+    test(
+      "listFiles with different commit SHA also works",
+      files.length > 0 && hasReadme,
+      `Expected README in files, got: ${JSON.stringify(files.map((f) => f.path))}`
+    );
+  } catch (error) {
+    test("listFiles with different commit SHA also works", false, String(error));
+  }
+}
+
+async function testReadFileHonorsRef() {
+  console.log("\n📄 Testing readFile honors ref...\n");
+
+  // Test 1: readFile at oldest commit returns content from that commit
+  try {
+    const source = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: OLDEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const content = await source.readFile("README");
+    const matches = content === OLDEST_COMMIT_README_CONTENT;
+
+    test(
+      "readFile at oldest commit returns correct content",
+      matches,
+      `Expected "${OLDEST_COMMIT_README_CONTENT}", got "${content}"`
+    );
+  } catch (error) {
+    test("readFile at oldest commit returns correct content", false, String(error));
+  }
+
+  // Test 2: readFile at newest commit returns different content
+  try {
+    const source = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: NEWEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const content = await source.readFile("README");
+    const matches = content === NEWEST_COMMIT_README_CONTENT;
+
+    test(
+      "readFile at newest commit returns correct content",
+      matches,
+      `Expected "${NEWEST_COMMIT_README_CONTENT}", got "${content}"`
+    );
+  } catch (error) {
+    test("readFile at newest commit returns correct content", false, String(error));
+  }
+
+  // Test 3: Two sources with different refs return different content
+  try {
+    const oldSource = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: OLDEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const newSource = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: NEWEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const oldContent = await oldSource.readFile("README");
+    const newContent = await newSource.readFile("README");
+
+    const contentsDiffer = oldContent !== newContent;
+
+    test(
+      "Different commit SHAs return different file content",
+      contentsDiffer,
+      `Expected different content, both returned: "${oldContent}"`
+    );
+  } catch (error) {
+    test("Different commit SHAs return different file content", false, String(error));
+  }
+}
+
+async function testMetadataResolvedRef() {
+  console.log("\n📋 Testing metadata resolvedRef...\n");
+
+  // Test: getMetadata returns the exact commit SHA as resolvedRef
+  try {
+    const source = new GitHubSource({
+      owner: "octocat",
+      repo: "Hello-World",
+      ref: OLDEST_COMMIT,
+      token: GITHUB_TOKEN,
+    });
+
+    const metadata = await source.getMetadata();
+
+    test(
+      "getMetadata returns correct resolvedRef",
+      metadata.type === "github" && metadata.resolvedRef === OLDEST_COMMIT,
+      `Expected resolvedRef=${OLDEST_COMMIT}, got ${metadata.type === "github" ? metadata.resolvedRef : "non-github type"}`
+    );
+
+    // Also verify config.ref is preserved separately
+    test(
+      "getMetadata preserves config.ref",
+      metadata.type === "github" && metadata.config.ref === OLDEST_COMMIT,
+      `Expected config.ref=${OLDEST_COMMIT}, got ${metadata.type === "github" ? metadata.config.ref : "non-github type"}`
+    );
+  } catch (error) {
+    test("getMetadata returns correct resolvedRef", false, String(error));
+  }
+}
+
+async function main() {
+  console.log("🧪 Resolved Ref Integration Tests\n");
+  console.log("=".repeat(50));
+  console.log("\nThese tests verify that GitHubSource operations use the");
+  console.log("exact commit SHA provided as ref, ensuring file operations");
+  console.log("return content from the indexed commit, not the latest.\n");
+
+  await testListFilesHonorsRef();
+  await testReadFileHonorsRef();
+  await testMetadataResolvedRef();
+
+  // Summary
+  console.log("\n" + "=".repeat(50));
+  const passed = results.filter((r) => r.passed).length;
+  const total = results.length;
+
+  if (passed === total) {
+    console.log(`\n✅ All ${total} tests passed!`);
+    process.exit(0);
+  } else {
+    console.log(`\n❌ ${passed}/${total} tests passed`);
+    const failed = results.filter((r) => !r.passed);
+    console.log("\nFailed tests:");
+    for (const f of failed) {
+      console.log(`  - ${f.name}: ${f.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error("Test runner error:", error);
+  process.exit(1);
+});

From f87b51673019bdd80384034059a6f1d48e0056da Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:01:50 -0800
Subject: [PATCH 09/13] Rename integration test to avoid vitest pickup

- Rename test/resolved-ref.test.ts to test/resolved-ref.ts
- Add to test:integration script in package.json
- Update test/README.md
---
 package.json                                   | 2 +-
 test/README.md                                 | 2 +-
 test/{resolved-ref.test.ts => resolved-ref.ts} | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename test/{resolved-ref.test.ts => resolved-ref.ts} (100%)

diff --git a/package.json b/package.json
index 34e2f1b..8343ac0 100644
--- a/package.json
+++ b/package.json
@@ -20,7 +20,7 @@
     "cli": "tsx src/bin/index.ts",
     "cli:index": "tsx src/bin/index.ts index",
     "cli:search": "tsx src/bin/index.ts search",
-    "test:integration": "tsx test/augment-provider.ts && tsx test/cli-agent.ts",
+    "test:integration": "tsx test/augment-provider.ts && tsx test/cli-agent.ts && tsx test/resolved-ref.ts",
     "format": "biome format --write .",
     "lint": "biome check .",
     "lint:fix": "biome check --write ."
diff --git a/test/README.md b/test/README.md
index 2c59707..2e8cc45 100644
--- a/test/README.md
+++ b/test/README.md
@@ -36,7 +36,7 @@ This directory contains integration tests that require real credentials and make
 |------|-------------|
 | `augment-provider.ts` | Tests the Augment provider SDK integration (credentials, model, API calls, tool calling) |
 | `cli-agent.ts` | Tests the built `ctxc` CLI binary end-to-end (indexes augmentcode/auggie, then runs agent) |
-| `resolved-ref.test.ts` | Tests that GitHubSource operations use the exact commit SHA provided as ref (honors resolvedRef) |
+| `resolved-ref.ts` | Tests that GitHubSource operations use the exact commit SHA provided as ref (honors resolvedRef) |
 
 ## Note
 
diff --git a/test/resolved-ref.test.ts b/test/resolved-ref.ts
similarity index 100%
rename from test/resolved-ref.test.ts
rename to test/resolved-ref.ts

From f8817135655ccb317ecbef3b5df20272c198f30a Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:11:22 -0800
Subject: [PATCH 10/13] Remove unused GitLab and BitBucket mocks from unit
 tests

---
 src/clients/multi-index-runner.test.ts | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/src/clients/multi-index-runner.test.ts b/src/clients/multi-index-runner.test.ts
index 7eea87b..8bea9a0 100644
--- a/src/clients/multi-index-runner.test.ts
+++ b/src/clients/multi-index-runner.test.ts
@@ -4,14 +4,17 @@
  * These tests verify that createSourceFromState correctly uses resolvedRef
  * from state metadata when creating source instances.
  *
- * The tests mock the source modules to capture what config gets passed
+ * We mock GitHub and Website sources to capture what config gets passed
  * to the constructors, without needing API credentials.
+ *
+ * Since all VCS sources (GitHub, GitLab, BitBucket) use the same getRef() logic,
+ * we only test GitHub as the representative case.
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import type { IndexStateSearchOnly, SourceMetadata } from "../core/types.js";
 
-// Mock the source modules to capture constructor calls
+// Mock only the sources we actually test
 vi.mock("../sources/github.js", () => ({
   GitHubSource: vi.fn().mockImplementation((config) => ({
     type: "github" as const,
@@ -19,20 +22,6 @@ vi.mock("../sources/github.js", () => ({
   })),
 }));
 
-vi.mock("../sources/gitlab.js", () => ({
-  GitLabSource: vi.fn().mockImplementation((config) => ({
-    type: "gitlab" as const,
-    config,
-  })),
-}));
-
-vi.mock("../sources/bitbucket.js", () => ({
-  BitBucketSource: vi.fn().mockImplementation((config) => ({
-    type: "bitbucket" as const,
-    config,
-  })),
-}));
-
 vi.mock("../sources/website.js", () => ({
   WebsiteSource: vi.fn().mockImplementation((config) => ({
     type: "website" as const,

From 47cbde198c393ce94171f0651edf440db22072c9 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:28:34 -0800
Subject: [PATCH 11/13] Simplify getRef by inlining in each branch

Instead of a separate getRef helper that couldn't be properly typed
(SourceMetadata is a discriminated union), inline the logic directly
where TypeScript can leverage the narrowed type from the if-checks.
---
 src/clients/multi-index-runner.ts | 22 ++++++----------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/src/clients/multi-index-runner.ts b/src/clients/multi-index-runner.ts
index d4a6fa1..8ea531c 100644
--- a/src/clients/multi-index-runner.ts
+++ b/src/clients/multi-index-runner.ts
@@ -56,30 +56,20 @@ export interface MultiIndexRunnerConfig {
 export async function createSourceFromState(state: IndexStateSearchOnly): Promise<Source> {
   const meta = state.source;
 
-  // Helper to get the ref for VCS sources.
-  // Uses resolvedRef (indexed commit SHA) to ensure file operations match search results.
+  // For VCS sources, use resolvedRef (indexed commit SHA) if available.
+  // This ensures file operations (listFiles, readFile) return content from
+  // the same commit that was indexed, so results match search.
   // Falls back to config.ref for backwards compatibility with older indexes.
-  const getRef = (configRef: string | undefined, resolvedRef: string | undefined) =>
-    resolvedRef ?? configRef;
 
   if (meta.type === "github") {
     const { GitHubSource } = await import("../sources/github.js");
-    return new GitHubSource({
-      ...meta.config,
-      ref: getRef(meta.config.ref, meta.resolvedRef),
-    });
+    return new GitHubSource({ ...meta.config, ref: meta.resolvedRef ?? meta.config.ref });
   } else if (meta.type === "gitlab") {
     const { GitLabSource } = await import("../sources/gitlab.js");
-    return new GitLabSource({
-      ...meta.config,
-      ref: getRef(meta.config.ref, meta.resolvedRef),
-    });
+    return new GitLabSource({ ...meta.config, ref: meta.resolvedRef ?? meta.config.ref });
   } else if (meta.type === "bitbucket") {
     const { BitBucketSource } = await import("../sources/bitbucket.js");
-    return new BitBucketSource({
-      ...meta.config,
-      ref: getRef(meta.config.ref, meta.resolvedRef),
-    });
+    return new BitBucketSource({ ...meta.config, ref: meta.resolvedRef ?? meta.config.ref });
   } else if (meta.type === "website") {
     const { WebsiteSource } = await import("../sources/website.js");
     return new WebsiteSource(meta.config);

From e4f69597c33a355311e4e94ad6c328621a934890 Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:47:56 -0800
Subject: [PATCH 12/13] Fix CLI integration test to use local build directly

Instead of using 'npx ctxc' which may pick up a globally installed
version, run the local build directly with 'node dist/bin/index.js'.

This makes the test more reliable and reproducible across different
environments.
---
 test/cli-agent.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/test/cli-agent.ts b/test/cli-agent.ts
index 9e31095..b42b96f 100644
--- a/test/cli-agent.ts
+++ b/test/cli-agent.ts
@@ -14,6 +14,7 @@
 
 import { spawn } from "child_process";
 import { mkdtemp, rm } from "fs/promises";
+import { resolve } from "path";
 import { tmpdir } from "os";
 import { join } from "path";
 
@@ -26,12 +27,15 @@ interface TestResult {
 
 let testIndexPath: string | null = null;
 
+// Path to the local CLI build
+const CLI_PATH = resolve(import.meta.dirname, "../dist/bin/index.js");
+
 async function runCLI(
   args: string[],
   timeoutMs = 60000
 ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve) => {
-    const proc = spawn("npx", ["ctxc", ...args], {
+    const proc = spawn(process.execPath, [CLI_PATH, ...args], {
       cwd: process.cwd(),
       env: process.env,
       timeout: timeoutMs,

From ac285f1ff9a714f5530f5ac30507bd35f7fad99f Mon Sep 17 00:00:00 2001
From: Rich Hankins <rich@augmentcode.com>
Date: Fri, 30 Jan 2026 13:52:25 -0800
Subject: [PATCH 13/13] Update resolved-ref test to import from built output

Import from dist/ instead of src/ to test the actual compiled code
that gets shipped, consistent with how cli-agent.ts tests the CLI.
---
 test/resolved-ref.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/resolved-ref.ts b/test/resolved-ref.ts
index f149f7a..d835c6a 100644
--- a/test/resolved-ref.ts
+++ b/test/resolved-ref.ts
@@ -16,7 +16,7 @@
  *   npx tsx test/resolved-ref.test.ts
  */
 
-import { GitHubSource } from "../src/sources/github.js";
+import { GitHubSource } from "../dist/sources/github.js";
 
 // Skip if no GitHub token
 const GITHUB_TOKEN = process.env.GITHUB_TOKEN;