ima2-gen 1.1.0 → 1.1.2

package/README.md

@@ -4,6 +4,8 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+> 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/)
+>
 > **Read in other languages**: [한국어](docs/README.ko.md) · [日本語](docs/README.ja.md) · [简体中文](docs/README.zh-CN.md)
 
 `ima2-gen` is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
@@ -27,6 +29,8 @@ npx @openai/codex login
 npx ima2-gen serve
 ```
 
+If `3333` is already occupied, `ima2-gen` binds the next available port and writes the actual URL to `~/.ima2/server.json`. Use `ima2 open` or the URL printed in the terminal instead of assuming the port.
+
 You can also install it globally:
 
 ```bash
@@ -34,6 +38,11 @@ npm install -g ima2-gen
 ima2 serve
 ```
 
+Before updating a global install on Windows, stop any running `ima2 serve`
+process. If npm reports `EBUSY` or `resource busy or locked`, close ima2
+terminals, end stale `node.exe` processes if needed, and retry. If the lock
+persists, reboot and run the update before starting ima2 again.
+
 ## What It Does
 
 - **Classic mode**: generate, edit, reuse the current image, paste references, and continue from history.
@@ -55,10 +64,10 @@ If the settings page says **Configured but disabled**, that means an API key exi
 
 ## Model Guidance
 
-Start with **`gpt-5.4`** when you want the safest balanced image workflow.
+The app defaults to **`gpt-5.4-mini`** for fast local iteration. Switch to **`gpt-5.4`** when you want the safest balanced image workflow.
 
 - `gpt-5.4` — recommended balanced choice.
-- `gpt-5.4-mini` — current app default and faster draft model.
+- `gpt-5.4-mini` — current default and faster draft model.
 - `gpt-5.5` — strongest quality option when your Codex CLI/OAuth backend supports it. It may use more quota, expose different tool capabilities, or require updating Codex CLI before it works reliably.
 
 The app also exposes quality (`low`, `medium`, `high`) and moderation (`auto`, `low`) controls.
@@ -82,6 +91,12 @@ Use Node mode when you want to explore branches.
 
 Each node keeps its own prompt and result. Root nodes can attach local references; child nodes use the parent image as their source. Completed jobs are matched back to nodes by request ID, so reloads and graph version conflicts can recover finished results.
 
+### Experimental Card News Mode
+
+Card News is still dev-only and experimental. It is hidden in the default
+published runtime unless explicitly enabled for development, and it should not
+be treated as a stable public feature yet.
+
 ### Settings And Style Sheets
 
 The settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.
@@ -98,7 +113,7 @@ Style sheets let you capture a reusable visual direction.
 
 | Command | Description |
 |---|---|
-| `ima2 serve` | Start the local web server |
+| `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |
 | `ima2 setup` | Reconfigure saved auth |
 | `ima2 status` | Show config and OAuth status |
 | `ima2 doctor` | Diagnose Node, package, config, and auth |
@@ -116,9 +131,17 @@ These require a running `ima2 serve`.
 | `ima2 ls` | List local history |
 | `ima2 show <name>` | Reveal a generated asset |
 | `ima2 ps` | List active jobs |
+| `ima2 cancel <requestId>` | Mark an in-flight job canceled |
 | `ima2 ping` | Health-check the running server |
 
-The server advertises its port at `~/.ima2/server.json`. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
+The server advertises its actual port at `~/.ima2/server.json`. If `3333` is busy, the backend can fall back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
+
+```bash
+ima2 gen "poster" --model gpt-5.4 --mode direct --moderation low
+ima2 edit input.png --prompt "make it rainy" --model gpt-5.4
+ima2 ps --terminal
+ima2 cancel <requestId>
+```
 
 ## Configuration
 
@@ -131,14 +154,24 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | Variable | Default | Description |
 |---|---:|---|
 | `IMA2_PORT` / `PORT` | `3333` | Web server port |
+| `IMA2_HOST` | `127.0.0.1` | Web server bind host |
 | `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth proxy port |
 | `IMA2_SERVER` | — | CLI target override |
 | `IMA2_CONFIG_DIR` | `~/.ima2` | Config and SQLite location |
+| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
+| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback image model |
 | `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |
+| `IMA2_LOG_LEVEL` | `warn` | Normal serve defaults to `warn`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | Recent terminal job retention for debug views |
 | `OPENAI_API_KEY` | — | API key for supported auxiliary paths, not image generation |
 
