ima2-gen 3.5.2 → 3.5.3

package/README.md

@@ -314,7 +314,9 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `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` | `60000` | Timeout for Grok search and planner calls |
+| `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) |
+| `IMA2_GROK_VIDEO_PLAN_TOTAL_TIMEOUT_MS` | `1500000` | Ceiling on the whole video planning phase (clamped above search + planner) |
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-quality` | Default final Grok image model |
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `120000` | Timeout for the final Grok Images API call |

package/bin/commands/video.js

@@ -6,6 +6,7 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import { runVideoGenerate } from "../lib/videoMcp.js";
 import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS, GROK_VIDEO_MODEL_BASE, validateVideoResolutionForRequest, } from "../../lib/imageModels.js";
+import { VIDEO_CLIENT_TIMEOUT_SEC } from "../../lib/videoClientTimeouts.js";
 const VALID_RESOLUTIONS = new Set(["480p", "720p", "1080p"]);
 const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
 const VALID_MODELS = new Set([GROK_VIDEO_MODEL_BASE, GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS]);
@@ -40,7 +41,7 @@ async function readJsonResponse(res, label) {
     }
 }
 function parseTimeoutSeconds(seconds) {
-    const sec = parseIntegerFlag(seconds, 600, "--timeout");
+    const sec = parseIntegerFlag(seconds, VIDEO_CLIENT_TIMEOUT_SEC, "--timeout");
     if (sec < 1)
         die(2, "--timeout must be at least 1");
     return sec;
@@ -82,7 +83,7 @@ const SPEC = {
         out: { short: "o", type: "string" },
         "out-dir": { short: "d", type: "string" },
         json: { type: "boolean" },
-        timeout: { type: "string", default: "600" },
+        timeout: { type: "string", default: String(VIDEO_CLIENT_TIMEOUT_SEC) },
         server: { type: "string" },
         session: { type: "string" },
         help: { short: "h", type: "boolean" },
@@ -126,7 +127,7 @@ const HELP = `
     -o, --out <file>                    Output file path
     -d, --out-dir <dir>                 Output directory
         --json                          Print JSON result to stdout
-        --timeout <sec>                 Default: 600
+        --timeout <sec>                 Default: 5400
         --server <url>                  Override server URL
         --session <id>                  Session ID
 
@@ -210,11 +211,11 @@ async function runVideoGenerateRequest(serverBase, body, timeout, silent) {
 }
 // --- Subcommands ---
 async function videoEditCmd(argv) {
-    const spec = { flags: { video: { type: "string" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: "600" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+    const spec = { flags: { video: { type: "string" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: String(VIDEO_CLIENT_TIMEOUT_SEC) }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
     const args = parseArgs(argv, spec);
     rejectUnknownFlags(args);
     if (args.help) {
-        out(`  ima2 video edit <prompt> --video <url|file_id|generated-file>\n\n  Edit existing video with text prompt (real V2V).\n  Model: grok-imagine-video only. Input: mp4, max 8.7s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n    -o, --out <file>      Download edited video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 600\n        --server <url>    Override server URL`);
+        out(`  ima2 video edit <prompt> --video <url|file_id|generated-file>\n\n  Edit existing video with text prompt (real V2V).\n  Model: grok-imagine-video only. Input: mp4, max 8.7s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n    -o, --out <file>      Download edited video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 5400\n        --server <url>    Override server URL`);
         return;
     }
     const prompt = args.positional.join(" ");
@@ -246,11 +247,11 @@ async function videoEditCmd(argv) {
     }
 }
 async function videoExtendCmd(argv) {
-    const spec = { flags: { video: { type: "string" }, duration: { type: "string", default: "6" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: "600" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+    const spec = { flags: { video: { type: "string" }, duration: { type: "string", default: "6" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: String(VIDEO_CLIENT_TIMEOUT_SEC) }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
     const args = parseArgs(argv, spec);
     rejectUnknownFlags(args);
     if (args.help) {
-        out(`  ima2 video extend <prompt> --video <url|file_id|generated-file> [--duration 6]\n\n  Extend video from its last frame.\n  Model: grok-imagine-video only. Extension: 2-10s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n        --duration <2-10> Extension duration (default: 6)\n    -o, --out <file>      Download extended video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 600\n        --server <url>    Override server URL`);
+        out(`  ima2 video extend <prompt> --video <url|file_id|generated-file> [--duration 6]\n\n  Extend video from its last frame.\n  Model: grok-imagine-video only. Extension: 2-10s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n        --duration <2-10> Extension duration (default: 6)\n    -o, --out <file>      Download extended video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 5400\n        --server <url>    Override server URL`);
         return;
     }
     const prompt = args.positional.join(" ");
@@ -297,7 +298,7 @@ async function videoContinueCmd(argv) {
             out: { short: "o", type: "string" },
             output: { type: "string" },
             json: { type: "boolean" },
-            timeout: { type: "string", default: "600" },
+            timeout: { type: "string", default: String(VIDEO_CLIENT_TIMEOUT_SEC) },
             server: { type: "string" },
             help: { short: "h", type: "boolean" },
         },
@@ -305,7 +306,7 @@ async function videoContinueCmd(argv) {
     const args = parseArgs(argv, spec);
     rejectUnknownFlags(args);
     if (args.help) {
-        out(`  ima2 video continue <prompt> --video <generated-file>\n\n  Generate a new clip from a generated video's last frame and carry branch-local revisedPrompt lineage.\n\n  Prompt must describe visual flow, motion, sound/music/no-music, dialogue/no-dialogue, ending frame, and how the selected duration should feel naturally filled.\n\n  Options:\n        --video <file>                 Generated .mp4 filename (required)\n        --duration <1..15>             Default: 5. Prompt motion should naturally fill this length\n        --resolution <480p|720p|1080p> Default: 720p. 1080p requires --model grok-imagine-video-1.5\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5 (preview alias accepted)\n    -o, --out <file>                   Download continued video to file\n        --output <file>                Alias for --out\n        --json                         Print JSON result\n        --timeout <sec>                Default: 600\n        --server <url>                 Override server URL`);
+        out(`  ima2 video continue <prompt> --video <generated-file>\n\n  Generate a new clip from a generated video's last frame and carry branch-local revisedPrompt lineage.\n\n  Prompt must describe visual flow, motion, sound/music/no-music, dialogue/no-dialogue, ending frame, and how the selected duration should feel naturally filled.\n\n  Options:\n        --video <file>                 Generated .mp4 filename (required)\n        --duration <1..15>             Default: 5. Prompt motion should naturally fill this length\n        --resolution <480p|720p|1080p> Default: 720p. 1080p requires --model grok-imagine-video-1.5\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5 (preview alias accepted)\n    -o, --out <file>                   Download continued video to file\n        --output <file>                Alias for --out\n        --json                         Print JSON result\n        --timeout <sec>                Default: 5400\n        --server <url>                 Override server URL`);
         return;
     }
     const prompt = args.positional.join(" ");

package/bin/lib/videoMcp.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { config } from "../../config.js";
 import { deriveVideoMode, 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 { loadCliDefaults } from "./config-store.js";
@@ -13,7 +14,10 @@ import { createCliRequestId } from "./recover-output.js";
 import { streamSse } from "./sse.js";
 const VALID_RESOLUTIONS = new Set(["480p", "720p", "1080p"]);
 const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
-const MCP_VIDEO_TIMEOUT_MS = 12 * 60_000 + 120_000 + 30_000;
+// Shared client ceiling (see lib/videoClientTimeouts.ts). Also guards the
+// runway/higgsfield MCP lanes, which end on their own terminal events, so a longer
+// ceiling is harmless there.
+const MCP_VIDEO_TIMEOUT_MS = VIDEO_CLIENT_TIMEOUT_MS;
 const MCP_LANES = new Set(["runway", "higgsfield"]);
 function parseInteger(value, fallback, label) {
     const raw = value === undefined ? String(fallback) : String(value);
@@ -134,7 +138,7 @@ function coreBody(args, context, options, references, requestId) {
 async function consumeCoreSse(url, body, args, requestId) {
     const controller = new AbortController();
     let timedOut = false;
-    const timeoutMs = parseInteger(args.timeout, 600, "--timeout") * 1000;
+    const timeoutMs = parseInteger(args.timeout, MCP_VIDEO_TIMEOUT_MS / 1000, "--timeout") * 1000;
     const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
     const onSignal = () => { controller.abort(); process.exit(130); };
     process.once("SIGINT", onSignal);
@@ -192,7 +196,7 @@ async function runCoreVideo(args, context) {
         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, 600, "--timeout") * 1000) });
+    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) });
     if (!response.ok)
         die(1, `failed to download video: HTTP ${response.status}`);
     await writeBuffer(target, Buffer.from(await response.arrayBuffer()));
