gogcli-mcp 2.21.1 → 2.22.0

package/tests/connector-runtime.test.ts

@@ -790,7 +790,12 @@ describe('makeFlyExecutor re-mints a rejected access token and replays once', ()
     vi.stubGlobal('fetch', fetchMock);
     const exec = makeFlyExecutor(ENDPOINT, KEY);
     await expect(exec(READ, {})).rejects.toThrow(/Google API error/);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
+    // Counted by ENDPOINT, not in total: this same refusal now also takes a
+    // read of the Google layer (`/health/google`, see the refusal-probe block
+    // below), and that reading is a diagnostic, not a second attempt. What
+    // "does not replay" means is that gog ran exactly once.
+    const runs = fetchMock.mock.calls.filter(([url]) => String(url).endsWith('/run'));
+    expect(runs).toHaveLength(1);
   });
 
   it('does not replay when the token source cannot invalidate', async () => {
@@ -1196,3 +1201,444 @@ describe('makeFlyExecutor re-mints a rejected access token and replays once', ()
     expect(result.content[0].text).toBe('{"threads":[]}');
   });
 });
+
+/**
+ * DEFECT 3, the half of it that survived grounding.
+ *
+ * `worker.ts` builds `makeFlyExecutor(FLY_ENDPOINT, key)` with NO token source,
+ * so the eviction + replay machinery is inert on the hosted path: `gog` runs as
+ * the Fly volume's own identity, and a Google 401 stops at the "no access token
+ * was supplied" guard. That much is by design and stays.
+ *
+ * What did NOT survive is the idea of building a replay for it. `gog` is spawned
+ * fresh per `/run` and re-reads the keyring every time, so there is no
+ * cross-spawn in-memory token that could go stale — a Google 401 here means the
+ * stored credential itself was refused, and no retry can fix that. Building a
+ * retry would have been the fifth plausible theory in a row.
+ *
+ * So this path gets INSTRUMENTATION instead. The one thing nobody could answer
+ * after the incident was: at the moment Google refused that call, was the
+ * refresh token on the volume alive or dead? `replay.declined` records only that
+ * WE did nothing. These tests pin a record of what GOOGLE said, measured at the
+ * moment of the refusal with the probe `/health/google` — and pin that the
+ * measurement changes nothing the caller sees.
+ */
+describe('the Google-layer measurement taken when a hosted call is refused', () => {
+  const ENDPOINT = 'https://gogcli-gog-runner.fly.dev';
+  const KEY = 'k';
+  const PREFIX = 'gog-auth ';
+
+  const GOOGLE_401_STDERR =
+    'Google API error (401 authError): Request had invalid authentication credentials.';
+  const READ = ['--json', '--color=never', '--no-input', 'gmail', 'search', 'q'];
+
+  function gogFailed(stderr: string) {
+    return {
+      ok: false,
+      status: 422,
+      json: async () => ({ error: `Command failed: gog gmail search q\n${stderr}`, stderr }),
+    };
+  }
+  const probeBody = (body: unknown, status = 200) => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  });
+
+  /** A `fetch` that answers `/run` and `/health/google` separately. */
+  function routedFetch(run: () => unknown, probe: () => unknown) {
+    return vi.fn(async (url: string) => {
+      if (url.endsWith('/run')) return run();
+      if (url.endsWith('/health/google')) return probe();
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+  }
+  const urls = (f: { mock: { calls: unknown[][] } }) => f.mock.calls.map((c) => c[0] as string);
+  const runCalls = (f: { mock: { calls: unknown[][] } }) =>
+    urls(f).filter((u) => u.endsWith('/run')).length;
+  const probeCalls = (f: { mock: { calls: unknown[][] } }) =>
+    urls(f).filter((u) => u.endsWith('/health/google')).length;
+
+  function captureLog() {
+    const emitted: Array<{ method: 'warn' | 'error'; line: string }> = [];
+    const toStdout: string[] = [];
+    for (const method of ['warn', 'error'] as const) {
+      vi.spyOn(console, method).mockImplementation((...args: unknown[]) => {
+        emitted.push({ method, line: args.map(String).join(' ') });
+      });
+    }
+    for (const method of ['log', 'info', 'debug', 'trace'] as const) {
+      vi.spyOn(console, method).mockImplementation((...args: unknown[]) => {
+        toStdout.push(args.map(String).join(' '));
+      });
+    }
+    return {
+      emitted,
+      toStdout,
+      records(): Record<string, unknown>[] {
+        return emitted.map((e) => {
+          expect(e.line.startsWith(PREFIX)).toBe(true);
+          return JSON.parse(e.line.slice(PREFIX.length)) as Record<string, unknown>;
+        });
+      },
+      byEvent(event: string): Record<string, unknown> | undefined {
+        return this.records().find((r) => r.event === event);
+      },
+    };
+  }
+
+  it('asks the runner whether Google still accepts the credential, with the same bearer', async () => {
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [{ email: 'a@b.c', valid: true }] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const exec = makeFlyExecutor(ENDPOINT, KEY);
+    // The caller's error is untouched — this is instrumentation, not recovery.
+    await expect(exec(READ, {})).rejects.toThrow(/Google API error \(401/);
+
+    expect(runCalls(fetchMock)).toBe(1);
+    expect(probeCalls(fetchMock)).toBe(1);
+    const [, init] = fetchMock.mock.calls[1] as [string, RequestInit];
+    expect(init.headers).toEqual({ Authorization: `Bearer ${KEY}` });
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('records an UNEXPLAINED refusal when Google says the credential is fine', async () => {
+    // The narrow theory the plan refused to build a fix for: a stored token
+    // refused by Google while the grant behind it is alive. This record is the
+    // only thing that can ever prove or kill it, so it is emitted at error
+    // level — "we cannot explain this" is the loudest thing a log can say.
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [{ email: 'a@b.c', valid: true }] }),
+    ));
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+
+    const record = log.byEvent('refusal.google-ok');
+    expect(record).toBeDefined();
+    expect(record!.service).toBe('gmail');
+    expect(record!.endpoint).toBe(ENDPOINT);
+    expect(log.emitted.find((e) => e.line.includes('refusal.google-ok'))!.method).toBe('error');
+    // Still followed by the decision record, so the pair reads: what Google
+    // said, then what we did about it.
+    expect(log.byEvent('replay.declined')).toBeDefined();
+    expect(log.toStdout).toEqual([]);
+  });
+
+  it('records a dead credential, carrying the runner’s classification and not gog’s words', async () => {
+    const log = captureLog();
+    const cause =
+      'invalid_grant: the stored Google refresh token is expired or revoked — re-authorize the account';
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: false, measured: true, accounts: [], error: cause }),
+    ));
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+
+    const record = log.byEvent('refusal.google-unhealthy');
+    expect(record).toBeDefined();
+    expect(record!.reason).toBe(cause);
+    expect(log.emitted.find((e) => e.line.includes('refusal.google-unhealthy'))!.method).toBe('error');
+  });
+
+  it('reports an unhealthy layer even when the runner names no cause', async () => {
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: false, measured: true, accounts: [] }),
+    ));
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+    expect(log.byEvent('refusal.google-unhealthy')!.reason).toMatch(/no cause/);
+  });
+
+  it('REVIEW DEFECT: a probe that could not RUN never becomes "the credential is refused"', async () => {
+    // This is the record that decides an incident: `refusal.google-unhealthy`
+    // means "Google refused the call AND the live check agrees the credential is
+    // refused". Three of the runner's causes are facts about the probe — it
+    // timed out, it could not be run at all (no `gog` on PATH, no
+    // `credentials.json` on the volume), its output could not be parsed — and
+    // filing those here would tell an operator the refresh token was dead on
+    // evidence nobody gathered. Worse, it silently disables `refusal.google-ok`,
+    // the ONE record that can prove or kill the narrow theory.
+    for (const error of [
+      'the Google probe timed out before gog answered',
+      'the Google probe could not be run',
+      'gog auth list --check returned unrecognized output',
+      'gog did not report token validity',
+      'gog reported an account it explicitly did not check',
+    ]) {
+      const log = captureLog();
+      vi.stubGlobal('fetch', routedFetch(
+        () => gogFailed(GOOGLE_401_STDERR),
+        () => probeBody({ ok: false, measured: false, accounts: [], error }),
+      ));
+
+      // The caller's error is untouched, as always.
+      await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/Google API error \(401/);
+
+      expect(log.byEvent('refusal.google-unhealthy')).toBeUndefined();
+      const record = log.byEvent('refusal.google-unmeasured');
+      expect(record).toBeDefined();
+      expect(record!.reason).toBe(error);
+      expect(log.emitted.find((e) => e.line.includes('refusal.google-unmeasured'))!.method).toBe('warn');
+      vi.restoreAllMocks();
+    }
+  });
+
+  it('will not claim the credential is refused from a runner that never said it measured', async () => {
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: false, accounts: [], error: 'something went wrong' }),
+    ));
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+
+    expect(log.byEvent('refusal.google-unhealthy')).toBeUndefined();
+    expect(log.byEvent('refusal.google-unmeasured')!.reason).toContain('something went wrong');
+  });
+
+  it('never turns a probe that could not run into a claim about Google', async () => {
+    // A runner deployed before /health/google existed answers 404. "I could not
+    // ask" must never be filed as "Google said no" — that is the defect this
+    // whole branch exists to delete, with the alarm merely inverted.
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ error: 'not found' }, 404),
+    ));
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+
+    const record = log.byEvent('refusal.google-unmeasured');
+    expect(record).toBeDefined();
+    expect(record!.reason).toMatch(/404/);
+    // NOT an error: the absence of a measurement is not evidence of anything.
+    expect(log.emitted.find((e) => e.line.includes('refusal.google-unmeasured'))!.method).toBe('warn');
+    expect(log.byEvent('refusal.google-unhealthy')).toBeUndefined();
+  });
+
+  it('survives a probe that rejects, and still lets the original error through', async () => {
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => { throw new Error('network down'); },
+    ));
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/Google API error \(401/);
+    expect(log.byEvent('refusal.google-unmeasured')!.reason).toMatch(/network down/);
+  });
+
+  it('survives a probe that rejects with a non-Error', async () => {
+    const log = captureLog();
+    vi.stubGlobal('fetch', routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => { throw 'nope'; },
+    ));
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+    expect(log.byEvent('refusal.google-unmeasured')!.reason).toBe('nope');
+  });
+
+  it('does not ask a question gog already answered: invalid_grant is not probed', async () => {
+    // gog said the grant is dead. Spending a Google API call to be told the same
+    // thing buys nothing, and this is the COMMON failure — the 7-day cliff — so
+    // probing it would be the one case that costs the most and learns the least.
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(`${GOOGLE_401_STDERR}\noauth2: "invalid_grant"`),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/invalid_grant/);
+    expect(probeCalls(fetchMock)).toBe(0);
+    expect(log.byEvent('grant.dead')).toBeDefined();
+  });
+
+  it('MUST NOT REGRESS: a runner transport failure is never probed for Google health', async () => {
+    // The runner's own 401 is about OUR bearer. gog never ran and no Google
+    // credential was read, so asking Google anything here would re-create the
+    // exact misattribution 2.21.1 fixed — one layer down, in the log.
+    const fetchMock = routedFetch(
+      () => ({ ok: false, status: 401, json: async () => ({ error: 'unauthorized' }) }),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    captureLog();
+
+    const err = await makeFlyExecutor(ENDPOINT, KEY)(READ, {}).catch((e: unknown) => e);
+    expect(isRunnerTransportError(err)).toBe(true);
+    expect(probeCalls(fetchMock)).toBe(0);
+  });
+
+  it('MUST NOT REGRESS: an ordinary gog failure is never probed', async () => {
+    const fetchMock = routedFetch(
+      () => gogFailed('row 401 is outside the sheet grid'),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    captureLog();
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/outside the sheet grid/);
+    expect(probeCalls(fetchMock)).toBe(0);
+  });
+
+  it('does not probe when the call carried a token of ours — that path repairs itself', async () => {
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    captureLog();
+    const readToken = Object.assign(vi.fn(async () => 'ya29.stale'), {
+      invalidate: vi.fn(async () => true),
+    });
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY, readToken)(READ, {})).rejects.toThrow(/401/);
+    // Two /run attempts (the replay), and no probe: the eviction already
+    // answered the question the probe would ask.
+    expect(runCalls(fetchMock)).toBe(2);
+    expect(probeCalls(fetchMock)).toBe(0);
+  });
+
+  it('will not spend the caller’s remaining deadline on a diagnostic', async () => {
+    // The probe shares the tool call's ONE deadline. Below the floor it could
+    // only abort, and an abort here would delay the caller's real error for
+    // nothing.
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    // opts.timeout 0 leaves only DEADLINE_GRACE_MS. The clock is read once to
+    // fix the deadline and once by the probe; making the second read land a
+    // minute later is exactly "the first attempt ran long".
+    const start = Date.now();
+    let reads = 0;
+    vi.spyOn(Date, 'now').mockImplementation(() => (reads++ === 0 ? start : start + 60_000));
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, { timeout: 0 })).rejects.toThrow(/401/);
+
+    expect(probeCalls(fetchMock)).toBe(0);
+    expect(log.byEvent('refusal.google-unmeasured')!.reason).toMatch(/deadline/);
+  });
+
+  it('probes at most once per interval, so a retry loop cannot storm the backend', async () => {
+    // /health/google spawns a real gog and takes the keyring's exclusive flock
+    // (gogcli v0.34.1: auth list → ListTokens → withWriteLock → unix.LOCK_EX;
+    // see the sourced note on PROBE_INTERVAL_MS). A model retrying a dead call
+    // must not turn one diagnostic into a queue.
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const exec = makeFlyExecutor(ENDPOINT, KEY);
+    await expect(exec(READ, {})).rejects.toThrow(/401/);
+    await expect(exec(READ, {})).rejects.toThrow(/401/);
+
+    expect(runCalls(fetchMock)).toBe(2);
+    expect(probeCalls(fetchMock)).toBe(1);
+    expect(log.byEvent('refusal.google-unmeasured')!.reason).toMatch(/attempted recently/);
+  });
+
+  // End to end through the REAL run() and the REAL diagnose(), because the claim
+  // that matters most about this whole feature is a NEGATIVE one: the caller's
+  // result is byte-identical whether the probe ran or not. This also re-pins the
+  // #250 shape — `Google API error (401 authError)` still reaching the auth
+  // hint — with the probe in the loop.
+  it('MUST NOT REGRESS: the caller’s diagnosed result is identical with the probe in the loop', async () => {
+    captureLog();
+    const withProbe = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', withProbe);
+    const probed = await runExecutor.run({ executor: makeFlyExecutor(ENDPOINT, KEY) }, () =>
+      runOrDiagnose(['gmail', 'search', 'q'], {}),
+    );
+
+    // The same failure through an executor whose probe is skipped outright
+    // (gog said invalid_grant is a different error, so use the throttle: a
+    // second call on the same executor never probes).
+    const exec = makeFlyExecutor(ENDPOINT, KEY);
+    const twice = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', twice);
+    await runExecutor.run({ executor: exec }, () => runOrDiagnose(['gmail', 'search', 'q'], {}));
+    const unprobed = await runExecutor.run({ executor: exec }, () =>
+      runOrDiagnose(['gmail', 'search', 'q'], {}),
+    );
+
+    expect(probed.isError).toBe(true);
+    expect(probed.content[0].text).toContain('Google API error (401 authError)');
+    expect(probed.content[0].text).toContain('gog_auth_add');
+    // The whole point: the probe is invisible to the caller.
+    expect(unprobed.content[0].text).toBe(probed.content[0].text);
+  });
+
+  it('MUST NOT CLAIM: the throttle line never asserts a measurement that did not happen', async () => {
+    // The whole thesis of this branch is that a log line may not claim health it
+    // did not measure. The throttle is the one place that rule can be broken
+    // from the inside: `lastProbeAt` is stamped BEFORE the fetch and is not
+    // reset when the probe comes back with no verdict, so every refusal for the
+    // next PROBE_INTERVAL_MS is explained by a sentence about the previous
+    // probe. If that sentence says the layer "was measured", it is describing a
+    // measurement that never occurred — here, a runner too old to have
+    // /health/google at all.
+    //
+    // Stamping before the await is correct and stays: it is what stops two
+    // overlapping refusals from both spawning a probe, and the backend cost the
+    // throttle protects was paid whether or not a verdict came back. So the
+    // sentence is what has to be true, not the timestamp.
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ error: 'not found' }, 404),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const exec = makeFlyExecutor(ENDPOINT, KEY);
+    await expect(exec(READ, {})).rejects.toThrow(/401/);
+    await expect(exec(READ, {})).rejects.toThrow(/401/);
+
+    // One probe attempted, and it produced no verdict about Google.
+    expect(probeCalls(fetchMock)).toBe(1);
+    const unmeasured = log
+      .records()
+      .filter((r) => r.event === 'refusal.google-unmeasured')
+      .map((r) => r.reason as string);
+    expect(unmeasured).toHaveLength(2);
+    expect(unmeasured[0]).toMatch(/did not answer the Google probe \(HTTP 404\)/);
+
+    // The throttled line: it must say a probe was ATTEMPTED, never that the
+    // Google layer was measured.
+    expect(unmeasured[1]).toMatch(/attempted recently/);
+    expect(unmeasured[1]).not.toMatch(/measured recently|was measured|re-measured/);
+  });
+
+  it('throttles per executor, so one session cannot silence another', async () => {
+    const log = captureLog();
+    const fetchMock = routedFetch(
+      () => gogFailed(GOOGLE_401_STDERR),
+      () => probeBody({ ok: true, measured: true, accounts: [] }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+    await expect(makeFlyExecutor(ENDPOINT, KEY)(READ, {})).rejects.toThrow(/401/);
+
+    expect(probeCalls(fetchMock)).toBe(2);
+    expect(log.byEvent('refusal.google-unmeasured')).toBeUndefined();
+  });
+});

