ima2-gen 3.13.1 → 3.14.0

package/bin/lib/recover-output.js

@@ -2,6 +2,7 @@ import { copyFile, mkdir } from "node:fs/promises";
 import { join, dirname, basename, isAbsolute } from "node:path";
 import { config } from "../../config.js";
 import { request } from "./client.js";
+import { exitCodeForError } from "./output.js";
 export function createCliRequestId(prefix = "req_cli") {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -91,13 +92,19 @@ export async function recoverGeneratedOutputs(base, requestId, target) {
         if (result)
             return result;
     }
-    catch { }
+    catch (error) {
+        if (exitCodeForError(error) === 4)
+            throw error;
+    }
     try {
         const result = await tryHistoryRecovery(base, requestId, target);
         if (result)
             return result;
     }
-    catch { }
+    catch (error) {
+        if (exitCodeForError(error) === 4)
+            throw error;
+    }
     return { recovered: false, paths: [], requestId, source: "none" };
 }
 export function formatRecoveryHint(result) {

package/bin/lib/sse.js

@@ -1,4 +1,6 @@
 // SSE consumer for CLI streaming endpoints. Plain fetch + line-based parser, no external libs.
+import { parseEventCursor } from "../../lib/eventsPolicy.js";
+import { fetchServerUrl } from "./client.js";
 let CLI_VERSION = "0.0.0";
 export function setCliVersion(v) { CLI_VERSION = v; }
 function requestHeaders(init) {
@@ -82,7 +84,7 @@ async function openWithMethod(url, init, defaultMethod) {
     if (init.signal?.aborted)
         close();
     try {
-        const res = await fetch(url, {
+        const res = await fetchServerUrl(url, {
             method: init.method || defaultMethod,
             headers: requestHeaders(init),
             ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
@@ -92,9 +94,15 @@ async function openWithMethod(url, init, defaultMethod) {
             close();
             throw await errorFromResponse(res);
         }
+        const cursorHeader = res.headers.get("x-ima2-event-cursor");
+        if (cursorHeader !== null && parseEventCursor(cursorHeader) === null) {
+            close();
+            throw new Error("SSE_INVALID_EVENT_CURSOR");
+        }
         const events = parseBody(res.body, () => closed);
         return {
             events,
+            ...(cursorHeader !== null ? { initialEventId: cursorHeader } : {}),
             close: () => {
                 init.signal?.removeEventListener("abort", forwardAbort);
                 close();

package/bin/lib/videoMcp.js

@@ -4,7 +4,7 @@ import { config } from "../../config.js";
 import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS, validateVideoResolutionForRequest, } from "../../lib/imageModels.js";
 import { VIDEO_CLIENT_TIMEOUT_MS } from "../../lib/videoClientTimeouts.js";
 import { wasFlagPassed } from "./argsExplicit.js";
-import { resolveHistoryReference, resolveServer, request } from "./client.js";
+import { resolveHistoryReference, resolveServer, request, fetchServer } from "./client.js";
 import { loadCliDefaults } from "./config-store.js";
 import { runMcpJob } from "./mcpJob.js";
 import { characterElementIdForMcp } from "./characterResolve.js";
@@ -41,7 +41,10 @@ async function writeBuffer(path, buffer) {
     await writeFile(path, buffer);
 }
 function failServer(jsonMode, error) {
+    const code = error?.code ?? "SERVER_REQUEST_FAILED";
     const message = error?.message || "server unreachable";
+    if (code !== "SERVER_UNREACHABLE")
+        fail({ json: jsonMode, code, message, exitCode: exitCodeForError(error) });
     if (jsonMode)
         err("Hint: start the server with `ima2 serve`.");
     fail({ json: jsonMode, code: "SERVER_UNREACHABLE", message: `${message}\nHint: run ima2 serve`, exitCode: 3 });
@@ -110,7 +113,7 @@ function validateCoreOptions(args, refs, model, lane) {
         die(2, check.error);
     return { duration, resolution, aspectRatio };
 }
-async function coreReferences(serverBase, refs) {
+async function coreReferences(serverBase, refs, jsonMode) {
     let latestPromise;
     return Promise.all(refs.map(async (path) => {
         if (path === "@last")
@@ -121,7 +124,8 @@ async function coreReferences(serverBase, refs) {
         return (await readFile(resolved)).toString("base64");
     })).catch((error) => {
         const typed = error;
-        return die(typed.code === "HISTORY_EMPTY" ? 5 : 1, typed.message || String(error));
+        return fail({ json: jsonMode, code: typed.code ?? "REFERENCE_FAILED", message: typed.message || String(error),
+            exitCode: typed.code === "HISTORY_EMPTY" ? 5 : exitCodeForError(error) });
     });
 }
 function coreBody(args, context, options, references, requestId) {
@@ -195,7 +199,10 @@ async function consumeCoreSse(url, body, args, requestId) {
             return null;
         if (!args.json && lastProgress >= 0)
             process.stdout.write("\n");
-        die(exitCodeForError(error), error.message);
+        if (!(error instanceof Error))
+            throw error;
+        fail({ json: Boolean(args.json), code: error.code ?? "VIDEO_FAILED",
+            message: error.message, exitCode: exitCodeForError(error) });
     }
     finally {
         clearTimeout(timer);
@@ -207,14 +214,14 @@ async function consumeCoreSse(url, body, args, requestId) {
 async function runCoreVideo(args, context) {
     const refs = (Array.isArray(args.ref) ? args.ref : []);
     const options = validateCoreOptions(args, refs, context.target.model, context.target.lane);
-    const references = await coreReferences(context.server.base, refs);
+    const references = await coreReferences(context.server.base, refs, Boolean(args.json));
     const requestId = createCliRequestId("req_cli_video");
     const done = await consumeCoreSse(`${context.server.base}/api/video/generate`, coreBody(args, context, options, references, requestId), args, requestId);
     if (!done?.filename)
         die(1, "server did not return a video filename");
     const filename = String(done.filename);
     const target = args.out ? String(args.out) : args["out-dir"] ? join(String(args["out-dir"]), filename) : join(config.storage.generatedDir, filename);
-    const response = await fetch(`${context.server.base}${done.url || `/generated/${encodeURIComponent(filename)}`}`, { signal: AbortSignal.timeout(parseInteger(args.timeout, MCP_VIDEO_TIMEOUT_MS / 1000, "--timeout") * 1000) });
+    const response = await fetchServer(context.server.base, String(done.url || `/generated/${encodeURIComponent(filename)}`), { signal: AbortSignal.timeout(parseInteger(args.timeout, MCP_VIDEO_TIMEOUT_MS / 1000, "--timeout") * 1000) });
     if (!response.ok)
         die(1, `failed to download video: HTTP ${response.status}`);
     await writeBuffer(target, Buffer.from(await response.arrayBuffer()));
@@ -357,7 +364,7 @@ function mcpMediaInputs(args, context, roles) {
     };
 }
 async function downloadMcpVideo(serverBase, url, target) {
-    const response = await fetch(`${serverBase}${url}`);
+    const response = await fetchServer(serverBase, url);
     if (!response.ok)
         die(1, `failed to download video: HTTP ${response.status}`);
     await writeBuffer(target, Buffer.from(await response.arrayBuffer()));
@@ -391,7 +398,8 @@ async function runMcpVideo(argv, args, context) {
     }
     catch (error) {
         const typed = error;
-        fail({ json: Boolean(args.json), code: typed.code ?? "MCP_GENERATION_FAILED", message: typed.message, exitCode: 1 });
+        fail({ json: Boolean(args.json), code: typed.code ?? "MCP_GENERATION_FAILED", message: typed.message,
+            exitCode: exitCodeForError(error) === 4 ? 4 : 1 });
     }
 }
 export async function runVideoGenerate(argv, args, prompt) {

package/config.js

@@ -8,17 +8,29 @@
 // `config.json` is loaded once at module import. Mutating the file at runtime
 // requires a server restart (same as env vars).
 //
-// Keep this module dependency-free aside from node:* built-ins to avoid
-// circular imports with lib/*.
+// Import only pure policy helpers from lib/*; never runtime owners that import config.
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync } from "node:fs";
+import { parsePublicOrigins } from "./lib/localAccessPolicy.js";
+export { SSE_STREAM_POLICY } from "./lib/eventsPolicy.js";
 import { deriveSupportedImageModels, deriveUnsupportedImageModels } from "./lib/providers/derive.js";
 import { DEFAULT_PROMPT_BUILDER_MODELS, PROMPT_BUILDER_BACKENDS, PROMPT_BUILDER_MODELS, } from "./lib/promptBuilder/constants.js";
 // 4.6 rewrites prompts in ways that read worse than 4.3 for this planner's job, which
 // is judged by the result rather than a benchmark. 4.6 stays selectable below.
 export const DEFAULT_GROK_PLANNER_MODEL = "grok-4.3";
+export const AGY_PROCESS_POLICY = Object.freeze({ timeoutMs: 360_000, terminateGraceMs: 1000, maxOutputBytes: 1_048_576 });
+export const AGY_ARTIFACT_POLICY = Object.freeze({ maxBytes: 52_428_800, chunkBytes: 65_536 });
+/** Per-process API admission; streaming frames do not consume request slots. */
+export const API_REQUEST_POLICY = Object.freeze({
+    windowMs: 60_000, requests: 600, mutations: 120, maxPeers: 4096,
+});
+export const LAN_SECURITY_POLICY = Object.freeze({
+    lanSessionTtlMs: 28_800_000, lanMaxSessions: 256,
+    lanAuthWindowMs: 60_000, lanAuthMaxFailures: 10,
+    lanAuthMaxBuckets: 4096, lanTokenMaxBytes: 4096,
+});
 export const GROK_PLANNER_MODELS = [
     DEFAULT_GROK_PLANNER_MODEL,
     "grok-4.6",
@@ -46,15 +58,21 @@ function loadConfigJson() {
             continue;
         try {
             const raw = readFileSync(p, "utf-8");
-            return JSON.parse(raw);
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return { values: parsed, source: p };
         }
         catch {
             // ignore malformed config.json; env+defaults still apply
         }
     }
-    return {};
+    return { values: {}, source: null };
 }
-const fileCfg = loadConfigJson();
+const loadedFileConfig = loadConfigJson();
+const fileCfg = loadedFileConfig.values;
+export const CONFIG_SOURCE_FILE = loadedFileConfig.source;
+const publicOriginsEnv = env.IMA2_PUBLIC_ORIGINS;
+const publicOriginsFile = fileCfg.server?.publicOrigins;
 function firstDefined(...vals) {
     return vals.find((v) => v !== undefined && v !== "");
 }
@@ -92,11 +110,29 @@ export function defaultLogLevelForEnv(runtimeEnv = env) {
     return runtimeEnv.IMA2_DEV === "1" ? "debug" : "info";
 }
 export const config = {
+    security: LAN_SECURITY_POLICY,
+    diagnostics: {
+        keyTimeoutMs: Math.min(30000, pickPositiveInt(env.IMA2_DIAGNOSTIC_KEY_TIMEOUT_MS, fileCfg.diagnostics?.keyTimeoutMs, 5000)),
+        runtimeTimeoutMs: Math.min(30000, pickPositiveInt(env.IMA2_DIAGNOSTIC_RUNTIME_TIMEOUT_MS, fileCfg.diagnostics?.runtimeTimeoutMs, 1500)),
+    },
     server: {
         // Accept both IMA2_PORT and legacy PORT.
         port: pickInt(firstDefined(env.IMA2_PORT, env.PORT), fileCfg.server?.port, 3333),
         host: pickStr(env.IMA2_HOST, fileCfg.server?.host, "127.0.0.1"),
         lanToken: env.IMA2_LAN_TOKEN || "",
+        // Lazy validation permits config rm to repair a bad file-layer value.
+        // Access policy snapshots this before listening; inputs stay import-time fixed.
+        get publicOrigins() {
+            try {
+                return parsePublicOrigins(publicOriginsEnv === undefined
+                    ? (publicOriginsFile === undefined ? [] : publicOriginsFile) : JSON.parse(publicOriginsEnv));
+            }
+            catch {
+                throw Object.assign(new Error("IMA2_PUBLIC_ORIGINS must be an array of exact HTTP(S) origins."), {
+                    code: "INVALID_PUBLIC_ORIGINS", status: 400,
+                });
+            }
+        },
         bodyLimit: pickStr(env.IMA2_BODY_LIMIT, fileCfg.server?.bodyLimit, "50mb"),
     },
     limits: {

package/docs/API.md

@@ -8,15 +8,63 @@ Base URL:
 http://localhost:3333
 ```
 
+## Local and LAN access
+
+The configured bind determines access mode. Loopback keeps single-user no-token
+use; a non-loopback bind requires `IMA2_LAN_TOKEN`, including requests arriving
+from a loopback proxy. LAN protects both `/api` and `/generated` before file,
+Range or conditional-response processing. UI/static assets remain public.
+
+| Endpoint | Contract |
+|---|---|
+| `GET /api/auth/lan/session` | No-store `{mode, authenticated, expiresAt}`; no token/cookie value returned |
+| `POST /api/auth/lan/session` | Same-origin `Origin`, JSON `{}`, valid `x-ima2-token`; 204 and an opaque HttpOnly/SameSite=Strict cookie in LAN mode |
+| `DELETE /api/auth/lan/session` | Same-origin `Origin` and presented cookie; revoke it and return 204 |
+
+Sessions are in memory, origin-bound and expire after an absolute eight hours.
+Restart/rotation invalidates them. Settings → General → Studio session signs out;
+sign-out/expiry closes admitted streams but does not cancel accepted generation.
+Reauthentication does not automatically submit a waiting generation again.
+The browser removes a supplied `?token=...` before loading App and never stores
+the token in local/sessionStorage; entering it in the sign-in form avoids putting
+it in initial URL/access logs. API clients can use `x-ima2-token`; legacy query
+tokens remain accepted. Header → query → cookie precedence applies. Malformed
+duplicates are rejected; an explicit invalid credential cannot fall back to a cookie.
+
+Serving Host/Origin must match the actual listener or exact configured
+`server.publicOrigins` / `IMA2_PUBLIC_ORIGINS` JSON array (maximum 16). No wildcards,
+userinfo, paths, query or fragments. This is a serving-origin list, not CORS
+permission: cross-origin and same-site sibling-origin requests remain rejected.
+Forwarded headers do not establish trust. The case-compatible exact GET MCP OAuth
+callback retains its existing state/PKCE check; admin stop still needs its nonce.
+
+For Vite development, use `http://127.0.0.1:5173` and explicitly include that origin
+on the backend (`IMA2_PUBLIC_ORIGINS='["http://127.0.0.1:5173"]'`). The dev proxy
+preserves Host. If opening `localhost` instead, list that exact origin too; local
+mode canonicalizes it to `127.0.0.1`, while LAN mode preserves the entered origin.
+
+LAN media uses `private, no-store, max-age=0`, no ETag/Last-Modified, and
+same-origin resource policy. JSON sidecars and outside-root links are not served;
+SVG retains its restrictive CSP. Previously cached/downloaded copies cannot be
+revoked: purge operator-controlled proxy caches during upgrade. HTTP LAN is for
+trusted networks only; use TLS/VPN on untrusted networks. HTTPS sessions use Secure
+cookies. A malicious process on the operator host is outside this boundary.
+
+Wrong/missing LAN credentials return `401 LAN_TOKEN_REQUIRED`; invalid Host/Origin
+returns 403. Bootstrap is limited to ten failed attempts per socket peer per minute
+and shares the app API request budget. Respect `Retry-After` on 429; a full
+256-session store returns 503 instead of evicting users. Tokens are bounded to
+4096 UTF-8 bytes. Access errors contain fixed messages, never supplied secrets.
+
 ## Provider Policy
 
 Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-api`) providers.
 
 - `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 Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.3` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. `grok-4.6` and `grok-4.5` remain selectable overrides. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
+- `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: "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 instead of the bundled progrok OAuth proxy. Same pipeline as `grok` (Web Search → planner → `/v1/images/generations`), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or `XAI_API_KEY` env var. Also supports video generation.
+- `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: "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.
@@ -27,8 +75,77 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 Grok video generation uses `POST /api/video/generate` (SSE). See the Video
 Generation section below for the full endpoint specification.
 
+### Grok image artifact retrieval
+
+Returned image URLs require HTTPS and a conservative numeric-address policy.
+Private/link-local/shared/loopback/documentation/transition destinations are
+rejected by default; every DNS answer and redirect hop is validated, and the
+connection uses only those validated addresses. No default re-resolution,
+connection pooling, API credential, cookie or referrer forwarding occurs.
+
+The exact server-configured proxy origin is a local exception only when it is
+the initial artifact origin. Leaving it permanently removes that exception for
+the chain: public→private-proxy and proxy→public→private-proxy cannot regain trust.
+At most five redirects and50MiB are accepted; the single30s default deadline
+covers DNS, retries, redirects and streamed bytes. An omitted/false Content-Length
+does not bypass the streamed cap. HTTP GET may retry under the existing policy;
+billable image POST is not automatically retried.
+
+The downloader reports `GROK_IMAGE_DOWNLOAD_FAILED`/502 for policy/body failures,
+`GROK_IMAGE_TIMEOUT`/504 for deadline, and `GENERATION_CANCELED`/499 for caller
+abort; existing surface error normalization still applies. Errors do not expose
+raw returned URL/query credentials. This restricted policy is not an exhaustive
+public-address/routability guarantee and does not change video or MCP URL policy.
+
+### Agy artifact reads and cleanup
+
+Reported and fallback artifact paths must be absolute regular files within the
+canonical `.gemini`, `.cache`, or system temporary roots. Intentionally relocated
+root directories remain supported; missing roots never broaden the boundary.
+Leaf symlinks, paths escaping those roots, unusable file identities and detected
+path/file replacement are rejected. The same checks apply to parsed result paths
+and fallback discovery; filename matching alone is not acceptance.
+
+The reader enforces an inclusive 50MiB limit before and during descriptor reads,
+using bounded blocks even when individual reads are short. A successful receipt
+authorizes cleanup only for that same checked file; replacements and unrelated
+siblings are left alone. Direct reader/operation cancellation returns
+`GENERATION_CANCELED`/499 after pending file I/O and descriptor close settle;
+existing node normalization can expose `INVALID_REQUEST`/499 instead.
+Policy-rejected artifacts are not deleted. The reader and Agy operation add no
+retries, but caller policies remain unchanged: reference-free node requests can
+retry once after retryable artifact errors, starting another generation attempt.
+
+`AGY_PATH_REJECTED`/502 covers the path/identity policy; `AGY_ARTIFACT_TOO_LARGE`/502
+covers overflow, and `AGY_ARTIFACT_NOT_FOUND`/502 covers missing reported files.
+Existing generation normalization may expose `code: UNKNOWN` while retaining
+the original `rawCode` and `errorClass: INTERNAL_STATE_ERROR`.
+Windows uses explicit path/identity checks without POSIX no-follow open flags.
+This is not an atomic filesystem sandbox against another same-user process, a
+hardlink-provenance guarantee, or a process-wide memory ceiling.
+
 ## Health And Status
 
+### Core provider surface metadata
+
+`GET /api/capabilities` includes `providerSurfaces[coreProviderId][surface]`.
+`GET /api/models` includes the same `surfaces` on each core lane; MCP lanes
+retain their existing model capabilities. Surfaces are `generate`, `edit`,
+`multimode`, `node`, and `video`.
+
+Each record contains `supported`, `references`, `mask`, `streaming`, and
+`catalogAccess` (`static` or `runtime`). These are application capability facts,
+not credential/liveness or entitlement checks. `references` means the surface
+can accept image input; a Comfy workflow still needs the appropriate binding.
+`streaming` describes partial-image delivery on Node/Multimode, not lifecycle SSE.
+
+NovelAI's generate/node/multimode entries are supported without references;
+edit/video are unsupported. Its models explicitly declare generation support,
+not fictitious edit support. Comfy is runtime-catalog backed: empty static
+model IDs do not disable its generate/edit/video surfaces, while node/multimode
+remain unsupported. Local capabilities expose the structural map without
+inventing a runtime `lanes` availability result.
+
 | Method | Path | Notes |
 |---|---|---|
 | `GET` | `/api/health` | Server health, version, paths, provider policy |
@@ -230,23 +347,23 @@ enabled alpha are V5-only. The four exact image models are
 text-to-image only: `NAI_REF_UNSUPPORTED`, `NAI_EDIT_UNSUPPORTED`, and
 `NAI_MASK_UNSUPPORTED` fail closed rather than discarding input.
 
-When `provider` is `"grok"`, supported models are `grok-imagine-image` and
-`grok-imagine-image-quality`. The server uses `grok-4.5` as the search/planner
-model by default (`IMA2_GROK_PLANNER_MODEL`) and times the mandatory search and
+When `provider` is `"grok"`, supported models include `grok-imagine-image-2.0`,
+`grok-imagine-image` and `grok-imagine-image-quality`. The server uses `grok-4.3`
+as the configured search/planner default (`IMA2_GROK_PLANNER_MODEL`) and times search and
 planner steps separately from the image call (`IMA2_GROK_PLANNER_TIMEOUT_MS`).
 For `n > 1`, search and planning run once and the planned prompt is reused for
-the image requests. Successful Grok classic generations report one mandatory
-web-search call in metadata.
+the image requests. Search-disabled classic generations report zero search calls;
+otherwise the shared plan reports one logical search call.
 
 If `references` are present on a Grok classic request, ima2 still performs the
-mandatory search and `grok-4.5` planning phases. The planner receives the
+configured planning phase, with search only when enabled. The planner receives the
 reference images as multimodal `image_url` inputs, and its forced
 `generate_image.prompt` argument is instructed to be English-only except for
 exact visible text requested by the user. The final image call then uses xAI
 `/v1/images/edits` with the same reference images instead of
 `/v1/images/generations`. This keeps image-to-image/reference context alive
-through the three-phase pipeline. xAI currently documents up to three source
-images for image editing, so Grok classic requests with more than three
+through the pipeline. The server permits up to three source images for these
+Grok classic requests; more than three
 references return `GROK_REF_TOO_MANY`.
 
 Grok size mapping:
@@ -280,9 +397,11 @@ With `provider: "grok"`, edit requests are sent to xAI `/v1/images/edits`
 through the bundled progrok proxy. Masked Grok edits are rejected before
 upstream with `GROK_MASK_UNSUPPORTED`.
 
-Grok multimode currently sends each image request directly to xAI Images API
-with the mapped `aspect_ratio`/`resolution`; the mandatory search + planner
-pipeline is limited to classic `/api/generate`.
+Grok multimode plans each attempted image in order and performs search only when
+enabled. Sparse successes retain their original attempt index: a failed first
+attempt cannot make the final sweep persist the second image twice. Identical
+bytes at different successful indices remain separate outputs. The internal
+originalIndexes array is not added to request/SSE/history/sidecar schemas.
 
 ### `POST /api/node/generate`
 
@@ -310,7 +429,7 @@ Body fields:
 
 When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Node-local references are allowed on both root and child/edit nodes; for child/edit nodes the parent image is sent first, then references, then the text prompt.
 
-With `provider: "grok"`, Node Mode uses the same xAI search + `grok-4.5` planner + Images API pipeline as classic generation. A parent node image, `externalSrc`, or extra references are passed to the planner and then to xAI `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return `GROK_REF_TOO_MANY` before upstream when that limit is exceeded. `quality: "high"` promotes the final image model to `grok-imagine-image-quality`.
+Grok Node Mode uses the configured planner and Images API, with search suppressed by `searchMode: "off"` or `webSearchEnabled: false`. A parent node image, `externalSrc`, or extra references are passed to the planner and then to `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. The server caps total input images at three, counting parent/current image plus references, and returns `GROK_REF_TOO_MANY` before upstream when exceeded. Existing quality-model resolution is unchanged.
 
 The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`. Alternatively, send `{ "async": true, "requestId": "req_xxx" }` in the body to receive `202 { requestId }` immediately and follow progress on `GET /api/events` (see Events section).
 
@@ -489,7 +608,7 @@ Grok prompt surfaces used by video APIs:
 
 | Code | Meaning |
 |---|---|
-| `VIDEO_PROVIDER_UNSUPPORTED` | Provider is not `"grok"` |
+| `VIDEO_PROVIDER_UNSUPPORTED` | Provider is not `"grok"` or `"grok-api"` |
 | `PROMPT_REQUIRED` | Empty or missing prompt |
 | `INVALID_GROK_VIDEO_MODEL` | Model not in valid set |
 | `INVALID_VIDEO_RESOLUTION` | Resolution is not 480p/720p/1080p, or 1080p was requested outside `grok-imagine-video-1.5` prompt-only T2V / I2V |
@@ -498,6 +617,24 @@ Grok prompt surfaces used by video APIs:
 | `GROK_VIDEO_REF_TOO_MANY` | More than 7 reference images |
 | `GROK_VIDEO_FAILED` | Upstream xAI video generation failed |
 | `GROK_VIDEO_FRAME_FAILED` | Server could not extract the parent video's last frame |
+| `GROK_VIDEO_DOWNLOAD_FAILED` | Download-stage HTTP, size, MIME, empty-body, MP4-prefix or read failure (502) |
+| `GROK_VIDEO_TIMEOUT` | The download's own non-resetting timeout expired (504) |
+| `GENERATION_CANCELED` | Caller cancellation observed while downloading, including custom reasons (499) |
+
+Completed Grok video artifacts are consumed incrementally with an inclusive
+**100 MiB** byte cap. Declared size and actual streamed bytes are checked before
+retaining an overflowing chunk; invalid/empty/aborted bodies do not reach caller
+persistence. Accepted MIME is MP4 or octet-stream (missing MIME defaults to MP4),
+and the existing minimum-length/`ftyp` prefix check is retained. This is not full
+MP4 decoding or a100MiB process-memory ceiling: fetch buffers, chunk overhead and
+downstream copies are separate. Safe GET retry ends at response headers; body
+failure never starts a new billed generation.
+
+The video destination policy is unchanged: initial HTTPS or the existing literal
+HTTP-loopback allowlist, with fetch's default redirect behavior. It does not gain
+the image downloader's DNS/private-address/per-hop pinning policy. Do not treat
+HTTPS alone or these body bounds as an SSRF/security guarantee. Download error
+status appears in the existing JSON or SSE/terminal envelope for each caller.
 
 ### `POST /api/video/edit`
 
@@ -751,7 +888,8 @@ Registered only when `config.features.cardNews` is true (`routes/cardNews.ts`).
 | `AGY_QUOTA_EXHAUSTED` | Gemini API quota exhausted (rate limit) |
 | `AGY_PARSE_FAILED` | Could not parse artifact path from agy output |
 | `AGY_ARTIFACT_NOT_FOUND` | Agy reported an artifact path that does not exist |
-| `AGY_PATH_REJECTED` | Agy artifact path was outside allowed directories |
+| `AGY_PATH_REJECTED` | Agy artifact path, file type, or identity failed the allowed-root policy |
+| `AGY_ARTIFACT_TOO_LARGE` | Agy artifact exceeded the inclusive 50MiB read limit |
 | `AGY_VIDEO_UNSUPPORTED` | Video generation is not supported by the Gemini (agy) provider |
 | `AGY_MASK_UNSUPPORTED` | Mask-based editing is not supported by the Gemini (agy) provider |
 | `AGY_REF_TOO_MANY` | Too many reference images for agy (max 3) |

package/docs/CLI.md

@@ -12,6 +12,7 @@ For a quick start, see the [main README](../README.md). For endpoint mapping, se
 | `ima2 setup` / `ima2 login` | Reconfigure saved auth (interactive) |
 | `ima2 status` | Show config and OAuth status |
 | `ima2 doctor` | Diagnose Node, package, config, and auth |
+| `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 |
@@ -24,10 +25,40 @@ These work on most client commands:
 
 | Flag | Meaning |
 |---|---|
-| `--server <url>` | Override server discovery (default uses `~/.ima2/server.json`, falls back to `IMA2_SERVER` env) |
+| `--server <url>` | Explicit server origin; overrides `IMA2_SERVER`, then credential-free advertise/default discovery |
 | `--json` | Emit machine-readable JSON instead of human-formatted output |
 | `-h`, `--help` | Show subcommand help |
 
+## LAN server authentication
+
+Export your private `IMA2_LAN_TOKEN`, then select the known server explicitly:
+
+```bash
+IMA2_SERVER=http://192.168.1.20:3333 ima2 ping --json
+ima2 models --server https://studio.example --json
+```
+
+The token goes only to the selected normalized HTTP(S) origin, never to arbitrary
+advertise entries, redirects or external returned media. Do not put credentials,
+query strings or non-root paths in `--server` / `IMA2_SERVER`. No token flag or
+cookie jar is used. Auth/forbidden failures exit 4 with a safe code; an unreachable
+explicit server exits 3. Explicit targets never silently fall back to local data.
+`--local`/`--offline` options keep their documented local behavior.
+
+For a proxy or changed published port, configure exact origins and restart:
+
+```bash
+ima2 config set server.publicOrigins '["https://studio.example"]' --yes
+ima2 config rm server.publicOrigins --yes
+```
+
+Invalid origin values are rejected without echoing them. Removal can recover an
+invalid primary or legacy file-layer value while preserving other settings; the
+edited full object is written privately to the primary path and the legacy file
+is retained. An invalid environment override must be unset or corrected separately.
+Config listings/get redact nested credentials; `config path` identifies the file.
+See [LAN HTTP/session and transport limits](API.md#local-and-lan-access).
+
 ## Agent discovery
 
 Agents should start from the packaged skill and capability commands instead of guessing from scattered help text.
@@ -278,6 +309,39 @@ download fields such as `ok`, `path`, and `filename`. `ima2 video continue
 
 ## Diagnostics
 
+`ima2 doctor --json` prints one JSON document with `schemaVersion: 1`, `mode`,
+`checks` and `summary`. Each check has a stable code, severity, evidence category
+and a fixed message/action. Exit0 means no failed checks; warnings alone do not
+fail. Exit1 means a prerequisite failed. Invalid flag combinations exit2 with
+stderr only. Standard mode retains provider-auth checks; missing OAuth can fail
+standard doctor even if a different provider is selected.
+
+Use `ima2 doctor --installation --json` to check only the package Node engine,
+runtime dependencies/CLI entries, in-memory SQLite binding, packaged skills and UI
+build. It does not load account/config files, repair anything, build the UI or make
+network requests. Missing optional provider credentials are not installation errors.
+It cannot combine with `--bundle`, `--verify-keys` or `--runtime`.
+
+`ima2 doctor --bundle --json` retains the legacy version/node/platform/hostnameHash/
+lanes fields and adds safe checks/summary. The compatibility hostname hash is not
+an anonymity guarantee. Machine reports omit arbitrary diagnostic text, raw paths,
+URLs, response bodies and credential values.
+
+`--verify-keys` explicitly checks registry-declared non-generating authentication
+endpoints. Configured/present is not verified, and successful authentication does
+not prove generation capability or balance. Authentication rejection, rate limit,
+upstream failure, network failure and timeout have different codes.
+
+`--runtime http://127.0.0.1:3333` explicitly checks only that loopback origin's
+`/api/health`; localhost and IPv6 loopback are also accepted. No credentials,
+redirects, arbitrary paths, query strings or server discovery are used. A version
+match proves a local response, not provider success. Authorization-required health
+responses direct the operator to the configured authorized client.
+
+Timeouts default to5000ms for key checks and1500ms for runtime health. Optional
+`IMA2_DIAGNOSTIC_KEY_TIMEOUT_MS` and `IMA2_DIAGNOSTIC_RUNTIME_TIMEOUT_MS` override
+them, capped at30000ms. Response cleanup remains inside the deadline.
+
 `ima2 doctor image-probe` runs live Responses probes that help classify image
 generation failures such as `EMPTY_RESPONSE`. It is intended for support
 bundles, especially when OAuth is green but a simple prompt produces no image.

package/docs/DOCKER.md

@@ -5,11 +5,13 @@ web UI and server from source and runs the Express server directly.
 
 ## Quick start
 
+First export your own strong, private `IMA2_LAN_TOKEN`. Do not deploy a sample token.
+
 ```bash
 docker build -t ima2-gen .
 docker run -d --name ima2 \
   -p 3333:3333 \
-  -e IMA2_LAN_TOKEN=change-me \
+  -e IMA2_LAN_TOKEN \
   -v ima2-data:/data \
   ima2-gen
 ```
@@ -17,11 +19,12 @@ docker run -d --name ima2 \
 Or with compose:
 
 ```bash
-IMA2_LAN_TOKEN=change-me docker compose up -d
+docker compose up -d
 ```
 
-Then open `http://localhost:3333/?token=change-me` (or send the token as an
-`x-ima2-token` header on API calls).
+Then open `http://localhost:3333/` and enter the token in the studio sign-in form.
+The browser uses a short-lived HttpOnly session for APIs, images, videos and SSE.
+CLI clients use the token environment variable with an explicit server origin.
 
 ## Why `IMA2_LAN_TOKEN` is required
 
@@ -38,6 +41,7 @@ container exits at startup with a clear error — that is by design, not a bug.
 | `IMA2_LAN_TOKEN` | — (required) | API access token for non-loopback bind |
 | `IMA2_PORT` | `3333` | Server port |
 | `IMA2_HOST` | `0.0.0.0` | Bind host |
+| `IMA2_PUBLIC_ORIGINS` | `[]` | JSON array of exact browser/proxy origins when address or published port differs |
 | `IMA2_CONFIG_DIR` | `/data` | Config + generated output + credentials |
 | `OPENAI_API_KEY` | — | Optional: API-key image provider |
 | `GEMINI_API_KEY` | — | Optional: Gemini API provider |
@@ -54,6 +58,17 @@ in `/data`.
 
 ## Limitations
 
+For `-p 8080:3333`, also pass
+`-e IMA2_PUBLIC_ORIGINS='["http://localhost:8080"]'`. Add the exact LAN IP/DNS URL
+used by remote browsers as needed. A TLS proxy must preserve external Host and
+Origin, forward Set-Cookie and avoid caching or logging token queries. Do not use
+a loopback bind behind an external proxy as a substitute for LAN authentication.
+HTTP does not encrypt credentials; use trusted networks or TLS/VPN.
+
+LAN generated media is now private/no-store. Old proxy/browser cached copies may
+outlive an upgrade or sign-out; purge caches you control. Restart invalidates browser
+sessions without deleting files. [Full access contract](API.md#local-and-lan-access).
+
 - The image runs the server only. CLI workflows (`ima2 gen`, etc.) can exec
   into the container (`docker exec -it ima2 node bin/ima2.js …`) but are
   primarily designed for host installs.