ima2-gen 3.13.1 → 3.14.0

package/.env.example

@@ -5,6 +5,10 @@
 # ── Server ─────────────────────────────────────────────────────────────
 # IMA2_PORT=3333            # also accepted: PORT
 # IMA2_HOST=127.0.0.1
+# Non-loopback access requires your own strong, private token (never commit it).
+# IMA2_LAN_TOKEN=
+# Exact serving origins for a TLS proxy, LAN DNS name or changed Docker port:
+# IMA2_PUBLIC_ORIGINS=["https://studio.example"]
 # IMA2_BODY_LIMIT=50mb
 
 # ── OAuth proxy (openai-oauth subprocess) ──────────────────────────────
@@ -50,6 +54,12 @@
 # ── Logging ────────────────────────────────────────────────────────────
 # IMA2_LOG_LEVEL=info    # trace|debug|info|warn|error|fatal
 
+# Explicit doctor checks only; defaults in milliseconds, maximum 30000.
+# --verify-keys checks remote authentication without generating images.
+# IMA2_DIAGNOSTIC_KEY_TIMEOUT_MS=5000
+# --runtime requires an explicit loopback server origin.
+# IMA2_DIAGNOSTIC_RUNTIME_TIMEOUT_MS=1500
+
 # ── Secrets (not merged from config.json, env only) ────────────────────
 # OPENAI_API_KEY=sk-...
 # XAI_API_KEY=xai-...

package/CHANGELOG.md

@@ -28,6 +28,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Production readiness
+
+- Correct NovelAI positive/negative prompt pane sizing, scrolling and toolbar spacing across sidebar, bottom, home and mobile composers; retain drafts when changing providers.
+- Keep provider/model labels, capabilities and selection consistent across the UI, CLI and generation routes, including unavailable or malformed provider catalogs.
+- Preserve accepted-job tracking through disconnects, cancellation, restart and LAN reauthentication without automatically submitting the job again.
+- Bound image/video artifact reads and downloads, reject escaped artifact paths, and keep cancellation from persisting an incomplete result.
+- Add LAN sign-in with origin-bound, HttpOnly session cookies; protect generated media, SSE, Range and HEAD requests. Default loopback use remains token-free, and explicit header/query API credentials remain supported.
+- Share failed-token cooldown across API, media, status and browser bootstrap; retain existing cookie sessions during a bearer-token cooldown.
+- Bind CLI LAN credentials only to an explicitly selected server, reject redirects and credential-bearing URLs, and preserve provider authentication errors separately from LAN access failures.
+- Add offline `doctor --installation --json`, safe diagnostic reports and metadata-derived installation/runtime documentation; improve Windows lock handling without terminating unrelated processes.
+- Use a patched, development-only Node SDK downloader for source builds; keep runtime dependencies and install-script approvals unchanged.
+
+LAN HTTP is intended for trusted networks and does not encrypt tokens or cookies; use an operator-configured HTTPS proxy or VPN on untrusted networks. Verification uses isolated synthetic providers, not a claim that live provider credentials, billing or every remote deployment have been exercised.
+
 ### Added
 
 - **Current model defaults** — Grok search, image/video planning, and frame analysis now default to `grok-4.5` while retaining `grok-4.3` as an explicit compatibility override. GPT image generation, stylesheet analysis, Card News planning, and Prompt Builder default to `gpt-5.6-luna`; Grok video model discovery projects `grok-imagine-video-1.5` from runtime config.

package/README.md

@@ -1,5 +1,18 @@
 # ima2-gen
 
+<!-- runtime-install:generated:start -->
+| Contract | Value |
+|---|---|
+| Node engine | `>=22` |
+| npm toolchain | `npm@11.18.0` |
+| Release Node | `24.17.0` |
+| CLI entry | `bin/ima2.js` |
+| OpenAI SDK | `^7.4.0` |
+| Express | `^5.1.0` |
+<!-- runtime-install:generated:end -->
+
+The installer derives its Node.js floor from package metadata and runs an offline installation check before launching the server.
+
 <p align="center">
   <img src="assets/logo.png" alt="ima2-gen logo" width="240">
 </p>