@@ -373,7 +377,7 @@ async function runMcpVideo(argv, args, context) {
     }
 }
 export async function runVideoGenerate(argv, args, prompt) {
-    if (parseInteger(args.timeout, 600, "--timeout") < 1)
+    if (parseInteger(args.timeout, MCP_VIDEO_TIMEOUT_MS / 1000, "--timeout") < 1)
         die(2, "--timeout must be at least 1");
     const { server, catalog } = await fetchCatalog(args);
     const target = resolveVideoTarget(args, catalog);

package/config.js

@@ -165,7 +165,12 @@ export const config = {
         nodeHexBytes: pickInt(env.IMA2_NODE_HEX_BYTES, fileCfg.ids?.nodeHexBytes, 5),
     },
     inflight: {
-        ttlMs: pickInt(env.IMA2_INFLIGHT_TTL_MS, fileCfg.inflight?.ttlMs, 10 * 60 * 1000),
+        // Must exceed the longest legal request. Grok video can legitimately run ~70 min
+        // (planning + start + poll + poll overshoot + download), and purgeStaleJobs() drops the
+        // job row without aborting its worker, so a 10-minute TTL used to erase live jobs
+        // mid-flight.
+        // devlog/_plan/260817_grok_video_planner_timeout/010_timeout_budgets.md
+        ttlMs: pickInt(env.IMA2_INFLIGHT_TTL_MS, fileCfg.inflight?.ttlMs, 90 * 60 * 1000),
         reapMs: pickInt(env.IMA2_INFLIGHT_REAP_MS, fileCfg.inflight?.reapMs, 60 * 1000),
         terminalTtlMs: pickInt(env.IMA2_INFLIGHT_TERMINAL_TTL_MS, fileCfg.inflight?.terminalTtlMs, 5 * 60 * 1000),
     },
@@ -200,21 +205,33 @@ export const config = {
         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),
-        // grok-4.6 web-search planning measured ~72 s against the live proxy and a full
-        // search+generate round trip measured ~202 s, so the old 60 s budget aborted every
-        // default-path search. 300 s absorbs slow search days with room to spare.
-        plannerTimeoutMs: pickInt(env.IMA2_GROK_PLANNER_TIMEOUT_MS, fileCfg.grokProvider?.plannerTimeoutMs, 300_000),
+        // 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
+        // was a planner call that STALLED for its entire 300 s budget while an isolated probe
+        // of the same payload answered in 32 s. Budgets are therefore calibrated against the
+        // stall, not the probe: 900 s is 3x the observed stall.
+        // devlog/_plan/260817_grok_video_planner_timeout/010_timeout_budgets.md
+        plannerTimeoutMs: pickInt(env.IMA2_GROK_PLANNER_TIMEOUT_MS, fileCfg.grokProvider?.plannerTimeoutMs, 900_000),
+        // The web-search brief gets its own bound: it is an enhancement, not a requirement, so
+        // it degrades instead of failing the request (lib/grokVideoAdapter.ts).
+        searchTimeoutMs: pickInt(env.IMA2_GROK_SEARCH_TIMEOUT_MS, fileCfg.grokProvider?.searchTimeoutMs, 300_000),
+        // Wired ceiling on search + planner combined, so the two stages cannot sum unbounded.
+        // It must be STRICTLY greater than searchTimeoutMs + plannerTimeoutMs (invariant enforced
+        // by tests): if it equals the sum, a slow search followed by a stalled planner lands both
+        // timers together, the phase ceiling wins the race, and the local planner fallback never
+        // runs. The margin exists so the planner's own timeout always fires first.
+        videoPlanTotalTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_PLAN_TOTAL_TIMEOUT_MS, fileCfg.grokProvider?.videoPlanTotalTimeoutMs, 1_500_000),
         defaultImageModel: pickStr(env.IMA2_GROK_IMAGE_MODEL_DEFAULT, fileCfg.grokProvider?.defaultImageModel, "grok-imagine-image-2.0"),
         // grok-imagine-image-2.0 measured 43-97 s per image; 2k/batch requests run longer,
         // so the image call gets the same generous 300 s ceiling as the planner.
         generationTimeoutMs: pickInt(env.IMA2_GROK_GENERATION_TIMEOUT_MS, fileCfg.grokProvider?.generationTimeoutMs, 300_000),
         statusTimeoutMs: pickInt(env.IMA2_GROK_STATUS_TIMEOUT_MS, fileCfg.grokProvider?.statusTimeoutMs, 3000),
         defaultVideoModel: pickStr(env.IMA2_GROK_VIDEO_MODEL_DEFAULT, fileCfg.grokProvider?.defaultVideoModel, "grok-imagine-video-1.5"),
