From 404e7827bcf7fda994de4f28e711a3eda3bac307 Mon Sep 17 00:00:00 2001
From: Colby Mchenry <me@colbymchenry.com>
Date: Fri, 2 Oct 2026 04:09:56 +0000
Subject: [PATCH 1/5] fix(windows): hide the git calls that flash console
 windows (#2094) (#2280)

* fix(windows): hide the git calls that flash console windows (#2094)

The two git calls added for exclude-standard scope parity (#1728),
`git config --get core.excludesFile` and
`git ls-files -o -i --exclude-standard --directory`, ran without
windowsHide. Inside the detached, console-less MCP daemon each one got a
fresh visible console, so a window flashed several times on daemon start
and again on every auto-sync. With Windows Terminal as the default
terminal each flash is a full Windows Terminal window. `git config
user.name` in the viewer's trails API had the same gap.

Add windowsHide: true to all three, and replace the per-file regex guards
with an AST guard over every child_process spawn in src/: options passed
through a variable or a function parameter are traced back to the object
literal that defines them, through every call site.

Supersedes #2095 (same fix, rebased on current main). Closes #2094,
closes #2096.

(cherry picked from commit dd2db41f1b03f2b17a68c69cdd3c341d62a44908)

* docs(changelog): credit the Windows console-window fix

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit cf93d497fd1b38fd9214945eeb55b6b0be9e2007)

---------

Co-authored-by: Suharaz <minesuhara@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                 |   2 +
 __tests__/child-process-windows-hide.test.ts | 208 +++++++++++++++++++
 src/extraction/index.ts                      |   3 +-
 src/ui-server/api/trails.ts                  |   1 +
 4 files changed, 213 insertions(+), 1 deletion(-)
 create mode 100644 __tests__/child-process-windows-hide.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b54d23d7a..592eea7ab0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixes
 
+- On Windows, terminal windows no longer flash open and closed while CodeGraph runs in the background. Since 1.6.1, a background MCP server popped up a console window (a full Windows Terminal window when that is the default terminal) several times when it started and again every time it re-synced a changed file. All of CodeGraph's git calls now run hidden. Thanks @Suharaz, @23q3, @A-Van-Gestel and @HarryMuc. (#2094, #2096)
 - In Vapor apps, a route whose handler is a trailing closure, like `app.get("hello") { req in … }` or `app.webSocket("chat") { req, ws in … }`, now links to what the closure calls, the way an Express inline handler does. Before, the route linked to nothing, so callers, impact and flows stopped at it.
 - A COBOL file whose last line ends inside the sequence area (columns 1-6), such as a closing period indented only four spaces, no longer stalls indexing for over a minute and then ends up in the index with no symbols.
 - In Laravel apps, a route whose controller is named by string now links to its handler, without needing a `Controller` suffix and keeping the namespace it's written with: `'Common\Uploads@inline'`, and `Route::resource('companies', 'Common\Companies', [...])` with an options array. Two same-named controllers in different namespaces are told apart by that namespace. Before, akaunting linked 304 of its 313 routes to nothing.
@@ -22,6 +23,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - In Vue, Svelte and Astro files, a component now owns its script, and what a `<script setup>`, a Svelte instance script or Astro frontmatter does at its top level is the component's doing. That covers a Nuxt page's `useAsyncData(…)`, a Svelte page's `onMount(…)` and Astro's `await getCollection(…)`. Imports and a module-level script stay with the file. Before, those calls belonged to the file, so callers and flows from a component found nothing. The component was also recorded as containing its own file, and a file with no script had no file node at all.
 - In JavaScript and TypeScript, a CommonJS `require('./application')` now counts as an import of that file, the way an ESM `import` does. A module path also resolves the way Node and bundlers find it: extensions, `index` files and path aliases. Before, a CommonJS file depended on nothing at file level, so Express's own `lib/express.js` showed no imports and impact analysis missed the files it loads. An extensionless side-effect import like `import './polyfills'` also stopped at its own import statement instead of reaching the file.
 - An Express route whose handler is written inline as `function (req, res) {…}`, the form Express's own examples use, now links to what that handler calls, just like an arrow handler does. The handler is the route's last argument, so an inline middleware before a named handler no longer stands in for it, and a wrapper like `asyncHandler(async function (req, res) {…})` and a trailing comma both work. Before, a route such as `POST /login` linked to nothing.
+- On Windows, terminal windows no longer flash open and closed while CodeGraph runs in the background. Since 1.6.1, a background MCP server popped up a console window (a full Windows Terminal window when that is the default terminal) several times when it started and again every time it re-synced a changed file. All of CodeGraph's git calls now run hidden. (#2094, #2096) Thanks @A-Van-Gestel, @HarryMuc and @23q3.
 - A Python module member used through the imported module, like `generic.ObjectEditView` after `from netbox.views import generic`, `serializers.ValidationError` or `utils.assert_deserialize(…)`, now also follows the package's re-exports to its definition. Before, netbox's view classes lost their `generic.*` base classes, and mealie's test helpers called through `utils.` went unresolved.
 - A Python name imported from a package now follows the package's re-exports to where it's defined. That covers both `from .users import *` and `from .tokens import Token` in its `__init__.py`. Before, httpx's own tests' `httpx.Client(…)` and `httpx.URL(…)`, pytest's `pytest.raises(…)` and `pytest.param(…)`, and netbox's `from users.models import User` went unresolved or to a same-named class elsewhere, such as a test's `User` or an Alembic migration's copy of a model.
 - In NestJS projects, the provider naming convention (`…Service`, `…Controller`, …) now picks a class only from the reference's own file. Another file's provider is reached through its import, or by ordinary name matching that prefers the nearest declaration. Before, the convention's preference for `*.service.ts` files sent Nest's own specs' `TransientService` and `TestService` to same-named classes in unrelated sample apps.
diff --git a/__tests__/child-process-windows-hide.test.ts b/__tests__/child-process-windows-hide.test.ts
new file mode 100644
index 0000000000..adb7056b76
--- /dev/null
+++ b/__tests__/child-process-windows-hide.test.ts
@@ -0,0 +1,208 @@
+/**
+ * Static source guard (all platforms): every child process spawned from `src/`
+ * sets `windowsHide: true`.
+ *
+ * The MCP daemon is spawned detached and has no console of its own. On
+ * Windows, a console program (git, …) it starts without windowsHide gets a
+ * brand-new visible console, so a terminal window flashes on screen and closes
+ * once per call: on daemon start and again on every auto-sync (#485, #928,
+ * #1092, #2094, #2096). With Windows Terminal set as the default terminal, each
+ * flash is a full Windows Terminal window.
+ *
+ * windowsHide is Windows-only behavior the POSIX test runs can't observe, so it
+ * is asserted on the TypeScript AST. Options passed through a variable or a
+ * function parameter are traced back to the object literal that defines them
+ * (for a parameter: through every call site of that function in the file).
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import ts from 'typescript';
+
+const SRC_DIR = path.join(__dirname, '..', 'src');
+
+/**
+ * child_process functions that start a process and accept `windowsHide`, by
+ * argument shape: `file` is `(file, args?, options?)`, `command` is
+ * `(command, options?)`.
+ */
+const SPAWNERS: Record<string, 'file' | 'command'> = {
+  exec: 'command',
+  execSync: 'command',
+  execFile: 'file',
+  execFileSync: 'file',
+  spawn: 'file',
+  spawnSync: 'file',
+  fork: 'file',
+};
+
+/**
+ * Spawns that intentionally run without windowsHide, keyed by
+ * `<path relative to src>:<spawner>(<command>)`, valued by the reason.
+ */
+const ALLOWED: Record<string, string> = {
+  "resolution/memory-budget.ts:execFileSync('/usr/bin/vm_stat')": 'macOS only: guarded by process.platform === darwin',
+  'ui-server/open-browser.ts:spawn(open.command)':
+    'detached: true maps to DETACHED_PROCESS on Windows, so `cmd /c start` gets no console to show',
+};
+
+function listSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listSourceFiles(p));
+    else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) out.push(p);
+  }
+  return out;
+}
+
+/** Local names bound to child_process exports in one file. */
+interface ChildProcessBindings {
+  /** Local name → imported child_process export (`import { spawn as s }`). */
+  named: Map<string, string>;
+  /** Namespace aliases (`import * as cp from 'child_process'`). */
+  namespaces: Set<string>;
+}
+
+function childProcessBindings(sf: ts.SourceFile): ChildProcessBindings {
+  const named = new Map<string, string>();
+  const namespaces = new Set<string>();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (!['child_process', 'node:child_process'].includes(stmt.moduleSpecifier.text)) continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else for (const el of bindings.elements) named.set(el.name.text, (el.propertyName ?? el.name).text);
+  }
+  return { named, namespaces };
+}
+
+/** The child_process function a call invokes, or null when it isn't one. */
+function spawnerOf(call: ts.CallExpression, b: ChildProcessBindings): string | null {
+  const callee = call.expression;
+  const name = ts.isIdentifier(callee)
+    ? b.named.get(callee.text)
+    : ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && b.namespaces.has(callee.expression.text)
+      ? callee.name.text
+      : undefined;
+  return name !== undefined && Object.hasOwn(SPAWNERS, name) ? name : null;
+}
+
+/** The options argument of a spawner call, or undefined when none is passed. */
+function optionsArg(call: ts.CallExpression, spawner: string): ts.Expression | undefined {
+  const [, second, third] = call.arguments;
+  if (SPAWNERS[spawner] === 'command') return second;
+  // (file, options) is allowed when the args array is omitted.
+  if (second && ts.isObjectLiteralExpression(second)) return second;
+  return third;
+}
+
+function unwrap(expr: ts.Expression): ts.Expression {
+  let e = expr;
+  while (ts.isAsExpression(e) || ts.isParenthesizedExpression(e) || ts.isSatisfiesExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
+  return e;
+}
+
+/** Variable initializer or function parameter that `name` refers to at `from`. */
+function resolveBinding(name: string, from: ts.Node): ts.VariableDeclaration | ts.ParameterDeclaration | null {
+  for (let scope: ts.Node | undefined = from.parent; scope; scope = scope.parent) {
+    if (ts.isFunctionLike(scope)) {
+      const param = scope.parameters.find((p) => ts.isIdentifier(p.name) && p.name.text === name);
+      if (param) return param;
+    }
+    if (ts.isBlock(scope) || ts.isSourceFile(scope) || ts.isModuleBlock(scope)) {
+      for (const stmt of scope.statements) {
+        if (!ts.isVariableStatement(stmt)) continue;
+        const decl = stmt.declarationList.declarations.find((d) => ts.isIdentifier(d.name) && d.name.text === name);
+        if (decl) return decl;
+      }
+    }
+  }
+  return null;
+}
+
+/** Calls to the function that declares `param`, found by name in the same file. */
+function callSitesOf(param: ts.ParameterDeclaration, sf: ts.SourceFile): ts.Expression[] | null {
+  const fn = param.parent;
+  const fnName = ts.isFunctionDeclaration(fn) && fn.name ? fn.name.text : null;
+  if (!fnName) return null;
+  const index = fn.parameters.indexOf(param);
+  const args: ts.Expression[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === fnName) {
+      const arg = node.arguments[index];
+      if (arg) args.push(arg);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return args.length > 0 ? args : null;
+}
+
+/** True when `expr` provably evaluates to options with `windowsHide: true`. */
+function hidesWindow(expr: ts.Expression | undefined, sf: ts.SourceFile, seen = new Set<ts.Node>()): boolean {
+  if (!expr) return false;
+  const e = unwrap(expr);
+  if (seen.has(e)) return false;
+  seen.add(e);
+  if (ts.isObjectLiteralExpression(e)) {
+    let hidden = false;
+    for (const prop of e.properties) {
+      if (ts.isPropertyAssignment(prop) && prop.name.getText(sf) === 'windowsHide') {
+        hidden = unwrap(prop.initializer).kind === ts.SyntaxKind.TrueKeyword;
+      } else if (ts.isShorthandPropertyAssignment(prop) && prop.name.text === 'windowsHide') {
+        hidden = false; // not provable statically
+      } else if (ts.isSpreadAssignment(prop) && hidesWindow(prop.expression, sf, seen)) {
+        hidden = true;
+      }
+    }
+    return hidden; // last write wins, matching object-literal semantics
+  }
+  if (ts.isIdentifier(e)) {
+    const binding = resolveBinding(e.text, e);
+    if (!binding) return false;
+    if (ts.isVariableDeclaration(binding)) return hidesWindow(binding.initializer, sf, seen);
+    const sites = callSitesOf(binding, sf);
+    return sites !== null && sites.every((arg) => hidesWindow(arg, sf, seen));
+  }
+  return false;
+}
+
+function commandLabel(call: ts.CallExpression, sf: ts.SourceFile): string {
+  const first = call.arguments[0];
+  if (!first) return '';
+  if (ts.isStringLiteralLike(first)) return `'${first.text}'`;
+  return first.getText(sf);
+}
+
+describe('child processes set windowsHide (#1092, #2094)', () => {
+  it('every child_process spawn under src/ sets windowsHide: true', () => {
+    const offenders: string[] = [];
+    let seen = 0;
+    for (const file of listSourceFiles(SRC_DIR)) {
+      const text = fs.readFileSync(file, 'utf8');
+      const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+      const bindings = childProcessBindings(sf);
+      if (bindings.named.size === 0 && bindings.namespaces.size === 0) continue;
+      const rel = path.relative(SRC_DIR, file).split(path.sep).join('/');
+      const visit = (node: ts.Node): void => {
+        if (ts.isCallExpression(node)) {
+          const spawner = spawnerOf(node, bindings);
+          if (spawner) {
+            seen++;
+            const key = `${rel}:${spawner}(${commandLabel(node, sf)})`;
+            if (!Object.hasOwn(ALLOWED, key) && !hidesWindow(optionsArg(node, spawner), sf)) {
+              const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+              offenders.push(`${rel}:${line + 1} ${key}`);
+            }
+          }
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(sf);
+    }
+    expect(seen).toBeGreaterThan(0); // guard against a false pass if the imports move
+    expect(offenders, `spawned without windowsHide:\n${offenders.join('\n')}`).toEqual([]);
+  });
+});
diff --git a/src/extraction/index.ts b/src/extraction/index.ts
index 80016bb59c..40afc9f7eb 100644
--- a/src/extraction/index.ts
+++ b/src/extraction/index.ts
@@ -395,7 +395,7 @@ function readGitExcludeExtraPatterns(rootDir: string): string {
     const configured = execFileSync(
       'git',
       ['-C', rootDir, 'config', '--get', 'core.excludesFile'],
-      { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'] },
+      { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true },
     ).trim();
     if (configured) {
       const abs = expandUserPath(configured);
@@ -426,6 +426,7 @@ function listGitIgnoredDirectories(rootDir: string): string[] {
         timeout: 60_000,
         maxBuffer: 50 * 1024 * 1024,
         stdio: ['ignore', 'pipe', 'ignore'],
+        windowsHide: true,
       },
     );
     const dirs: string[] = [];
diff --git a/src/ui-server/api/trails.ts b/src/ui-server/api/trails.ts
index 5babe4c14e..f9f4d74f66 100644
--- a/src/ui-server/api/trails.ts
+++ b/src/ui-server/api/trails.ts
@@ -458,6 +458,7 @@ function gitUserName(projectRoot: string): string | null {
       encoding: 'utf-8',
       timeout: 2_000,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     });
     const name = out.trim();
     return name === '' ? null : name.slice(0, 120);

From 96ba8805564a548a89582ee6f6d74e6b2358beb4 Mon Sep 17 00:00:00 2001
From: Colby Mchenry <me@colbymchenry.com>
Date: Fri, 2 Oct 2026 04:12:11 +0000
Subject: [PATCH 2/5] fix(prompt-hook): skip Claude Code <agent-message>
 subagent hand-backs (#2184) (#2281)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(prompt-hook): skip Claude Code <agent-message> subagent hand-backs

Claude Code delivers a subagent's report to the parent session as a
UserPromptSubmit prompt wrapped in <agent-message from="…">…</agent-message>.
The prompt hook treated it as user input and ran a full codegraph_explore
on the whole report, which is slow on a multi-KB prose query (past the
30 s hook timeout in the report) and injects context unrelated to the
user's question.

Add isAgentMessage next to isTaskNotification (#1832) with the same rule:
only a prompt that is entirely the envelope is skipped, so a user question
that mentions the tag still goes through the gate.

Fixes #2184

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 240022db704818278e89dd8e1c734c3563a6e8cf)

* docs(changelog): credit the prompt-hook hand-back fix

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: danusha2345 <ewidusoc498@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |  1 +
 __tests__/frontload-hook.test.ts | 25 ++++++++++++++++++++++++-
 src/bin/codegraph.ts             |  9 +++++----
 src/directory.ts                 | 10 ++++++++++
 4 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 592eea7ab0..42adc334f7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -158,6 +158,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - A Swift reference to a type now links to the type's own declaration, not to a file that extends it. An `extension View { … }` or `extension Text { … }` used to stand in for SwiftUI's type, so every view, every `Text("…")` and every `Color.red` in an app linked to whichever file happened to extend it. Those files topped the most-depended-on lists and their impact reached the whole app. A bare name like `@State`, `@Test` or `Result<…>` no longer links to some other type's nested `State` or `Result`, and a qualified name like `Build.Id` links to the `Id` it names. Methods declared in an extension of an SDK type still resolve on the types that conform to it, and a protocol's methods declared in any of its extensions now connect to each conforming type's own implementation. Re-index Swift projects after upgrading.
 - A Vapor route now links to the handler it names. `use: SearchController.show` used to link to whichever controller's `show` came first, so routes with a common handler name, like `show`, `index` or `get`, pointed at another endpoint's code in callers, impact and `codegraph_explore` answers. Nested types like `API.PackageController.get` and handlers declared in an extension of the controller now resolve too, and `use: self.index` resolves to the collection's own `index`. Re-index Vapor projects after upgrading.
 - A PHP call written without a receiver, such as `redirect($url)`, `view('books.show')`, `auth()` or `basename($path)`, is a function call, and no longer links to a same-named method, field or class elsewhere in the project. These wrong links showed up in callers, impact and `codegraph_explore` answers wherever a Laravel helper or PHP built-in shared its name with a project member. Re-index PHP projects after upgrading.
+- The Claude Code prompt hook no longer runs on the messages Claude Code uses to hand a subagent's report back to the main session. Before, such a long report could keep the hook busy past Claude Code's 30-second hook timeout and inject context unrelated to what you asked. Thanks @danusha2345, and @tippmar-nr for the report. (#2184)
 
 ## [1.6.1] - 2026-09-29
 
diff --git a/__tests__/frontload-hook.test.ts b/__tests__/frontload-hook.test.ts
index 3e81e6090e..c85700b9c0 100644
--- a/__tests__/frontload-hook.test.ts
+++ b/__tests__/frontload-hook.test.ts
@@ -13,7 +13,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'node:child_process';
 import { CodeGraph } from '../src';
-import { planFrontload, isTaskNotification, findIndexedSubprojectRoots, unsafeIndexRootReason, isStructuralPrompt, hasStructuralKeyword, extractCodeTokens, PROMPT_HOOK_INJECTION_MAX, CLAUDE_CODE_INLINE_HOOK_OUTPUT_LIMIT, capPromptHookInjection } from '../src/directory';
+import { planFrontload, isTaskNotification, isAgentMessage, findIndexedSubprojectRoots, unsafeIndexRootReason, isStructuralPrompt, hasStructuralKeyword, extractCodeTokens, PROMPT_HOOK_INJECTION_MAX, CLAUDE_CODE_INLINE_HOOK_OUTPUT_LIMIT, capPromptHookInjection } from '../src/directory';
 
 // Make the built-in exports configurable so HOME can point at a real temp
 // fixture without changing the process environment or the user's home files.
@@ -374,6 +374,12 @@ export class OrderStateMachine {
     }
   });
 
+  it('stays silent on a subagent hand-back envelope, even one that names indexed symbols (#2184)', () => {
+    const report = 'how does OrderStateMachine work? submitOrder() calls into the state machine.';
+    expect(hook(report)).toContain('Structural context from CodeGraph');
+    expect(hook(`<agent-message from="agent-7f3e">\n[Subagent hand-back] ${report}\n</agent-message>`)).toBe('');
+  });
+
   it('uses MEDIUM for indexed prose segments without a strong keyword or verified token', () => {
     for (const prompt of ['como state machine?', 'wie state machine?']) {
       const output = hook(prompt);
@@ -471,3 +477,20 @@ describe('system task notifications (#1832)', () => {
     expect(isTaskNotification('trace AuthService login')).toBe(false);
   });
 });
+
+describe('subagent hand-backs (#2184)', () => {
+  const handBack = '<agent-message from="a1b2c3">\n[Subagent hand-back] Traced how AuthService.login calls TokenStore.save and which callers are affected.\n</agent-message>';
+
+  it('skips the complete hand-back envelope', () => {
+    expect(isAgentMessage(handBack)).toBe(true);
+    expect(isAgentMessage(` \n${handBack}\n`)).toBe(true);
+    expect(isAgentMessage('<agent-message>trace AuthService login flow</agent-message>')).toBe(true);
+  });
+  it('does not suppress a user question that mentions the marker', () => {
+    expect(isAgentMessage(`Why does ${handBack} trigger the hook?`)).toBe(false);
+    expect(isAgentMessage(`${handBack} Explain this.`)).toBe(false);
+    expect(isAgentMessage('<agent-messages>trace AuthService</agent-messages>')).toBe(false);
+    expect(isAgentMessage('<agent-message from="x">trace AuthService')).toBe(false);
+    expect(isAgentMessage('trace AuthService login')).toBe(false);
+  });
+});
diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts
index 38b4e55b56..64078dfab6 100644
--- a/src/bin/codegraph.ts
+++ b/src/bin/codegraph.ts
@@ -53,7 +53,7 @@ try {
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { getCodeGraphDir, isInitialized, hasSchemalessDb, hasForeignDbFile, unsafeIndexRootReason, findNearestCodeGraphRoot, planFrontload, isTaskNotification, hasStructuralKeyword, extractCodeTokens, capPromptHookInjection, codeGraphDirName, DEFAULT_CODEGRAPH_DIR } from '../directory';
+import { getCodeGraphDir, isInitialized, hasSchemalessDb, hasForeignDbFile, unsafeIndexRootReason, findNearestCodeGraphRoot, planFrontload, isTaskNotification, isAgentMessage, hasStructuralKeyword, extractCodeTokens, capPromptHookInjection, codeGraphDirName, DEFAULT_CODEGRAPH_DIR } from '../directory';
 import { extractProseCandidates } from '../search/identifier-segments';
 import { detectWorktreeIndexMismatch, worktreeMismatchWarning } from '../sync/worktree';
 import { createShimmerProgress } from '../ui/shimmer-progress';
@@ -1473,9 +1473,10 @@ program
       let input: { prompt?: string; cwd?: string } = {};
       try { input = JSON.parse(raw); } catch { return; }
       const prompt = String(input.prompt || '');
-      // System-injected task notifications are not user prompts: exit before
-      // any project lookup or explore work (#1832).
-      if (isTaskNotification(prompt)) return;
+      // System-injected task notifications and subagent hand-backs are not
+      // user prompts: exit before any project lookup or explore work (#1832,
+      // #2184).
+      if (isTaskNotification(prompt) || isAgentMessage(prompt)) return;
 
       // Gate telemetry: how often each tier fires vs. no-ops — counter names
       // only, NEVER prompt content (see TELEMETRY.md). This is the data that
diff --git a/src/directory.ts b/src/directory.ts
index 0a08df9521..d99860f04e 100644
--- a/src/directory.ts
+++ b/src/directory.ts
@@ -1079,3 +1079,13 @@ export function validateDirectory(projectRoot: string): {
 export function isTaskNotification(prompt: string): boolean {
   return /^\s*<task-notification>[\s\S]*<\/task-notification>\s*$/.test(prompt);
 }
+
+/**
+ * Claude Code hands a subagent's report back to the parent session as a
+ * `<agent-message from="…">…</agent-message>` prompt, which UserPromptSubmit
+ * hooks also receive (#2184). Same rule as {@link isTaskNotification}: only a
+ * prompt that is entirely that envelope is skipped.
+ */
+export function isAgentMessage(prompt: string): boolean {
+  return /^\s*<agent-message(?:\s[^>]*)?>[\s\S]*<\/agent-message>\s*$/.test(prompt);
+}

From 49248e25ebce4690fff5dafc5d7dadc8b0f53bd2 Mon Sep 17 00:00:00 2001
From: Colby Mchenry <me@colbymchenry.com>
Date: Fri, 2 Oct 2026 04:13:42 +0000
Subject: [PATCH 3/5] fix(mcp): answer server/discover locally in the stdio
 proxy (#2084) (#2282)

* fix(mcp): answer server/discover locally in the stdio proxy (#2084)

Clients that probe `server/discover` before the legacy `initialize`
(Antigravity 2.5) wait for its answer. The proxy forwarded it to the shared
daemon, so no reply was written until the daemon connected: a client that
closed stdin first got nothing, and with the daemon unavailable the reply
came ~6s later as -32603 "daemon unavailable". Answer it in the proxy with
-32601 Method not found, which is what sends such a client on to
`initialize`. The direct and daemon sessions already answer unknown methods
with -32601; the new test pins that too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 77db6c659cbd4f404952440a80289610e1650175)

* docs(changelog): credit the server/discover fix

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: danusha2345 <ewidusoc498@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          |   1 +
 __tests__/mcp-server-discover.test.ts | 135 ++++++++++++++++++++++++++
 src/mcp/proxy.ts                      |   7 ++
 3 files changed, 143 insertions(+)
 create mode 100644 __tests__/mcp-server-discover.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42adc334f7..d20a33d7d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -159,6 +159,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - A Vapor route now links to the handler it names. `use: SearchController.show` used to link to whichever controller's `show` came first, so routes with a common handler name, like `show`, `index` or `get`, pointed at another endpoint's code in callers, impact and `codegraph_explore` answers. Nested types like `API.PackageController.get` and handlers declared in an extension of the controller now resolve too, and `use: self.index` resolves to the collection's own `index`. Re-index Vapor projects after upgrading.
 - A PHP call written without a receiver, such as `redirect($url)`, `view('books.show')`, `auth()` or `basename($path)`, is a function call, and no longer links to a same-named method, field or class elsewhere in the project. These wrong links showed up in callers, impact and `codegraph_explore` answers wherever a Laravel helper or PHP built-in shared its name with a project member. Re-index PHP projects after upgrading.
 - The Claude Code prompt hook no longer runs on the messages Claude Code uses to hand a subagent's report back to the main session. Before, such a long report could keep the hook busy past Claude Code's 30-second hook timeout and inject context unrelated to what you asked. Thanks @danusha2345, and @tippmar-nr for the report. (#2184)
+- Newer MCP clients such as Antigravity 2.5 connect again: the server now answers their `server/discover` probe right away with "method not found", so they go straight on to the regular handshake instead of waiting on a reply that could take seconds or never come. Thanks @danusha2345, and @samem26 for the report. (#2084)
 
 ## [1.6.1] - 2026-09-29
 
diff --git a/__tests__/mcp-server-discover.test.ts b/__tests__/mcp-server-discover.test.ts
new file mode 100644
index 0000000000..c464a57701
--- /dev/null
+++ b/__tests__/mcp-server-discover.test.ts
@@ -0,0 +1,135 @@
+/**
+ * `server/discover` probe regression tests (issue #2084).
+ *
+ * Newer MCP clients (Antigravity 2.5) send `server/discover` before the legacy
+ * `initialize` and wait for the answer. A legacy server is expected to reply
+ * `-32601 Method not found`, which sends the client on to `initialize`. The
+ * stdio proxy forwarded the probe to the shared daemon instead, so nothing was
+ * written until the daemon connected: a client that closed stdin first got no
+ * reply at all, and with the daemon unavailable the reply came ~6s later as a
+ * `-32603` the client can't read as "use initialize".
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
+import { once } from 'events';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CodeGraph } from '../src';
+import { WASM_RUNTIME_FLAGS } from '../src/extraction/wasm-runtime-flags';
+import { recordSpawns, removeSpawnLog, settleLosingCandidates, spawnLogFor } from './daemon-candidates';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+const DISCOVER = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'server/discover' }) + '\n';
+
+function readLockPid(root: string): number | null {
+  try {
+    const info = JSON.parse(fs.readFileSync(path.join(root, '.codegraph', 'daemon.pid'), 'utf8'));
+    return typeof info === 'number' ? info : typeof info.pid === 'number' ? info.pid : null;
+  } catch { return null; }
+}
+
+function isAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+/**
+ * Send one `server/discover` line and resolve with everything the server wrote
+ * to stdout once it has exited. `closeStdin: 'at-once'` is the shape of the
+ * `printf … | codegraph serve --mcp` repro; `'after-reply'` is a client that
+ * waits for the answer (stdin is closed on the first stdout line).
+ */
+async function discover(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  children: ChildProcessWithoutNullStreams[],
+  closeStdin: 'at-once' | 'after-reply' = 'at-once',
+): Promise<string> {
+  const recorder = recordSpawns(cwd);
+  const child = spawn(process.execPath, [...WASM_RUNTIME_FLAGS, ...recorder.args, BIN, 'serve', '--mcp', '--no-watch'], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, ...recorder.env, CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '1000', ...env },
+  }) as ChildProcessWithoutNullStreams;
+  children.push(child);
+  child.on('error', () => { /* ignore */ });
+  child.stdin.on('error', () => { /* ignore */ });
+  let stdout = '';
+  child.stdout.on('data', (chunk: Buffer) => {
+    stdout += chunk.toString('utf8');
+    if (closeStdin === 'after-reply' && stdout.includes('\n')) child.stdin.end();
+  });
+  child.stderr.resume();
+  const exited = once(child, 'exit');
+  if (closeStdin === 'at-once') child.stdin.end(DISCOVER);
+  else child.stdin.write(DISCOVER);
+  await exited;
+  return stdout;
+}
+
+function expectMethodNotFound(stdout: string): void {
+  const replies = stdout.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+  expect(replies).toEqual([
+    { jsonrpc: '2.0', id: 1, error: expect.objectContaining({ code: -32601 }) },
+  ]);
+}
+
+describe('server/discover probe (issue #2084)', () => {
+  let tempDir: string;
+  let realRoot: string;
+  const children: ChildProcessWithoutNullStreams[] = [];
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-mcp-discover-'));
+    realRoot = fs.realpathSync(tempDir);
+  });
+
+  afterEach(async () => {
+    await Promise.all(children.map(async (child) => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      const exited = once(child, 'exit');
+      child.kill('SIGKILL');
+      await exited;
+    }));
+    children.length = 0;
+    // The proxy spawns a detached daemon candidate; wait for the losers, then
+    // stop the lock holder — never the vitest worker, which one test plants as
+    // the holder.
+    if (fs.existsSync(spawnLogFor(tempDir))) {
+      await settleLosingCandidates(tempDir, () => readLockPid(realRoot));
+      const daemonPid = readLockPid(realRoot);
+      if (daemonPid && daemonPid !== process.pid && isAlive(daemonPid)) {
+        try { process.kill(daemonPid, 'SIGKILL'); } catch { /* race */ }
+        for (let i = 0; i < 100 && isAlive(daemonPid); i++) await new Promise((r) => setTimeout(r, 50));
+      }
+      removeSpawnLog(tempDir);
+    }
+    await fs.promises.rm(tempDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }, 45_000);
+
+  it('proxy mode answers -32601 even when the client closes stdin right after the probe', async () => {
+    const cg = await CodeGraph.init(tempDir);
+    cg.close();
+    expectMethodNotFound(await discover(tempDir, {}, children));
+  }, 20_000);
+
+  it('proxy mode answers -32601, not "daemon unavailable", when the daemon cannot start', async () => {
+    const cg = await CodeGraph.init(tempDir);
+    cg.close();
+    // A legacy plain-pid lock held by a live process (this worker) makes every
+    // daemon candidate step aside, so the proxy never gets a daemon.
+    fs.writeFileSync(path.join(realRoot, '.codegraph', 'daemon.pid'), `${process.pid}\n`);
+    expectMethodNotFound(await discover(tempDir, {}, children, 'after-reply'));
+  }, 20_000);
+
+  it.each([
+    ['CODEGRAPH_NO_DAEMON=1 on an indexed project', true, { CODEGRAPH_NO_DAEMON: '1' }],
+    ['no .codegraph/ in the working directory', false, {}],
+  ])('direct mode answers -32601 (%s)', async (_label, indexed, env) => {
+    if (indexed) {
+      const cg = await CodeGraph.init(tempDir);
+      cg.close();
+    }
+    expectMethodNotFound(await discover(tempDir, env, children));
+  }, 20_000);
+});
diff --git a/src/mcp/proxy.ts b/src/mcp/proxy.ts
index bdcb997d2a..17c5a59cb1 100644
--- a/src/mcp/proxy.ts
+++ b/src/mcp/proxy.ts
@@ -30,6 +30,7 @@ import { CodeGraphPackageVersion } from './version';
 import { SERVER_INFO, PROTOCOL_VERSION, initializeInstructions } from './session';
 import { SERVER_INSTRUCTIONS } from './server-instructions';
 import { getStaticTools } from './tools';
+import { ErrorCodes } from './transport';
 import { ExploreSessionState } from './explore-session-state';
 import { getTelemetry, ClientInfo } from '../telemetry';
 import { installMainThreadWatchdog, WatchdogHandle } from './liveness-watchdog';
@@ -332,6 +333,12 @@ export async function runLocalHandshakeProxy(deps: LocalHandshakeDeps): Promise<
         writeClient({ jsonrpc: '2.0', id: msg.id, result: { resourceTemplates: [] } });
       } else if (msg.method === 'prompts/list') {
         writeClient({ jsonrpc: '2.0', id: msg.id, result: { prompts: [] } });
+      } else if (msg.method === 'server/discover' && msg.id !== undefined) {
+        // Newer clients (Antigravity 2.5) probe this before `initialize` and wait
+        // for the answer. We don't implement it; Method-not-found is what sends
+        // them on to `initialize`. Answer locally — forwarded, it waited on the
+        // daemon connection and was lost if the client closed stdin first. (#2084)
+        writeClient({ jsonrpc: '2.0', id: msg.id, error: { code: ErrorCodes.MethodNotFound, message: 'Method not found: server/discover' } });
       } else {
         routeToDaemon(line);
       }

From 637fb0fac8c49eddf2c129b1d8420b709b6dd4ea Mon Sep 17 00:00:00 2001
From: Colby Mchenry <me@colbymchenry.com>
Date: Fri, 2 Oct 2026 04:15:24 +0000
Subject: [PATCH 4/5] fix(mcp): release an idle explicit project and its writer
 lock (#2087) (#2283)

* fix(mcp): release an idle explicit project and its writer lock (#2087)

A daemon that answered a `projectPath` query for another indexed project
opened it in-process and, with no owner there, took its writer lock. The
project cache only evicted over its LRU bound or on shutdown, so the lock
stayed held for the daemon's whole life: the project's own daemon could not
become its writer and `codegraph index` there was refused.

Release a cached explicit project once it has gone unused for 10 minutes
(CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS; 0 never releases), through the same
trim path as LRU eviction, so an active call or a running catch-up still
defers it. The next call reopens the project and catches it up (#1835).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 092d49d3dbe1e6e43d416e73ee28aa70e71bec78)

* docs(changelog): credit the idle project release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: danusha2345 <ewidusoc498@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                |  1 +
 __tests__/mcp-projectpath-lifecycle.test.ts | 55 +++++++++++++++++++
 src/mcp/tools.ts                            | 58 ++++++++++++++++++++-
 3 files changed, 112 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d20a33d7d1..5d38859d8e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -160,6 +160,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - A PHP call written without a receiver, such as `redirect($url)`, `view('books.show')`, `auth()` or `basename($path)`, is a function call, and no longer links to a same-named method, field or class elsewhere in the project. These wrong links showed up in callers, impact and `codegraph_explore` answers wherever a Laravel helper or PHP built-in shared its name with a project member. Re-index PHP projects after upgrading.
 - The Claude Code prompt hook no longer runs on the messages Claude Code uses to hand a subagent's report back to the main session. Before, such a long report could keep the hook busy past Claude Code's 30-second hook timeout and inject context unrelated to what you asked. Thanks @danusha2345, and @tippmar-nr for the report. (#2184)
 - Newer MCP clients such as Antigravity 2.5 connect again: the server now answers their `server/discover` probe right away with "method not found", so they go straight on to the regular handshake instead of waiting on a reply that could take seconds or never come. Thanks @danusha2345, and @samem26 for the report. (#2084)
+- A CodeGraph session that queried another project through `projectPath` no longer keeps that project locked for as long as it runs: after 10 minutes without a query it lets the project go, so the project's own session and `codegraph index` can take over again (tune with `CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS`, `0` keeps it open). Thanks @danusha2345, and @bompus for the report. (#2087)
 
 ## [1.6.1] - 2026-09-29
 
diff --git a/__tests__/mcp-projectpath-lifecycle.test.ts b/__tests__/mcp-projectpath-lifecycle.test.ts
index 23a1a36a95..10ea19abc6 100644
--- a/__tests__/mcp-projectpath-lifecycle.test.ts
+++ b/__tests__/mcp-projectpath-lifecycle.test.ts
@@ -442,6 +442,61 @@ describe('MCP explicit projectPath lifecycle (#1835)', { timeout: 30_000 }, () =
   }, 60_000);
 
 
+  // A daemon that answered one projectPath query for another project must not
+  // keep that project's writer lock until it exits: the project's own daemon
+  // and `codegraph index` there would stay locked out (#2087).
+  it('releases an idle explicit project and its writer lock, and retakes it on the next call', async () => {
+    const prev = process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS;
+    process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS = '200';
+    const lock = path.join(serviceB, '.codegraph/writer.pid');
+    try {
+      expect(await search(serviceB, 'betaOriginal')).toContain('betaOriginal');
+      expect(JSON.parse(fs.readFileSync(lock, 'utf8')).pid).toBe(process.pid);
+      expect(opened[0]!.isWatching()).toBe(true);
+
+      expect(await waitFor(async () => !fs.existsSync(lock), 10000)).toBe(true);
+      expect(() => opened[0]!.getStats()).toThrow();
+
+      // Still synchronized while in use: the next call reopens and catches up.
+      fs.writeFileSync(path.join(serviceB, 'src/sample.ts'), 'export function afterIdleRelease() {}\n');
+      expect(await search(serviceB, 'afterIdleRelease')).toContain('afterIdleRelease');
+      expect(opened).toHaveLength(2);
+      expect(opened[1]!.isWatching()).toBe(true);
+      expect(JSON.parse(fs.readFileSync(lock, 'utf8')).pid).toBe(process.pid);
+    } finally {
+      if (prev === undefined) delete process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS;
+      else process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS = prev;
+    }
+  });
+
+  it('defers an idle release until an active catch-up finishes (#2087)', async () => {
+    let release!: () => void;
+    const held = new Promise<void>((resolve) => { release = resolve; });
+    onOpen = (cg) => {
+      const sync = cg.sync.bind(cg);
+      vi.spyOn(cg, 'sync').mockImplementation(async (...args) => { await held; return sync(...args); });
+    };
+    const prevIdle = process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS;
+    process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS = '50';
+    process.env.CODEGRAPH_CATCHUP_GATE_TIMEOUT_MS = '10';
+    const lock = path.join(serviceB, '.codegraph/writer.pid');
+    try {
+      fs.writeFileSync(path.join(serviceB, 'src/sample.ts'), 'export function idleCatchUp() {}\n');
+      await search(serviceB, 'betaOriginal');
+      await new Promise((r) => setTimeout(r, 300));
+      expect(() => opened[0]!.getStats()).not.toThrow();
+      expect(fs.existsSync(lock)).toBe(true);
+      release();
+      expect(await waitFor(async () => !fs.existsSync(lock), 10000)).toBe(true);
+      expect(names(serviceB)).toEqual(['idleCatchUp']);
+      expect(() => opened[0]!.getStats()).toThrow();
+    } finally {
+      release();
+      if (prevIdle === undefined) delete process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS;
+      else process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS = prevIdle;
+    }
+  });
+
   it('drains a tool operation before closing its cached graph', async () => {
     await search(serviceA, 'alphaOriginal');
     const handler = engine.getToolHandler();
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 7553ca5a65..d11fa40c5f 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -1867,6 +1867,23 @@ function canonicalPath(p: string): string {
  */
 export const MAX_CACHED_PROJECTS = 8;
 
+/**
+ * How long an explicit-`projectPath` project may go unused before the handler
+ * releases it (#2087). Releasing frees its SQLite handle, its watcher and the
+ * writer lock the engine may hold on that project — which otherwise stays held
+ * for the whole life of this daemon, locking the project's own daemon and
+ * `codegraph index` out. The next call reopens it and catches up.
+ * `CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS` overrides it; `0` never releases.
+ */
+const DEFAULT_PROJECT_IDLE_TIMEOUT_MS = 600_000;
+function resolveProjectIdleTimeoutMs(): number {
+  const raw = process.env.CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return DEFAULT_PROJECT_IDLE_TIMEOUT_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_PROJECT_IDLE_TIMEOUT_MS;
+  return Math.floor(n);
+}
+
 /**
  * Engine-side lifecycle for a project the ToolHandler opened for an explicit
  * `projectPath` (#1835). `activate` gives it the same treatment the default
@@ -1892,6 +1909,10 @@ export class ToolHandler {
   // CANONICAL (realpath) index root. Map insertion order doubles as LRU order:
   // a hit re-inserts, and `MAX_CACHED_PROJECTS` bounds the size (#1835).
   private projectCache: Map<string, CodeGraph> = new Map();
+  // When each cached root was last handed to a call, and the one timer that
+  // releases the oldest once it has been idle long enough (#2087).
+  private projectUsedAt: Map<string, number> = new Map();
+  private idleReleaseTimer: NodeJS.Timeout | null = null;
   // Engine hook that watches + catches up an explicit project (null for the
   // CLI and worker-thread handlers, which never own a watcher).
   private projectLifecycle: ProjectLifecycle | null = null;
@@ -2260,6 +2281,7 @@ export class ToolHandler {
       // Refresh LRU position.
       this.projectCache.delete(canonicalRoot);
       this.projectCache.set(canonicalRoot, cached);
+      this.projectUsedAt.set(canonicalRoot, Date.now());
       return this.freshen(cached);
     }
 
@@ -2269,6 +2291,7 @@ export class ToolHandler {
       if (isSameIndexRoot(root, resolvedRoot)) {
         this.projectCache.delete(root);
         this.projectCache.set(root, open);
+        this.projectUsedAt.set(root, Date.now());
         return this.freshen(open);
       }
     }
@@ -2276,6 +2299,7 @@ export class ToolHandler {
     const open = () => loadCodeGraph().openSync(canonicalRoot);
     const cg = this.projectLifecycle?.open(canonicalRoot, open) ?? open();
     this.projectCache.set(canonicalRoot, cg);
+    this.projectUsedAt.set(canonicalRoot, Date.now());
     this.trimProjects();
     return cg;
   }
@@ -2295,13 +2319,21 @@ export class ToolHandler {
     await this.awaitCatchUpGate(gate);
   }
 
-  /** Never evict a graph while a tool call or its timed-out reconcile uses it. */
+  /**
+   * Never evict a graph while a tool call or its timed-out reconcile uses it.
+   * Evicts over the LRU bound, on close, and once idle past the timeout
+   * (#2087). The cache is in last-use order, so idle entries lead it.
+   */
   private trimProjects(): void {
     if (this.activeCalls > 0) return;
+    const idleMs = resolveProjectIdleTimeoutMs();
+    const now = Date.now();
     for (const [root, cg] of this.projectCache) {
-      if (!this.closing && this.projectCache.size <= MAX_CACHED_PROJECTS) break;
+      const idle = idleMs > 0 && now - (this.projectUsedAt.get(root) ?? now) >= idleMs;
+      if (!this.closing && this.projectCache.size <= MAX_CACHED_PROJECTS && !idle) break;
       if (this.projectGates.has(cg)) continue;
       this.projectCache.delete(root);
+      this.projectUsedAt.delete(root);
       if (this.projectLifecycle) {
         this.pendingCloses++;
         void Promise.resolve(this.projectLifecycle.release(cg)).finally(() => {
@@ -2313,6 +2345,26 @@ export class ToolHandler {
     if (this.closing && this.projectCache.size === 0 && this.pendingCloses === 0) {
       for (const resolve of this.closeWaiters.splice(0)) resolve();
     }
+    this.scheduleIdleRelease(idleMs);
+  }
+
+  /**
+   * Arm one unref'd timer for the oldest project a trim could release. A
+   * project whose catch-up is still running is trimmed when that settles; the
+   * 1s floor keeps a project a trim must skip from re-arming in a tight loop.
+   */
+  private scheduleIdleRelease(idleMs: number): void {
+    if (this.idleReleaseTimer || this.closing || idleMs <= 0) return;
+    for (const [root, cg] of this.projectCache) {
+      if (this.projectGates.has(cg)) continue;
+      const due = (this.projectUsedAt.get(root) ?? Date.now()) + idleMs - Date.now();
+      this.idleReleaseTimer = setTimeout(() => {
+        this.idleReleaseTimer = null;
+        this.trimProjects();
+      }, Math.min(Math.max(due, 1000), 0x7fffffff)); // setTimeout's 32-bit cap
+      this.idleReleaseTimer.unref();
+      return;
+    }
   }
 
   /**
@@ -2347,6 +2399,8 @@ export class ToolHandler {
   closeAll(): Promise<void> {
     this.closing = true;
     this.worktreeMismatchCache.clear();
+    if (this.idleReleaseTimer) clearTimeout(this.idleReleaseTimer);
+    this.idleReleaseTimer = null;
     this.trimProjects();
     if (this.projectCache.size === 0 && this.activeCalls === 0 && this.pendingCloses === 0) return Promise.resolve();
     return new Promise((resolve) => this.closeWaiters.push(resolve));

From fdc7754a72065ac9a06702aa32ee3bf116a0658f Mon Sep 17 00:00:00 2001
From: Colby Mchenry <me@colbymchenry.com>
Date: Fri, 2 Oct 2026 04:16:48 +0000
Subject: [PATCH 5/5] fix(mcp): return status and stale refusals as text only
 (#2088) (#2284)

* fix(mcp): return status and stale refusals as text only (#2088)

Claude Code shows the model a tool result's structuredContent in place
of its content text, under every protocol version. codegraph_status and
explore's stale-index refusal both set structuredContent.freshness, so
the model saw a JSON object instead of the refusal, its retry guidance
or the status report. The text already carries every field, and nothing
in the codebase reads structuredContent, so both results drop it.

The tests now assert that the field is absent and that the text keeps
the refusal line and the stale file list.

(cherry picked from commit 18d65f8e106b1ee02e9d8a9cf482cce00fbc9dbe)

* fix(mcp): list every unverified file in the stale refusal (#2088)

(cherry picked from commit f1b0ec7f56e003d9fd6b1286f17a76e2287d43c6)

* fix(mcp): keep the stale refusal's unchecked-file list bounded

The text-only refusal now names the first 20 files it could not verify and
counts the rest, as it did before; an impact answer over a hub symbol can
leave thousands unchecked, and every one of them would land in the agent's
context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit c4513a66c9ae6bb10ede80d102d4122ed7f0508d)

* docs(changelog): one entry for the text-only results fix

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Aaron Queen <bompus@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                           |  1 +
 __tests__/mcp-stale-refusal.test.ts    | 14 +++++++++++---
 __tests__/mcp-status-freshness.test.ts |  5 ++---
 src/mcp/tools.ts                       | 11 ++++++-----
 4 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d38859d8e..392e10bb6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -161,6 +161,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - The Claude Code prompt hook no longer runs on the messages Claude Code uses to hand a subagent's report back to the main session. Before, such a long report could keep the hook busy past Claude Code's 30-second hook timeout and inject context unrelated to what you asked. Thanks @danusha2345, and @tippmar-nr for the report. (#2184)
 - Newer MCP clients such as Antigravity 2.5 connect again: the server now answers their `server/discover` probe right away with "method not found", so they go straight on to the regular handshake instead of waiting on a reply that could take seconds or never come. Thanks @danusha2345, and @samem26 for the report. (#2084)
 - A CodeGraph session that queried another project through `projectPath` no longer keeps that project locked for as long as it runs: after 10 minutes without a query it lets the project go, so the project's own session and `codegraph index` can take over again (tune with `CODEGRAPH_PROJECT_IDLE_TIMEOUT_MS`, `0` keeps it open). Thanks @danusha2345, and @bompus for the report. (#2087)
+- Claude Code now shows the model the full text of `codegraph_status` and of explore's stale-index refusal. Both results also carried `structuredContent`, and Claude Code shows a result's `structuredContent` in place of its text, so the model saw only a freshness JSON object: no refusal message, no retry guidance and no status report. Both results are now text only. Thanks @bompus. (#2088)
 
 ## [1.6.1] - 2026-09-29
 
diff --git a/__tests__/mcp-stale-refusal.test.ts b/__tests__/mcp-stale-refusal.test.ts
index 53362c7a29..309cf92ee2 100644
--- a/__tests__/mcp-stale-refusal.test.ts
+++ b/__tests__/mcp-stale-refusal.test.ts
@@ -121,7 +121,9 @@ describe('a degraded index refuses answers from changed files (#1959)', () => {
     const result = await handler.execute('codegraph_search', { query: 'unicodeSymbol' });
     expect(result.isError).toBeFalsy();
     expect(result.content[0].text).toContain('cannot answer from this index');
-    expect(result.structuredContent).toEqual({ freshness: { stale: [relative], unchecked: [] } });
+    expect(result.content[0].text).toContain(`- ${relative}`);
+    // Claude Code would show structuredContent in place of this text (#2088).
+    expect(result).not.toHaveProperty('structuredContent');
     expect(result).not.toHaveProperty('_cgAnswerFiles');
   });
 
@@ -137,7 +139,7 @@ describe('a degraded index refuses answers from changed files (#1959)', () => {
   );
 
   it('refuses rather than silently validating only the first 200 contributing files', async () => {
-    for (let i = 0; i < 201; i++) {
+    for (let i = 0; i < 230; i++) {
       fs.writeFileSync(path.join(root, `caller${i}.ts`),
         `import { alphaOnly } from './alpha'; export function caller${i}() { return alphaOnly(); }\n`);
     }
@@ -147,7 +149,13 @@ describe('a degraded index refuses answers from changed files (#1959)', () => {
     const result = await handler.execute('codegraph_impact', { symbol: 'alphaOnly' });
     expect(result.isError).toBeFalsy();
     expect(result.content[0].text).toContain('validation budget');
-    expect((result.structuredContent!.freshness as { unchecked: string[] }).unchecked.length).toBeGreaterThan(0);
+    const text = result.content[0].text;
+    const total = Number(text.match(/validation budget for (\d+) files/)![1]);
+    // A long unchecked list stays bounded: the first 20 and a count of the rest.
+    expect(total).toBeGreaterThan(20);
+    expect(text.split('\n').filter(line => /^- (?!…)/.test(line))).toHaveLength(20);
+    expect(text).toContain(`- … ${total - 20} more (narrow the query)`);
+    expect(result).not.toHaveProperty('structuredContent');
     expect(result.content[0].text).not.toContain('**Impact');
   });
 
diff --git a/__tests__/mcp-status-freshness.test.ts b/__tests__/mcp-status-freshness.test.ts
index 19c14f7ce1..923f77ae3f 100644
--- a/__tests__/mcp-status-freshness.test.ts
+++ b/__tests__/mcp-status-freshness.test.ts
@@ -42,9 +42,8 @@ describe('MCP status freshness (#1959)', () => {
     fs.writeFileSync(path.join(root, 'add.ts'), 'export const added = 1;\n');
 
     const result = await handler.execute('codegraph_status', {});
-    expect(result.structuredContent).toEqual({ freshness: {
-      lastIndexedAt: cg.getLastIndexedAt(), changes: { added: 1, modified: 1, removed: 1 }, complete: true,
-    } });
+    // Claude Code would show structuredContent in place of this text (#2088).
+    expect(result).not.toHaveProperty('structuredContent');
     const changed = result.content[0].text;
     expect(changed).toContain('**Changes since index:** 1 added, 1 modified, 1 removed');
   });
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index d11fa40c5f..3aa5fab87d 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -1538,7 +1538,6 @@ export interface ToolResult {
   _cgExploreEmission?: ExploreEmission;
   /** Internal structured provenance, preserved by query workers and stripped by execute. */
   _cgAnswerFiles?: AnswerFile[];
-  structuredContent?: Record<string, unknown>;
 }
 
 /**
@@ -2811,7 +2810,10 @@ export class ToolHandler {
             if (validation.unchecked.length > 20) lines.push(`- … ${validation.unchecked.length - 20} more (narrow the query)`);
           }
           lines.push('Retry after a successful codegraph sync, or narrow the query.');
-          return { ...this.textResult(lines.join('\n')), structuredContent: { freshness: validation } };
+          // Text only: Claude Code shows the model a result's structuredContent
+          // in place of its text (#2088). The text names every stale file and
+          // the first unchecked ones; the rest only need a narrower query.
+          return this.textResult(lines.join('\n'));
         }
       }
       // Record + STRIP before anything else touches the result: the emission is
@@ -8060,9 +8062,8 @@ export class ToolHandler {
       }
     }
 
-    return { ...this.textResult(lines.join('\n')), structuredContent: {
-      freshness: { lastIndexedAt, changes, complete: changes !== null },
-    } };
+    // Text only, for the same reason as the stale-answer path (#2088).
+    return this.textResult(lines.join('\n'));
   }
 
   /**