@@ -75,7 +88,7 @@ irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
 curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
 ```
 
-Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best available method, and handles stale process cleanup automatically.
+Each script checks the package-derived Node.js floor, installs Node LTS through the best available method, installs once, and runs the offline installation check before launching `ima2 serve`. It does not stop unrelated processes or clear global locks.
 
 ### Setup
 
@@ -97,7 +110,7 @@ Stop the running server with Ctrl+C, then:
 npm install -g ima2-gen@latest
 ```
 
-Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. On older versions (< 1.1.22) or if you see `EBUSY` on Windows, use the install script which handles stale process cleanup automatically.
+Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. If an installation fails, inspect the reported npm permissions or stop the specific `ima2` process yourself; the installer does not perform broad process cleanup.
 
 ## What It Does
 

package/bin/commands/capabilities.js

@@ -5,7 +5,7 @@ import { config } from "../../config.js";
 import { buildIma2Capabilities } from "../../lib/capabilities.js";
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
-import { color, dieWithError, json, out } from "../lib/output.js";
+import { color, exitCodeForError, fail, json, out } from "../lib/output.js";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const PACKAGE_PATH = join(ROOT, "package.json");
 const HELP = `
@@ -47,7 +47,8 @@ async function readCapabilities(args) {
         return await request(server.base, "/api/capabilities", { timeoutMs: 5000 });
     }
     catch (error) {
-        if (args.server || args["require-server"])
+        if (args.server !== undefined || process.env.IMA2_SERVER !== undefined || args["require-server"]
+            || error?.code !== "SERVER_UNREACHABLE")
             throw error;
         return localCapabilities();
     }
@@ -131,6 +132,7 @@ export default async function capabilitiesCmd(argv) {
             printText(capabilities);
     }
     catch (error) {
-        dieWithError(error);
+        fail({ json: Boolean(args.json), code: error?.code ?? "SERVER_REQUEST_FAILED",
+            message: error?.message || "server request failed", exitCode: exitCodeForError(error) });
     }
 }

package/bin/commands/config.js

@@ -2,6 +2,7 @@ import { createInterface } from "readline/promises";
 import { parseArgs } from "../lib/args.js";
 import { confirmDestructiveAction } from "../lib/destructive-confirm.js";
 import { out, die, color, json, exitFlushed } from "../lib/output.js";
+import { parsePublicOrigins } from "../../lib/localAccessPolicy.js";
 import { CONFIG_FILE, KEY_TO_ENV, WRITABLE_CONFIG_KEYS, buildEffectiveConfig, deleteNestedKey, displayPath, envOverrideForKey, getNestedKey, isAuthConfigKey, isSensitiveConfigKey, isWritableConfigKey, loadFileCfg, parseConfigValue, redactValue, restartNotice, saveFileCfg, setNestedKey, } from "../lib/config-store.js";
 const HELP = `
   ima2 config <subcommand> [options]