-        videoStartTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_START_TIMEOUT_MS, fileCfg.grokProvider?.videoStartTimeoutMs, 150_000),
+        videoStartTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_START_TIMEOUT_MS, fileCfg.grokProvider?.videoStartTimeoutMs, 300_000),
         videoPollIntervalMs: pickInt(env.IMA2_GROK_VIDEO_POLL_INTERVAL_MS, fileCfg.grokProvider?.videoPollIntervalMs, 5_000),
         videoPollMaxConsecutiveErrors: pickInt(env.IMA2_GROK_VIDEO_POLL_MAX_ERRORS, fileCfg.grokProvider?.videoPollMaxConsecutiveErrors, 5),
-        videoTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_TIMEOUT_MS, fileCfg.grokProvider?.videoTimeoutMs, 900_000),
-        videoDownloadTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_DOWNLOAD_TIMEOUT_MS, fileCfg.grokProvider?.videoDownloadTimeoutMs, 120_000),
+        videoTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_TIMEOUT_MS, fileCfg.grokProvider?.videoTimeoutMs, 1_800_000),
+        videoDownloadTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_DOWNLOAD_TIMEOUT_MS, fileCfg.grokProvider?.videoDownloadTimeoutMs, 300_000),
     },
     // Direct MiniMax image-generation provider (text-to-image / image-to-image).
     // Region selects the global (.io) or China (.minimaxi.com) OpenAI-compatible

