ima2-gen 1.1.20 → 1.1.22

package/bin/commands/video.js

@@ -4,10 +4,54 @@ import { streamSse } from "../lib/sse.js";
 import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { config } from "../../config.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 const VALID_RESOLUTIONS = new Set(["480p", "720p"]);
 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-imagine-video", "grok-imagine-video-1.5-preview"]);
+const ACTIVE_VIDEO_PROMPT_GUIDANCE = "Active video prompt required: describe visual flow, motion flow, sound/no-music intent, dialogue/no-dialogue intent, and the desired ending frame. Pace the scene to naturally fill the selected duration with an opening composition, connected motion/emotion change, and stable ending frame.";
+function parseIntegerFlag(value, fallback, label) {
+    const raw = value === undefined ? String(fallback) : String(value);
+    if (!/^\d+$/.test(raw))
+        die(2, `${label} must be an integer`);
+    return Number(raw);
+}
+function rejectUnknownFlags(args) {
+    if (args._unknown?.length)
+        die(2, `unknown option: ${args._unknown[0]}`);
+}
+async function readJsonResponse(res, label) {
+    const text = await res.text();
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        die(1, `${label} failed: expected JSON response, got ${text.slice(0, 120) || `HTTP ${res.status}`}`);
+    }
+}
+function parseTimeoutSeconds(seconds) {
+    const sec = parseIntegerFlag(seconds, 600, "--timeout");
+    if (sec < 1)
+        die(2, "--timeout must be at least 1");
+    return sec;
+}
+function timeoutSignal(seconds) {
+    const sec = parseTimeoutSeconds(seconds);
+    return AbortSignal.timeout(sec * 1000);
+}
+async function writeBuffer(path, buf) {
+    await mkdir(dirname(path), { recursive: true }).catch(() => { });
+    await writeFile(path, buf);
+}
+async function downloadReturnedVideo(serverBase, data, outPath, signal) {
+    const rawUrl = typeof data.url === "string" ? data.url : "";
+    const url = rawUrl.startsWith("/") ? `${serverBase}${rawUrl}` : rawUrl;
+    if (!url)
+        die(1, "server did not return a video url");
+    const res = await fetch(url, { signal });
+    if (!res.ok)
+        die(1, `failed to download video: HTTP ${res.status}`);
+    await writeBuffer(outPath, Buffer.from(await res.arrayBuffer()));
+}
 const SPEC = {
     flags: {
         duration: { type: "string", default: "5" },
@@ -27,11 +71,24 @@ const SPEC = {
 };
 const HELP = `
   ima2 video <prompt...> [options]
+  ima2 video edit <prompt> --video <url|file_id|generated-file>
+  ima2 video extend <prompt> --video <url|file_id|generated-file> [--duration 6]
+  ima2 video continue <prompt> --video <generated-file>
+  ima2 video frame <file> [--last] [-o output.png]
+  ima2 video analyze <generated-file>
 
-  Generate a video via the Grok video provider (SSE streaming).
+  Generate, edit, extend, or analyze video via Grok.
 
-  Options:
-        --duration <1..15>              Duration in seconds. Default: 5
+  Subcommands:
+    (default)   Generate video (T2V / I2V / Ref2V)
+    edit        Edit existing video with text prompt (V2V)
+    extend      Continue video from last frame
+    continue    Generate a new I2V clip from a generated video's last frame with lineage
+    frame       Extract a frame from video (requires ffmpeg on server)
+    analyze     Analyze video with Grok 4.3 vision
+
+  Options (generate mode):
+        --duration <1..15>              Duration in seconds. Default: 5. Prompt motion should naturally fill this length
         --resolution <480p|720p>        Default: 480p
         --aspect-ratio <ratio|auto>     1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto. Default: auto
         --model <name>                  grok-imagine-video, grok-imagine-video-1.5-preview
@@ -44,6 +101,10 @@ const HELP = `
         --server <url>                  Override server URL
         --session <id>                  Session ID
 
+  Edit/extend subcommands:
+        --video <value>                 HTTPS URL, xAI file_id, data URL, or generated filename
+        --duration <2..10>              Extension duration only. Default: 6
+
   Modes (auto-detected from --ref count):
     0 refs  → text-to-video
     1 ref   → image-to-video
@@ -52,18 +113,34 @@ const HELP = `
   Examples:
     ima2 video "a cat playing piano"
     ima2 video "animate this" --ref photo.png --duration 10
-    ima2 video "cinematic" --resolution 720p --aspect-ratio 16:9 -o out.mp4
+    ima2 video edit "make it sunset" --video https://vidgen.x.ai/.../clip.mp4
+    ima2 video extend "camera pulls back" --video https://vidgen.x.ai/.../clip.mp4 --duration 5
+    ima2 video continue "she turns back as the music cuts to room tone" --video 1780226256355_50252101.mp4
+    ima2 video frame 1780226256355_50252101.mp4 --last -o lastframe.png
+    ima2 video analyze 1780226256355_50252101.mp4
 `;
 export default async function videoCmd(argv) {
+    const sub = argv[0];
+    if (sub === "edit")
+        return videoEditCmd(argv.slice(1));
+    if (sub === "extend")
+        return videoExtendCmd(argv.slice(1));
+    if (sub === "continue")
+        return videoContinueCmd(argv.slice(1));
+    if (sub === "frame")
+        return videoFrameCmd(argv.slice(1));
+    if (sub === "analyze")
+        return videoAnalyzeCmd(argv.slice(1));
     const args = parseArgs(argv, SPEC);
+    rejectUnknownFlags(args);
     if (args.help) {
         out(HELP);
         return;
     }
     const prompt = args.positional.join(" ");
-    if (!prompt)
-        die(2, "prompt is required");
-    const duration = parseInt(String(args.duration)) || 5;
+    if (!prompt.trim())
+        die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+    const duration = parseIntegerFlag(args.duration, 5, "--duration");
     if (duration < 1 || duration > 15)
         die(2, "--duration must be between 1 and 15");
     const resolution = String(args.resolution);
@@ -78,6 +155,12 @@ export default async function videoCmd(argv) {
     const refs = (Array.isArray(args.ref) ? args.ref : []);
     if (refs.length > 7)
         die(2, "max 7 --ref attachments for video");
+    if (refs.length >= 2 && duration > 10)
+        die(2, "--duration must be between 1 and 10 when using 2 or more --ref attachments");
+    const timeoutSeconds = parseIntegerFlag(args.timeout, 600, "--timeout");
+    if (timeoutSeconds < 1)
+        die(2, "--timeout must be at least 1");
+    const timeoutMs = timeoutSeconds * 1000;
     let server;
     try {
         server = await resolveServer({ serverFlag: args.server });
@@ -90,7 +173,6 @@ export default async function videoCmd(argv) {
         const buf = await readFile(p);
         return buf.toString("base64");
     }));
-    const timeoutMs = (parseInt(String(args.timeout)) || 600) * 1000;
     const requestId = `req_cli_video_${Date.now().toString(36)}`;
     const body = {
         prompt,
@@ -149,7 +231,7 @@ export default async function videoCmd(argv) {
                 case "error":
                     if (!args.json && lastProgress >= 0)
                         process.stdout.write("\n");
-                    die(1, `video error: ${ev.data.error || ev.data}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+                    die(1, `video error: ${ev.data.error || ev.data}${ev.data.guidance ? `\n${ev.data.guidance}` : ""}${ev.data.code ? ` (${ev.data.code})` : ""}`);
             }
         }
     }
@@ -183,12 +265,11 @@ export default async function videoCmd(argv) {
     }
     // Download the video file from server
     const videoUrl = `${server.base}${doneData.url || `/generated/${encodeURIComponent(filename)}`}`;
-    const dlRes = await fetch(videoUrl, { signal: AbortSignal.timeout(30_000) });
+    const dlRes = await fetch(videoUrl, { signal: timeoutSignal(args.timeout) });
     if (!dlRes.ok)
         die(1, `failed to download video: HTTP ${dlRes.status}`);
     const videoBuf = Buffer.from(await dlRes.arrayBuffer());
-    await mkdir(dirname(target), { recursive: true }).catch(() => { });
-    await writeFile(target, videoBuf);
+    await writeBuffer(target, videoBuf);
     if (args.json) {
         json({
             ok: true,
@@ -213,3 +294,244 @@ function renderBar(pct) {
     const filled = Math.round((pct / 100) * width);
     return color.green("█".repeat(filled)) + color.dim("░".repeat(width - filled));
 }
+async function runVideoGenerateRequest(serverBase, body, timeout, silent) {
+    let doneData = null;
+    let lastProgress = -1;
+    for await (const ev of streamSse(`${serverBase}/api/video/generate`, {
+        body: { provider: "grok", ...body },
+        signal: timeoutSignal(timeout),
+        headers: typeof body.requestId === "string" ? { "X-Request-Id": body.requestId } : undefined,
+    })) {
+        if (ev.event === "progress") {
+            const pct = typeof ev.data.progress === "number" ? Math.round(ev.data.progress * 100) : null;
+            if (pct !== null && pct !== lastProgress && !silent) {
+                process.stdout.write(`\r  ${renderBar(pct)} ${pct}%`);
+                lastProgress = pct;
+            }
+        }
+        else if (ev.event === "done") {
+            if (!silent && lastProgress >= 0)
+                process.stdout.write("\n");
+            doneData = ev.data;
+        }
+        else if (ev.event === "error") {
+            if (!silent && lastProgress >= 0)
+                process.stdout.write("\n");
+            die(1, `video error: ${ev.data.error || ev.data}${ev.data.guidance ? `\n${ev.data.guidance}` : ""}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+        }
+    }
+    if (!doneData)
+        die(1, "server did not return a video result");
+    return doneData;
+}
+// --- 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 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`);
+        return;
+    }
+    const prompt = args.positional.join(" ");
+    if (!prompt.trim())
+        die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+    if (!args.video)
+        die(2, "--video <url> is required");
+    parseTimeoutSeconds(args.timeout);
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const res = await fetch(`${server.base}/api/video/edit`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt, videoUrl: args.video }), signal: timeoutSignal(args.timeout) });
+    const data = await readJsonResponse(res, "edit");
+    if (!res.ok)
+        die(1, `edit failed: ${data.error ?? res.status}`);
+    const outPath = (args.out || args.output);
+    if (outPath)
+        await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+    if (args.json) {
+        out(JSON.stringify(data, null, 2));
+    }
+    else {
+        out(color.green("✓ ") + `Edited video: ${data.url}`);
+    }
+}
+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 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`);
+        return;
+    }
+    const prompt = args.positional.join(" ");
+    if (!prompt.trim())
+        die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+    if (!args.video)
+        die(2, "--video <url> is required");
+    const duration = parseIntegerFlag(args.duration, 6, "--duration");
+    if (duration < 2 || duration > 10)
+        die(2, "--duration must be between 2 and 10");
+    parseTimeoutSeconds(args.timeout);
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const res = await fetch(`${server.base}/api/video/extend`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt, videoUrl: args.video, duration }), signal: timeoutSignal(args.timeout) });
+    const data = await readJsonResponse(res, "extend");
+    if (!res.ok)
+        die(1, `extend failed: ${data.error ?? res.status}`);
+    const outPath = (args.out || args.output);
+    if (outPath)
+        await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+    if (args.json) {
+        out(JSON.stringify(data, null, 2));
+    }
+    else {
+        out(color.green("✓ ") + `Extended video (${data.duration}s): ${data.url}`);
+    }
+}
+async function videoContinueCmd(argv) {
+    const spec = {
+        flags: {
+            video: { type: "string" },
+            duration: { type: "string", default: "5" },
+            resolution: { type: "string", default: "720p" },
+            "aspect-ratio": { type: "string", default: "auto" },
+            model: { 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 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>       Default: 720p\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5-preview\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`);
+        return;
+    }
+    const prompt = args.positional.join(" ");
+    if (!prompt.trim())
+        die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+    if (!args.video)
+        die(2, "--video <generated-file> is required");
+    const duration = parseIntegerFlag(args.duration, 5, "--duration");
+    if (duration < 1 || duration > 15)
+        die(2, "--duration must be between 1 and 15");
+    const resolution = String(args.resolution);
+    if (!VALID_RESOLUTIONS.has(resolution))
+        die(2, "--resolution must be one of: 480p, 720p");
+    const aspectRatio = String(args["aspect-ratio"]);
+    if (!VALID_ASPECT_RATIOS.has(aspectRatio))
+        die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
+    if (args.model && !VALID_MODELS.has(String(args.model))) {
+        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+    }
+    parseTimeoutSeconds(args.timeout);
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const requestId = `req_cli_video_continue_${Date.now().toString(36)}`;
+    const body = {
+        prompt,
+        requestId,
+        duration,
+        resolution,
+        aspectRatio,
+        continueFromVideo: args.video,
+    };
+    if (args.model)
+        body.model = args.model;
+    const data = await runVideoGenerateRequest(server.base, body, args.timeout, Boolean(args.json));
+    const outPath = (args.out || args.output);
+    if (outPath)
+        await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+    if (args.json)
+        out(JSON.stringify(data, null, 2));
+    else
+        out(color.green("✓ ") + `Continued video: ${data.url}`);
+}
+async function videoFrameCmd(argv) {
+    const spec = { flags: { last: { type: "boolean" }, position: { type: "string" }, out: { type: "string" }, output: { short: "o", type: "string" }, timeout: { type: "string", default: "60" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+    const args = parseArgs(argv, spec);
+    rejectUnknownFlags(args);
+    if (args.help) {
+        out(`  ima2 video frame <generated-file> [--last] [--position <sec>] [-o output.png]\n\n  Extract a frame from a generated video file.\n\n  Options:\n        --last            Extract last frame (default)\n        --position <sec>  Extract frame at specific second\n    -o, --output <path>   Output file path\n        --out <path>      Alias for --output\n        --timeout <sec>   Default: 60\n        --server <url>    Override server URL`);
+        return;
+    }
+    const file = args.positional[0];
+    if (!file)
+        die(2, "file argument required");
+    if (args.last && args.position)
+        die(2, "use either --last or --position, not both");
+    const position = args.last ? "last" : (String(args.position || "last"));
+    if (position !== "last" && !/^\d+(\.\d+)?$/.test(position))
+        die(2, "--position must be a non-negative number");
+    parseTimeoutSeconds(args.timeout);
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const url = `${server.base}/api/video/frame?file=${encodeURIComponent(file)}&position=${encodeURIComponent(position)}`;
+    const res = await fetch(url, { signal: timeoutSignal(args.timeout) });
+    if (!res.ok) {
+        const d = await readJsonResponse(res, "frame extraction");
+        die(1, `frame extraction failed: ${d.error || res.status}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const outPath = (args.output || args.out) || `frame-${basename(file).replace(/\.[^.]+$/, "")}.png`;
+    await writeBuffer(outPath, buf);
+    out(color.green("✓ ") + `Frame saved: ${outPath} (${buf.length} bytes)`);
+}
+async function videoAnalyzeCmd(argv) {
+    const spec = { flags: { json: { type: "boolean" }, timeout: { type: "string", default: "180" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+    const args = parseArgs(argv, spec);
+    rejectUnknownFlags(args);
+    if (args.help) {
+        out(`  ima2 video analyze <generated-file>\n\n  Analyze first/last frames from a generated .mp4 with Grok 4.3 image understanding. Outputs structured recreation prompt.\n\n  Options:\n        --json            Print JSON result\n        --timeout <sec>   Default: 180\n        --server <url>    Override server URL`);
+        return;
+    }
+    const videoUrl = args.positional[0];
+    if (!videoUrl)
+        die(2, "generated video filename required");
+    parseTimeoutSeconds(args.timeout);
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const res = await fetch(`${server.base}/api/video/analyze`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ videoUrl }), signal: timeoutSignal(args.timeout) });
+    const data = await readJsonResponse(res, "analyze");
+    if (!res.ok)
+        die(1, `analyze failed: ${data.error || res.status}`);
+    if (args.json) {
+        out(JSON.stringify(data, null, 2));
+    }
+    else {
+        out(data.analysis);
+    }
+}

package/bin/ima2.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { spawn, execSync } from "child_process";
 import { confirmDestructiveAction } from "./lib/destructive-confirm.js";
 import { doctor } from "./commands/doctor.js";
-import { openUrl, resolveBin } from "./lib/platform.js";
+import { openUrl, resolveBin, killProcessTree } from "./lib/platform.js";
 import { maybePromptGithubStar } from "./lib/star-prompt.js";
 import { ensureFreshUiDist } from "./lib/ui-build.js";
 import { detectCodexAuth } from "../lib/codexDetect.js";
@@ -88,7 +88,7 @@ async function setup() {
         saveConfig(config);
         console.log("\n  Starting Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
         }
         catch {
             console.log("\n  Grok login failed or cancelled. You can retry with 'ima2 grok login'.\n");
@@ -121,7 +121,7 @@ async function setup() {
         // Grok OAuth
         console.log("  Running Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
         }
         catch {
             console.log("\n  Grok login failed. You can retry with 'ima2 grok login'.\n");
@@ -135,7 +135,7 @@ async function setup() {
         config.oauth.disableAutoStart = false;
         delete config.apiKey;
         saveConfig(config);
-        console.log("\n  Starting OAuth login...\n");
+        console.log("\n  Starting GPT OAuth login...\n");
         const auth = detectCodexAuth();
         const hasAuth = auth.authed;
         if (!hasAuth) {
@@ -154,10 +154,10 @@ async function setup() {
         }
         else {
             const how = auth.probe === "authed" ? "codex CLI" : "auth file";
-            console.log(`  Existing OAuth session found (${how}).\n`);
+            console.log(`  Existing GPT OAuth session found (${how}).\n`);
         }
         saveConfig(config);
-        console.log("  OAuth configured. Starting server...\n");
+        console.log("  GPT OAuth configured. Starting server...\n");
     }
     rl.close();
     return config;
@@ -197,9 +197,16 @@ async function serve(serveArgs = []) {
         env,
         cwd: ROOT,
     });
+    child.on("error", (err) => {
+        console.error(`[ima2] Failed to start server: ${err.message}`);
+        process.exit(1);
+    });
     child.on("exit", (code) => process.exit(code));
-    process.on("SIGINT", () => child.kill("SIGINT"));
-    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    process.on("SIGINT", () => killProcessTree(child.pid));
+    process.on("SIGTERM", () => killProcessTree(child.pid));
+    if (process.platform === "win32") {
+        process.on("SIGBREAK", () => killProcessTree(child.pid));
+    }
 }
 async function showStatus() {
     const config = loadConfig();
@@ -222,7 +229,7 @@ async function showStatus() {
     }
     // Check OAuth auth files + codex CLI probe
     const auth = detectCodexAuth();
-    console.log(`  OAuth sessions:`);
+    console.log(`  GPT OAuth sessions:`);
     console.log(`    ${auth.files.codex}          ${auth.fileHits.codex ? "✓" : "✗"}`);
     console.log(`    ${auth.files.chatgpt}  ${auth.fileHits.chatgpt ? "✓" : "✗"}`);
     if (auth.fileHits.xdgCodex) {
@@ -255,7 +262,7 @@ function showHelp() {
 
   Server commands:
     serve [--dev]  Start the image generation server
-    setup, login   Configure API key or OAuth (interactive)
+    setup, login   Configure API key or GPT OAuth (interactive)
     status         Show current configuration status
     doctor         Diagnose environment and setup
     open           Open web UI in browser
@@ -283,8 +290,8 @@ function showHelp() {
     storage <sub>  Storage status / open-dir       (ima2 storage --help)
     billing        API usage / quota
     providers      Configured providers
-    oauth <sub>    OAuth proxy status              (ima2 oauth --help)
-    grok <sub>     Bundled progrok login/status     (ima2 grok --help)
+    oauth <sub>    GPT OAuth proxy status              (ima2 oauth --help)
+    grok <sub>     Bundled Grok auth/status         (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)
@@ -335,7 +342,10 @@ switch (command) {
         break;
     case "setup":
     case "login":
-        setup().then(() => console.log("  Done. Run 'ima2 serve' to start."));
+        setup().then(() => console.log("  Done. Run 'ima2 serve' to start.")).catch((e) => {
+            console.error(`Setup failed: ${e?.message || e}`);
+            process.exit(1);
+        });
         break;
     case "status":
         showStatus();

package/bin/lib/error-hints.js

@@ -3,11 +3,11 @@ const HINTS = {
     APIKEY_DISABLED: "API-key generation is supported in current builds; switch providers or update the configured API key.",
     IMAGE_MODEL_UNSUPPORTED: "This model is visible but cannot generate images here. Use gpt-5.4 or gpt-5.4-mini.",
     INVALID_IMAGE_MODEL: "Use one of: gpt-5.5, gpt-5.4, gpt-5.4-mini.",
-    OAUTH_UNAVAILABLE: "OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
+    OAUTH_UNAVAILABLE: "GPT OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
     NETWORK_FAILED: "Network/proxy failed. This is not a moderation refusal.",
     SAFETY_REFUSAL: "The image backend refused this generation.",
     MODERATION_REFUSED: "The prompt or image was rejected by moderation.",
-    AUTH_CHATGPT_EXPIRED: "Run `npx @openai/codex login`, then restart `ima2 serve`.",
+    AUTH_CHATGPT_EXPIRED: "Re-run `ima2 setup` (option 1), then restart `ima2 serve`.",
     REF_TOO_LARGE: "Reference image is too large. Resize/compress it and retry.",
     REF_NOT_BASE64: "Reference payload is invalid. Use a normal PNG/JPEG/WebP file.",
 };

package/bin/lib/platform.js

@@ -80,20 +80,29 @@ export function openUrl(url) {
  * Windows does NOT raise SIGTERM from the OS — SIGINT (Ctrl+C) and SIGBREAK
  * (Ctrl+Break) are the observable signals. We still register SIGTERM so that
  * Node-internal `child.kill("SIGTERM")` calls work in tests.
+ *
+ * Handlers may return a Promise — they run with a grace period (default 3s)
+ * before forceful exit, giving file handles and sockets time to close cleanly.
  */
+const SHUTDOWN_GRACE_MS = 3_000;
+let shutdownStarted = false;
 export function onShutdown(handler) {
     const signals = isWin
         ? ["SIGINT", "SIGTERM", "SIGBREAK"]
         : ["SIGINT", "SIGTERM", "SIGHUP"];
     for (const sig of signals) {
         try {
-            process.on(sig, () => {
+            process.on(sig, async () => {
+                if (shutdownStarted)
+                    return;
+                shutdownStarted = true;
+                const forceExit = setTimeout(() => process.exit(0), SHUTDOWN_GRACE_MS);
+                forceExit.unref?.();
                 try {
-                    handler(sig);
-                }
-                finally {
-                    process.exit(0);
+                    await handler(sig);
                 }
+                catch { }
+                process.exit(0);
             });
         }
         catch {
@@ -101,3 +110,23 @@ export function onShutdown(handler) {
         }
     }
 }
+/**
+ * Kill an entire process tree. On Windows, child.kill() only kills the
+ * immediate process, leaving grandchildren alive and holding file locks.
+ * taskkill /T /F kills the whole tree.
+ */
+export function killProcessTree(pid) {
+    if (!pid)
+        return;
+    try {
+        if (isWin) {
+            execSync(`taskkill /T /F /PID ${pid}`, { stdio: "ignore" });
+        }
+        else {
+            process.kill(pid, "SIGTERM");
+        }
+    }
+    catch {
+        // Process already exited
+    }
+}