+### Logging modes
+
+`ima2 serve` keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.
+
+Use `ima2 serve --dev`, `npm run dev`, or `IMA2_LOG_LEVEL=debug ima2 serve` when you need request IDs, node generation phases, OAuth stream diagnostics, or inflight state transitions. Explicit `IMA2_LOG_LEVEL` and `~/.ima2/config.json` values still override the built-in defaults.
+
 ## API Reference
 
 The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay focused on first-run use.
@@ -146,6 +179,8 @@ The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay fo
 Useful references:
 
 - [API Reference](docs/API.md)
+- [FAQ](docs/FAQ.md)
+- [Recover old images](docs/RECOVER_OLD_IMAGES.md)
 - [Korean README](docs/README.ko.md)
 - [Japanese README](docs/README.ja.md)
 - [Chinese README](docs/README.zh-CN.md)
@@ -170,8 +205,13 @@ Recent versions moved generated images from the installed package folder to `~/.
 **`gpt-5.5` fails but other models work**
 Update Codex CLI first, then retry. If it still fails, your account or backend route may not expose the same image capability or quota for `gpt-5.5` yet; use `gpt-5.4` as the stable fallback.
 
-**The port is unexpectedly `3457`**
-Your shell may have inherited `PORT=3457` from another local tool. Run `unset PORT` or start with `IMA2_PORT=3333 ima2 serve`.
+**The app opened on a different port**
+If the requested server port is busy, `ima2-gen` falls back to the next available port and records it in `~/.ima2/server.json`. If the port is unexpectedly `3457`, your shell may also have inherited `PORT=3457` from another local tool. Run `unset PORT` or start with `IMA2_PORT=3333 ima2 serve`.
+
+**Port `10531` is already used on Windows**
+Some Windows security tools, including `AnySign4PC.exe`, may occupy the default OAuth proxy port. Current builds track the actual fallback OAuth port. If you still need a manual override, start with `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve` and check `ima2 doctor`.
+
+For more beginner-friendly answers, see the [FAQ](docs/FAQ.md).
 
 ## Development
 
@@ -184,7 +224,7 @@ npm test
 npm run build
 ```
 
-`npm run dev` builds the UI and starts `server.js` with `--watch`. Node mode is part of the packaged UI by default.
+`npm run dev` builds the UI and starts `server.js` with `--watch` and verbose server diagnostics. Node mode is part of the packaged UI by default.
 
 ## License
 

package/assets/card-news/templates/academy-lesson-square/template.json

@@ -0,0 +1,20 @@
+{
+  "id": "academy-lesson-square",
+  "name": "Academy Lesson Square",
+  "description": "Education-focused square template with headline, visual, and caption safe areas.",
+  "authoringLabel": "Academy lesson carousel",
+  "size": "2048x2048",
+  "recommendedOutputSizes": ["1024x1024", "2048x2048"],
+  "previewFilename": "preview.png",
+  "baseFilename": "base.png",
+  "stylePrompt": "Modern Korean academy lesson card, confident educational tone, bright study-focused composition, blue and white palette, safe headline area, reusable card-news frame.",
+  "negativePrompt": "messy notes, unreadable tiny text, low contrast, watermark, signature, chaotic classroom",
+  "slots": [
+    { "id": "title", "kind": "text", "textKind": "headline", "label": "Top headline", "placement": "top-center", "x": 140, "y": 140, "w": 1768, "h": 320, "required": true, "maxChars": 28, "safeArea": true },
+    { "id": "visual", "kind": "image", "label": "Main visual area", "placement": "center", "x": 200, "y": 540, "w": 1648, "h": 1000, "required": true, "safeArea": false },
+    { "id": "caption", "kind": "text", "textKind": "body", "label": "Bottom caption", "placement": "bottom-center", "x": 200, "y": 1610, "w": 1648, "h": 260, "required": false, "maxChars": 48, "safeArea": true }
+  ],
+  "palette": ["white", "blue", "slate"],
+  "typography": { "headline": "strong sans", "body": "rounded sans" },
+  "recommendedRoleNodeIds": ["mid-5", "long-8"]
+}

package/assets/card-news/templates/clean-report-square/template.json