package/docs/CLI.md

@@ -162,7 +162,7 @@ Video generate flags:
 | `--ref <file>` | Attach source/reference image (repeatable, max 7) |
 | `-o, --out <file>` | Output file path |
 | `-d, --out-dir <dir>` | Output directory |
-| `--timeout <sec>` | Timeout in seconds (default: 600) |
+| `--timeout <sec>` | Timeout in seconds (default: 5400) |
 | `--session <id>` | Session ID |
 
 Blank video prompts are rejected. Prompts should include visual flow, camera or
@@ -181,7 +181,7 @@ Video edit/extend flags:
 | `--duration <2..10>` | Extension duration only (default: 6) |
 | `-o, --out <file>` | Download the edited or extended video to a file |
 | `--json` | Print JSON result |
-| `--timeout <sec>` | Timeout in seconds (default: 600) |
+| `--timeout <sec>` | Timeout in seconds (default: 5400) |
 
 Video continue flags:
 

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 360 (runtime: 157, contract: 203)
+Total: 362 (runtime: 159, contract: 203)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -66,6 +66,8 @@ Total: 360 (runtime: 157, contract: 203)
 - `tests/grok-size-mapper.test.ts`
 - `tests/grok-upstream-retry.test.ts`
 - `tests/grokVideoAdapter.test.ts`
+- `tests/grokVideoPlannerFallback.test.ts`
+- `tests/grokVideoTimeoutBudgets.test.ts`
 - `tests/history-metadata-fallback.test.ts`
 - `tests/history-tombstone.test.ts`
 - `tests/history-video-row.test.ts`

package/lib/errors/providerMap.js