package/tests/google-probe.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { readGoogleProbe } from '../src/google-probe.js';
+
+/**
+ * REVIEW DEFECT: "the probe could not run" was filed as "Google refused".
+ *
+ * The runner collapses every non-healthy outcome into `ok:false`, and BOTH
+ * connector call sites used to branch on `ok === true` alone. Three of the
+ * runner's causes are facts about the probe, not about Google — it timed out, it
+ * could not be run (`gog` missing from PATH, `credentials.json` missing from the
+ * volume), or its output could not be parsed — and each of those became an
+ * error-level `connect.google-unhealthy` / `refusal.google-unhealthy`, whose
+ * documented meaning is "Google was asked and refused". An operator grepping
+ * event names would close the incident on evidence nobody gathered.
+ *
+ * The runner now states `measured` explicitly. This module is the ONE place that
+ * reads it, precisely because the defect was two call sites making the same
+ * judgement separately.
+ */
+describe('readGoogleProbe', () => {
+  it('reads a healthy answer as ok', () => {
+    expect(readGoogleProbe({ ok: true, measured: true })).toEqual({ kind: 'ok' });
+  });
+
+  it('reads a measured refusal as unhealthy, carrying the runner’s cause', () => {
+    expect(readGoogleProbe({ ok: false, measured: true, error: 'invalid_grant: …' })).toEqual({
+      kind: 'unhealthy',
+      reason: 'invalid_grant: …',
+    });
+  });
+
+  it('says so plainly when a measured refusal names no cause', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: true });
+    expect(verdict.kind).toBe('unhealthy');
+    expect(verdict.reason).toMatch(/no cause/i);
+  });
+
+  it('reads measured:false as UNMEASURED however loudly the cause reads', () => {
+    // The regression under test. Every one of these used to be `unhealthy`.
+    for (const error of [
+      'the Google probe timed out before gog answered',
+      'the Google probe could not be run',
+      'gog auth list --check returned unrecognized output',
+      'gog did not report token validity',
+      'gog reported an account it explicitly did not check',
+    ]) {
+      expect(readGoogleProbe({ ok: false, measured: false, error })).toEqual({
+        kind: 'unmeasured',
+        reason: error,
+      });
+    }
+  });
+
+  it('refuses to claim HEALTH from a runner that never said it measured', () => {
+    // The row this table was missing, and the last place `ok` outranked
+    // `measured`. A bare `ok:true` used to return {kind:'ok'}, which on the
+    // refusal path is `refusal.google-ok` — the record documented as "the one
+    // record that means we cannot explain this", logged at error level, and
+    // held up as the only evidence that could justify automatic recovery on the
+    // hosted path. Raising it from a measurement nobody took is this branch's
+    // founding defect surviving in the module written to delete it. `ok:true`
+    // is not self-licensing: it is a health claim, and a health claim needs a
+    // measurement behind it — exactly what the runner's README asserts when it
+    // says `ok:true` always travels with `measured:true`.
+    const verdict = readGoogleProbe({ ok: true });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toMatch(/did not report whether/i);
+  });
+
+  it('carries the runner’s cause when a bare ok:true also names one', () => {
+    const verdict = readGoogleProbe({ ok: true, error: 'something went wrong' });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toContain('something went wrong');
+  });
+
+  it('never claims health from an incoherent ok:true + measured:false', () => {
+    // `measured` is read FIRST, so the field that can only under-claim wins.
+    const verdict = readGoogleProbe({ ok: true, measured: false });
+    expect(verdict.kind).toBe('unmeasured');
+  });
+
+  it('describes an unmeasured answer that names no cause', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: false });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toMatch(/could not measure/i);
+  });
+
+  it('refuses to claim ill health from a runner that never said it measured', () => {
+    // Silence is not a measurement. An `ok:false` with no `measured` field is
+    // read as unmeasured — under-claiming, the only safe direction.
+    const verdict = readGoogleProbe({ ok: false, error: 'something went wrong' });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toContain('something went wrong');
+    expect(verdict.reason).toMatch(/did not report whether/i);
+  });
+
+  it('reads a body with no fields at all, and a null body, as unmeasured', () => {
+    expect(readGoogleProbe({}).kind).toBe('unmeasured');
+    expect(readGoogleProbe(null).kind).toBe('unmeasured');
+    expect(readGoogleProbe(undefined).kind).toBe('unmeasured');
+    expect(readGoogleProbe('a proxy error page').kind).toBe('unmeasured');
+  });
+
+  it('ignores non-boolean field types rather than trusting them', () => {
+    // JSON from a proxy, or a future runner, may put anything here.
+    expect(readGoogleProbe({ ok: 'true', measured: 'true' }).kind).toBe('unmeasured');
+    expect(readGoogleProbe({ ok: 1, measured: 1 }).kind).toBe('unmeasured');
+  });
+
+  it('never carries a non-string cause into a log line', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: true, error: { nested: 'object' } });
+    expect(verdict.kind).toBe('unhealthy');
+    expect(typeof verdict.reason).toBe('string');
+    expect(verdict.reason).toMatch(/no cause/i);
+  });
+});

