ima2-gen 3.15.1 → 3.16.0

package/CHANGELOG.md

@@ -26,7 +26,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Windows installer npm handling** — compose global npm lockfile path with nested `Join-Path` calls for PowerShell 5.1 compatibility; wrap npm invocations in `Invoke-Npm` with `Continue` error action preference so stderr warnings do not abort the installer (#110, #111).
 
-## [Unreleased]
+## [3.16.0] - 2026-09-09
+
+### Removed
+
+- **Bundled progrok proxy** — the `grok` lane no longer bundles or spawns the progrok child process, and there is no local Grok proxy or port 18645. `IMA2_GROK_PROXY_HOST`, `IMA2_GROK_PROXY_PORT`, `IMA2_NO_GROK_PROXY`, and `IMA2_GROK_RESTART_*` are no longer read; setting them is harmless.
+- **`ima2 grok models` and `ima2 grok proxy`** — the subcommand surface is now `login`, `status [--json] [--probe]`, and `logout`.
+
+### Changed
+
+- **Native xAI OAuth on the `grok` lane** — image and video requests call `https://api.x.ai` directly with the OAuth session stored in `~/.progrok/auth.json`, obtained through `ima2 grok login` or the web UI and refreshed automatically two minutes before expiry. The credential file keeps its path and schema, so existing users are not asked to log in again, and it is still shared with the progrok CLI for anyone who has that installed. `grok-api` continues to use `XAI_API_KEY` directly. xAI documents only `/v1/me` as accepting OAuth tokens, so this path carries no compatibility promise; `grok-api` remains the documented one.
+- **Grok readiness reporting** — `/api/grok/status` returns `ready`, `no_image_model`, `error`, or `offline` with `reason: "login_required"` when no session is stored, and `/api/health` plus `~/.ima2/server.json` publish `grok: { auth: "oauth" | "none" }`.
 
 ## [3.15.0] - 2026-09-08
 

package/README.md

@@ -166,12 +166,12 @@ The web UI uses a single `GET /api/events` Server-Sent Events connection for all
 
 ## Provider Paths
 
-Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, the bundled Grok provider, or the Gemini provider via Antigravity CLI.
+Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, the Grok provider, or the Gemini provider via Antigravity CLI.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
-- `provider: "grok"` starts bundled `progrok` on `127.0.0.1:18645`, runs mandatory xAI Web Search plus a planner pass (default: `grok-4.5`, configurable in settings or via `--planner-model`), then calls xAI Images API through the local proxy. `grok-4.3` remains available as an explicit compatibility override.
-- `provider: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no bundled progrok OAuth proxy).
+- `provider: "grok"` calls `https://api.x.ai` directly with the xAI OAuth session stored in `~/.progrok/auth.json`, running mandatory xAI Web Search plus a planner pass (default: `grok-4.5`, configurable in settings or via `--planner-model`) before the xAI Images API call. `grok-4.3` remains available as an explicit compatibility override. Log in once with `ima2 grok login` or the Settings **Switch Account** button; the session refreshes itself two minutes before expiry.
+- `provider: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no OAuth session involved).
 - `provider: "nai"` calls the NovelAI image API with a persistent API token (saved in Settings > API Keys or `NOVELAI_API_KEY`; no fixed token prefix is required). Four models: `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, `nai-diffusion-4-5-curated`. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images, edits, and masks are refused rather than silently dropped. Browser and CLI surfaces expose negative prompt, sampler/schedule, steps/guidance/CFG rescale, seed, presets, Auto SMEA, Decrisper, Variety+, and V5 alpha.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (model: `nano-banana-2`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
 - `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
@@ -180,6 +180,8 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 
 If no provider is specified, the app keeps the current GPT OAuth/default behavior. GPT OAuth and API-key generation default to `gpt-5.6-luna`; the API-key path also defaults to `low` reasoning and `1024x1024` unless the request passes validated options. Grok image generation defaults to `grok-imagine-image-quality`.
 
+One caveat on the OAuth Grok lane: xAI documents only `/v1/me` as accepting an OAuth token, so image and video calls to `api.x.ai` with that token ride an undocumented path. It works today — progrok relied on the same path — but it carries no compatibility promise. If xAI closes it, `provider: "grok-api"` with `XAI_API_KEY` is the documented route and stays unaffected.
+
 Grok image generation exposes a model picker (`grok-imagine-image` / `grok-imagine-image-quality`) and a size picker (aspect ratio + 1k/2k resolution). The Settings page prefers the Grok Build weekly credits percentage and reset time from `GET /v1/billing?format=credits`; if that source is unavailable, it falls back to the legacy monthly billing window and `$used/$limit`. A **Switch Account** button starts a device-code OAuth flow (`POST /api/auth/switch`) for re-authenticating without leaving the app.
 
 Grok video generation defaults to canonical `grok-imagine-video-1.5`; `grok-imagine-video` remains available for base-model-only Ref2V, V2V edit, and extension paths, and the legacy `grok-imagine-video-1.5-preview` string is accepted as an alias. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2-14 refs; up to 15s on grok-imagine-video-1.5, 10s on grok-imagine-video). 1080p is available for `grok-imagine-video-1.5` prompt-only text-to-video and single image/frame image-to-video; prompt-only 1.5 uses the internal white-canvas I2V shim before the upstream request. Video controls include duration (1-15s), resolution (480p, 720p, 1080p when supported), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
@@ -352,9 +354,6 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |
 | `IMA2_API_ALLOW_WEB_SEARCH` | `true` | Toggle web search for `provider: "api"` |
-| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | Host for the bundled progrok proxy |
-| `IMA2_GROK_PROXY_PORT` | `18645` | Port for the bundled progrok proxy |
-| `IMA2_NO_GROK_PROXY` | — | Set `1` to disable automatic progrok startup |
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.5` | Grok search/planner model (also configurable via settings UI or `--planner-model` CLI flag) |
 | `IMA2_GROK_PLANNER_TIMEOUT_MS` | `900000` | Timeout for the Grok planner call |
 | `IMA2_GROK_SEARCH_TIMEOUT_MS` | `300000` | Timeout for the Grok web-search brief (degrades instead of failing) |
@@ -368,6 +367,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |
 | `IMA2_MAX_PARALLEL` | `24` | Server-wide parallel generation cap |
 
+`IMA2_GROK_PROXY_HOST`, `IMA2_GROK_PROXY_PORT`, `IMA2_NO_GROK_PROXY`, and `IMA2_GROK_RESTART_*` were removed in 3.16 together with the local Grok proxy; they are no longer read, and setting them is harmless.
+
 ### Logging modes
 
 `ima2 serve` keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.

package/bin/commands/grok.js

@@ -1,55 +1,154 @@
-import { spawn } from "node:child_process";
-import { dirname, join, delimiter } from "node:path";
-import { fileURLToPath } from "node:url";
-import { color, die, out } from "../lib/output.js";
-import { isWin } from "../lib/platform.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = join(__dirname, "..", "..");
+/**
+ * ima2 grok — xAI OAuth session management.
+ *
+ * There is no proxy left to manage: the Grok lanes call https://api.x.ai directly with the
+ * session in ~/.progrok/auth.json (lib/xaiAuth.ts). `login` prefers a running ima2 server so
+ * the CLI and the web UI drive the same device-code session, and falls back to running the
+ * flow in-process when no server answers.
+ */
+import { parseArgs } from "../lib/args.js";
+import { findRunningServer, request } from "../lib/client.js";
+import { color, die, json, out } from "../lib/output.js";
+import { clearGrokCredentials, grokAuthFilePath, loadGrokCredentials, } from "../../lib/xaiAuth.js";
+import { runXaiDeviceLogin } from "../../lib/xaiDeviceLogin.js";
+import { fetchWithGrokAuth, getGrokEndpoint } from "../../lib/grokRuntime.js";
 const HELP = `
   ima2 grok <subcommand> [options]
 
-  Manage the bundled progrok runtime used by the Grok image provider.
-  No separate progrok install is required.
+  Manage the xAI (Grok) OAuth session used by the grok image and video lanes.
+  Requests go straight to https://api.x.ai; no local proxy is involved.
 
   Subcommands:
-    login [options]        Log in to xAI OAuth (default: --manual-paste)
-    logout                 Remove stored xAI credentials
-    status                 Show bundled progrok authentication status
-    models                 List available Grok models
-    proxy [options]        Start the bundled proxy directly
+    login                  Log in to xAI with the OAuth device-code flow
+    status [--json]        Show the stored session (add --probe to call /v1/models)
+    logout                 Remove the stored xAI session
 
   Notes:
-    ima2 serve auto-starts the bundled proxy on 127.0.0.1:18645 by default.
-    ima2 grok login defaults to --manual-paste for reliable copy/paste auth.
-    Use IMA2_NO_GROK_PROXY=1 to disable automatic proxy startup.
+    The session is stored in ~/.progrok/auth.json and is shared with the
+    progrok CLI if you have it installed.
+    ima2 grok login uses a running 'ima2 serve' when one is available so the
+    CLI and the web UI share one login; otherwise it runs the flow directly.
 `;
-const MANUAL_PASTE_FLAG = "--manual-paste";
-const NON_MANUAL_LOGIN_FLOW_FLAGS = new Set(["--device-code", "--browser"]);
-function localBinPath() {
-    return join(ROOT, "node_modules", ".bin");
+const SPEC = {
+    flags: {
+        json: { type: "boolean" },
+        probe: { type: "boolean" },
+        help: { short: "h", type: "boolean" },
+    },
+};
+const POLL_INTERVAL_MS = 3_000;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function printUserCode(info) {
+    out("");
+    out(`  Open ${color.cyan(info.verificationUrl)}`);
+    out(`  and enter the code ${color.bold(info.userCode)}`);
+    out(color.dim(`  The code expires in ${Math.round(info.expiresIn / 60)} minutes.`));
+    out("");
+}
+/** Relative rendering of an absolute epoch-ms expiry, e.g. "in 58m" or "expired 2h ago". */
+function relativeTime(epochMs) {
+    const deltaMs = epochMs - Date.now();
+    const minutes = Math.round(Math.abs(deltaMs) / 60_000);
+    const span = minutes < 60 ? `${minutes}m` : minutes < 1440 ? `${Math.round(minutes / 60)}h` : `${Math.round(minutes / 1440)}d`;
+    return deltaMs >= 0 ? `in ${span}` : `expired ${span} ago`;
+}
+function statusJson(creds) {
+    if (!creds)
+        return { auth: "none", refreshable: false };
+    return {
+        auth: "oauth",
+        ...(creds.email !== undefined ? { email: creds.email } : {}),
+        ...(creds.expiresAt !== undefined ? { expiresAt: new Date(creds.expiresAt).toISOString() } : {}),
+        refreshable: typeof creds.refreshToken === "string" && creds.refreshToken.length > 0,
+    };
+}
+/** Drives the server-side device-code session so the CLI and web UI share one login. */
+async function loginViaServer(base) {
+    const start = await request(base, "/api/auth/switch", { method: "POST", body: { provider: "grok" } });
+    printUserCode({ userCode: start.userCode, verificationUrl: start.verificationUrl, expiresIn: start.expiresIn });
+    const deadline = Date.now() + start.expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        const poll = await request(base, `/api/auth/switch/${encodeURIComponent(start.sessionId)}`);
+        if (poll.status === "complete")
+            return;
+        if (poll.status === "error")
+            throw new Error(poll.error || "xAI device login failed");
+        if (poll.status === "expired")
+            throw new Error("xAI device login expired before it was approved");
+    }
+    throw new Error("xAI device login expired before it was approved");
 }
-function spawnProgrok(argv, env) {
-    return new Promise((resolve, reject) => {
-        const progrokBin = join(localBinPath(), isWin ? "progrok.cmd" : "progrok");
-        const child = spawn(progrokBin, argv, {
-            cwd: ROOT,
-            env,
-            stdio: "inherit",
-            shell: isWin,
-            windowsHide: true,
-        });
-        child.on("error", (err) => reject(err));
-        child.on("close", resolve);
+async function loginCmd() {
+    let server = null;
+    try {
+        server = await findRunningServer({ includeEnv: false });
+    }
+    catch {
+        // An unreachable or misconfigured server is not a login failure; run the flow locally.
+    }
+    try {
+        if (server)
+            await loginViaServer(server.base);
+        else
+            await runXaiDeviceLogin({ onUserCode: printUserCode });
+    }
+    catch (error) {
+        die(1, `Grok login failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    out(color.green("✓ ") + `Grok OAuth session saved to ${grokAuthFilePath()}`);
+}
+/** Lists the grok-imagine model ids the stored session can actually see. */
+async function probeImagineModels() {
+    // The grok lane reads only grokAuthHomeDir off the context, and the CLI always wants the
+    // real ~/.progrok session, so an empty context is the whole dependency here.
+    const ctx = {};
+    const response = await fetchWithGrokAuth(ctx, "grok", (credential) => {
+        const endpoint = getGrokEndpoint("/v1/models", credential);
+        return fetch(endpoint.url, { headers: endpoint.headers, signal: AbortSignal.timeout(20_000) });
     });
+    if (!response.ok)
+        throw new Error(`xAI /v1/models failed: HTTP ${response.status}`);
+    const body = await response.json();
+    return (body.data ?? [])
+        .map((entry) => entry.id)
+        .filter((id) => typeof id === "string" && id.includes("imagine"));
 }
-export function normalizeGrokLoginArgs(argv) {
-    const sub = argv[0];
-    if (sub !== "login")
-        return argv;
-    const normalized = argv.filter((arg) => !NON_MANUAL_LOGIN_FLOW_FLAGS.has(arg));
-    if (normalized.includes(MANUAL_PASTE_FLAG))
-        return normalized;
-    return [...normalized, MANUAL_PASTE_FLAG];
+/** A probe failure is reported, never thrown, so --json still emits one parseable object. */
+async function probeResult() {
+    try {
+        return { imagineModels: await probeImagineModels() };
+    }
+    catch (error) {
+        return { probeError: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function statusCmd(argv) {
+    const args = parseArgs(argv, SPEC);
+    const creds = loadGrokCredentials();
+    const probe = args.probe === true && creds !== null ? await probeResult() : undefined;
+    if (args.json) {
+        json({ ...statusJson(creds), ...(probe ?? {}) });
+        return;
+    }
+    if (!creds) {
+        out(color.yellow("○ ") + "Not logged in to Grok. Run: ima2 grok login");
+        return;
+    }
+    out(color.green("✓ ") + `Grok OAuth session (${creds.email ?? "email unknown"})`);
+    out(`  expires: ${creds.expiresAt === undefined ? "unknown" : relativeTime(creds.expiresAt)}`);
+    out(`  refresh token: ${creds.refreshToken ? "present" : "absent"}`);
+    out(color.dim(`  file: ${grokAuthFilePath()}`));
+    if (!probe)
+        return;
+    if (probe.probeError !== undefined)
+        die(1, `Grok model probe failed: ${probe.probeError}`);
+    const ids = probe.imagineModels ?? [];
+    out(ids.length ? `  imagine models: ${ids.join(", ")}` : color.yellow("  no grok-imagine model is visible to this session"));
 }
 export default async function grokCmd(argv) {
     const sub = argv[0];
@@ -57,28 +156,15 @@ export default async function grokCmd(argv) {
         out(HELP);
         return;
     }
-    const env = {
-        ...process.env,
-        PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
-    };
-    try {
-        argv = normalizeGrokLoginArgs(argv);
-        const code = await spawnProgrok(argv, env);
-        if (code && code !== 0) {
-            if (sub === "login") {
-                out(color.yellow("⚠ ") + "Login failed. Try again with:\n");
-                out("  ima2 grok login\n");
-                die(code, "bundled Grok OAuth login failed");
-            }
-            else {
-                die(code, `bundled progrok exited with code ${code}`);
-            }
-        }
-    }
-    catch (err) {
-        die(1, `bundled progrok failed to start: ${err.message}`);
-    }
-    if (sub === "login") {
-        out(color.green("✓ ") + "Grok OAuth is ready for ima2 serve");
+    const rest = argv.slice(1);
+    if (sub === "login")
+        return loginCmd();
+    if (sub === "status")
+        return statusCmd(rest);
+    if (sub === "logout") {
+        clearGrokCredentials();
+        out(color.green("✓ ") + "Removed the stored Grok OAuth session");
+        return;
     }
+    die(2, `unknown subcommand '${sub}'. Run 'ima2 grok --help'.`);
 }

package/bin/commands/service.js

@@ -123,10 +123,11 @@ function reportProviderLiveness(entry) {
     if (oauth?.status && oauth.status !== "ready" && oauth.status !== "disabled") {
         console.log(`  Warning: GPT OAuth proxy status is "${oauth.status}" — check 'ima2 service logs'.`);
     }
-    // grok.live only exists in the advertise payload, not /api/health (audit note).
-    if (grok && grok.live === false) {
-        console.log("  Warning: Grok proxy is not live under the service environment.");
-        console.log("  If Grok worked in a terminal, the service PATH may be missing its binary.");
+    // The service runs under its own HOME, so it can read a different
+    // ~/.progrok/auth.json than the terminal the user logged in from.
+    if (grok?.auth === "none") {
+        console.log("  Warning: Grok is not logged in under the service environment.");
+        console.log("  Run: ima2 grok login");
     }
 }
 // ── macOS (launchd) ──

package/bin/ima2.js

@@ -115,7 +115,7 @@ async function setup() {
         saveConfig(config);
         console.log("\n  Starting Grok OAuth login...\n");
         try {
-            runSelf(["grok", "login", "--manual-paste"]);
+            runSelf(["grok", "login"]);
         }
         catch {
             console.log("\n  Grok login failed or cancelled. You can retry with 'ima2 grok login'.\n");
@@ -151,7 +151,7 @@ async function setup() {
         // Grok OAuth
         console.log("  Running Grok OAuth login...\n");
         try {
-            runSelf(["grok", "login", "--manual-paste"]);
+            runSelf(["grok", "login"]);
         }
         catch {
             console.log("\n  Grok login failed. You can retry with 'ima2 grok login'.\n");
@@ -353,7 +353,7 @@ function showHelp() {
     billing        API usage / quota
     providers      Configured providers
     oauth <sub>    GPT OAuth proxy status              (ima2 oauth --help)
-    grok <sub>     Bundled Grok auth/status         (ima2 grok --help)
+    grok <sub>     xAI OAuth login/status/logout    (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     models         List available lane models      (ima2 models --help)

package/bin/lib/doctor-providers.js

@@ -43,6 +43,9 @@ function inspectOauth(lane) {
     }
     if (lane === "grok") {
         const home = homedir();
+        // First path is the ima2 session (lib/xaiAuth.ts grokAuthFilePath; spelled out here so
+        // the doctor bundle stays free of node:crypto). ~/.grok/auth.json is the xAI CLI file
+        // that routes/quota.ts still reads; different schema, never a lib/xaiAuth.ts source.
         const files = [join(home, ".progrok", "auth.json"), join(home, ".grok", "auth.json")];
         if (files.some((path) => existsSync(path))) {
             return { code: "CREDENTIAL_PRESENT", lane, kind: "pass", text: `${lane}: local Grok auth file present` };
@@ -98,7 +101,9 @@ export function inspectProviderLane(provider, fileConfig) {
     return provider.credentials.map((credential) => {
         if (credential.kind === "api-key")
             return inspectApiKey(provider.id, credential, fileConfig);
-        if (credential.kind === "oauth-proxy")
+        // "oauth" (grok, first-party session) and "oauth-proxy" (a separate local
+        // process holds the session) both land on the same per-lane file checks.
+        if (credential.kind === "oauth-proxy" || credential.kind === "oauth")
             return inspectOauth(provider.id);
         if (credential.kind === "service-account")
             return inspectServiceAccount(provider.id, credential, fileConfig);

package/bin/lib/doctor-runtime.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { getUiDistBuildStatus } from "./ui-build.js";
-const RUNTIME_DEPENDENCIES = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json", "@openai/codex/package.json", "zod"];
+const RUNTIME_DEPENDENCIES = ["express", "better-sqlite3", "openai", "openai-oauth", "@openai/codex/package.json", "zod"];
 const REQUIRED_BINS = [["openai-oauth", "openai-oauth"], ["@openai/codex", "codex"]];
 const line = (code, kind, text) => ({ code, kind, text, evidence: "local" });
 export function parseMinimumNodeMajor(engine) {

package/config.js

@@ -247,15 +247,6 @@ export const config = {
         allowWebSearch: pickBool(env.IMA2_API_ALLOW_WEB_SEARCH, fileCfg.apiProvider?.allowWebSearch, true),
     },
     grokProvider: {
-        proxyPort: pickInt(env.IMA2_GROK_PROXY_PORT, fileCfg.grokProvider?.proxyPort, 18645),
-        proxyHost: pickStr(env.IMA2_GROK_PROXY_HOST, fileCfg.grokProvider?.proxyHost, "127.0.0.1"),
-        autoStart: !pickBool(env.IMA2_NO_GROK_PROXY, fileCfg.grokProvider?.disableAutoStart, false),
-        restartDelayMs: pickInt(env.IMA2_GROK_RESTART_DELAY_MS, fileCfg.grokProvider?.restartDelayMs, 2000),
-        // 6 attempts at 2s doubling to a 60s cap is roughly two minutes: enough to ride out a
-        // transient port conflict, short of spinning forever on a broken binary.
-        restartMaxAttempts: pickInt(env.IMA2_GROK_RESTART_MAX_ATTEMPTS, fileCfg.grokProvider?.restartMaxAttempts, 6),
-        restartMaxDelayMs: pickInt(env.IMA2_GROK_RESTART_MAX_DELAY_MS, fileCfg.grokProvider?.restartMaxDelayMs, 60_000),
-        restartHealthyMs: pickInt(env.IMA2_GROK_RESTART_HEALTHY_MS, fileCfg.grokProvider?.restartHealthyMs, 60_000),
         plannerModel: pickStr(env.IMA2_GROK_PLANNER_MODEL, fileCfg.grokProvider?.plannerModel, DEFAULT_GROK_PLANNER_MODEL),
         // Measured 260817: the forced web_search brief takes 70-73 s idle / 44-79 s concurrent,
         // and the planner tool call 9-32 s idle / 28-41 s concurrent. But the reported failure

package/docs/API.md

@@ -62,9 +62,9 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
-- `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node and multimode image generation honor `webSearchEnabled: false` (Node also honors `searchMode: "off"`): this skips `/v1/responses` search, not the configured planner's forced `generate_image` call. Planner default is `grok-4.3`; `grok-4.6` and `grok-4.5` remain selectable overrides. References select `/v1/images/edits` instead of `/v1/images/generations`. Agent's omitted-option search default is unchanged.
+- `provider: "grok"` calls `https://api.x.ai` directly with the xAI OAuth session in `~/.progrok/auth.json`. Classic, Node and multimode image generation honor `webSearchEnabled: false` (Node also honors `searchMode: "off"`): this skips `/v1/responses` search, not the configured planner's forced `generate_image` call. Planner default is `grok-4.3`; `grok-4.6` and `grok-4.5` remain selectable overrides. References select `/v1/images/edits` instead of `/v1/images/generations`. Agent's omitted-option search default is unchanged.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool. Model is `nano-banana-2`. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (`AGY_VIDEO_UNSUPPORTED`).
-- `provider: "grok-api"` uses a direct xAI API key with the same image search/planner/image semantics. Missing or blank image credentials are refused with `GROK_API_KEY_MISSING` before admission, never changed to the proxy lane. Video remains a separate path. Configure the key in Settings or `XAI_API_KEY`.
+- `provider: "grok-api"` uses a direct xAI API key with the same image search/planner/image semantics. Missing or blank image credentials are refused with `GROK_API_KEY_MISSING` before admission, never changed to the OAuth lane. Video remains a separate path. Configure the key in Settings or `XAI_API_KEY`.
 - `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K) on both auth paths — the direct API path sends `generation_config.response_format.image` (snake_case) while the Vertex AI endpoint (`aiplatform.googleapis.com`) sends `generationConfig.imageConfig` (camelCase). With `size: "auto"` the image config is omitted entirely and the model decides ratio/size. Auth: `GEMINI_API_KEY` env var, web UI key management (`/api/keys/gemini`), or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON` or `/api/keys/vertex`). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (`apikey` or `vertex`) persists to `~/.ima2/config.json` as `geminiAuthMode` and is restored on server startup. Per-model cost: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
 - `provider: "nai"` calls NovelAI text-to-image generation with one of `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, or `nai-diffusion-4-5-curated`. It accepts the provider-native request fields documented below and returns a ZIP that ima2 decodes to PNG. References, edits, and masks are explicitly refused.
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
@@ -148,11 +148,11 @@ inventing a runtime `lanes` availability result.
 
 | Method | Path | Notes |
 |---|---|---|
-| `GET` | `/api/health` | Server health, version, paths, provider policy |
+| `GET` | `/api/health` | Server health, version, paths, provider policy; includes `grok: { auth: "oauth" \| "none" }`, mirrored in `~/.ima2/server.json` |
 | `POST` | `/api/admin/stop` | Clean shutdown (local admin only): requires the boot-generated `X-Ima2-Admin-Nonce` from `~/.ima2/server.json`; any request with an `Origin` header is refused (browser drive-by protection). Responds `202` then self-signals SIGTERM |
 | `GET` | `/api/providers` | Provider availability and runtime ports |
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
-| `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
+| `GET` | `/api/grok/status` | xAI OAuth session state and visible xAI image models: `ready`, `no_image_model`, `error`, or `offline` with `reason: "login_required"` when no session is stored |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
 | `GET` | `/api/quota` | Provider quota: returns `{ codex, grok, nai }`. Codex windows are `5h` and `7d`. NovelAI returns a `v5-battery` remaining-charge window when available (`resetsAt` is the ISO ETA for +1%, not full recharge), with Anlas balances in `nai.anlasFixed` / `nai.anlasPurchased`; a missing meter has no window. NovelAI account email is always null. Eligible Grok Build xAI OIDC/external auth returns a `weekly` percentage/reset window from `GET /v1/billing?format=credits`. If unavailable, the legacy endpoint may return a `monthly` window plus `billing: { usedUsd, limitUsd }`. |
 
@@ -394,7 +394,7 @@ Image edit / image-to-image generation.
 The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.
 
 With `provider: "grok"`, edit requests are sent to xAI `/v1/images/edits`
-through the bundled progrok proxy. Masked Grok edits are rejected before
+with the stored OAuth session. Masked Grok edits are rejected before
 upstream with `GROK_MASK_UNSUPPORTED`.
 
 Grok multimode plans each attempted image in order and performs search only when
@@ -879,8 +879,8 @@ Registered only when `config.features.cardNews` is true (`routes/cardNews.ts`).
 | `GRAPH_TOO_LARGE` | Graph exceeds node/edge limits |
 | `NODE_NOT_FOUND` | Node metadata was not found |
 | `INVALID_GROK_IMAGE_MODEL` | A Grok request used a model outside `grok-imagine-image` or `grok-imagine-image-quality` |
-| `GROK_RATE_LIMITED` | xAI returned a rate-limit response through progrok |
-| `GROK_AUTH_FAILED` | progrok could not authenticate the xAI request |
+| `GROK_RATE_LIMITED` | xAI returned a rate-limit response |
+| `GROK_AUTH_FAILED` | The xAI request could not be authenticated |
 | `GROK_SEARCH_TIMEOUT` / `GROK_PLANNER_TIMEOUT` / `GROK_IMAGE_TIMEOUT` | The Grok search, planner, or image API step exceeded its timeout budget |
 | `AGY_GENERATION_FAILED` | Gemini (agy) image generation failed |
 | `AGY_TIMEOUT` | Agy CLI process exceeded its 360-second timeout |

package/docs/API.zh-CN.md

@@ -14,9 +14,9 @@ http://localhost:3333
 
 - `provider: "oauth"`使用本地的Codex OAuth代理人。
 - `provider: "api"`使用OpenAI回应API与托管的`image_generation`工具。
-- `provider: "grok"`使用捆绑的progrok xAI代理人。经典、节点和代理生成强制运行xAI网页搜索通过`/v1/responses`，然后运行`grok-4.5`计划员与强制本地人通话`generate_image`函数，那么ima2执行xAI `/v1/images/generations`. `grok-4.3`仍然可以作为显式兼容性覆盖使用。如果附加了参考图像、节点父图像或代理当前图像，则最后一步将切换到xAI `/v1/images/edits`因此图像到图像的上下文被保留。
+- `provider: "grok"`使用保存在`~/.progrok/auth.json`的xAI OAuth会话直接调用`https://api.x.ai`，不再有本地代理进程。经典、节点和代理生成强制运行xAI网页搜索通过`/v1/responses`，然后运行`grok-4.5`计划员与强制本地人通话`generate_image`函数，那么ima2执行xAI `/v1/images/generations`. `grok-4.3`仍然可以作为显式兼容性覆盖使用。如果附加了参考图像、节点父图像或代理当前图像，则最后一步将切换到xAI `/v1/images/edits`因此图像到图像的上下文被保留。
 - `provider: "agy"`产生Antigravity CLI (`agy -p`）通过Google生成图像Gemini's `default_api:generate_image`工具。型号是`nano-banana-2`。输出固定为1024×1024JPEG。最多 3 个参考图像 (i2i)。没有网络搜索、质量、尺寸或遮罩控制。多模式返回单个图像。不支持视频（`AGY_VIDEO_UNSUPPORTED`).
-- `provider: "grok-api"`使用直接xAI API密钥而不是捆绑的progrok OAuth代理人。与相同的管道`grok`（网页搜索 → 策划 →`/v1/images/generations`），相同的宽高比和分辨率选项。需要一个xAI API通过网络配置的密钥UI密钥管理或`XAI_API_KEY`环境变量。还支持视频生成。
+- `provider: "grok-api"`使用直接xAI API密钥而不是OAuth会话；缺少或为空的图像凭证会在准入前以`GROK_API_KEY_MISSING`拒绝，绝不改走OAuth通道。与相同的管道`grok`（网页搜索 → 策划 →`/v1/images/generations`），相同的宽高比和分辨率选项。需要一个xAI API通过网络配置的密钥UI密钥管理或`XAI_API_KEY`环境变量。还支持视频生成。
 - `provider: "gemini-api"`调用 Google 生成语言API直接（或Vertex AI使用服务帐户JSON）。支持型号`nano-banana-2` (Gemini3.1 Flash 图像）和`nano-banana-pro` (Gemini3 专业图像）。在两个身份验证路径上支持可变宽高比（1:1 到 21:9）和四个分辨率层（512px、1K、2K、4K）——直接API路径发送`generation_config.response_format.image`（蛇_情况）而Vertex AI端点（`aiplatform.googleapis.com`) 发送`generationConfig.imageConfig`（驼峰式）。和`size: "auto"`图像配置被完全省略，模型决定比率/大小。授权：`GEMINI_API_KEY`环境变量、网络UI密钥管理（`/api/keys/gemini`），或一个Vertex AI服务帐户JSON (`VERTEX_SERVICE_ACCOUNT_JSON`或者`/api/keys/vertex`）。当 Vertex 凭证和APIkey 已配置，Vertex 优先。选择的身份验证模式（`apikey`或者`vertex`）坚持`~/.ima2/config.json`作为`geminiAuthMode`并在服务器启动时恢复。每个模型的成本：`nano-banana-2`（闪存）：512=0.001 美元、1K=0.003 美元、2K=0.004 美元、4K=0.006 美元；`nano-banana-pro`：1K=0.007 美元，2K=0.007 美元，4K=0.013 美元。没有网络搜索或掩码控制。
 - API-密钥生成涵盖经典生成、编辑、掩模引导编辑、多模式和节点生成。
 - 如果`provider: "api"`请求时没有API关键，路由在上游之前失败`401`和`API_KEY_REQUIRED`.
@@ -30,10 +30,10 @@ Grok视频生成用途`POST /api/video/generate` (SSE）。看视频
 
 |方法|小路|笔记|
 |---|---|---|
-| `GET` | `/api/health` |服务器健康状况、版本、路径、提供商策略|
+| `GET` | `/api/health` |服务器健康状况、版本、路径、提供商策略；包含`grok: { auth: "oauth" \| "none" }`，同样写入`~/.ima2/server.json`|
 | `GET` | `/api/providers` |提供者可用性和运行时端口|
 | `GET` | `/api/oauth/status` | OAuth代理状态和可见模型|
-| `GET` | `/api/grok/status` |捆绑式progrok状态和可见xAI图像模型|
+| `GET` | `/api/grok/status` | xAI OAuth会话状态和可见xAI图像模型。返回`ready`、`no_image_model`、`error`或`offline`；没有会话时原因是`login_required`|
 | `GET` | `/api/billing` |计费/状态探测，包括API配置时的密钥源|
 | `GET` | `/api/quota` |供应商配额：回报`{ codex, grok }`。有资格的Grok建造xAIOIDC/外部身份验证返回`weekly`百分比/重置窗口`GET /v1/billing?format=credits`。如果不可用，旧端点可能会返回`monthly`窗口加`billing: { usedUsd, limitUsd }`. |
 
@@ -262,7 +262,7 @@ Grok尺寸映射：
 该请求包括提示和图像负载。`provider: "api"`通过共享响应图像适配器发送提示和图像。可选蒙版作为蒙版指导转发，而不是像素完美的编辑保证。
 
 和`provider: "grok"`，编辑请求发送至xAI `/v1/images/edits`
-通过捆绑的progrok代理人。蒙面Grok之前编辑被拒绝
+使用OAuth会话直接发送。蒙面Grok之前编辑被拒绝
 上游与`GROK_MASK_UNSUPPORTED`.
 
 Grokmultimode 目前将每个图像请求直接发送到xAI图片API
@@ -727,8 +727,8 @@ X-Ima2-Tab-Id
 | `GRAPH_TOO_LARGE` |图超出节点/边限制|
 | `NODE_NOT_FOUND` |未找到节点元数据|
 | `INVALID_GROK_IMAGE_MODEL` | A Grok请求使用外部模型`grok-imagine-image`或者`grok-imagine-image-quality` |
-| `GROK_RATE_LIMITED` | xAI通过返回速率限制响应progrok |
-| `GROK_AUTH_FAILED` | progrok无法验证xAI要求|
+| `GROK_RATE_LIMITED` | xAI返回了速率限制响应|
+| `GROK_AUTH_FAILED` | xAI请求鉴权失败（OAuth会话无效或已过期，需要重新`ima2 grok login`）|
 | `GROK_SEARCH_TIMEOUT` / `GROK_PLANNER_TIMEOUT` / `GROK_IMAGE_TIMEOUT` |这Grok搜索、规划器或图像API步骤超出了其超时预算|
 | `AGY_GENERATION_FAILED` | Gemini(agy) 图像生成失败|
 | `AGY_TIMEOUT` |阿吉CLI进程超过 360 秒超时|

package/docs/API.zh-TW.md

@@ -14,9 +14,9 @@ http://localhost:3333
 
 - `provider: "oauth"`使用本地的Codex OAuth代理人。
 - `provider: "api"`使用OpenAI回應API與託管的`image_generation`工具。
-- `provider: "grok"`使用捆綁的progrok xAI代理人。經典、節點和代理生成強制運行xAI網頁搜尋透過`/v1/responses`，然後運行`grok-4.5`計劃員與強製本地人通話`generate_image`函數，那麼ima2執行xAI `/v1/images/generations`. `grok-4.3`仍然可以作為顯式相容性覆蓋使用。如果附加了參考影像、節點父映像或代理目前影像，則最後一步將切換到xAI `/v1/images/edits`因此圖像到圖像的上下文被保留。
+- `provider: "grok"`使用儲存在`~/.progrok/auth.json`的xAI OAuth工作階段直接呼叫`https://api.x.ai`，不再有本機代理程式。經典、節點和代理生成強制運行xAI網頁搜尋透過`/v1/responses`，然後運行`grok-4.5`計劃員與強製本地人通話`generate_image`函數，那麼ima2執行xAI `/v1/images/generations`. `grok-4.3`仍然可以作為顯式相容性覆蓋使用。如果附加了參考影像、節點父映像或代理目前影像，則最後一步將切換到xAI `/v1/images/edits`因此圖像到圖像的上下文被保留。
 - `provider: "agy"`產生Antigravity CLI (`agy -p`）透過Google生成圖像Gemini's `default_api:generate_image`工具。型號是`nano-banana-2`。輸出固定為1024×1024JPEG。最多 3 個參考影像 (i2i)。沒有網路搜尋、品質、尺寸或遮罩控制。多模式返回單一影像。不支援影片（`AGY_VIDEO_UNSUPPORTED`).
-- `provider: "grok-api"`使用直接xAI API密鑰而不是捆綁的progrok OAuth代理人。與相同的管道`grok`（網頁搜尋 → 策劃 →`/v1/images/generations`），相同的寬高比和解析度選項。需要一個xAI API透過網路配置的密鑰UI密鑰管理或`XAI_API_KEY`環境變數。也支援視頻生成。
+- `provider: "grok-api"`使用直接xAI API密鑰而不是OAuth工作階段；缺少或為空的影像憑證會在准入前以`GROK_API_KEY_MISSING`拒絕，絕不改走OAuth通道。與相同的管道`grok`（網頁搜尋 → 策劃 →`/v1/images/generations`），相同的寬高比和解析度選項。需要一個xAI API透過網路配置的密鑰UI密鑰管理或`XAI_API_KEY`環境變數。也支援視頻生成。
 - `provider: "gemini-api"`呼叫 Google 生成語言API直接（或Vertex AI使用服務帳戶JSON）。支援型號`nano-banana-2` (Gemini3.1 Flash 影像）和`nano-banana-pro` (Gemini3 專業圖像）。在兩個身份驗證路徑上支援可變寬高比（1:1 到 21:9）和四個解析度層（512px、1K、2K、4K）—直接API路徑發送`generation_config.response_format.image`（蛇_情況）而Vertex AI端點（`aiplatform.googleapis.com`) 發送`generationConfig.imageConfig`（駝峰式）。和`size: "auto"`影像配置被完全省略，模型決定比率/大小。授權：`GEMINI_API_KEY`環境變數、網絡UI密鑰管理（`/api/keys/gemini`），或一個Vertex AI服務帳戶JSON (`VERTEX_SERVICE_ACCOUNT_JSON`或者`/api/keys/vertex`）。當 Vertex 憑證和APIkey 已配置，Vertex 優先。選擇的身份驗證模式（`apikey`或者`vertex`）堅持`~/.ima2/config.json`作為`geminiAuthMode`並在伺服器啟動時恢復。每個模型的成本：`nano-banana-2`（快閃記憶體）：512=0.001 美元、1K=0.003 美元、2K=0.004 美元、4K=0.006 美元；`nano-banana-pro`：1K=0.007 美元，2K=0.007 美元，4K=0.013 美元。沒有網路搜尋或遮罩控制。
 - API-金鑰產生涵蓋經典生成、編輯、掩模引導編輯、多模式和節點生成。
 - 如果`provider: "api"`請求時沒有API關鍵，路由在上游之前失敗`401`和`API_KEY_REQUIRED`.
@@ -30,10 +30,10 @@ Grok影片生成用途`POST /api/video/generate` (SSE）。看影片
 
 |方法|小路|筆記|
 |---|---|---|
-| `GET` | `/api/health` |伺服器健康狀況、版本、路徑、提供者策略|
+| `GET` | `/api/health` |伺服器健康狀況、版本、路徑、提供者策略；包含`grok: { auth: "oauth" \| "none" }`，同樣寫入`~/.ima2/server.json`|
 | `GET` | `/api/providers` |提供者可用性和運行時端口|
 | `GET` | `/api/oauth/status` | OAuth代理狀態和可見模型|
-| `GET` | `/api/grok/status` |捆綁式progrok狀態和可見xAI影像模型|
+| `GET` | `/api/grok/status` | xAI OAuth工作階段狀態和可見xAI影像模型。回傳`ready`、`no_image_model`、`error`或`offline`；沒有工作階段時原因是`login_required`|
 | `GET` | `/api/billing` |計費/狀態探測，包括API配置時的密鑰來源|
 | `GET` | `/api/quota` |供應商配額：回報`{ codex, grok }`。有資格的Grok建造xAIOIDC/外部身份驗證返回`weekly`百分比/重置視窗`GET /v1/billing?format=credits`。如果不可用，舊端點可能會返回`monthly`視窗加`billing: { usedUsd, limitUsd }`. |
 
@@ -262,7 +262,7 @@ Grok尺寸映射：
 該請求包括提示和圖像負載。`provider: "api"`透過共享響應圖像適配器發送提示和圖像。可選蒙版作為蒙版指導轉發，而不是像素完美的編輯保證。
 
 和`provider: "grok"`，編輯請求發送至xAI `/v1/images/edits`
-透過捆綁的progrok代理人。蒙面Grok之前編輯被拒絕
+使用OAuth工作階段直接傳送。蒙面Grok之前編輯被拒絕
 上游與`GROK_MASK_UNSUPPORTED`.
 
 Grokmultimode 目前將每個圖像請求直接發送到xAI圖片API
@@ -727,8 +727,8 @@ X-Ima2-Tab-Id
 | `GRAPH_TOO_LARGE` |圖超出節點/邊限制|
 | `NODE_NOT_FOUND` |未找到節點元數據|
 | `INVALID_GROK_IMAGE_MODEL` | A Grok請求使用外部模型`grok-imagine-image`或者`grok-imagine-image-quality` |
-| `GROK_RATE_LIMITED` | xAI透過返回速率限制響應progrok |
-| `GROK_AUTH_FAILED` | progrok無法驗證xAI要求|
+| `GROK_RATE_LIMITED` | xAI回傳了速率限制回應|
+| `GROK_AUTH_FAILED` | xAI請求驗證失敗（OAuth工作階段無效或已過期，需要重新`ima2 grok login`）|
 | `GROK_SEARCH_TIMEOUT` / `GROK_PLANNER_TIMEOUT` / `GROK_IMAGE_TIMEOUT` |這Grok搜尋、規劃器或圖片API步驟超出了其超時預算|
 | `AGY_GENERATION_FAILED` | Gemini(agy) 影像生成失敗|
 | `AGY_TIMEOUT` |阿吉CLI進程超過 360 秒逾時|

package/docs/CLI.md

@@ -15,7 +15,7 @@ For a quick start, see the [main README](../README.md). For endpoint mapping, se
 | `ima2 doctor --installation --json` | Offline package checks without config, account or network access |
 | `ima2 doctor image-probe [--json]` | Run live sanitized Responses image probes for `EMPTY_RESPONSE` support |
 | `ima2 open` | Open the web UI in a browser |
-| `ima2 grok login/status/models/proxy` | Manage the bundled progrok runtime used by the Grok provider |
+| `ima2 grok login/status/logout` | Manage the xAI OAuth session used by the Grok provider |
 | `ima2 reset` | Remove saved config |
 | `ima2 backfill-thumbs` | Generate missing gallery thumbnails for images and videos (offline, no running server needed) |
 
@@ -113,7 +113,7 @@ Provider override semantics:
 
 - `api` forces the API-key Responses path and requires a configured API key.
 - `oauth` forces the local OAuth proxy path.
-- `grok` uses the bundled progrok xAI proxy (`127.0.0.1:18645`). Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.5` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. `grok-4.3` remains available as an explicit compatibility override. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
+- `grok` calls `https://api.x.ai` directly with the xAI OAuth session in `~/.progrok/auth.json`. Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.5` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. `grok-4.3` remains available as an explicit compatibility override. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
 - `agy` spawns the Antigravity CLI to generate via Google Gemini (`nano-banana-2`). Fixed 1024×1024 JPEG output, max 3 refs. No web search, quality, size, or mask controls. If `agy` is not on the server process PATH, ima2 also checks common user-local installs such as `~/.local/bin/agy`; set `IMA2_AGY_BIN=/absolute/path/to/agy` to force a specific binary.
 - `gemini-api` calls the Google Generative Language API directly. Models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Use `--model nano-banana-2` or `--model nano-banana-pro` to select. Supports `--size` for aspect ratio and resolution (512px–4K) on the direct API path; Vertex AI ignores aspect/size. Requires `GEMINI_API_KEY` or a Vertex AI service account (`VERTEX_SERVICE_ACCOUNT_JSON`). Switching from `agy` or `gemini-api` provider auto-selects the corresponding Gemini model; switching away resets to the GPT default.
 - `atlascloud` calls Atlas Cloud's Media API directly. Models: `openai/gpt-image-2/text-to-image` for text-to-image and `openai/gpt-image-2/edit` when references are attached. Requires `ATLASCLOUD_API_KEY`; web search, reasoning, mask, and video controls are ignored.
@@ -162,11 +162,12 @@ ima2 node generate "portrait" --provider nai --model nai-diffusion-5-curated \
   --nai-uc-preset light --nai-quality-preset light
 ```
 
-`ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
-install is required. Use `ima2 grok login` once to authorize xAI OAuth. Login
-defaults to `--manual-paste` so PowerShell, Terminal, and remote shells all use
-the same copy/paste flow. Set `IMA2_NO_GROK_PROXY=1` only if you want to manage
-the proxy yourself.
+The Grok lane needs no local proxy and no separate install. Use `ima2 grok login`
+once to authorize xAI OAuth; the device-code flow prints a URL and a code, and the
+stored session refreshes itself two minutes before it expires. The session lives in
+`~/.progrok/auth.json` and is shared with the progrok CLI if you happen to have it
+installed. `ima2 grok status --probe` checks it against xAI, and `ima2 grok logout`
+removes it.
 
 Grok size mapping follows xAI's image API, not OpenAI's `size` field. ima2
 keeps the requested size in local metadata, but sends `aspect_ratio` such as
@@ -465,7 +466,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 billing` | API usage probe via `/api/billing` (OpenAI/API-key credits when configured). Grok and NovelAI quota are web-UI only via `GET /api/quota`: weekly percentage/reset for current Grok Build xAI auth, with legacy monthly `usedUsd`/`limitUsd` fallback. |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
-| `ima2 grok status` | Bundled progrok / xAI image-model probe state |
+| `ima2 grok status` | Stored xAI OAuth session, with `--probe` for image-model visibility |
 | `ima2 ping` | Health-check the running server |
 
 ## Config