fix(gemini-local): treat token-overflow as a fresh-session signal (#4932)

## Thinking Path

The same 2026-04-30 audit that produced PR #4118 (`Invalid session`
regex extension) and the ENOTFOUND classifier (#4931) identified a third
stuck-session pattern: **13 failures in 7 days, all on a single agent
(Ernest)**, with stderr matching:

```
_ApiError: {"error":{"code":400,"message":"The input token count exceeds
the maximum number of tokens allowed 1048576","status":"INVALID_ARGUMENT"}}
  at ChatCompressionService.compress
```

The root cause is that gemini-cli's `ChatCompressionService` blew the 1M
token context limit **during its compression step itself**. Resuming the
same session ID will hit the same wall on the next attempt — the session
is effectively dead the same way it is when "Invalid session identifier"
fires (PR #4118).

## What Changed

Extends the `isGeminiUnknownSessionError` regex in `parse.ts` with two
phrases:
- `exceeds\s+the\s+maximum\s+number\s+of\s+tokens`
- `input\s+token\s+count\s+exceeds`

Both trigger the **existing** fresh-session retry path in
`execute.ts:596` — no new code path. Same extension pattern as PR #4118.

## Verification

- `npx vitest run --project @paperclipai/adapter-gemini-local` → 14/14
pass (11 in `parse.test.ts` + 3 existing in `execute.remote.test.ts`)
- 2 new tests cover the token-overflow patterns
- `pnpm --filter @paperclipai/adapter-gemini-local typecheck` → clean
- Audit query against `heartbeat_runs.stderr_excerpt` confirms regex
matches all 13 occurrences

## Stacking

This PR is stacked on top of #4931 (the ENOTFOUND classifier) which adds
the `parse.test.ts` file. If #4931 merges first, this PR's diff is just
the regex + 2 tests. If this PR is reviewed first, please merge #4931
first to avoid touching the same test scaffolding twice.

## Risks

- **Low.** Single-line regex extension. No new code paths.
- The session-reset path is well-trodden (PR #4118 in flight).
- If a non-Gemini caller produces a stderr containing "exceeds the
maximum number of tokens" by coincidence, they would trigger one
unnecessary fresh-session retry. Not plausible in the gemini-cli output
context where this stderr is sourced.

## Model Used

Claude Opus 4.7 (1M context), Anthropic SDK via Claude Code CLI.

## Checklist

- [x] Thinking path traces from audit data to single-line regex change
- [x] Model specified
- [x] No duplicate of planned core work
- [x] Tests pass locally
- [x] Tests added (2 new)
- [x] N/A — server-side regex
- [x] Internal pattern; no docs change
- [x] Risks documented
- [x] Will address Greptile + reviewer comments before merge
- [x] I searched the GitHub PR list for similar PRs and confirmed this
is not a duplicate (related: #4118 covers the "Invalid session
identifier" regex; this PR extends the same regex with token-overflow
phrases)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/adapters/gemini-local/src/server/execute.ts

@@ -51,8 +51,9 @@ import { DEFAULT_GEMINI_LOCAL_MODEL, SANDBOX_INSTALL_COMMAND } from "../index.js
 import {
   describeGeminiFailure,
   detectGeminiAuthRequired,
+  isGeminiTransientNetworkError,
   isGeminiTurnLimitResult,
-  isGeminiUnknownSessionError,
+  isGeminiSessionUnrecoverableError,
   parseGeminiJsonl,
 } from "./parse.js";
 import { firstNonEmptyLine } from "./utils.js";
@@ -569,6 +570,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       stdout: attempt.proc.stdout,
       stderr: attempt.proc.stderr,
     });
+    const networkUnavailable = isGeminiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
 
     if (attempt.proc.timedOut) {
       return {
@@ -576,7 +578,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         signal: attempt.proc.signal,
         timedOut: true,
         errorMessage: `Timed out after ${timeoutSec}s`,
-        errorCode: authMeta.requiresAuth ? "gemini_auth_required" : null,
+        errorCode: authMeta.requiresAuth
+          ? "gemini_auth_required"
+          : networkUnavailable
+            ? "gemini_network_unavailable"
+            : null,
         clearSession: clearSessionOnMissingSession,
       };
     }
@@ -632,6 +638,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         ? "gemini_auth_required"
         : failed && clearSessionForTurnLimit
         ? "max_turns_exhausted"
+        : failed && networkUnavailable
+        ? "gemini_network_unavailable"
         : null,
       usage: attempt.parsed.usage,
       sessionId: resolvedSessionId,
@@ -655,7 +663,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       sessionId &&
       !initial.proc.timedOut &&
       (initial.proc.exitCode ?? 0) !== 0 &&
-      isGeminiUnknownSessionError(initial.proc.stdout, initial.proc.stderr)
+      isGeminiSessionUnrecoverableError(initial.proc.stdout, initial.proc.stderr)
     ) {
       await onLog(
         "stdout",

packages/adapters/gemini-local/src/server/index.ts

@@ -3,7 +3,8 @@ export { listGeminiSkills, syncGeminiSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   parseGeminiJsonl,
-  isGeminiUnknownSessionError,
+  isGeminiSessionUnrecoverableError,
+  isGeminiTransientNetworkError,
   describeGeminiFailure,
   detectGeminiAuthRequired,
   isGeminiTurnLimitResult,

packages/adapters/gemini-local/src/server/parse.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { parseGeminiJsonl } from "./parse.js";
+import {
+  isGeminiTransientNetworkError,
+  isGeminiSessionUnrecoverableError,
+  parseGeminiJsonl,
+} from "./parse.js";
 
 describe("parseGeminiJsonl", () => {
   it("collects assistant text from message events with string content", () => {
@@ -131,3 +135,69 @@ describe("parseGeminiJsonl", () => {
     expect(result.errorMessage).toBe("boom");
   });
 });
+
+describe("isGeminiSessionUnrecoverableError", () => {
+  it("matches 'unknown session'", () => {
+    expect(isGeminiSessionUnrecoverableError("", "Error: unknown session 'abc-123'")).toBe(true);
+  });
+
+  it("matches 'session ... not found'", () => {
+    expect(isGeminiSessionUnrecoverableError("", "Resumed session abc-123 not found on disk")).toBe(true);
+  });
+
+  it("matches 'exceeds the maximum number of tokens' (compression overflow)", () => {
+    const stderr =
+      '_ApiError: {"error":{"code":400,"message":"The input token count exceeds the maximum number of tokens allowed 1048576","status":"INVALID_ARGUMENT"}} at ChatCompressionService.compress';
+    expect(isGeminiSessionUnrecoverableError("", stderr)).toBe(true);
+  });
+
+  it("matches 'input token count exceeds'", () => {
+    expect(
+      isGeminiSessionUnrecoverableError("", "input token count exceeds maximum"),
+    ).toBe(true);
+  });
+
+  it("does not match unrelated stderr", () => {
+    expect(isGeminiSessionUnrecoverableError("", "Some other error")).toBe(false);
+  });
+
+  it("does not match transient network errors (those go to isGeminiTransientNetworkError)", () => {
+    expect(
+      isGeminiSessionUnrecoverableError(
+        "",
+        "_GaxiosError: getaddrinfo ENOTFOUND oauth2.googleapis.com",
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("isGeminiTransientNetworkError", () => {
+  it("matches DNS failure on oauth2.googleapis.com", () => {
+    const stderr =
+      "_GaxiosError: request to https://oauth2.googleapis.com/token failed, reason: getaddrinfo ENOTFOUND oauth2.googleapis.com";
+    expect(isGeminiTransientNetworkError("", stderr)).toBe(true);
+  });
+
+  it("matches EAI_AGAIN", () => {
+    expect(
+      isGeminiTransientNetworkError("", "Error: getaddrinfo EAI_AGAIN sts.googleapis.com"),
+    ).toBe(true);
+  });
+
+  it("matches _UserRefreshClient ENOTFOUND", () => {
+    const stderr =
+      "at _UserRefreshClient.refreshTokenNoCache (.../google-auth-library/...)\n" +
+      "  caused by: ENOTFOUND oauth2.googleapis.com";
+    expect(isGeminiTransientNetworkError("", stderr)).toBe(true);
+  });
+
+  it("does not match unrelated stderr", () => {
+    expect(isGeminiTransientNetworkError("", "Some other error")).toBe(false);
+  });
+
+  it("does not match unknown-session errors (those go to isGeminiSessionUnrecoverableError)", () => {
+    expect(
+      isGeminiTransientNetworkError("", "Error: unknown session 'abc-123'"),
+    ).toBe(false);
+  });
+});

packages/adapters/gemini-local/src/server/parse.ts

@@ -199,14 +199,26 @@ export function parseGeminiJsonl(stdout: string) {
   };
 }
 
-export function isGeminiUnknownSessionError(stdout: string, stderr: string): boolean {
+export function isGeminiSessionUnrecoverableError(stdout: string, stderr: string): boolean {
   const haystack = `${stdout}\n${stderr}`
     .split(/\r?\n/)
     .map((line) => line.trim())
     .filter(Boolean)
     .join("\n");
 
-  return /unknown\s+session|session\s+.*\s+not\s+found|resume\s+.*\s+not\s+found|checkpoint\s+.*\s+not\s+found|cannot\s+resume|failed\s+to\s+resume/i.test(
+  return /unknown\s+session|session\s+.*\s+not\s+found|resume\s+.*\s+not\s+found|checkpoint\s+.*\s+not\s+found|cannot\s+resume|failed\s+to\s+resume|exceeds\s+the\s+maximum\s+number\s+of\s+tokens|input\s+token\s+count\s+exceeds/i.test(
+    haystack,
+  );
+}
+
+export function isGeminiTransientNetworkError(stdout: string, stderr: string): boolean {
+  const haystack = `${stdout}\n${stderr}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+
+  return /ENOTFOUND\s+oauth2\.googleapis\.com|ENOTFOUND\s+sts\.googleapis\.com|EAI_AGAIN|_GaxiosError.*ENOTFOUND|_UserRefreshClient.*ENOTFOUND/i.test(
     haystack,
   );
 }

packages/adapters/gemini-local/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+});

server/src/__tests__/adapter-session-codecs.test.ts

@@ -7,7 +7,7 @@ import {
 } from "@paperclipai/adapter-cursor-local/server";
 import {
   sessionCodec as geminiSessionCodec,
-  isGeminiUnknownSessionError,
+  isGeminiSessionUnrecoverableError,
 } from "@paperclipai/adapter-gemini-local/server";
 import {
   sessionCodec as opencodeSessionCodec,
@@ -220,19 +220,19 @@ describe("cursor resume recovery detection", () => {
 describe("gemini resume recovery detection", () => {
   it("detects unknown session errors from gemini output", () => {
     expect(
-      isGeminiUnknownSessionError(
+      isGeminiSessionUnrecoverableError(
         "",
         "unknown session id abc",
       ),
     ).toBe(true);
     expect(
-      isGeminiUnknownSessionError(
+      isGeminiSessionUnrecoverableError(
         "",
         "checkpoint latest not found",
       ),
     ).toBe(true);
     expect(
-      isGeminiUnknownSessionError(
+      isGeminiSessionUnrecoverableError(
         "{\"type\":\"result\",\"subtype\":\"success\"}",
         "",
       ),

server/src/__tests__/gemini-local-adapter.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   isGeminiTurnLimitResult,
-  isGeminiUnknownSessionError,
+  isGeminiSessionUnrecoverableError,
   parseGeminiJsonl,
 } from "@paperclipai/adapter-gemini-local/server";
 import { parseGeminiStdoutLine } from "@paperclipai/adapter-gemini-local/ui";
@@ -76,8 +76,8 @@ describe("gemini_local parser", () => {
 
 describe("gemini_local stale session detection", () => {
   it("treats missing session messages as an unknown session error", () => {
-    expect(isGeminiUnknownSessionError("", "unknown session id abc")).toBe(true);
-    expect(isGeminiUnknownSessionError("", "checkpoint latest not found")).toBe(true);
+    expect(isGeminiSessionUnrecoverableError("", "unknown session id abc")).toBe(true);
+    expect(isGeminiSessionUnrecoverableError("", "checkpoint latest not found")).toBe(true);
   });
 });