fix(#64): stop Claude Code disconnects via lazy progress + opt-out

[jamubc]

Summary

Fixes the MCP server disconnects reported in #64, folded into the unpublished 1.1.8 release. The reproduction in #64 is a plain ping — an instant call that disconnects right after a successful response — so this is not a timeout. The root cause is the upstream Claude Code behavior tracked in anthropics/claude-code#53617: on some client versions, emitting progress notifications around a successful tools/call response disconnects the stdio server.

The 1.1.7 stdin/EPIPE hardening was a candidate fix but did not resolve it, which pointed away from a crash-only cause and toward the progress-notification trigger.

What changed

Lazy progress (the core fix). The server no longer sends an immediate progress:0 ack, and the final progress:100 is gated behind a per-call emittedProgress flag. A tool that finishes before the first keepalive tick now emits zero progress notifications, so quick calls like ping never bracket their response with progress — removing the #53617 trigger for the common case. Long operations still receive keepalive progress on each interval and survive the SDK's 60s request timeout.

GEMINI_MCP_DISABLE_PROGRESS opt-out (absorbed from #80). Setting GEMINI_MCP_DISABLE_PROGRESS=1 (or =true) suppresses all progress notifications, for clients still affected by #53617 even on long calls. Progress stays on by default.

Robustness, independent of the above:

• Per-call ProgressContext replaces shared module globals, so a finishing call can no longer clear the keepalive timer of another call in flight.
• Process-level guards (stdout/stderr error handlers + unhandledRejection/uncaughtException) keep the long-lived server alive through a stray async error or an EPIPE after the client goes away. Startup failures still exit.
• The keepalive now sends a spec-correct notifications/progress carrying the client's progressToken (the only notification the MCP SDK uses to reset a request's timeout — verified in shared/protocol.js, _onprogress), and stops its own timer if a write fails on a dead pipe.

Docs. Added a "Known Issues" entry in docs/resources/troubleshooting.md covering #53617 and the opt-out env var.

Why not "more heartbeats"

A drive-by comment on #64 suggested adding more frequent heartbeats. That is the wrong direction for this symptom: #64's failing case is an instant call, and on a #53617-affected client more progress notifications mean more disconnect triggers. Two of that comment's three hypotheses (undici fetch failed in @google/genai, p-retry behavior) do not apply here at all — this project spawns the gemini CLI via child_process and pulls in none of @google/genai, undici, or p-retry (confirmed with npm ls). The 429 case is already handled by the existing flash fallback.

Test plan

• npm run build — clean
• npm test — 57/57 unit + integration pass
• Manual: ping repeatedly in Claude Code v2.1.109 and confirm no disconnect
• Manual: a >15s changeMode still streams progress and does not time out

Closes #64.

[gemini-code-assist]

Code Review

This pull request addresses MCP server disconnect issues by implementing lazy progress notifications, managing progress state per-call to support concurrent tool executions, and adding process-level error handlers to prevent stray async or stream errors from crashing the server. The feedback recommends terminating the process on uncaughtException rather than keeping it alive to avoid unpredictable state corruption, and suggests optimizing the progress update logic by not scheduling a setInterval timer when no progress token is provided.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Keeping the process alive after an uncaughtException is highly discouraged in Node.js because the application state becomes unpredictable and corrupted. Since you have already added a stream error handler on process.stdout to catch EPIPE errors (which prevents them from becoming uncaught exceptions), any other uncaught exception is likely a critical error where the process should be terminated gracefully to avoid memory leaks or zombie processes.

process.on("uncaughtException", (error) => {
  Logger.error("Uncaught exception (shutting down):", error);
  process.exit(1);
});

[gemini-code-assist]

If progressToken is undefined (which happens when progress is disabled or not requested by the client), we still set up a setInterval timer that ticks every 15 seconds. Although it is cleared when the tool execution finishes, during execution it schedules unnecessary ticks on the event loop that do nothing because of the if (!progressToken) return; guard. We can optimize this by returning early and not scheduling the interval when progressToken is not provided.

function startProgressUpdates(operationName: string, progressToken?: string | number) {
  const ctx: ProgressContext = {
    isProcessing: true,
    operationName,
    latestOutput: "",
    messageIndex: 0,
    progress: 0,
    emittedProgress: false,
  };

  if (!progressToken) {
    return { interval: undefined, progressToken, ctx };
  }

  const progressMessages = [
    "🧠 " + operationName + " - Gemini is analyzing your request...",
    "📊 " + operationName + " - Processing files and generating insights...",
    "✨ " + operationName + " - Creating structured response for your review...",
    "⏱️ " + operationName + " - Large analysis in progress (this is normal for big requests)...",
    "🔍 " + operationName + " - Still working... Gemini takes time for quality results..."
  ];

  const progressInterval = setInterval(async () => {
    if (!ctx.isProcessing) {
      clearInterval(progressInterval);
      return;
    }

    const baseMessage = progressMessages[ctx.messageIndex % progressMessages.length];
    const outputPreview = ctx.latestOutput.slice(-150).trim();
    const message = outputPreview ? baseMessage + "\n📝 Output: ..." + outputPreview : baseMessage;
    ctx.messageIndex++;
    ctx.progress += 1;

    try {
      await server.notification({
        method: PROTOCOL.NOTIFICATIONS.PROGRESS,
        params: { progressToken, progress: ctx.progress, message },
      });
      ctx.emittedProgress = true;
    } catch (error) {
      Logger.error("Keepalive progress notification failed; stopping updates:", error);
      ctx.isProcessing = false;
      clearInterval(progressInterval);
    }
  }, PROTOCOL.KEEPALIVE_INTERVAL);

  return { interval: progressInterval, progressToken, ctx };
}

[gemini-code-assist]

Update the signature of stopProgressUpdates to allow interval to be undefined (since we avoided scheduling the interval when progressToken is not provided), and conditionally clear it.

Suggested change

	async function stopProgressUpdates(
	progressData: { interval: NodeJS.Timeout; progressToken?: string | number; ctx: ProgressContext },
	success: boolean = true
	) {
	const operationName = currentOperationName; // Store before clearing
	isProcessing = false;
	currentOperationName = "";
	const operationName = progressData.ctx.operationName;
	progressData.ctx.isProcessing = false;
	clearInterval(progressData.interval);
	async function stopProgressUpdates(
	progressData: { interval?: NodeJS.Timeout; progressToken?: string | number; ctx: ProgressContext },
	success: boolean = true
	) {
	const operationName = progressData.ctx.operationName;
	progressData.ctx.isProcessing = false;
	if (progressData.interval) {
	clearInterval(progressData.interval);
	}