package/tests/timestamps.test.ts

@@ -316,3 +316,55 @@ describe('normalizeTimestamps', () => {
     expect(out.date).toMatch(/[+-]\d{2}:\d{2}$/);
   });
 });
+
+// gog 0.35.0 (#946) adds `internalDateIso` to Gmail message AND thread
+// listings: Gmail's own internalDate rendered RFC3339 with a real offset. It is
+// separately sourced from the neighbouring `date` (a naive reconstruction of
+// the sender's Date header), so the two can legitimately disagree — but only
+// `internalDateIso` carries its own zone, which makes it the field a machine
+// consumer should read.
+describe('internalDateIso (gog >= 0.35.0 Gmail listings)', () => {
+  it('gains a display sibling and survives a DISPLAY_TZ unlike its own offset', () => {
+    const payload = JSON.stringify({
+      messages: [{ id: 'm1', date: '2026-07-28 03:36', internalDateIso: '2026-07-28T03:36:12-04:00' }],
+    });
+    const pt = JSON.parse(normalizeTimestamps(payload, 'America/Los_Angeles', 'UTC'));
+    const row = pt.messages[0];
+    // Re-rendered in the display zone, same instant, offset still explicit.
+    expect(row.internalDateIso).toBe('2026-07-28T00:36:12-07:00');
+    expect(Date.parse(row.internalDateIso)).toBe(Date.parse('2026-07-28T03:36:12-04:00'));
+    expect(row.internalDateIsoDisplay).toContain('Tue, Jul 28');
+    expect(isNaiveTimestamp(row.internalDateIso)).toBe(false);
+  });
+
+  it('keeps sub-second precision when gog emits milliseconds', () => {
+    const out = JSON.parse(normalizeTimestamps(
+      JSON.stringify({ internalDateIso: '2026-07-28T03:36:12.250-04:00' }), ET,
+    ));
+    expect(out.internalDateIso).toBe('2026-07-28T03:36:12.250-04:00');
+    expect(out.internalDateIsoDisplay).toContain('Tue, Jul 28');
+  });
+
+  // The trap: `date` is gog re-formatting the sender header into GOG_TIMEZONE
+  // with no offset, so the wrapper has to re-read it in that zone. Only
+  // `internalDateIso` is self-describing, and the two are allowed to disagree.
+  it('is trusted verbatim while the naive sibling is read in GOG_TIMEZONE', () => {
+    const out = JSON.parse(normalizeTimestamps(JSON.stringify({
+      date: '2026-07-28 03:36',
+      internalDateIso: '2026-07-27T23:36:12-04:00',
+    }), ET, 'UTC'));
+    expect(out.internalDateIso).toBe('2026-07-27T23:36:12-04:00');
+    expect(out.date).toBe('2026-07-27T23:36:00-04:00');
+    expect(out.dateDisplay).toContain('Jul 27');
+    expect(out.internalDateIsoDisplay).toContain('Jul 27');
+  });
+
+  // A thread listing carries the same field (gmail_thread_search_helpers.go).
+  it('normalizes the field on thread listings too', () => {
+    const out = JSON.parse(normalizeTimestamps(
+      JSON.stringify({ threads: [{ id: 't1', internalDateIso: '2026-07-28T03:36:12Z' }] }), ET,
+    ));
+    expect(out.threads[0].internalDateIso).toBe('2026-07-27T23:36:12-04:00');
+    expect(out.threads[0].internalDateIsoDisplay).toContain('Mon, Jul 27');
+  });
+});