@@ -33,7 +34,7 @@ async function pathSub(_argv) {
 async function lsSub(argv) {
     const args = parseArgs(argv, { flags: FLAGS });
     if (args.effective) {
-        const eff = buildEffectiveConfig();
+        const eff = redactValue("", buildEffectiveConfig());
         if (args.json) {
             json(eff);
             return;
@@ -41,7 +42,7 @@ async function lsSub(argv) {
         out(JSON.stringify(eff, null, 2));
     }
     else {
-        const fileCfg = loadFileCfg();
+        const fileCfg = redactValue("", loadFileCfg());
         if (args.json) {
             json(fileCfg);
             return;
@@ -93,11 +94,21 @@ async function setSub(argv) {
     if (!isWritableConfigKey(key)) {
         die(2, `unknown config key: "${key}". Run 'ima2 config ls --effective' to see the config structure.`);
     }
-    const value = parseConfigValue(rawValue);
+    let value = parseConfigValue(rawValue);
+    if (key === "server.publicOrigins") {
+        try {
+            value = parsePublicOrigins(value);
+        }
+        catch {
+            die(2, "INVALID_PUBLIC_ORIGINS: expected an array of exact HTTP(S) origins without credentials, paths, query or fragments.");
+        }
+    }
     // Warn if env var is overriding this key
     const override = envOverrideForKey(key);
     if (override) {
-        out(color.yellow(`warning: env ${override.envVar}=${override.value} is currently overriding this value.`));
+        out(color.yellow(key === "server.publicOrigins"
+            ? `warning: env ${override.envVar} is currently overriding this value.`
+            : `warning: env ${override.envVar}=${override.value} is currently overriding this value.`));
         out(`The file change will only apply after unsetting the env var and restarting the server.`);
     }
     // Confirm if writing a sensitive key

package/bin/commands/defaults.js

@@ -2,7 +2,7 @@ import { config } from "../../config.js";
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
 import { buildEffectiveConfig, deleteNestedKey, displayPath, envOverrideForKey, getNestedKey, loadCliDefaults, loadFileCfg, restartNotice, saveFileCfg, setNestedKey, CONFIG_FILE, } from "../lib/config-store.js";
-import { color, die, dieWithError, fail, json, out } from "../lib/output.js";
+import { color, die, exitCodeForError, fail, json, out } from "../lib/output.js";
 const MODEL_KEYS = ["imageModels.default", "apiProvider.defaultImageModel"];
 const REASONING_KEYS = ["imageModels.reasoningEffort", "apiProvider.defaultReasoningEffort"];
 const HELP = `
@@ -67,7 +67,8 @@ async function readDefaults(args) {
         };
     }
     catch (error) {
-        if (args.server)
+        if (args.server !== undefined || process.env.IMA2_SERVER !== undefined
+            || error?.code !== "SERVER_UNREACHABLE")
             throw error;
         return localDefaults();
     }
@@ -143,8 +144,8 @@ async function fetchModelCatalog(args) {
     }
     catch (error) {
         fail({
-            json: Boolean(args.json), code: "SERVER_UNREACHABLE",
-            message: error?.message || "server unreachable", exitCode: 3,
+            json: Boolean(args.json), code: error?.code ?? "SERVER_REQUEST_FAILED",
+            message: error?.message || "server request failed", exitCode: exitCodeForError(error),
         });
     }
 }
@@ -197,7 +198,8 @@ async function listSub(argv) {
             printDefaults(payload);
     }
     catch (error) {
-        dieWithError(error);
+        fail({ json: Boolean(args.json), code: error?.code ?? "SERVER_REQUEST_FAILED",
+            message: error?.message || "server request failed", exitCode: exitCodeForError(error) });
     }
 }
 async function setSub(argv) {

package/bin/commands/doctor.js

@@ -1,25 +1,26 @@
-import { createRequire } from "module";
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { buildHardeningDoctorLines } from "../lib/doctor-checks.js";
 import { buildStorageDoctorLines } from "../lib/storage-doctor.js";
 import { detectCodexAuth } from "../../lib/codexDetect.js";
-import { resolvePackageBin } from "../../lib/packageCli.js";
 import { runImageDoctorProbe } from "../../lib/responsesDoctor.js";
 import { config as runtimeConfig } from "../../config.js";
 import { exitFlushed } from "../lib/output.js";
 import { buildProviderDoctorLines, verifyConfiguredKeys } from "../lib/doctor-providers.js";
 import { buildMediaDoctorLines } from "../lib/doctor-media.js";
 import { buildDoctorBundle } from "../lib/doctor-bundle.js";
+import { buildDoctorReport, renderDoctorReport } from "../lib/doctor-report.js";
+import { buildInstallationDoctorLines, checkNodeEngine, missingRuntimeDeps, probeDoctorRuntime } from "../lib/doctor-runtime.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "../..");
-const requireFromRoot = createRequire(join(ROOT, "package.json"));
 const CONFIG_FILE = runtimeConfig.storage.configFile;
 const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
 let pkg = { version: "?", name: "ima2-gen" };
 try {
-    pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+    const metadata = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+    if (metadata && typeof metadata.version === "string" && typeof metadata.name === "string")
+        pkg = metadata;
 }
 catch { }
 function loadConfig() {
@@ -34,32 +35,6 @@ function loadConfig() {
     }
     return {};
 }
-function missingRuntimeDeps() {
-    const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json", "@openai/codex/package.json", "zod"];
-    const missing = deps.filter((dep) => {
-        try {
-            requireFromRoot.resolve(dep);
-            return false;
-        }
-        catch {
-            return true;
-        }
-    }).map((dep) => dep.endsWith("/package.json") ? dep.slice(0, -"/package.json".length) : dep);
-    for (const pair of [["openai-oauth", "openai-oauth"], ["@openai/codex", "codex"]]) {
-        const packageName = pair[0];
-        const binName = pair[1];
-        if (!packageName || !binName)
-            continue;
-        try {
-            resolvePackageBin(packageName, binName);
-        }
-        catch {
-            if (!missing.includes(packageName))
-                missing.push(packageName);
-        }
-    }
-    return missing;
-}
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     if (index === -1)
@@ -92,6 +67,13 @@ export function showDoctorHelp() {
   Usage: ima2 doctor [image-probe] [options]
 
   Diagnose environment, storage, dependencies, and authentication.
+  --json                 Emit one machine-readable diagnostic report
+  --bundle               Emit a safe compatibility bundle (--json for JSON only)
+  --installation         Offline installation checks; no account/config reads
+  --verify-keys          Explicit non-generating remote authentication checks
+  --runtime <origin>     Explicit loopback health/version check; no credentials
+  Installation mode cannot combine with bundle, verify-keys or runtime.
+  image-probe performs live billed generation; ordinary doctor never runs it.
   Run 'ima2 doctor image-probe --help' for live image probe options.
 `);
 }
@@ -136,16 +118,12 @@ async function standardDoctor(args = []) {
     console.log(`\n  ${pkg.name} v${pkg.version} — Doctor\n`);
     let ok = 0;
     let fail = 0;
-    const nodeVersion = process.version;
-    const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0] ?? "0", 10);
-    if (nodeMajor >= 20) {
-        console.log(`  ✓ Node.js ${nodeVersion} (>= 20)`);
+    const node = checkNodeEngine(process.version, pkg.engines?.node);
+    console.log(`  ${node.kind === "pass" ? "✓" : "✗"} ${node.text}`);
+    if (node.kind === "pass")
         ok++;
-    }
-    else {
-        console.log(`  ✗ Node.js ${nodeVersion} (requires >= 20)`);
+    else
         fail++;
-    }
     if (existsSync(join(ROOT, "package.json"))) {
         console.log("  ✓ package.json found");
         ok++;
@@ -154,7 +132,7 @@ async function standardDoctor(args = []) {
         console.log("  ✗ package.json missing");
         fail++;
     }
-    const missingDeps = missingRuntimeDeps();
+    const missingDeps = missingRuntimeDeps(ROOT);
     if (missingDeps.length === 0) {
         console.log("  ✓ runtime dependencies resolvable");
         ok++;
@@ -276,5 +254,76 @@ export async function doctor(args = []) {
         await imageProbe(args.slice(1));
         return;
     }
+    if (!validDoctorArguments(args)) {
+        console.error("Invalid doctor options; use ima2 doctor --help.");
+        exitFlushed(2);
+    }
+    if (args.includes("--json") || args.includes("--bundle") || args.includes("--runtime") || args.includes("--installation")) {
+        await machineDoctor(args);
+        return;
+    }
     await standardDoctor(args);
 }
+function validDoctorArguments(args) {
+    const seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (seen.has(arg) || !["--json", "--bundle", "--installation", "--verify-keys", "--runtime"].includes(arg))
+            return false;
+        seen.add(arg);
+        if (arg === "--runtime" && (!args[++i] || args[i].startsWith("--")))
+            return false;
+    }
+    return !seen.has("--installation") || !["--bundle", "--verify-keys", "--runtime"].some((flag) => seen.has(flag));
+}
+function diagnosticConfig(lines) {
+    try {
+        const path = existsSync(CONFIG_FILE) ? CONFIG_FILE : existsSync(LEGACY_CONFIG_FILE) ? LEGACY_CONFIG_FILE : null;
+        const value = path ? JSON.parse(readFileSync(path, "utf8")) : {};
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw Error("CONFIG_INVALID");
+        return value;
+    }
+    catch {
+        lines.push({ code: "CONFIG_INVALID", kind: "fail", text: "Configuration is not a JSON object" });
+        return {};
+    }
+}
+async function machineDoctor(args) {
+    const installation = args.includes("--installation"), lines = buildInstallationDoctorLines(ROOT);
+    let providerLines = [];
+    try {
+        if (!installation) {
+            const fileConfig = diagnosticConfig(lines);
+            lines.push({ code: fileConfig.provider ? "CONFIG_PRESENT" : "CONFIG_MISSING", kind: fileConfig.provider ? "info" : "warn", text: "Configuration selection" });
+            try {
+                if (existsSync(runtimeConfig.storage.advertiseFile)) {
+                    const value = JSON.parse(readFileSync(runtimeConfig.storage.advertiseFile, "utf8"));
+                    if (!value || typeof value !== "object" || Array.isArray(value))
+                        throw Error("invalid");
+                }
+            }
+            catch {
+                lines.push({ code: "ADVERTISEMENT_INVALID", kind: "warn", text: "Invalid server advertisement" });
+            }
+            lines.push(...await buildHardeningDoctorLines({ root: ROOT, configFile: CONFIG_FILE, fileConfig, includeInstallationChecks: false }));
+            providerLines = buildProviderDoctorLines(fileConfig);
+            lines.push(...providerLines);
+            if (args.includes("--verify-keys"))
+                lines.push(...await verifyConfiguredKeys(fileConfig));
+            lines.push(...await buildMediaDoctorLines());
+            const url = valueAfter(args, "--runtime");
+            if (url)
+                lines.push(...await probeDoctorRuntime({ url, expectedVersion: pkg.version, timeoutMs: runtimeConfig.diagnostics.runtimeTimeoutMs }));
+        }
+    }
+    catch {
+        lines.push({ code: "DIAGNOSTIC_UNKNOWN", kind: "fail", text: "A diagnostic could not complete" });
+    }
+    const report = buildDoctorReport({ version: pkg.version, mode: installation ? "installation" : "standard", lines });
+    if (args.includes("--json"))
+        console.log(JSON.stringify(args.includes("--bundle") ? buildDoctorBundle({ version: pkg.version, providerLines, report }) : report));
+    else
+        console.log(renderDoctorReport(report));
+    exitFlushed(report.summary.exitCode);
+}

package/bin/commands/gen.js

@@ -6,13 +6,13 @@ import { sizeDrifted } from "../../lib/sizeNudge.js";
 import { errInfo } from "../../lib/errInfo.js";
 import { parseArgs } from "../lib/args.js";
 import { wasFlagPassed } from "../lib/argsExplicit.js";
-import { resolveServer, request, normalizeGenerate } from "../lib/client.js";
+import { resolveServer, request, normalizeGenerate, fetchServer } from "../lib/client.js";
 import { fileToDataUri, dataUriToFile, defaultOutName, readStdin } from "../lib/files.js";
 import { loadCliDefaults } from "../lib/config-store.js";
 import { runMcpJob } from "../lib/mcpJob.js";
 import { characterElementIdForMcp } from "../lib/characterResolve.js";
 import { resolveTarget } from "../lib/modelResolver.js";
-import { out, die, dieWithError, color, err, fail, json } from "../lib/output.js";
+import { out, die, dieWithError, color, err, exitCodeForError, fail, json } from "../lib/output.js";
 import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from "../lib/recover-output.js";
 import { deriveProviderIds } from "../../lib/providers/derive.js";
 import { listProviders } from "../../lib/mcp/providerRegistry.js";
@@ -140,7 +140,10 @@ function savedLine(path, actual, requested) {
     return [head, color.dim(`  ! requested ${String(requested)}; the provider returned a different size`)];
 }
 function failServer(jsonMode, error) {
+    const code = error?.code ?? "SERVER_REQUEST_FAILED";
     const message = error?.message || "server unreachable";
+    if (code !== "SERVER_UNREACHABLE")
+        fail({ json: jsonMode, code, message, exitCode: exitCodeForError(error) });
     if (jsonMode)
         err("Hint: start the server with `ima2 serve`.");
     fail({ json: jsonMode, code: "SERVER_UNREACHABLE", message: `${message}\nHint: run ima2 serve`, exitCode: 3 });
@@ -231,7 +234,7 @@ function validateMcpRefs(refs, context, roles, jsonMode) {
     return parsed;
 }
 async function downloadMcpResult(serverBase, url, target) {
-    const response = await fetch(`${serverBase}${url}`);
+    const response = await fetchServer(serverBase, url);
     if (!response.ok)
         die(1, `failed to download image: HTTP ${response.status}`);
     await mkdir(dirname(target), { recursive: true });
@@ -267,7 +270,8 @@ async function runMcpImage(argv, args, context) {
     }
     catch (error) {
         const typed = error;
-        fail({ json: Boolean(args.json), code: typed.code ?? "MCP_GENERATION_FAILED", message: typed.message, exitCode: 1 });
+        fail({ json: Boolean(args.json), code: typed.code ?? "MCP_GENERATION_FAILED", message: typed.message,
+            exitCode: exitCodeForError(error) === 4 ? 4 : 1 });
     }
 }
 function validateCoreFlags(args) {
@@ -384,11 +388,24 @@ async function runCoreImage(args, context) {
     }
 }
 export default async function genCmd(argv) {
+    try {
+        await generate(argv);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error; // Preserve the output owner's exit marker.
+        fail({ json: argv.includes("--json"), code: error.code ?? "GENERATION_FAILED",
+            message: error.message, exitCode: exitCodeForError(error) });
+    }
+}
+async function generate(argv) {
     const args = parseArgs(argv, SPEC);
     if (args.help) {
         out(HELP);
         return;
     }
+    if (args._unknown.length)
+        die(2, `unknown option: ${args._unknown[0]}`);
     const naiPreflight = unwrapNaiCliResult(parseNaiCliOptions(args, "allow-unknown"), Boolean(args.json));
     let prompt = args.positional.join(" ");
     if (!prompt && !args.stdin)

package/bin/commands/models.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "../lib/args.js";
 import { request, resolveServer } from "../lib/client.js";
-import { fail, json, out, table } from "../lib/output.js";
+import { exitCodeForError, fail, json, out, table } from "../lib/output.js";
 const SPEC = {
     flags: {
         kind: { type: "string" },
@@ -61,7 +61,7 @@ async function fetchCatalog(serverFlag, isJson) {
     }
     catch (error) {
         const message = error?.message || "server unreachable";
-        fail({ json: isJson, code: "SERVER_UNREACHABLE", message, exitCode: 3 });
+        fail({ json: isJson, code: error?.code ?? "SERVER_REQUEST_FAILED", message, exitCode: exitCodeForError(error) });
     }
 }
 export default async function modelsCmd(argv) {

package/bin/commands/ping.js

@@ -28,7 +28,7 @@ export default async function pingCmd(argv) {
     catch (e) {
         const err = errInfo(e);
         if (args.json) {
-            json({ ok: false, error: err.message });
+            json({ ok: false, error: err.message, code: err.code });
             exitFlushed(exitCodeForError(e));
         }
         die(exitCodeForError(e), err.message);

package/bin/commands/prompt.js

@@ -356,9 +356,11 @@ async function importSources(argv) {
     const args = parseArgs(argv, { flags: COMMON_FLAGS });
     const server = await getServer(args);
     const [curated, discovery] = await Promise.all([
-        request(server.base, "/api/prompts/import/curated-sources").catch(() => ({})),
-        request(server.base, "/api/prompts/import/discovery").catch(() => ({})),
-    ]);
+        request(server.base, "/api/prompts/import/curated-sources").catch((error) => { if (exitCodeForError(error) === 4)
+            throw error; return {}; }),
+        request(server.base, "/api/prompts/import/discovery").catch((error) => { if (exitCodeForError(error) === 4)
+            throw error; return {}; }),
+    ]).catch(handle);
     if (args.json) {
         json({ curated, discovery });
         return;

package/bin/commands/service.js

@@ -3,6 +3,8 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { clearServerBinding, fetchServerUrl, resolveServer } from "../lib/client.js";
+import { dieWithError } from "../lib/output.js";
 import { LAUNCHD_LABEL, SYSTEMD_UNIT, launchctlOutputIndicatesFailure, renderLaunchdPlist, renderSystemdUnit, serviceStateStale, } from "../lib/serviceTemplates.js";
 import { corroborateByStartTime, escalateKill, gracefulStop, isProcessAlive, verifyServerIdentity, waitForExit, } from "../../lib/processControl.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -82,19 +84,35 @@ function readAdvertise() {
     }
 }
 async function waitForHealth(timeoutMs) {
+    clearServerBinding();
+    const explicitTarget = process.env.IMA2_SERVER;
+    let lastSelectionError;
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const entry = readAdvertise();
-        if (entry?.url) {
-            try {
-                const r = await fetch(`${String(entry.url).replace(/\/$/, "")}/api/health`, { headers: { connection: "close" } });
+        try {
+            if (explicitTarget !== undefined) {
+                const selected = await resolveServer({ serverFlag: explicitTarget });
+                // Only a matching advertisement can describe the selected service.
+                return { ok: true, entry: entry?.url?.replace(/\/$/, "") === selected.base ? entry : { url: selected.base } };
+            }
+            if (entry?.url) {
+                const r = await fetchServerUrl(`${String(entry.url).replace(/\/$/, "")}/api/health`, { headers: { connection: "close" } });
                 if (r.ok)
                     return { ok: true, entry };
             }
-            catch { /* keep polling */ }
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "NETWORK_FAILED" && code !== "SERVER_UNREACHABLE")
+                throw error;
+            if (explicitTarget !== undefined)
+                lastSelectionError = error;
         }
         await new Promise((r) => setTimeout(r, 500));
     }
+    if (lastSelectionError)
+        throw lastSelectionError;
     return { ok: false, entry: readAdvertise() };
 }
 function reportProviderLiveness(entry) {
@@ -415,6 +433,16 @@ const HELP = `
     repair      Re-render artifacts after node/npm path moves
 `;
 export async function service(args = []) {
+    try {
+        await dispatchService(args);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        dieWithError(error);
+    }
+}
+async function dispatchService(args) {
     const sub = args[0];
     switch (sub) {
         case "install":

package/bin/commands/tools.js

@@ -11,7 +11,7 @@ import { buildToolShow, buildToolsList, catalogVersion, errorEnvelope, execution
 import { loadAllBundledSnapshots, readLocalSnapshot } from "../../lib/mcp/snapshotStore.js";
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
-import { json, out } from "../lib/output.js";
+import { json, out, exitCodeForError } from "../lib/output.js";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const HELP = `
   ima2 tools <list|show|schema|call> [id] [--json] [--offline] [--server <url>] [--input '<json>']
@@ -65,7 +65,7 @@ async function fromServer(args, path) {
         return await request(server.base, path, { timeoutMs: 8000 });
     }
     catch (error) {
-        if (error.code === "SERVER_UNREACHABLE" && !args.server)
+        if (error.code === "SERVER_UNREACHABLE" && !args.server && !process.env.IMA2_SERVER)
             return null; // offline fallback
         throw error;
     }
@@ -77,7 +77,7 @@ function emit(payload, asJson) {
     }
     json(payload); // machine surface: JSON is the primary output either way
 }
-export default async function toolsCommand(argv) {
+async function runToolsCommand(argv) {
     const args = parseArgs(argv, { flags: FLAGS });
     if (args.help) {
         out(HELP);
@@ -124,6 +124,22 @@ export default async function toolsCommand(argv) {
     out(HELP);
     process.exitCode = sub ? 1 : 0;
 }
+export default async function toolsCommand(argv) {
+    try {
+        await runToolsCommand(argv);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        const code = error.code;
+        const exit = exitCodeForError(error);
+        if (exit !== 4 && code !== "SERVER_UNREACHABLE")
+            throw error;
+        const envelope = errorEnvelope("server_error", error.message, { catalogVersion: "unavailable", cliVersion: cliVersion() });
+        json({ ...envelope, error: { ...envelope.error, code: code ?? "SERVER_ACCESS_DENIED" } });
+        process.exitCode = exit;
+    }
+}
 async function callTool(args, id, asJson) {
     const entries = localEntries();
     const meta = localMeta(entries);