clauderipple 0.9.1 → 0.9.2

package/dist/mod/tests/register.test.tsx

@@ -918,6 +918,42 @@ test('keep-warm forks near expiry, refreshes the memo and stops once on a null f
   expect(stats.text).toContain('Warm: 1 pings')
 })
 
+test('a cache-reading ping keeps the card, a real reply and /clear drop it, and the demo draws it', async ($, on) => {
+  const b = boundaries(on, { keepWarm: true })
+  http(on)
+  judgeStub(on)
+  stepStub(on)
+  on('model.fork', () => ({ value: { isAnswered: true, text: 'ok', usage: USAGE } }))
+  await start($)
+  await step($)
+  await complete($)
+  await b.clock.advance(3375000)
+  // The ping read 40000 cache tokens: the card tells it, with the memo's minutes left.
+  const ui = await band($)
+  expect(await ui.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeDefined()
+  await ui.unmount()
+  // A prompt counts as having seen the card; the next is a real reply, which clears the count.
+  await submit($)
+  await step($)
+  await complete($)
+  const after = await band($)
+  expect(await after.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeUndefined()
+  await after.unmount()
+  await b.clock.advance(3375000)
+  await b.clock.settle()
+  const again = await band($)
+  expect(await again.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeDefined()
+  await again.unmount()
+  await $.classic.SessionStart({ source: 'clear' })
+  const cleared = await band($)
+  expect(await cleared.find({ type: 'Text', text: /held 40k tokens in cache/ })).toBeUndefined()
+  await cleared.unmount()
+  // The demo shows the card with sample values, whatever the state.
+  await command($, 'kept')
+  const demo = await band($)
+  expect(await demo.find({ type: 'Text', text: /held 312k tokens in cache/ })).toBeDefined()
+})
+
 test('fork turn.step is not effort-steered, busy or main-request cost', async ($, on) => {
   const b = boundaries(on, { keepWarm: true })
   http(on)
@@ -941,6 +977,23 @@ test('fork turn.step is not effort-steered, busy or main-request cost', async ($
   expect(stats.text).toContain('Warm: 1 pings')
 })
 
+test('the flame turns keep-warm off for this chat only; Settings stay as they are', async ($, on) => {
+  const b = boundaries(on, { keepWarm: true })
+  http(on)
+  judgeStub(on, '{"effort":"high","why":"scope"}')
+  stepStub(on)
+  let forks = 0
+  on('model.fork', async () => { forks++; return { value: { isAnswered: true, text: 'ok', usage: USAGE } } })
+  await start($)
+  await submit($)
+  await step($)
+  await complete($)
+  await $.command.run({ command: 'ripple', origin: { kind: 'composer' }, presentation: { isFullscreen: true, columns: 140 }, args: 'warm' })
+  await b.clock.advance(3375000)
+  expect(forks).toBe(0)
+  expect(b.router().settings.keepWarm).toBe(true)
+})
+
 test('Haiku compaction returns replacement messages and forwards the keep note', async ($, on) => {
   boundaries(on)
   http(on)

package/dist/mod/tests/ui.test.tsx

@@ -265,6 +265,7 @@ test('a ko frame resolves temporary Korean text in labels and hover cards', asyn
 
 const ALERTS: AlertView[] = [
   { kind: 'cold', tokens: 182_000, idleMinutes: 74 },
+  { kind: 'kept', pings: 2, tokens: 312_000, minutesLeft: 47 },
   { kind: 'swamp', percent: 63, tokens: 126_000 },
   { kind: 'hot', limitKind: 'five_hour', percent: 86, resetsAt: '2026-10-10T15:40:00', save: false },
   { kind: 'judgeDown', judge: 'jev', reason: 'key rejected (401)' },
@@ -297,14 +298,17 @@ test('alert choices reach their callbacks', async ($, on) => {
     setHandoffKind: fn('kind'), setHandoffAfter: fn('after'), go: fn('go'), copy: fn('copy'), openNew: fn('open-new'),
   }
   drawPane(on, 'cold', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[0]!, actions))
-  drawPane(on, 'hot', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[2]!, actions))
+  drawPane(on, 'kept', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[1]!, actions))
+  drawPane(on, 'hot', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[3]!, actions))
   drawPane(on, 'note', (el, surface) => renderAlert(el, frameOf(surface), { kind: 'compactNote', draft: '' }, actions))
-  drawPane(on, 'choice', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[10]!, actions))
+  drawPane(on, 'choice', (el, surface) => renderAlert(el, frameOf(surface), ALERTS[11]!, actions))
   for (const surface of SURFACES) {
     const cold = await mount($, 'cold', surface)
     await cold.press({ key: 'compact' })
     await cold.press({ key: 'handoff' })
     await cold.press({ key: 'dismiss' })
+    const kept = await mount($, 'kept', surface)
+    await kept.press({ key: 'dismiss' })
     const hot = await mount($, 'hot', surface)
     await hot.press({ key: 'save' })
     const note = await mount($, 'note', surface)
@@ -314,7 +318,7 @@ test('alert choices reach their callbacks', async ($, on) => {
     await choice.press({ key: 'after-copy' })
     await choice.press({ key: 'go' })
   }
-  const once = ['compact', 'handoff', 'dismiss', 'save', 'compact:["keep the API decision"]', 'kind:["full"]', 'after:["copy"]', 'go']
+  const once = ['compact', 'handoff', 'dismiss', 'dismiss', 'save', 'compact:["keep the API decision"]', 'kind:["full"]', 'after:["copy"]', 'go']
   expect(calls).toEqual([...once, ...once])
 })
 
@@ -354,9 +358,9 @@ test('each alert shows 리플이 with the face of its state, its gauge in 5% ste
     expect(mascots(await terminal.drawn()).length).toBe(0)
     await terminal.unmount()
   }
-  // handoffDone and compacted share the pleased face, compactNote and handoffChoice the asking
-  // one; every other state has its own.
-  expect(new Set(sources).size).toBe(ALERTS.length - 2)
+  // handoffDone, compacted and kept share the pleased face, compactNote and handoffChoice the
+  // asking one; every other state has its own.
+  expect(new Set(sources).size).toBe(ALERTS.length - 3)
   const source = async (id: string) => {
     const ui = await mount($, id, 'desktop')
     const s = String(mascots(await ui.drawn())[0]?.props?.source)

package/dist/mod/types/index.d.ts

@@ -301,12 +301,15 @@ declare module 'claude-code' {
       agents: AgentRec[]
       cache: CacheMemo | null
       warm: WarmState
+      /** Keep-warm for this chat alone, set by the band's flame; null follows Settings. */
+      warmHere: boolean | null
       context: { percent: number; tokens: number; window: number } | null
       hot: Hot | null
       hotHidden: number | null
       saveUntil: number | null
       swampHidden: number | null
       coldHidden: boolean
+      kept: { pings: number; tokens: number } | null
       judgeDown: string | null
       advice: string | null
       handoff: { stage: HandoffStage; kind: HandoffKind; text?: string } | null
@@ -345,7 +348,7 @@ declare module 'claude-code' {
       judgeRuns: JudgeRun[]
       judgeDownNetwork: boolean
       limit: Hot | null
-      demo: 'cold' | 'swamp' | 'hot' | 'down' | null
+      demo: 'cold' | 'swamp' | 'hot' | 'down' | 'kept' | null
     }
   }
 }

package/dist/router/src/admin.js

@@ -23,7 +23,7 @@ import path from "node:path";
 import http from "node:http";
 import { execFile, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { adminPort, homeDir, searchProviderFor, validate } from "./config.js";
+import { adminPort, headerValueProblem, homeDir, searchProviderFor, validate } from "./config.js";
 export { adminPort } from "./config.js";
 import { generatedAgents } from "./agents.js";
 import { isJudgeOnlyModel } from "./model-policy.js";
@@ -33,6 +33,7 @@ import { normalizeSettings } from "../../mod/hooks/settings.js";
 import { chatPickerModels } from "./picker.js";
 import { PRESETS } from "./presets.js";
 import { resolveCompatibleCaps } from "./compat.js";
+import { redactErrorText } from "./redact.js";
 import { CHATGPT_FALLBACK_MODELS } from "./providers/chatgpt/catalog.js";
 import { measureModel, refusedByPlan } from "./capabilities.js";
 import { catalogEntry } from "./catalog.js";
@@ -53,6 +54,9 @@ import { exhaustedForMs, IMAGE_ASPECTS, IMAGE_BACKGROUNDS, IMAGE_FORMATS } from
 import { ANTIGRAVITY_WARNING, staticAntigravityModels } from "./providers/google/antigravity.js";
 import { readGoogleAccounts, removeGoogleAccount, summarize as summarizeGoogleAccount, updateGoogleAccount } from "./providers/google/accounts.js";
 import { GoogleOAuthSession } from "./providers/google/login.js";
+import { GROK_AUTH_HINT, grokAuthPath, grokHome, readGrokToken, sharedGrokAuth } from "./providers/grok/auth.js";
+import { GROK_DEFAULT_URL, GROK_EFFORT_LEVELS, GROK_FALLBACK_MODELS, grokModelsFromListing } from "./providers/grok/catalog.js";
+import { GROK_WARNING, grokHeaders } from "./providers/grok/index.js";
 const MAX_BODY = 1024 * 1024;
 /** `/api/image` carries reference images inline, so it gets more room than a config save. */
 const MAX_IMAGE_BODY = 32 * 1024 * 1024;
@@ -157,6 +161,12 @@ export function effortLevels(cfg) {
             providers[name] = { default: ANTHROPIC_EFFORT_LEVELS };
             continue;
         }
+        if (provider.type === "grok") {
+            // The proxy's listing gives each model its ladder (the probe saves it); a model it has not
+            // described gets the common one, which is also what the adapter sends it.
+            providers[name] = { default: [...GROK_EFFORT_LEVELS], ...(Object.keys(modelLevels).length ? { models: modelLevels } : {}) };
+            continue;
+        }
         const preset = provider.preset ? PRESETS.find((entry) => entry.id === provider.preset) : undefined;
         providers[name] = {
             default: resolveCompatibleCaps(preset ? { effortLevels: preset.effortLevels, thinking: preset.thinking, ...(preset.serverTools ? { serverTools: true } : {}) } : undefined, provider.caps).effortLevels,
@@ -282,6 +292,14 @@ export function chatgptSignedIn(mode) {
     const borrowed = fs.existsSync(path.join(os.homedir(), ".codex", "auth.json"));
     return mode === "own" ? own : mode === "borrow-codex" ? borrowed : own || borrowed;
 }
+/**
+ * Whether the Grok CLI's session is there and not yet expired. A session near its end still counts:
+ * the router asks the CLI to refresh it before the next turn.
+ */
+export function grokSignedIn(p) {
+    const token = readGrokToken(grokAuthPath(p.home ?? grokHome()));
+    return token !== null && (token.expiresAt === 0 || token.expiresAt > Date.now());
+}
 /**
  * An Antigravity provider is only as usable as its accounts: none signed in, or every one waiting on
  * Google's verification page, answers nothing however reachable the host is.
@@ -409,7 +427,7 @@ async function buildStatus(deps, opts = {}) {
     // Keyed in the order the config lists them. Assigning inside the Promise.all callbacks ordered
     // them by whichever TCP check answered first, so the Health list reshuffled on every poll.
     const checked = await Promise.all(Object.entries(cfg.providers).map(async ([name, p]) => {
-        const url = p.type === "anthropic" ? "https://api.anthropic.com" : p.type === "chatgpt" ? (p.url ?? "https://chatgpt.com/backend-api") : p.type === "google" ? (p.url ?? "https://generativelanguage.googleapis.com") : p.url;
+        const url = p.type === "anthropic" ? "https://api.anthropic.com" : p.type === "chatgpt" ? (p.url ?? "https://chatgpt.com/backend-api") : p.type === "google" ? (p.url ?? "https://generativelanguage.googleapis.com") : p.type === "grok" ? (p.url ?? GROK_DEFAULT_URL) : p.url;
         let reachable = false;
         try {
             const u = new URL(url);
@@ -444,6 +462,7 @@ async function buildStatus(deps, opts = {}) {
                 // Reaching the host says nothing about being able to use it: a chatgpt provider with no
                 // credentials is not "connected", and calling it that sends the user off believing it works.
                 ...(p.type === "chatgpt" ? { needsLogin: !chatgptSignedIn(p.auth) } : {}),
+                ...(p.type === "grok" ? { needsLogin: !grokSignedIn(p) } : {}),
                 ...(p.type === "google" && p.auth === "antigravity" ? googleHealth(deps.google?.().accounts?.()[name] ?? []) : {}),
                 ...(p.type === "anthropic"
                     ? {
@@ -843,6 +862,53 @@ async function probeGoogleAntigravity(deps) {
     const models = named ? await deps.google?.().models?.(named).catch(() => null) ?? null : null;
     return { ok: true, auth: "ok", models: models ?? staticAntigravityModels() };
 }
+/**
+ * `{type:"grok"}`: whether the Grok CLI's session is usable, and the models its chat proxy lists.
+ * The session goes through the same `GrokAuth` the adapter uses — one near its end is refreshed
+ * through the CLI here too — and the listing is asked with the headers live traffic sends, since a
+ * test that presents another auth set certifies a path nobody uses (§5).
+ */
+async function probeGrok(body, log, probeFetch = fetchWithTimeout) {
+    const text = (value) => typeof value === "string" && value ? value : undefined;
+    const home = text(body.home) ?? grokHome();
+    const cli = text(body.cli);
+    const clientVersion = text(body.clientVersion);
+    const fallback = (result) => ({ ...result, models: GROK_FALLBACK_MODELS, modelsSource: "fallback", warning: GROK_WARNING });
+    const versionProblem = clientVersion ? headerValueProblem(clientVersion) : null;
+    if (versionProblem)
+        return fallback({ ok: false, auth: "unknown", error: `clientVersion cannot be sent as a header: ${versionProblem}` });
+    // The adapter's own instance for this session, so a probe joins a refresh a turn started (and the
+    // reverse) instead of spawning a second CLI.
+    const auth = sharedGrokAuth({ home, ...(cli ? { cli } : {}), log });
+    let token;
+    try {
+        token = await auth.token();
+    }
+    catch (error) {
+        return fallback({ ok: false, auth: "missing", error: errorText(error) });
+    }
+    const base = (text(body.url) ?? GROK_DEFAULT_URL).replace(/\/+$/, "");
+    const { "x-grok-model-override": _route, ...headers } = grokHeaders(token.key, "", await auth.clientVersion(clientVersion));
+    let response;
+    try {
+        response = await probeFetch(`${base}/models`, { headers });
+    }
+    catch (error) {
+        // fetch quotes a header value it refuses, which here is the session token.
+        return fallback({ ok: false, auth: "unreachable", error: redactErrorText(errorText(error), [token.key]) });
+    }
+    if (response.status === 401 || response.status === 403) {
+        return fallback({ ok: false, auth: "bad-key", error: `the proxy refused the Grok session (HTTP ${response.status}): ${GROK_AUTH_HINT}` });
+    }
+    if (!response.ok) {
+        const detail = redactErrorText(await response.text().catch(() => ""), [token.key]);
+        return fallback({ ok: false, auth: "unknown", error: `HTTP ${response.status}${detail ? `: ${detail.slice(0, 300)}` : ""}` });
+    }
+    const models = grokModelsFromListing(await response.json().catch(() => null));
+    return models.length
+        ? { ok: true, auth: "ok", models, modelsSource: "catalog", warning: GROK_WARNING }
+        : fallback({ ok: true, auth: "ok" });
+}
 function chatCompletionsUrl(base) {
     return `${base.replace(/\/+$/, "")}/chat/completions`;
 }
@@ -1532,6 +1598,10 @@ export function startAdmin(deps) {
                     });
                     return;
                 }
+                if (probe.type === "grok") {
+                    sendJson(res, 200, await probeGrok(probe, deps.log, deps.probeFetch));
+                    return;
+                }
                 if (probe.type === "google") {
                     if (probe.auth === "antigravity") {
                         sendJson(res, 200, await probeGoogleAntigravity(deps));

package/dist/router/src/agents.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { adminPort, homeDir } from "./config.js";
 import { declaredBy } from "./routing.js";
 import { isJudgeOnlyModel } from "./model-policy.js";
+import { GROK_EFFORT_LEVELS } from "./providers/grok/catalog.js";
 import { shortName } from "../../cli/src/hooks/agent-title.js";
 /** Where Claude Code's Agent tool reads its worker definitions. */
 export function defaultAgentDir() {
@@ -145,6 +146,9 @@ export function agentNameFor(modelId) {
     return modelId.replace(/[^a-z0-9-]/g, "-");
 }
 function capsEffortLevels(provider) {
+    // A grok provider has no caps: its adapter sends the common ladder to a model the listing left out.
+    if (provider.type === "grok")
+        return [...GROK_EFFORT_LEVELS];
     return provider.caps?.effortLevels;
 }
 /**

package/dist/router/src/config.js

@@ -153,6 +153,9 @@ export function headerValueProblem(value) {
         // A newline would split the header; a stray one usually means a copied line rather than a key.
         if (code === 0x0a || code === 0x0d)
             return `there is a line break at character ${i + 1} — paste the key on its own, without the line around it`;
+        // fetch refuses a NUL too, so a value that passes here would only fail when sent.
+        if (code === 0x00)
+            return `there is a NUL character at character ${i + 1} — paste the key on its own`;
     }
     return null;
 }
@@ -429,6 +432,27 @@ export function validate(c) {
                 errors.push(`provider ${name}: ${MODELS_SHAPE}`);
             }
         }
+        else if (p.type === "grok") {
+            for (const field of ["home", "cli", "clientVersion"]) {
+                if (p[field] !== undefined && (typeof p[field] !== "string" || !p[field]))
+                    errors.push(`provider ${name}: ${field} must be a non-empty string`);
+            }
+            // Sent as `x-grok-client-version`, so it has to survive being a header value.
+            const versionProblem = typeof p.clientVersion === "string" && p.clientVersion ? headerValueProblem(p.clientVersion) : null;
+            if (versionProblem)
+                errors.push(`provider ${name}: clientVersion cannot be sent as a header: ${versionProblem}`);
+            if (p.url !== undefined && !/^https?:\/\//.test(p.url))
+                errors.push(`provider ${name}: url must start with http:// or https://`);
+            if (p.models !== undefined) {
+                if (!validModels(p.models))
+                    errors.push(`provider ${name}: ${MODELS_SHAPE}`);
+                // `providerFor` turns a model with its own wire, url or auth header into an openai-compatible
+                // provider, which would go out without the session headers this one exists to add.
+                else if (p.models.some((m) => m.wire !== undefined || m.url !== undefined || m.authHeader !== undefined)) {
+                    errors.push(`provider ${name}: a grok model cannot set wire, url or authHeader`);
+                }
+            }
+        }
         else {
             errors.push(`provider ${name}: unknown type "${p.type}"`);
         }

package/dist/router/src/ingress/server.js

@@ -332,8 +332,8 @@ export class OpenAiIngress {
             // is an OpenAI wire, which the refusal below would otherwise turn away on the provider's type
             // alone. One subscription is one provider, so the model decides.
             const provider = providerFor(configured, route.model);
-            if (provider.type === "chatgpt" || provider.type === "openai-compatible" || provider.type === "google") {
-                const label = provider.type === "chatgpt" ? "ChatGPT" : provider.type === "google" ? "Google" : "OpenAI-compatible";
+            if (provider.type === "chatgpt" || provider.type === "openai-compatible" || provider.type === "google" || provider.type === "grok") {
+                const label = provider.type === "chatgpt" ? "ChatGPT" : provider.type === "google" ? "Google" : provider.type === "grok" ? "Grok" : "OpenAI-compatible";
                 const bytes = sendJson(res, 400, openAiError(`${label} provider is not available through OpenAI ingress`, "invalid_request_error", "unsupported_provider"));
                 finish(400, bytes, { note: `model ${requested} -> ${provider.type} provider unsupported` });
                 return;

package/dist/router/src/providers/grok/auth.js

@@ -0,0 +1,289 @@
+// Grok subscription sign-in, borrowed from the Grok CLI. Nothing here signs anyone in.
+//
+//   <grok home>/auth.json   written by `grok login` ($GROK_HOME, else ~/.grok). One entry per issuer,
+//                           keyed `https://auth.x.ai::<id>`; each has `key` (the session token, sent
+//                           as a bearer), `expires_at` (RFC 3339) and a `refresh_token`.
+//
+// Read-only, for the same reason as `borrow-codex`: the CLI refreshes its grant under a lock of its
+// own (`auth lock` in ~/.grok/logs), and if that refresh rotates the refresh token — not measured —
+// refreshing it from here would race the CLI and could sign it out. Measured 2026-10-08 on CLI 1.0.46: a session token lives six hours, and a running
+// CLI refreshes it about five minutes before expiry (`GROK_AUTH_EARLY_INVALIDATION_SECS`, default 300).
+// With no CLI running the file simply goes stale. So when the token is near its end the router asks
+// the CLI to do it: `grok models` with that same variable set to our own threshold makes the CLI see
+// the token as expiring, refresh it under its lock, and write the file — which we then read again.
+// `grok models` was measured to do exactly this (expiry moved six hours, file rewritten).
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** `x-grok-client-version` when the CLI cannot be asked. The proxy refuses a request without one (426). */
+export const GROK_CLIENT_VERSION_FALLBACK = "1.0.46";
+/** What the user can do about a missing or rejected session, appended to the errors they read. */
+export const GROK_AUTH_HINT = "sign in with `grok login`, or run `grok` once so the CLI refreshes its session";
+export function grokHome(env = process.env) {
+    return env.GROK_HOME ? env.GROK_HOME : path.join(os.homedir(), ".grok");
+}
+export function grokAuthPath(home) {
+    return path.join(home, "auth.json");
+}
+/**
+ * The session token in `file`: of the entries carrying one, the one that expires last. The entry key
+ * is the issuer plus an id, and the CLI's own README reads a different key than the one it writes
+ * (`https://accounts.x.ai/sign-in` vs `https://auth.x.ai::…`, 1.0.46), so no key is assumed.
+ */
+export function readGrokToken(file) {
+    let doc;
+    try {
+        doc = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return null;
+    let best = null;
+    for (const value of Object.values(doc)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const entry = value;
+        // A key that cannot be a header value would only fail inside fetch, which quotes it in the error.
+        if (typeof entry.key !== "string" || !entry.key || /[\0\r\n]|[^\0-\xff]/.test(entry.key))
+            continue;
+        const expiresAt = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) || 0 : 0;
+        if (best && expiresAt <= best.expiresAt)
+            continue;
+        best = { key: entry.key, expiresAt, ...(typeof entry.email === "string" ? { email: entry.email } : {}) };
+    }
+    return best;
+}
+function executable(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The `grok` binary. The router runs under launchd with PATH=/usr/bin:/bin:/usr/sbin:/sbin (measured
+ * 2026-10-08), where the CLI never is, so the installer's own location comes before PATH.
+ */
+export function findGrokCli(home, explicit, env = process.env) {
+    if (explicit)
+        return executable(explicit) ? explicit : null;
+    const name = process.platform === "win32" ? "grok.exe" : "grok";
+    const candidates = [
+        path.join(home, "bin", name),
+        ...(env.PATH ?? "").split(path.delimiter).filter(Boolean).map((dir) => path.join(dir, name)),
+        path.join(env.HOME || os.homedir(), ".local", "bin", name),
+    ];
+    return candidates.find(executable) ?? null;
+}
+const runCli = (file, args, env, timeoutMs) => new Promise((resolve, reject) => {
+    execFile(file, args, { env, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        if (error)
+            reject(error);
+        else
+            resolve(String(stdout));
+    });
+});
+export class GrokAuthError extends Error {
+}
+/**
+ * Bounded by the CLI's own: it waits up to 25s for its auth lock (`auth lock: attempting acquire
+ * (timeout=25000ms)`), so a refresh that cannot finish in 30s is not going to.
+ */
+const REFRESH_TIMEOUT_MS = 30_000;
+/**
+ * A rejected token is not ours to keep, so the refresh that follows one treats whatever is there as
+ * expiring. A day is past any session's six hours, and is the value measured to make the CLI refresh.
+ */
+const FORCE_REFRESH_SECS = 24 * 3600;
+/**
+ * A proxy that keeps refusing a freshly minted token is refusing the account, not the token, and
+ * forcing a refresh for every turn would only churn the grant. The CLI's README states the same rule
+ * for its own credential helpers: a token rejected within 30s of being fetched is not fetched again.
+ */
+const FORCED_REFRESH_GAP_MS = 60_000;
+/**
+ * A proactive refresh that ran and still left the token short (the CLI failed, or the IdP is down) is
+ * not run again for every turn in the minutes the token has left: each run can take 30s.
+ */
+const REFRESH_RETRY_GAP_MS = 60_000;
+export class GrokAuth {
+    file;
+    opts;
+    refreshAheadMs;
+    run;
+    now;
+    env;
+    cached;
+    refreshing;
+    lastForcedAt = -Infinity;
+    lastAttemptAt = -Infinity;
+    version;
+    constructor(opts) {
+        this.opts = opts;
+        this.file = grokAuthPath(opts.home);
+        this.refreshAheadMs = opts.refreshAheadMs ?? 10 * 60_000;
+        this.run = opts.run ?? runCli;
+        this.now = opts.now ?? Date.now;
+        this.env = opts.env ?? process.env;
+    }
+    /** The token on disk, read again only when the file changes. One stat per call. */
+    current() {
+        let st;
+        try {
+            st = fs.statSync(this.file);
+        }
+        catch {
+            this.cached = undefined;
+            return null;
+        }
+        if (this.cached && this.cached.mtimeMs === st.mtimeMs && this.cached.size === st.size)
+            return this.cached.token;
+        const token = readGrokToken(this.file);
+        this.cached = { mtimeMs: st.mtimeMs, size: st.size, token };
+        return token;
+    }
+    usable(token, marginMs) {
+        return token !== null && (token.expiresAt === 0 || token.expiresAt - this.now() > marginMs);
+    }
+    /**
+     * A token with at least `refreshAheadMs` to live, asking the CLI for a fresh one when the file's has
+     * less. A token that is merely close to its end is still used when the CLI cannot refresh it: it
+     * works until it expires, and refusing it early would fail a turn that could have run.
+     */
+    async token() {
+        const now = this.current();
+        if (this.usable(now, this.refreshAheadMs))
+            return now;
+        if (now === null && !fs.existsSync(this.file))
+            throw new GrokAuthError(`no Grok session at ${this.file}: ${GROK_AUTH_HINT}`);
+        // A refresh already running is joined. Otherwise one that failed less than a minute ago is not
+        // run again, whether or not the token has expired since: with the IdP down every turn would
+        // spawn the CLI for nothing. The file is still read again, in case the CLI fixed it on its own.
+        if (this.refreshing)
+            await this.refreshing;
+        else if (this.now() - this.lastAttemptAt >= REFRESH_RETRY_GAP_MS)
+            await this.refresh(Math.ceil(this.refreshAheadMs / 1000));
+        const after = this.current();
+        if (this.usable(after, 0))
+            return after;
+        throw new GrokAuthError(`the Grok session in ${this.file} has expired: ${GROK_AUTH_HINT}`);
+    }
+    /**
+     * After the proxy refused `key`: whether a different, live token is available now. The file is read
+     * first, since the CLI may already have rotated it; only when it still holds the refused token is
+     * the CLI asked to refresh, and that refresh is forced — the token was refused, however long it had.
+     */
+    async rejected(key) {
+        const replaced = () => {
+            const now = this.current();
+            return now !== null && now.key !== key && this.usable(now, 0);
+        };
+        if (replaced())
+            return true;
+        // Concurrent turns refused together share the refresh the first one started, rather than the
+        // second one finding the once-a-minute limit spent and failing.
+        if (this.refreshing) {
+            await this.refreshing;
+            if (replaced())
+                return true;
+        }
+        if (this.now() - this.lastForcedAt < FORCED_REFRESH_GAP_MS)
+            return false;
+        this.lastForcedAt = this.now();
+        await this.refresh(FORCE_REFRESH_SECS);
+        return replaced();
+    }
+    /** One refresh at a time: concurrent turns that all find the token stale share the CLI run. */
+    refresh(earlySecs) {
+        if (this.refreshing)
+            return this.refreshing;
+        this.lastAttemptAt = this.now();
+        const cli = findGrokCli(this.opts.home, this.opts.cli, this.env);
+        if (!cli) {
+            this.opts.log.warn(`grok: session needs a refresh but no grok CLI was found${this.opts.cli ? ` at ${this.opts.cli}` : ""}`);
+            return Promise.resolve();
+        }
+        const env = {
+            ...this.env,
+            GROK_AUTH_EARLY_INVALIDATION_SECS: String(earlySecs),
+            // The CLI reads its session from $GROK_HOME; a home given in the config has to reach it.
+            ...(this.opts.home !== grokHome(this.env) ? { GROK_HOME: this.opts.home } : {}),
+        };
+        const started = this.now();
+        this.refreshing = this.run(cli, ["models"], env, REFRESH_TIMEOUT_MS)
+            .then(() => this.opts.log.info(`grok: session refreshed through the CLI in ${this.now() - started}ms`))
+            .catch((error) => this.opts.log.warn(`grok: CLI session refresh failed: ${error.message.split("\n")[0]?.slice(0, 200)}`))
+            // The CLI rewrites the file with a token of the same length, possibly within the mtime's
+            // resolution, so the read after a refresh must not trust the stat-keyed cache.
+            .finally(() => { this.refreshing = undefined; this.cached = undefined; });
+        return this.refreshing;
+    }
+    /**
+     * `x-grok-client-version`: the installed CLI's own version, so the proxy sees the client the token
+     * was issued to. Read again when the binary changes: an update either replaces the file the symlink
+     * names or rewrites the binary in place, so the key is the resolved path with its mtime and size.
+     */
+    clientVersion(pinned = this.opts.clientVersion) {
+        if (pinned)
+            return Promise.resolve(pinned);
+        const cli = findGrokCli(this.opts.home, this.opts.cli, this.env);
+        let binary = "";
+        try {
+            if (cli) {
+                const real = fs.realpathSync(cli);
+                const st = fs.statSync(real);
+                binary = `${real}\0${st.mtimeMs}\0${st.size}`;
+            }
+        }
+        catch {
+            binary = cli ?? ""; /* keep the unresolved name */
+        }
+        if (this.version && this.version.binary === binary)
+            return this.version.value;
+        const value = !cli
+            ? Promise.resolve(GROK_CLIENT_VERSION_FALLBACK)
+            : this.run(cli, ["--version"], this.env, 10_000)
+                .then((out) => /\b(\d+\.\d+\.\d+)\b/.exec(out)?.[1] ?? GROK_CLIENT_VERSION_FALLBACK)
+                .catch((error) => {
+                this.opts.log.warn(`grok: \`grok --version\` failed (${error.message.split("\n")[0]?.slice(0, 120)}); sending ${GROK_CLIENT_VERSION_FALLBACK}`);
+                return GROK_CLIENT_VERSION_FALLBACK;
+            });
+        this.version = { binary, value };
+        return value;
+    }
+}
+const shared = new Map();
+/**
+ * The `GrokAuth` for one Grok home and binary, made once per process. The refresh is single-flight
+ * and backed off per instance, so the dashboard's probes and the turns that use the same session
+ * have to share one, or two of them spawn two CLI runs against the same lock. A pinned client version
+ * is not part of it: that is passed to `clientVersion()` by whoever sends the header.
+ */
+export function sharedGrokAuth(opts) {
+    const real = (file) => {
+        try {
+            return fs.realpathSync(file);
+        }
+        catch {
+            return file; /* not there yet: the resolved path names it */
+        }
+    };
+    const home = real(path.resolve(opts.home));
+    // The binary that would actually run, so a config that names the CLI the lookup would find anyway
+    // still shares the instance of one that leaves it out.
+    const cli = findGrokCli(home, opts.cli, opts.env);
+    const key = JSON.stringify([home, cli ? real(cli) : opts.cli ?? ""]);
+    let auth = shared.get(key);
+    if (!auth) {
+        // Built on the resolved home: one created through a symlink must not follow the link elsewhere
+        // later while still being found under the old target.
+        auth = new GrokAuth({ ...opts, home });
+        shared.set(key, auth);
+    }
+    return auth;
+}