@@ -48,6 +48,7 @@ export const PROVIDER_ERROR_MAP = {
     GROK_VIDEO_INVALID_MODE: "CAPABILITY_UNSUPPORTED",
     GROK_VIDEO_MODERATION_BLOCKED: "CONTENT_REJECTED",
     GROK_VIDEO_POLL_FAILED: "NETWORK_FAILURE",
+    GROK_VIDEO_PLAN_TIMEOUT: "PROVIDER_TIMEOUT",
     GROK_VIDEO_REF_TOO_MANY: "CAPABILITY_UNSUPPORTED",
     GROK_VIDEO_REQUEST_FAILED: "CAPABILITY_UNSUPPORTED",
     GROK_VIDEO_TIMEOUT: "PROVIDER_TIMEOUT",

package/lib/grokImageAdapter.js

@@ -182,7 +182,10 @@ export async function searchGrokVisualContext(prompt, ctx, options = {}) {
     const plannerModel = options.plannerModel || planner.model;
     const payload = buildGrokSearchPayload(prompt, plannerModel);
     const { url, headers } = getGrokEndpoint(ctx, "/v1/responses", options.directApiKey);
-    const { combinedSignal, timer } = withTimeoutSignal(options.signal, planner.timeoutMs);
+    // The search brief has its own, smaller budget: it runs BEFORE the planner call inside
+    // the same user request, so charging it the full planner budget lets one slow stage eat
+    // the other's time. See devlog/_plan/260817_grok_video_planner_timeout/010.
+    const { combinedSignal, timer } = withTimeoutSignal(options.signal, planner.searchTimeoutMs);
     logEvent("grok", "search:start", { requestId: options.requestId, plannerModel, promptChars: prompt.length });
     try {
         // Safe to replay: search produces no billable artifact, only a research summary.

package/lib/grokImageCore.js

@@ -39,7 +39,10 @@ export function getPlannerConfig(ctx) {
     const grokCfg = ctx.config.grokProvider || {};
     return {
         model: grokCfg.plannerModel || DEFAULT_GROK_PLANNER_MODEL,
-        timeoutMs: grokCfg.plannerTimeoutMs || 300_000,
+        timeoutMs: grokCfg.plannerTimeoutMs || 900_000,
+        // The forced web_search brief is bounded separately: it is an enhancement, so a slow
+        // search should cost a less-researched prompt, not the whole generation.
+        searchTimeoutMs: grokCfg.searchTimeoutMs || 300_000,
     };
 }
 export function withTimeoutSignal(signal, timeoutMs) {

package/lib/grokVideoAdapter.js

@@ -1,10 +1,10 @@
-import { logEvent } from "./logger.js";
+import { logEvent, logWarn } from "./logger.js";
 import { grokError, searchGrokVisualContext } from "./grokImageAdapter.js";
 import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
 import { detectImageMimeFromB64 } from "./refs.js";
 import { aspectToCanvas, generateWhiteCanvasB64 } from "./grokVideoCanvas.js";
 import { downloadVideo } from "./grokVideoDownload.js";
-import { buildGrokVideoPlannerSystemPrompt, formatDurationPacingGuidance } from "./grokVideoPlannerPrompt.js";
+import { buildGrokVideoPlannerSystemPrompt, composeFallbackVideoPrompt, formatDurationPacingGuidance } from "./grokVideoPlannerPrompt.js";
 import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS, GROK_VIDEO_MODEL_BASE, MAX_REF2V_REFERENCES, validateVideoResolutionForRequest, } from "./imageModels.js";
 import { formatVideoContinuityForPlanner } from "./videoContinuity.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
@@ -13,6 +13,34 @@ import { pollVideoUntilDone } from "./grokVideoPoll.js";
 export { downloadVideo } from "./grokVideoDownload.js";
 export { normalizeVideoPoll } from "./grokVideoShared.js";
 export { isRecoverablePollError, pollVideoOnce, pollVideoUntilDone } from "./grokVideoPoll.js";
+/**
+ * A planner failure is degradable when retrying or waiting could plausibly have produced a
+ * prompt: a stall, an upstream 5xx, or a network fault.
+ *
+ * A 4xx is NOT degradable — the request itself is malformed or unauthorized, and generating
+ * a video anyway would spend the user's quota on a request the provider already rejected.
+ *
+ * Neither is a 200 that carries no usable tool call: the planner ANSWERED and declined or
+ * malfunctioned, which is a judgment about the request rather than an availability problem.
+ * Billing a video start on the back of a refusal is worse for the user than an honest error.
+ */
+export function isDegradablePlannerFailure(err) {
+    const message = typeof err?.message === "string" ? err.message : "planner unavailable";
+    if (err?.name === "AbortError")
+        return { reason: "timeout", message };
+    const code = typeof err?.code === "string" ? err.code : "";
+    if (code === "GROK_PLANNER_TIMEOUT")
+        return { reason: "timeout", message };
+    if (code === "GROK_PLANNER_NETWORK_FAILED")
+        return { reason: "failed", message };
+    const status = typeof err?.status === "number" ? err.status : 0;
+    if (code === "GROK_PLANNER_BAD_REQUEST" && status >= 500)
+        return { reason: "failed", message };
+    // 429 is the same availability class as a stall: the upstream is saturated, not offended.
+    if (code === "GROK_PLANNER_BAD_REQUEST" && status === 429)
+        return { reason: "failed", message };
+    return null;
+}
 function canonicalVideoModel(model) {
     return model === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : model;
 }
@@ -117,46 +145,132 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
     const aspectRatio = options.aspectRatio || "auto";
     const plannerModel = options.plannerModel || cfg.plannerModel;
     const model = canonicalVideoModel(options.model || cfg.model);
-    const search = await searchGrokVisualContext(prompt, ctx, { ...(options.signal ? { signal: options.signal } : {}), ...(options.requestId ? { requestId: options.requestId } : {}), ...(options.directApiKey ? { directApiKey: options.directApiKey } : {}), plannerModel });
-    const referenceImageUrls = (options.referenceImages ?? []).map((img) => sourceImageUrl(img, undefined));
-    const payload = buildGrokVideoPlannerPayload(prompt, {
-        model,
-        mode,
-        duration,
-        resolution,
-        aspectRatio,
-        plannerModel,
-        searchSummary: search.summary,
-        sourceImageUrl: options.sourceImage ? sourceImageUrl(options.sourceImage, options.sourceMime) : undefined,
-        referenceImageUrls,
-        continuityLineage: options.continuityLineage,
-        backgroundConstraint: options.backgroundConstraint,
-    });
-    const { url, headers } = videoEndpoint(ctx, "/v1/chat/completions", options.directApiKey);
-    const { combinedSignal, timer } = withTimeoutSignal(options.signal, cfg.plannerTimeoutMs);
-    logEvent("grok", "video:planner:start", { requestId: options.requestId, mode, duration, resolution });
+    // One deadline for the whole planning phase. Both stages run under it, so search and
+    // planner can never sum to two independent budgets (the shape of the 360 s failure).
+    // devlog/_plan/260817_grok_video_planner_timeout/010_timeout_budgets.md
+    const phase = withTimeoutSignal(options.signal, cfg.planTotalTimeoutMs);
+    const phaseSignal = phase.combinedSignal;
+    /** A phase-ceiling abort is fatal; it must never be mistaken for a degradable failure. */
+    const phaseExpired = () => phaseSignal.aborted && !options.signal?.aborted;
     try {
-        // Safe to replay: the planner produces no billable artifact, only a prompt.
-        const res = await grokFetchWithRetry(() => fetch(url, { method: "POST", headers, body: JSON.stringify(payload), signal: combinedSignal }), { signal: combinedSignal, label: "video-planner" });
-        clearTimeout(timer);
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            throw grokError(`Grok video planner failed: ${text || `HTTP ${res.status}`}`, res.status >= 500 ? 502 : res.status, "GROK_PLANNER_BAD_REQUEST");
+        // The web-search brief is an enhancement, not a requirement: a slow or failing search
+        // used to abort the whole video request (GROK_PLANNER_TIMEOUT / GROK_SEARCH_TIMEOUT).
+        // Degrade instead, and keep the planner's own budget intact.
+        // devlog/_plan/260817_grok_video_planner_timeout/020_search_resilience.md
+        let searchSummary;
+        let searchDegraded;
+        try {
+            // Pass the PHASE signal, never a locally wrapped search timer: searchGrokVisualContext
+            // reports any abort of its `options.signal` as a user cancellation, so handing it our
+            // own deadline would turn a slow search — the exact case 020 exists to degrade — into
+            // GENERATION_CANCELED. The stage bound is applied inside that function via
+            // getPlannerConfig().searchTimeoutMs.
+            const search = await searchGrokVisualContext(prompt, ctx, { signal: phaseSignal, ...(options.requestId ? { requestId: options.requestId } : {}), ...(options.directApiKey ? { directApiKey: options.directApiKey } : {}), plannerModel });
+            searchSummary = search.summary;
         }
-        const planPrompt = parseGrokVideoPlanPrompt(await res.json());
-        logEvent("grok", "video:planner:done", { requestId: options.requestId, mode, promptChars: planPrompt.length });
-        return { prompt: planPrompt, mode, duration, resolution, aspectRatio, webSearchCalls: 1 };
-    }
-    catch (e) {
-        clearTimeout(timer);
-        if (e.name === "AbortError") {
+        catch (e) { // justified: adapter rejections are untyped; the shape is narrowed here
+            // A user cancellation is a real cancellation and must never be swallowed. Neither is
+            // the planning-phase ceiling: searchGrokVisualContext reports an inherited abort as its
+            // own cancellation, so without this check a ceiling hit would "degrade" and then start
+            // the planner after the phase had already expired.
+            if (options.signal?.aborted)
+                throw e;
+            if (phaseExpired())
+                throw grokError("Grok video planning timed out", 504, "GROK_VIDEO_PLAN_TIMEOUT");
+            if (e?.code === "GENERATION_CANCELED")
+                throw e;
+            searchDegraded = {
+                reason: e?.code === "GROK_SEARCH_TIMEOUT" ? "timeout" : "failed",
+                message: typeof e?.message === "string" ? e.message : "web search unavailable",
+            };
+            logWarn("grok", "video:search:degraded", {
+                requestId: options.requestId,
+                reason: searchDegraded.reason,
+                error: searchDegraded.message,
+            });
+        }
+        const referenceImageUrls = (options.referenceImages ?? []).map((img) => sourceImageUrl(img, undefined));
+        const payload = buildGrokVideoPlannerPayload(prompt, {
+            model,
+            mode,
+            duration,
+            resolution,
+            aspectRatio,
+            plannerModel,
+            searchSummary,
+            sourceImageUrl: options.sourceImage ? sourceImageUrl(options.sourceImage, options.sourceMime) : undefined,
+            referenceImageUrls,
+            continuityLineage: options.continuityLineage,
+            backgroundConstraint: options.backgroundConstraint,
+        });
+        const { url, headers } = videoEndpoint(ctx, "/v1/chat/completions", options.directApiKey);
+        const { combinedSignal, timer } = withTimeoutSignal(phaseSignal, cfg.plannerTimeoutMs);
+        logEvent("grok", "video:planner:start", { requestId: options.requestId, mode, duration, resolution });
+        try {
+            // Safe to replay: the planner produces no billable artifact, only a prompt.
+            const res = await grokFetchWithRetry(() => fetch(url, { method: "POST", headers, body: JSON.stringify(payload), signal: combinedSignal }), { signal: combinedSignal, label: "video-planner" });
+            clearTimeout(timer);
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw grokError(`Grok video planner failed: ${text || `HTTP ${res.status}`}`, res.status >= 500 ? 502 : res.status, "GROK_PLANNER_BAD_REQUEST");
+            }
+            const planPrompt = parseGrokVideoPlanPrompt(await res.json());
+            logEvent("grok", "video:planner:done", { requestId: options.requestId, mode, promptChars: planPrompt.length });
+            return {
+                prompt: planPrompt,
+                mode,
+                duration,
+                resolution,
+                aspectRatio,
+                // Honest accounting: no brief means no billable search call was completed.
+                webSearchCalls: searchDegraded ? 0 : 1,
+                ...(searchDegraded ? { searchDegraded } : {}),
+            };
+        }
+        catch (e) {
+            clearTimeout(timer);
+            // Real cancellation and the planning-phase ceiling are always fatal.
             if (options.signal?.aborted)
                 throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
-            throw grokError("Grok video planner timed out", 504, "GROK_PLANNER_TIMEOUT");
+            if (phaseExpired())
+                throw grokError("Grok video planning timed out", 504, "GROK_VIDEO_PLAN_TIMEOUT");
+            const normalized = e.name === "AbortError"
+                ? grokError("Grok video planner timed out", 504, "GROK_PLANNER_TIMEOUT")
+                : (e.code && e.status ? e : grokError(`Grok video planner request failed: ${e.message}`, 502, "GROK_PLANNER_NETWORK_FAILED"));
+            // A stalled or broken planner must not cost the user their video: the user's own
+            // prompt is already usable, so compose one locally and continue. 4xx stays fatal.
+            // devlog/_plan/260817_grok_video_planner_timeout/040_planner_fallback.md
+            const degradable = isDegradablePlannerFailure(normalized);
+            if (!degradable)
+                throw normalized;
+            const fallbackPrompt = composeFallbackVideoPrompt(prompt, {
+                mode,
+                duration,
+                resolution,
+                searchSummary,
+                continuityText: formatVideoContinuityForPlanner(options.continuityLineage) || undefined,
+                backgroundConstraint: options.backgroundConstraint,
+            });
+            logWarn("grok", "video:planner:degraded", {
+                requestId: options.requestId,
+                reason: degradable.reason,
+                error: degradable.message,
+                promptChars: fallbackPrompt.length,
+            });
+            return {
+                prompt: fallbackPrompt,
+                mode,
+                duration,
+                resolution,
+                aspectRatio,
+                webSearchCalls: searchDegraded ? 0 : 1,
+                ...(searchDegraded ? { searchDegraded } : {}),
+                plannerDegraded: degradable,
+            };
         }
-        if (e.code && e.status)
-            throw e;
-        throw grokError(`Grok video planner request failed: ${e.message}`, 502, "GROK_PLANNER_NETWORK_FAILED");
+    }
+    finally {
+        clearTimeout(phase.timer);
     }
 }
 export function buildVideoGenerationPayload(plan, opts) {
@@ -288,5 +402,7 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
         requestedModel: model,
         effectiveModel,
         modelFallback,
+        ...(plan.searchDegraded ? { searchDegraded: plan.searchDegraded } : {}),
+        ...(plan.plannerDegraded ? { plannerDegraded: plan.plannerDegraded } : {}),
     };
 }

package/lib/grokVideoDownload.js

@@ -3,7 +3,7 @@ import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
 const MAX_VIDEO_DOWNLOAD_BYTES = 100 * 1024 * 1024;
 function downloadTimeoutMs(ctx) {
     const g = ctx.config.grokProvider || {};
-    return g.videoDownloadTimeoutMs || 120_000;
+    return g.videoDownloadTimeoutMs || 300_000;
 }
 function withTimeoutSignal(signal, timeoutMs) {
     const timeoutController = new AbortController();

package/lib/grokVideoPlannerPrompt.js

@@ -153,3 +153,49 @@ export function buildGrokVideoPlannerSystemPrompt(ctx) {
         "Call generate_video exactly once. Do not answer with plain text.",
     ].join("\n");
 }
+/** Hard cap so a degraded prompt never bloats the generation payload. */
+const FALLBACK_PROMPT_MAX_CHARS = 4000;
+/** The user's own scene text is the one part that must never be cut. */
+const FALLBACK_USER_PROMPT_RESERVE = 2500;
+/**
+ * Deterministic, network-free video prompt used when the Grok planner is unavailable
+ * (timeout, upstream 5xx/429, or a network fault). A planner that ANSWERS without a tool
+ * call is a refusal, not an availability problem, and stays fatal.
+ *
+ * The user's own prompt is already a legitimate video prompt; this only adds the pacing
+ * and mode guidance the planner would have applied, so a stalled planner costs prompt
+ * polish instead of the whole generation.
+ * devlog/_plan/260817_grok_video_planner_timeout/040_planner_fallback.md
+ */
+export function composeFallbackVideoPrompt(userPrompt, opts) {
+    // The caller's prompt may already carry a long storyboard preamble. Truncating from the
+    // front would keep the boilerplate and drop the user's actual scene, so the user text is
+    // reserved first and everything else is fitted around it.
+    const base = userPrompt.trim().slice(0, FALLBACK_USER_PROMPT_RESERVE);
+    const modeLine = opts.mode === "image-to-video"
+        ? "Start from the provided source image as the first frame and preserve the subject's identity and composition while the described motion happens."
+        : opts.mode === "reference-to-video"
+            ? "Keep the referenced subjects recognizable throughout while the described motion happens."
+            : "Describe a fresh scene: establish the setting, then carry the described motion and camera work through the shot.";
+    // Continuity and background constraints are load-bearing: without them a continue-from
+    // clip can drift off-series, or a background preset can be silently ignored.
+    const continuity = opts.continuityText?.trim()
+        ? `Continuation context:\n${opts.continuityText.trim().slice(0, 600)}`
+        : "";
+    const background = opts.backgroundConstraint?.trim() ?? "";
+    const brief = opts.searchSummary?.trim()
+        ? `Research context: ${opts.searchSummary.trim().slice(0, 600)}`
+        : "";
+    const composed = [
+        base,
+        "",
+        modeLine,
+        continuity,
+        background,
+        formatDurationPacingGuidance(opts.duration, opts.mode, opts.resolution),
+        brief,
+    ].filter(Boolean).join("\n");
+    return composed.length > FALLBACK_PROMPT_MAX_CHARS
+        ? composed.slice(0, FALLBACK_PROMPT_MAX_CHARS).trimEnd()
+        : composed;
+}

package/lib/grokVideoShared.js

@@ -12,14 +12,25 @@ export const FAILED_CODE_MAP = {
 };
 export function videoConfig(ctx) {
     const g = ctx.config.grokProvider || {}; // justified: RouteRuntimeContext.config is a loose runtime bag; every Grok adapter reads grokProvider this way
+    const plannerTimeoutMs = g.plannerTimeoutMs || 900_000;
+    const searchTimeoutMs = g.searchTimeoutMs || 300_000;
+    // The planning ceiling must stay STRICTLY greater than the two stages it contains, or a
+    // slow search plus a stalled planner lands both timers together and the fatal ceiling
+    // preempts the planner fallback. Operator config can violate that, so clamp at runtime
+    // rather than trusting the defaults to survive an env override.
+    // devlog/_plan/260817_grok_video_planner_timeout/010_timeout_budgets.md
+    const configuredPlanTotal = g.videoPlanTotalTimeoutMs || 1_500_000;
+    const minimumPlanTotal = searchTimeoutMs + plannerTimeoutMs + 60_000;
     return {
         model: g.defaultVideoModel || GROK_FALLBACK_VIDEO_MODEL,
-        startTimeoutMs: g.videoStartTimeoutMs || 150_000,
+        startTimeoutMs: g.videoStartTimeoutMs || 300_000,
         pollIntervalMs: g.videoPollIntervalMs || 5_000,
-        totalTimeoutMs: g.videoTimeoutMs || 900_000,
+        totalTimeoutMs: g.videoTimeoutMs || 1_800_000,
         pollMaxConsecutiveErrors: g.videoPollMaxConsecutiveErrors || 5,
         plannerModel: g.plannerModel || DEFAULT_GROK_PLANNER_MODEL,
-        plannerTimeoutMs: g.plannerTimeoutMs || 300_000,
+        plannerTimeoutMs,
+        searchTimeoutMs,
+        planTotalTimeoutMs: Math.max(configuredPlanTotal, minimumPlanTotal),
     };
 }
 export function videoEndpoint(ctx, path, directApiKey) {

package/lib/videoClientTimeouts.js

@@ -0,0 +1,17 @@
+/**
+ * Client-side ceilings for a whole video request, shared by the CLI, the MCP lane, and the
+ * budget contract test so none of them can drift apart.
+ *
+ * The server worst case for one Grok video is
+ *   1500 s planning + 300 s start + 1800 s poll + 300 s poll overshoot + 300 s download
+ *   = 4200 s
+ * (the poll loop checks its deadline BEFORE each request, so the final poll can exceed the
+ * poll budget by one request timeout). Every client must sit ABOVE that with real slack —
+ * an equal ceiling is a race the client can win, abandoning a request the server would
+ * have completed.
+ *
+ * MUST stay a leaf module: no imports, so bin/, ui/, and tests can all read it.
+ * devlog/_plan/260817_grok_video_planner_timeout/010_timeout_budgets.md
+ */
+export const VIDEO_CLIENT_TIMEOUT_SEC = 5400;
+export const VIDEO_CLIENT_TIMEOUT_MS = VIDEO_CLIENT_TIMEOUT_SEC * 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -119,5 +119,5 @@
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   },
-  "gitHead": "aa5cbf2137e0093fb1c4c050b177285d8f85137e"
+  "gitHead": "ff8f95493fc2e2b5130223e6c63f55043d79fcfe"
 }