@@ -0,0 +1,20 @@
+{
+  "id": "clean-report-square",
+  "name": "Clean Report Square",
+  "description": "Editorial report-style square template for clear title, visual, and CTA hierarchy.",
+  "authoringLabel": "Clean editorial report",
+  "size": "2048x2048",
+  "recommendedOutputSizes": ["1024x1024", "2048x2048"],
+  "previewFilename": "preview.png",
+  "baseFilename": "base.png",
+  "stylePrompt": "Clean Korean card news report layout, white editorial surface, subtle grid, restrained navy accent, large safe title area, clear central visual slot, minimal decoration.",
+  "negativePrompt": "busy layout, tiny text, watermark, signature, excessive decoration, cluttered typography",
+  "slots": [
+    { "id": "title", "kind": "text", "textKind": "headline", "label": "Top title", "placement": "top-center", "x": 160, "y": 160, "w": 1728, "h": 260, "required": true, "maxChars": 26, "safeArea": true },
+    { "id": "visual", "kind": "image", "label": "Main visual area", "placement": "center", "x": 160, "y": 500, "w": 1728, "h": 980, "required": true, "safeArea": false },
+    { "id": "cta", "kind": "text", "textKind": "cta", "label": "Bottom CTA", "placement": "bottom-center", "x": 160, "y": 1620, "w": 1728, "h": 260, "required": false, "maxChars": 32, "safeArea": true }
+  ],
+  "palette": ["white", "navy", "blue"],
+  "typography": { "headline": "bold sans", "body": "clean sans" },
+  "recommendedRoleNodeIds": ["mid-5", "short-3"]
+}

package/bin/commands/cancel.js