package/tests/tools/auth.test.ts

@@ -69,6 +69,20 @@ describe('gog_auth_status', () => {
     const result = await harness.callTool('gog_auth_status', {});
     expect(result.content[0].text).toBe('Error: Status failed');
   });
+
+  it('does not present itself as a health check', async () => {
+    // `gog auth status` prints the keyring backend and where the credential
+    // files live. It contacts nothing. Named "status" next to a connector whose
+    // UI says "connected", it reads as the answer to "is my auth OK?" — which is
+    // the question only gog_auth_health can answer.
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const desc = tools.find((t) => t.name === 'gog_auth_status')!.description!;
+
+    expect(desc).toMatch(/does not contact Google/i);
+    expect(desc).toContain('gog_auth_health');
+    await harness.close();
+  });
 });
 
 describe('gog_auth_services', () => {
@@ -127,6 +141,20 @@ describe('gog_auth_add', () => {
 });
 
 describe('gog_auth_health', () => {
+  it('names itself as the only live measurement of the Google layer', async () => {
+    // DEFECT 1's wording half: the hosted connector's "connected" / "refreshed"
+    // is an OAuth refresh inside OAUTH_KV that contacts neither Fly nor Google.
+    // Nothing in this repo can change that word, so the tool that DOES measure
+    // has to say that it is the one that does.
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const desc = tools.find((t) => t.name === 'gog_auth_health')!.description!;
+
+    expect(desc).toMatch(/connected|refreshed/i);
+    expect(desc).toMatch(/only|nothing else/i);
+    await harness.close();
+  });
+
   const CHECK_JSON = JSON.stringify({
     accounts: [
       { email: 'chris.c.hall@gmail.com', created_at: '2026-07-17T15:08:39Z', valid: true },