@@ -0,0 +1,45 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { out, die, dieWithError, color, json } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    json: { type: "boolean" },
+    server: { type: "string" },
+    help: { short: "h", type: "boolean" },
+  },
+};
+
+const HELP = `
+  ima2 cancel <requestId> [--json]
+
+  Mark an in-flight job as canceled in the local ima2 server registry.
+`;
+
+export default async function cancelCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out(HELP); return; }
+
+  const requestId = args.positional[0];
+  if (!requestId) die(2, "requestId required");
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) {
+    if (args.json) json({ ok: false, requestId, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
+  }
+
+  try {
+    await request(server.base, `/api/inflight/${encodeURIComponent(requestId)}`, {
+      method: "DELETE",
+      timeoutMs: 30_000,
+    });
+  } catch (e) {
+    if (args.json) json({ ok: false, requestId, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
+  }
+
+  if (args.json) json({ ok: true, requestId });
+  else out(color.green("✓ ") + `canceled ${requestId}`);
+}

package/bin/commands/edit.js

@@ -1,7 +1,11 @@
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
 import { fileToDataUri, dataUriToFile, defaultOutName } from "../lib/files.js";
-import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { out, die, dieWithError, color, json } from "../lib/output.js";
+
+const VALID_MODES = new Set(["auto", "direct"]);
+const VALID_MODERATION = new Set(["auto", "low"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
 
 const SPEC = {
   flags: {
@@ -12,6 +16,10 @@ const SPEC = {
     json:    {              type: "boolean" },
     timeout: {              type: "string", default: "180" },
     server:  {              type: "string" },
+    model:   {              type: "string" },
+    mode:    {              type: "string", default: "auto" },
+    moderation: {            type: "string", default: "low" },
+    session: {              type: "string" },
     help:    { short: "h", type: "boolean" },
   },
 };
@@ -27,6 +35,10 @@ const HELP = `
     -s, --size <WxH>
     -o, --out <file>
         --json
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
+        --mode <auto|direct>       Prompt handling mode. Default: auto
+        --moderation <auto|low>    Default: low
+        --session <id>             Apply session style sheet if enabled
 `;
 
 export default async function editCmd(argv) {
@@ -35,10 +47,18 @@ export default async function editCmd(argv) {
   const input = args.positional[0];
   if (!input) die(2, "input image path required");
   if (!args.prompt) die(2, "--prompt is required");
+  if (!VALID_MODES.has(args.mode)) die(2, "--mode must be one of: auto, direct");
+  if (!VALID_MODERATION.has(args.moderation)) die(2, "--moderation must be one of: auto, low");
+  if (args.model && !KNOWN_IMAGE_MODELS.has(args.model)) {
+    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+  }
 
   let server;
   try { server = await resolveServer({ serverFlag: args.server }); }
-  catch (e) { die(exitCodeForError(e), e.message); }
+  catch (e) {
+    if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
+  }
 
   const imageDataUri = await fileToDataUri(input);
   const imageB64 = imageDataUri.split(",")[1];
@@ -48,12 +68,21 @@ export default async function editCmd(argv) {
   try {
     resp = await request(server.base, "/api/edit", {
       method: "POST",
-      body: { prompt: args.prompt, image: imageB64, quality: args.quality, size: args.size },
+      body: {
+        prompt: args.prompt,
+        image: imageB64,
+        quality: args.quality,
+        size: args.size,
+        model: args.model,
+        mode: args.mode,
+        moderation: args.moderation,
+        sessionId: args.session,
+      },
       timeoutMs,
     });
   } catch (e) {
     if (args.json) json({ ok: false, error: e.message, code: e.code });
-    die(exitCodeForError(e), e.message);
+    dieWithError(e);
   }
 
   const image = resp.image;

package/bin/commands/gen.js

@@ -1,7 +1,11 @@
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request, normalizeGenerate } from "../lib/client.js";
 import { fileToDataUri, dataUriToFile, defaultOutName, readStdin } from "../lib/files.js";
-import { out, err, die, color, json, exitCodeForError } from "../lib/output.js";
+import { out, die, dieWithError, color, json } from "../lib/output.js";
+
+const VALID_MODES = new Set(["auto", "direct"]);
+const VALID_MODERATION = new Set(["auto", "low"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
 
 const SPEC = {
   flags: {
@@ -17,6 +21,10 @@ const SPEC = {
     stdin:     {              type: "boolean" },
     timeout:   {              type: "string", default: "180" },
     server:    {              type: "string" },
+    model:     {              type: "string" },
+    mode:      {              type: "string", default: "auto" },
+    moderation: {              type: "string", default: "low" },
+    session:   {              type: "string" },
     help:      { short: "h", type: "boolean" },
   },
 };
@@ -38,9 +46,14 @@ const HELP = `
         --stdin                              Read prompt from stdin
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
+        --mode <auto|direct>                Prompt handling mode. Default: auto
+        --moderation <auto|low>             Default: low
+        --session <id>                      Apply session style sheet if enabled
 
   Examples:
     ima2 gen "a shiba in space"
+    ima2 gen "poster" --model gpt-5.4 --mode direct --moderation low
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     cat prompt.txt | ima2 gen --stdin -n 2 -d ./out
 `;
@@ -58,6 +71,11 @@ export default async function genCmd(argv) {
 
   const refs = args.ref || [];
   if (refs.length > 5) die(2, "max 5 --ref attachments");
+  if (!VALID_MODES.has(args.mode)) die(2, "--mode must be one of: auto, direct");
+  if (!VALID_MODERATION.has(args.moderation)) die(2, "--moderation must be one of: auto, low");
+  if (args.model && !KNOWN_IMAGE_MODELS.has(args.model)) {
+    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+  }
 
   const n = Math.max(1, Math.min(8, parseInt(args.count) || 1));
   const timeoutMs = (parseInt(args.timeout) || 180) * 1000;
@@ -66,7 +84,8 @@ export default async function genCmd(argv) {
   try {
     server = await resolveServer({ serverFlag: args.server });
   } catch (e) {
-    die(exitCodeForError(e), e.message);
+    if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
   }
 
   const references = await Promise.all(refs.map((p) => fileToDataUri(p)));
@@ -77,6 +96,10 @@ export default async function genCmd(argv) {
     size: args.size,
     n,
     references,
+    model: args.model,
+    mode: args.mode,
+    moderation: args.moderation,
+    sessionId: args.session,
   };
 
   let resp;
@@ -84,7 +107,7 @@ export default async function genCmd(argv) {
     resp = await request(server.base, "/api/generate", { method: "POST", body, timeoutMs });
   } catch (e) {
     if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
-    die(exitCodeForError(e), e.message);
+    dieWithError(e);
   }
 
   const norm = normalizeGenerate(resp);

package/bin/commands/ps.js

@@ -1,11 +1,12 @@
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
-import { out, die, color, json, table, exitCodeForError } from "../lib/output.js";
+import { out, dieWithError, color, json, table } from "../lib/output.js";
 
 const SPEC = {
   flags: {
     kind:    { type: "string" },
     session: { type: "string" },
+    terminal: { type: "boolean" },
     json:    { type: "boolean" },
     server:  { type: "string" },
     help:    { short: "h", type: "boolean" },
@@ -14,33 +15,64 @@ const SPEC = {
 
 export default async function psCmd(argv) {
   const args = parseArgs(argv, SPEC);
-  if (args.help) { out("ima2 ps [--kind classic|node] [--session id] [--json]"); return; }
+  if (args.help) { out("ima2 ps [--kind classic|node] [--session id] [--terminal] [--json]"); return; }
 
   let server;
   try { server = await resolveServer({ serverFlag: args.server }); }
-  catch (e) { die(exitCodeForError(e), e.message); }
+  catch (e) {
+    if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
+  }
 
   const qs = new URLSearchParams();
   if (args.kind) qs.set("kind", args.kind);
   if (args.session) qs.set("sessionId", args.session);
+  if (args.terminal) qs.set("includeTerminal", "1");
   const path = `/api/inflight${qs.toString() ? `?${qs}` : ""}`;
   let resp;
   try { resp = await request(server.base, path); }
-  catch (e) { die(exitCodeForError(e), e.message); }
+  catch (e) {
+    if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
+    dieWithError(e);
+  }
 
   const jobs = resp.jobs || resp.items || [];
-  if (args.json) { json({ jobs }); return; }
-  if (jobs.length === 0) { out(color.dim("(no active jobs)")); return; }
+  const terminalJobs = resp.terminalJobs || [];
+  if (args.json) {
+    json(args.terminal ? { jobs, terminalJobs } : { jobs });
+    return;
+  }
+  if (jobs.length === 0 && terminalJobs.length === 0) {
+    out(color.dim(args.terminal ? "(no active or terminal jobs)" : "(no active jobs)"));
+    return;
+  }
 
   const now = Date.now();
-  table(jobs, [
-    { key: "requestId", label: "ID", format: (v) => String(v || "").slice(0, 10) },
-    { key: "kind", label: "KIND" },
-    { key: "phase", label: "PHASE" },
-    { key: "startedAt", label: "AGE", format: (v) => v ? `${Math.round((now - v) / 1000)}s` : "" },
-    { key: "prompt", label: "PROMPT", format: (v) => {
-      const s = String(v || "").replace(/\s+/g, " ");
-      return s.length > 40 ? s.slice(0, 37) + "…" : s;
-    } },
-  ]);
+  if (jobs.length > 0) {
+    out(color.bold("Active jobs"));
+    table(jobs, [
+      { key: "requestId", label: "ID", format: (v) => String(v || "").slice(0, 10) },
+      { key: "kind", label: "KIND" },
+      { key: "phase", label: "PHASE" },
+      { key: "startedAt", label: "AGE", format: (v) => v ? `${Math.round((now - v) / 1000)}s` : "" },
+      { key: "prompt", label: "PROMPT", format: (v) => {
+        const s = String(v || "").replace(/\s+/g, " ");
+        return s.length > 40 ? s.slice(0, 37) + "…" : s;
+      } },
+    ]);
+  }
+  if (terminalJobs.length > 0) {
+    if (jobs.length > 0) out("");
+    out(color.bold("Terminal jobs"));
+    table(terminalJobs, [
+      { key: "requestId", label: "ID", format: (v) => String(v || "").slice(0, 10) },
+      { key: "kind", label: "KIND" },
+      { key: "status", label: "STATUS" },
+      { key: "finishedAt", label: "AGE", format: (v) => v ? `${Math.round((now - v) / 1000)}s` : "" },
+      { key: "prompt", label: "PROMPT", format: (v) => {
+        const s = String(v || "").replace(/\s+/g, " ");
+        return s.length > 40 ? s.slice(0, 37) + "…" : s;
+      } },
+    ]);
+  }
 }

package/bin/ima2.js

@@ -3,6 +3,7 @@ import { createInterface } from "readline/promises";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 import { spawn, execSync } from "child_process";
 import { networkInterfaces, homedir } from "os";
 import { openUrl, resolveBin } from "./lib/platform.js";
@@ -14,6 +15,7 @@ import { config as runtimeConfig } from "../config.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const HOME = homedir();
+const requireFromRoot = createRequire(join(ROOT, "package.json"));
 // Config lives under runtimeConfig.storage.configDir (honors IMA2_CONFIG_DIR).
 // Legacy installs that stored config at <packageRoot>/.ima2/config.json will be
 // migrated on first write.
@@ -43,6 +45,33 @@ function saveConfig(config) {
   writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
 }
 
+function loadAdvertisement() {
+  const p = runtimeConfig.storage.advertiseFile;
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function advertisedServerUrl() {
+  const adv = loadAdvertisement();
+  return adv?.backend?.url || adv?.url || (adv?.port ? `http://localhost:${adv.port}` : null);
+}
+
+function missingRuntimeDeps() {
+  const deps = ["express", "better-sqlite3", "openai", "openai-oauth"];
+  return deps.filter((dep) => {
+    try {
+      requireFromRoot.resolve(dep);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+}
+
 async function setup() {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
 
@@ -102,7 +131,7 @@ async function setup() {
   return config;
 }
 
-async function serve() {
+async function serve(serveArgs = []) {
   try {
     await maybePromptGithubStar();
   } catch (err) {
@@ -135,6 +164,11 @@ async function serve() {
   }
 
   const env = { ...process.env };
+  const serveDev = serveArgs.includes("--dev");
+  if (serveDev) {
+    env.IMA2_DEV = "1";
+    env.IMA2_LOG_LEVEL = env.IMA2_LOG_LEVEL || "debug";
+  }
 
   if (config.provider === "api" && config.apiKey) {
     env.OPENAI_API_KEY = config.apiKey;
@@ -216,12 +250,14 @@ async function doctor() {
     fail++;
   }
 
-  // node_modules
-  if (existsSync(join(ROOT, "node_modules"))) {
-    console.log("  ✓ node_modules installed");
+  // Runtime dependencies may be hoisted by npm, pnpm, or Yarn. Resolve the
+  // packages instead of requiring a package-local node_modules folder.
+  const missingDeps = missingRuntimeDeps();
+  if (missingDeps.length === 0) {
+    console.log("  ✓ runtime dependencies resolvable");
     ok++;
   } else {
-    console.log("  ✗ node_modules missing — run 'npm install'");
+    console.log(`  ✗ missing runtime dependencies: ${missingDeps.join(", ")}`);
     fail++;
   }
 
@@ -243,8 +279,14 @@ async function doctor() {
   }
 
   // Port availability (simple check)
-  const port = runtimeConfig.server.port;
-  console.log(`  ℹ Default port: ${port}`);
+  const adv = loadAdvertisement();
+  console.log(`  ℹ Preferred backend port: ${runtimeConfig.server.port}`);
+  if (adv?.backend || adv?.port) {
+    console.log(`  ℹ Backend actual URL: ${adv?.backend?.url || adv?.url || `http://localhost:${adv.port}`}`);
+    if (adv?.oauth) {
+      console.log(`  ℹ OAuth actual URL: ${adv.oauth.url} (${adv.oauth.status || "unknown"})`);
+    }
+  }
 
   const storageLines = await buildStorageDoctorLines({
     rootDir: ROOT,
@@ -258,8 +300,7 @@ async function doctor() {
 }
 
 function openBrowser() {
-  const port = runtimeConfig.server.port;
-  const url = `http://localhost:${port}`;
+  const url = advertisedServerUrl() || `http://localhost:${runtimeConfig.server.port}`;
   const res = openUrl(url);
   if (res.ok) {
     console.log(`\n  Opening ${url} ...\n`);
@@ -275,7 +316,7 @@ function showHelp() {
   Usage: ima2 <command> [options]
 
   Server commands:
-    serve          Start the image generation server
+    serve [--dev]  Start the image generation server
     setup, login   Configure API key or OAuth (interactive)
     status         Show current configuration status
     doctor         Diagnose environment and setup
@@ -288,6 +329,7 @@ function showHelp() {
     ls             List recent history            (ima2 ls --help)
     show <name>    Show one history item          (ima2 show --help)
     ps             List active jobs               (ima2 ps --help)
+    cancel <id>    Mark an in-flight job canceled (ima2 cancel --help)
     ping           Ping running server / check health
 
   Options:
@@ -296,6 +338,7 @@ function showHelp() {
 
   Examples:
     ima2 serve                       Start server
+    ima2 serve --dev                 Start with verbose server diagnostics
     ima2 gen "a shiba in space"      Generate from CLI
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     ima2 ls -n 10                    Last 10 generations
@@ -313,14 +356,14 @@ if (args.includes("-v") || args.includes("--version")) {
 }
 
 if ((!command || args.includes("-h") || args.includes("--help"))
-    && !["gen", "edit", "ls", "show", "ps", "ping"].includes(command)) {
+    && !["gen", "edit", "ls", "show", "ps", "cancel", "ping"].includes(command)) {
   showHelp();
   process.exit(command ? 0 : 1);
 }
 
 switch (command) {
   case "serve":
-    serve();
+    serve(args.slice(1));
     break;
   case "setup":
   case "login":
@@ -348,6 +391,7 @@ switch (command) {
   case "ls":
   case "show":
   case "ps":
+  case "cancel":
   case "ping": {
     const { setCliVersion } = await import("./lib/client.js");
     setCliVersion(pkg.version);