ima2-gen 3.13.1 → 3.14.0

package/bin/lib/doctor-checks.js

@@ -1,10 +1,10 @@
-import { createRequire } from "module";
 import { createServer } from "net";
 import { accessSync, constants, existsSync, statSync } from "fs";
 import { execFileSync } from "child_process";
-import { dirname, join } from "path";
+import { dirname } from "path";
 import { config as runtimeConfig } from "../../config.js";
 import { isSensitiveConfigKey } from "../../lib/configKeys.js";
+import { checkNativeBinding, checkPackagedSkills } from "./doctor-runtime.js";
 function hasSensitiveValue(value, path = "") {
     if (!value || typeof value !== "object")
         return false;
@@ -32,34 +32,20 @@ function probeNpmVersion() {
         const raw = execFileSync("npm", ["-v"], { encoding: "utf8", timeout: 4000 }).trim();
         const major = Number.parseInt(raw.split(".")[0] || "", 10);
         if (Number.isFinite(major) && major >= 9)
-            return { kind: "pass", text: `npm ${raw} (>= 9)` };
-        return { kind: "warn", text: `npm ${raw} (recommend >= 9)` };
+            return { code: "NPM_READY", kind: "pass", text: `npm ${raw} (>= 9)` };
+        return { code: "NPM_OLD", kind: "warn", text: `npm ${raw} (recommend >= 9)` };
     }
     catch {
-        return { kind: "warn", text: "npm not found on PATH" };
+        return { code: "NPM_MISSING", kind: "warn", text: "npm not found on PATH" };
     }
 }
 function probeDbPathWritable(dbPath) {
     try {
         accessSync(dirname(dbPath), constants.W_OK);
-        return { kind: "pass", text: `dbPath writable: ${dbPath}` };
+        return { code: "DB_PARENT_WRITABLE", kind: "pass", text: `dbPath writable: ${dbPath}` };
     }
     catch {
-        return { kind: "fail", text: `dbPath not writable: ${dbPath}` };
-    }
-}
-function probeBetterSqlite(root) {
-    try {
-        const requireFromRoot = createRequire(join(root, "package.json"));
-        const mod = requireFromRoot("better-sqlite3");
-        const Database = (mod.default ?? mod);
-        const db = new Database(":memory:");
-        db.close();
-        return { kind: "pass", text: "better-sqlite3 native binding loads" };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { kind: "fail", text: `better-sqlite3 native binding failed: ${message}` };
+        return { code: "DB_PARENT_UNWRITABLE", kind: "fail", text: `dbPath not writable: ${dbPath}` };
     }
 }
 function configPermissionLine(configFile, fileConfig) {
@@ -70,30 +56,28 @@ function configPermissionLine(configFile, fileConfig) {
     if ((mode & 0o077) === 0)
         return null;
     return {
+        code: "CONFIG_PERMISSIONS",
         kind: "warn",
         text: `${configFile} is readable by group/other; consider chmod 600`,
     };
 }
-export async function buildHardeningDoctorLines({ root, configFile, fileConfig, }) {
+export async function buildHardeningDoctorLines({ root, configFile, fileConfig, includeInstallationChecks = true, }) {
     const lines = [];
     const portAvailable = await probePort(runtimeConfig.server.host, runtimeConfig.server.port);
     lines.push({
+        code: portAvailable ? "PORT_AVAILABLE" : "PORT_IN_USE",
         kind: "info",
         text: `Preferred backend port ${runtimeConfig.server.port}: ${portAvailable ? "available" : "in use"}`,
     });
     lines.push({
+        code: runtimeConfig.features.cardNews ? "FEATURE_ENABLED" : "FEATURE_DISABLED",
         kind: "info",
         text: `Card News: ${runtimeConfig.features.cardNews ? "enabled" : "disabled"}`,
     });
-    for (const skillDir of ["ima2", "ima2-front", "ima2-uiux"]) {
-        const skillPath = join(root, "skills", skillDir, "SKILL.md");
-        lines.push(existsSync(skillPath)
-            ? { kind: "pass", text: `packaged skill found: ${skillPath}` }
-            : { kind: "fail", text: `packaged skill missing: ${skillPath}` });
-    }
+    if (includeInstallationChecks)
+        lines.push(...checkPackagedSkills(root), checkNativeBinding(root));
     lines.push(probeNpmVersion());
     lines.push(probeDbPathWritable(runtimeConfig.storage.dbPath));
-    lines.push(probeBetterSqlite(root));
     const perm = configPermissionLine(configFile, fileConfig);
     if (perm)
         lines.push(perm);

package/bin/lib/doctor-media.js

@@ -4,12 +4,12 @@ const execFileAsync = promisify(execFile);
 export async function buildMediaDoctorLines() {
     try {
         await execFileAsync("ffmpeg", ["-version"], { timeout: 4000 });
-        return [{ kind: "pass", text: "ffmpeg available on PATH" }];
+        return [{ code: "FFMPEG_READY", kind: "pass", text: "ffmpeg available on PATH" }];
     }
     catch (error) {
         const code = error.code;
         if (code === "ENOENT")
-            return [{ kind: "warn", text: "ffmpeg not on PATH (video features unavailable)" }];
-        return [{ kind: "warn", text: "ffmpeg probe failed" }];
+            return [{ code: "FFMPEG_MISSING", kind: "warn", text: "ffmpeg not on PATH (video features unavailable)" }];
+        return [{ code: "FFMPEG_PROBE_FAILED", kind: "warn", text: "ffmpeg probe failed" }];
     }
 }

package/bin/lib/doctor-providers.js

@@ -22,58 +22,58 @@ function configString(fileConfig, key) {
 function inspectApiKey(lane, credential, fileConfig) {
     const value = firstEnv(credential.envVars) || configString(fileConfig, credential.configKey);
     if (!value) {
-        return { lane, kind: "warn", text: `${lane}: api-key unset` };
+        return { code: "CREDENTIAL_MISSING", lane, kind: "warn", text: `${lane}: api-key unset` };
     }
     if (credential.keyPrefix && !value.startsWith(credential.keyPrefix)) {
-        return { lane, kind: "fail", text: `${lane}: api-key prefix mismatch (expected ${credential.keyPrefix})` };
+        return { code: "CREDENTIAL_SHAPE_INVALID", lane, kind: "fail", text: `${lane}: api-key prefix mismatch (expected ${credential.keyPrefix})` };
     }
     if (!credential.keyPrefix) {
         // Several lanes (minimax region-specific, nai persistent tokens) have no
         // stable prefix, so the message must stay vocabulary-neutral.
-        return { lane, kind: "pass", text: `${lane}: api-key present (no prefix check; this lane has no fixed key prefix)` };
+        return { code: "CREDENTIAL_PRESENT", lane, kind: "pass", text: `${lane}: api-key present (no prefix check; this lane has no fixed key prefix)` };
     }
-    return { lane, kind: "pass", text: `${lane}: api-key present` };
+    return { code: "CREDENTIAL_PRESENT", lane, kind: "pass", text: `${lane}: api-key present` };
 }
 function inspectOauth(lane) {
     if (lane === "oauth") {
         const auth = detectCodexAuth();
         if (auth.proxyReady)
-            return { lane, kind: "pass", text: `${lane}: file-backed Codex session ready` };
-        return { lane, kind: "fail", text: `${lane}: no file-backed Codex session; run ima2 login` };
+            return { code: "OAUTH_FILE_READY", lane, kind: "pass", text: `${lane}: file-backed Codex session ready` };
+        return { code: "OAUTH_FILE_REQUIRED", lane, kind: "fail", text: `${lane}: no file-backed Codex session; run ima2 login` };
     }
     if (lane === "grok") {
         const home = homedir();
         const files = [join(home, ".progrok", "auth.json"), join(home, ".grok", "auth.json")];
         if (files.some((path) => existsSync(path))) {
-            return { lane, kind: "pass", text: `${lane}: local Grok auth file present` };
+            return { code: "CREDENTIAL_PRESENT", lane, kind: "pass", text: `${lane}: local Grok auth file present` };
         }
-        return { lane, kind: "warn", text: `${lane}: no ~/.progrok or ~/.grok auth file` };
+        return { code: "CREDENTIAL_MISSING", lane, kind: "warn", text: `${lane}: no ~/.progrok or ~/.grok auth file` };
     }
-    return { lane, kind: "warn", text: `${lane}: oauth-proxy has no lane-specific checker` };
+    return { code: "DIAGNOSTIC_UNKNOWN", lane, kind: "warn", text: `${lane}: oauth-proxy has no lane-specific checker` };
 }
 function inspectServiceAccount(lane, credential, fileConfig) {
     const raw = firstEnv(credential.envVars) || configString(fileConfig, credential.configKey);
     if (!raw)
-        return { lane, kind: "warn", text: `${lane}: service-account unset` };
+        return { code: "CREDENTIAL_MISSING", lane, kind: "warn", text: `${lane}: service-account unset` };
     try {
         const parsed = JSON.parse(raw);
         if (parsed.type !== "service_account" || typeof parsed.project_id !== "string" || !parsed.project_id) {
-            return { lane, kind: "fail", text: `${lane}: service-account JSON missing type/project_id` };
+            return { code: "CREDENTIAL_SHAPE_INVALID", lane, kind: "fail", text: `${lane}: service-account JSON missing type/project_id` };
         }
-        return { lane, kind: "pass", text: `${lane}: service-account JSON present` };
+        return { code: "CREDENTIAL_PRESENT", lane, kind: "pass", text: `${lane}: service-account JSON present` };
     }
     catch {
-        return { lane, kind: "fail", text: `${lane}: service-account is not JSON` };
+        return { code: "CREDENTIAL_SHAPE_INVALID", lane, kind: "fail", text: `${lane}: service-account is not JSON` };
     }
 }
 function inspectLocalCli(lane, credential) {
     const override = firstEnv(credential.envVars);
     if (override) {
         return existsSync(override)
-            ? { lane, kind: "pass", text: `${lane}: local CLI override found` }
-            : { lane, kind: "fail", text: `${lane}: local CLI override missing` };
+            ? { code: "LOCAL_CLI_FOUND", lane, kind: "pass", text: `${lane}: local CLI override found` }
+            : { code: "LOCAL_CLI_MISSING", lane, kind: "fail", text: `${lane}: local CLI override missing` };
     }
-    return { lane, kind: "warn", text: `${lane}: local CLI env unset` };
+    return { code: "LOCAL_CLI_MISSING", lane, kind: "warn", text: `${lane}: local CLI env unset` };
 }
 /**
  * A local-http lane has no binary and no key: its env var holds a URL, so the
@@ -88,10 +88,10 @@ function inspectLocalHttp(lane, credential) {
     const raw = firstEnv(credential.envVars) ?? runtimeConfig.comfy.defaultUrl;
     try {
         const origin = normalizeComfyOrigin(raw);
-        return { lane, kind: "pass", text: `${lane}: origin ${origin}` };
+        return { code: "LOCAL_ORIGIN_VALID", lane, kind: "pass", text: `${lane}: origin ${origin}` };
     }
     catch {
-        return { lane, kind: "fail", text: `${lane}: invalid origin ${raw}` };
+        return { code: "LOCAL_ORIGIN_INVALID", lane, kind: "fail", text: `${lane}: invalid configured origin` };
     }
 }
 export function inspectProviderLane(provider, fileConfig) {
@@ -126,7 +126,7 @@ export function listedValidateUrls() {
         return url ? [url] : [];
     }));
 }
-export async function verifyConfiguredKeys(fileConfig, fetchImpl = fetch) {
+export async function verifyConfiguredKeys(fileConfig, fetchImpl = fetch, options = {}) {
     const lines = [];
     for (const provider of listProviders()) {
         for (const credential of provider.credentials) {
@@ -138,23 +138,36 @@ export async function verifyConfiguredKeys(fileConfig, fetchImpl = fetch) {
             const value = firstEnv(credential.envVars) || configString(fileConfig, credential.configKey);
             if (!value)
                 continue;
-            try {
-                const headers = credential.keyVocabulary === "gemini"
-                    ? { "x-goog-api-key": value }
-                    : { Authorization: `Bearer ${value}` };
-                const response = await fetchImpl(url, { headers });
-                if (response.ok) {
-                    lines.push({ lane: provider.id, kind: "pass", text: `${provider.id}: validateUrl ok` });
-                }
-                else {
-                    lines.push({ lane: provider.id, kind: "fail", text: `${provider.id}: AUTH_INVALID (${response.status})` });
-                }
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                lines.push({ lane: provider.id, kind: "fail", text: `${provider.id}: AUTH_INVALID (${message})` });
-            }
+            const headers = credential.keyVocabulary === "gemini"
+                ? { "x-goog-api-key": value } : { Authorization: `Bearer ${value}` };
+            const code = await verifyKey(url, headers, fetchImpl, options.timeoutMs ?? runtimeConfig.diagnostics.keyTimeoutMs);
+            lines.push({ lane: provider.id, code, kind: code === "AUTH_VERIFIED" ? "pass" : "fail", evidence: "remote-auth", text: `${provider.id}: ${code}` });
         }
     }
     return lines;
 }
+async function verifyKey(url, headers, fetchImpl, requestedTimeout) {
+    const timeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0 ? Math.min(requestedTimeout, 30000) : 5000;
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(Error("AUTH_TIMEOUT")); }, timeoutMs);
+    });
+    try {
+        const request = (async () => {
+            const response = await fetchImpl(url, { headers, signal: controller.signal, redirect: "error" });
+            const code = response.ok ? "AUTH_VERIFIED" : response.status === 401 || response.status === 403 ? "AUTH_INVALID"
+                : response.status === 429 ? "AUTH_RATE_LIMITED" : "AUTH_UPSTREAM_FAILED";
+            await response.body?.cancel();
+            return code;
+        })();
+        return await Promise.race([request, deadline]);
+    }
+    catch {
+        return controller.signal.aborted ? "AUTH_TIMEOUT" : "AUTH_NETWORK_FAILED";
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+}

package/bin/lib/doctor-report.js

@@ -0,0 +1,78 @@
+import { listProviders } from "../../lib/providers/registry.js";
+const REINSTALL = "Reinstall the same approved package version.";
+const CODES = {
+    NODE_RUNTIME_OK: { message: "Node satisfies the package engine requirement." },
+    NODE_RUNTIME_UNSUPPORTED: { message: "Node does not satisfy the package engine requirement.", action: "Install a Node version satisfying package.json engines.node." },
+    ENGINE_REQUIREMENT_INVALID: { message: "The package Node engine requirement is invalid.", action: "Inspect package.json engines.node." },
+    INSTALL_PACKAGE_OK: { message: "Package metadata is present." },
+    INSTALL_PACKAGE_MISSING: { message: "Package metadata is missing or invalid.", action: REINSTALL },
+    INSTALL_DEPENDENCIES_OK: { message: "Required runtime dependencies and CLI entries resolve." },
+    INSTALL_DEPENDENCY_MISSING: { message: "A required runtime dependency or CLI entry is missing.", action: REINSTALL },
+    INSTALL_NATIVE_OK: { message: "The in-memory SQLite native binding loads." },
+    INSTALL_NATIVE_FAILED: { message: "The SQLite native binding could not load.", action: REINSTALL },
+    INSTALL_SKILLS_OK: { message: "Packaged skills are present." },
+    INSTALL_SKILL_MISSING: { message: "A packaged skill is missing.", action: REINSTALL },
+    INSTALL_UI_OK: { message: "The packaged UI build is available." },
+    INSTALL_UI_MISSING: { message: "The packaged UI build is missing.", action: REINSTALL },
+    INSTALL_UI_STALE: { message: "The source checkout UI build is stale.", action: "Run the project UI build in the source checkout." },
+    NPM_READY: { message: "The package manager is available." },
+    NPM_MISSING: { message: "The package manager is unavailable.", action: "Install the required package manager." },
+    NPM_OLD: { message: "The package manager is older than recommended.", action: "Update the package manager." },
+    DB_PARENT_WRITABLE: { message: "The configured database parent is writable." },
+    DB_PARENT_UNWRITABLE: { message: "The configured database parent is not writable.", action: "Check configured directory permissions." },
+    CONFIG_PERMISSIONS: { message: "Configuration permissions allow other users to read it.", action: "Restrict access to the configuration file." },
+    CONFIG_INVALID: { message: "Configuration is not a valid JSON object.", action: "Repair the configuration JSON object." },
+    CONFIG_PRESENT: { message: "A provider configuration is present; execution is not verified." },
+    CONFIG_MISSING: { message: "No provider configuration is selected.", action: "Run ima2 setup when ready to configure a provider." },
+    ADVERTISEMENT_INVALID: { message: "The local server advertisement is invalid.", action: "Start the intended local server." },
+    CREDENTIAL_PRESENT: { message: "A local credential is present; remote validity is not verified." },
+    CREDENTIAL_MISSING: { message: "A local credential is not configured.", action: "Configure this provider lane when needed." },
+    CREDENTIAL_SHAPE_INVALID: { message: "The configured credential has an invalid shape.", action: "Check this provider credential configuration." },
+    OAUTH_FILE_READY: { message: "A file-backed OAuth session is available." },
+    OAUTH_FILE_REQUIRED: { message: "A file-backed OAuth session is required.", action: "Run ima2 login yourself." },
+    LOCAL_CLI_FOUND: { message: "The configured local CLI exists." },
+    LOCAL_CLI_MISSING: { message: "The local CLI is not configured or missing.", action: "Check the configured executable." },
+    LOCAL_ORIGIN_VALID: { message: "The configured local origin has a valid shape; reachability is not verified." },
+    LOCAL_ORIGIN_INVALID: { message: "The configured local origin is invalid.", action: "Correct the configured local origin." },
+    FFMPEG_READY: { message: "ffmpeg is available." },
+    FFMPEG_MISSING: { message: "ffmpeg is not installed.", action: "Install ffmpeg for video tasks." },
+    FFMPEG_PROBE_FAILED: { message: "The ffmpeg check failed.", action: "Check the ffmpeg installation." },
+    AUTH_VERIFIED: { message: "The non-generating authentication endpoint accepted the credential." },
+    AUTH_INVALID: { message: "The authentication endpoint rejected the credential.", action: "Sign in again or replace this provider credential." },
+    AUTH_RATE_LIMITED: { message: "The authentication check was rate limited.", action: "Retry later; do not reset the credential for this result." },
+    AUTH_UPSTREAM_FAILED: { message: "The authentication endpoint returned an upstream failure.", action: "Check provider status and retry later." },
+    AUTH_NETWORK_FAILED: { message: "The authentication check could not complete.", action: "Inspect network connectivity and retry later." },
+    AUTH_TIMEOUT: { message: "The authentication check timed out.", action: "Check connectivity and retry later." },
+    RUNTIME_READY: { message: "The local server responded with the expected version; upstream generation is not verified." },
+    RUNTIME_AUTH_REQUIRED: { message: "The local server requires authorization.", action: "Use the configured authorized client." },
+    RUNTIME_VERSION_MISMATCH: { message: "The local server version differs from this CLI.", action: "Start the intended version of the server." },
+    RUNTIME_UNREACHABLE: { message: "The requested local server could not be reached.", action: "Start the intended server and check its address." },
+    RUNTIME_TIMEOUT: { message: "The local server health request timed out.", action: "Check the intended local server." },
+    RUNTIME_INVALID_HEALTH: { message: "The local server returned an invalid health response.", action: "Verify that the endpoint belongs to ima2-gen." },
+    RUNTIME_ORIGIN_INVALID: { message: "Runtime diagnostics require an explicit loopback origin without credentials.", action: "Use a loopback HTTP or HTTPS origin with no path, query or fragment." },
+    PORT_AVAILABLE: { message: "The preferred local port is available." },
+    PORT_IN_USE: { message: "The preferred local port is in use." },
+    FEATURE_ENABLED: { message: "The optional feature is enabled." },
+    FEATURE_DISABLED: { message: "The optional feature is disabled." },
+    DIAGNOSTIC_UNKNOWN: { message: "A diagnostic returned an unrecognized result.", action: "Inspect this package version's diagnostic support." },
+};
+export function buildDoctorReport(input) {
+    const lanes = new Set(listProviders().map((provider) => provider.id));
+    const checks = input.lines.map((line) => {
+        const known = Object.hasOwn(CODES, line.code), code = known ? line.code : "DIAGNOSTIC_UNKNOWN";
+        const definition = CODES[code];
+        const kind = known ? line.kind : line.kind === "fail" ? "fail" : "warn";
+        const evidence = line.evidence === "remote-auth" || line.evidence === "local-http" ? line.evidence : "local";
+        return { code, kind, evidence, ...definition, ...(line.lane && lanes.has(line.lane) ? { lane: line.lane } : {}) };
+    });
+    const passed = checks.filter((line) => line.kind === "pass").length;
+    const failed = checks.filter((line) => line.kind === "fail").length;
+    const warned = checks.filter((line) => line.kind === "warn").length;
+    return { schemaVersion: 1, version: input.version, mode: input.mode, checks,
+        summary: { passed, failed, warned, exitCode: failed ? 1 : 0 } };
+}
+export function renderDoctorReport(report) {
+    const checks = report.checks.map((line) => `[${line.kind}] ${line.lane ? line.lane + ": " : ""}${line.message}${line.action ? " Next: " + line.action : ""}`);
+    return [`ima2-gen ${report.version} — ${report.mode} doctor`, ...checks,
+        `${report.summary.passed} passed, ${report.summary.failed} failed, ${report.summary.warned} warnings`].join("\n");
+}

package/bin/lib/doctor-runtime.js

@@ -0,0 +1,173 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getUiDistBuildStatus } from "./ui-build.js";
+const RUNTIME_DEPENDENCIES = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json", "@openai/codex/package.json", "zod"];
+const REQUIRED_BINS = [["openai-oauth", "openai-oauth"], ["@openai/codex", "codex"]];
+const line = (code, kind, text) => ({ code, kind, text, evidence: "local" });
+export function parseMinimumNodeMajor(engine) {
+    if (typeof engine !== "string" || !/^>=[1-9][0-9]*$/.test(engine))
+        throw Error("ENGINE_REQUIREMENT_INVALID");
+    const major = Number(engine.slice(2));
+    if (!Number.isSafeInteger(major))
+        throw Error("ENGINE_REQUIREMENT_INVALID");
+    return major;
+}
+export function checkNodeEngine(version, engine) {
+    try {
+        const minimum = parseMinimumNodeMajor(engine), match = /^v?([0-9]+)\.[0-9]+\.[0-9]+$/.exec(version);
+        const major = match ? Number(match[1]) : NaN;
+        if (!Number.isSafeInteger(major) || major < minimum)
+            return line("NODE_RUNTIME_UNSUPPORTED", "fail", `Node runtime requires >=${minimum}`);
+        return line("NODE_RUNTIME_OK", "pass", `Node.js ${version} (>=${minimum})`);
+    }
+    catch {
+        return line("ENGINE_REQUIREMENT_INVALID", "fail", "Package Node engine requirement is invalid");
+    }
+}
+export function missingRuntimeDeps(root) {
+    const require = createRequire(join(resolve(root), "package.json")), missing = [];
+    for (const dependency of RUNTIME_DEPENDENCIES) {
+        try {
+            require.resolve(dependency);
+        }
+        catch {
+            missing.push(dependency.replace(/\/package\.json$/, ""));
+        }
+    }
+    for (const [name, bin] of REQUIRED_BINS) {
+        try {
+            let manifestPath;
+            try {
+                manifestPath = require.resolve(name + "/package.json");
+            }
+            catch {
+                let parent = dirname(require.resolve(name));
+                while (!existsSync(join(parent, "package.json"))) {
+                    const next = dirname(parent);
+                    if (next === parent)
+                        throw Error("MISSING_MANIFEST");
+                    parent = next;
+                }
+                manifestPath = join(parent, "package.json");
+            }
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            const entry = typeof manifest.bin === "string" ? manifest.bin
+                : manifest.bin && typeof manifest.bin === "object" ? manifest.bin[bin] : undefined;
+            if (manifest.name !== name || typeof entry !== "string" || !existsSync(resolve(dirname(manifestPath), entry)))
+                throw Error("MISSING_BIN");
+        }
+        catch {
+            if (!missing.includes(name))
+                missing.push(name);
+        }
+    }
+    return missing;
+}
+export function checkNativeBinding(root) {
+    let db;
+    try {
+        const require = createRequire(join(resolve(root), "package.json"));
+        const module = require("better-sqlite3");
+        const Database = (module.default ?? module);
+        db = new Database(":memory:");
+        db.close();
+        db = undefined;
+        return line("INSTALL_NATIVE_OK", "pass", "better-sqlite3 native binding loads");
+    }
+    catch {
+        return line("INSTALL_NATIVE_FAILED", "fail", "better-sqlite3 native binding failed; reinstall the approved package");
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* The failed native check is already reported. */ }
+    }
+}
+export function checkPackagedSkills(root) {
+    return ["ima2", "ima2-front", "ima2-uiux"].map((name) => existsSync(join(root, "skills", name, "SKILL.md"))
+        ? line("INSTALL_SKILLS_OK", "pass", `packaged skill found: ${name}`)
+        : line("INSTALL_SKILL_MISSING", "fail", `packaged skill missing: ${name}`));
+}
+export function buildInstallationDoctorLines(root) {
+    const lines = [];
+    try {
+        const metadata = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+            throw Error("INSTALL_PACKAGE_MISSING");
+        lines.push(line("INSTALL_PACKAGE_OK", "pass", "package.json found"), checkNodeEngine(process.version, metadata.engines?.node));
+    }
+    catch {
+        lines.push(line("INSTALL_PACKAGE_MISSING", "fail", "package.json missing or invalid"));
+    }
+    const missing = missingRuntimeDeps(root);
+    lines.push(missing.length ? line("INSTALL_DEPENDENCY_MISSING", "fail", `Missing runtime dependencies: ${missing.join(", ")}`)
+        : line("INSTALL_DEPENDENCIES_OK", "pass", "Runtime dependencies and bins resolve"));
+    lines.push(checkNativeBinding(root), ...checkPackagedSkills(root));
+    try {
+        const ui = getUiDistBuildStatus(root);
+        const code = ui.reason === "stale" ? "INSTALL_UI_STALE"
+            : ui.reason === "missing" || ui.reason === "missing-source-and-dist" ? "INSTALL_UI_MISSING" : "INSTALL_UI_OK";
+        lines.push(line(code, code === "INSTALL_UI_OK" ? "pass" : code === "INSTALL_UI_STALE" ? "warn" : "fail", code));
+    }
+    catch {
+        lines.push(line("INSTALL_UI_MISSING", "fail", "UI build could not be inspected"));
+    }
+    return lines;
+}
+export async function probeDoctorRuntime(input) {
+    const result = (code, kind = "fail") => [{ code, kind, text: code, evidence: "local-http" }];
+    let url;
+    try {
+        url = new URL(input.url);
+        if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+            || url.username || url.password || url.search || url.hash || url.pathname !== "/")
+            return result("RUNTIME_ORIGIN_INVALID");
+    }
+    catch {
+        return result("RUNTIME_ORIGIN_INVALID");
+    }
+    const timeoutMs = Number.isFinite(input.timeoutMs) && input.timeoutMs > 0 ? Math.min(input.timeoutMs, 30000) : 1500;
+    const controller = new AbortController();
+    let timeout, response;
+    const deadline = new Promise((_, reject) => {
+        timeout = setTimeout(() => { controller.abort(); reject(Error("RUNTIME_TIMEOUT")); }, timeoutMs);
+    });
+    try {
+        const work = (async () => {
+            response = await (input.fetchImpl ?? fetch)(new URL("/api/health", url), {
+                redirect: "error", signal: controller.signal, headers: { Connection: "close" },
+            });
+            if (response.status === 401 || response.status === 403) {
+                await response.body?.cancel();
+                return result("RUNTIME_AUTH_REQUIRED", "warn");
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                return result("RUNTIME_INVALID_HEALTH");
+            }
+            let data;
+            try {
+                data = await response.json();
+            }
+            catch {
+                return result(controller.signal.aborted ? "RUNTIME_TIMEOUT" : "RUNTIME_INVALID_HEALTH");
+            }
+            if (!data || typeof data !== "object" || Array.isArray(data))
+                return result("RUNTIME_INVALID_HEALTH");
+            const health = data;
+            if (health.ok !== true || typeof health.version !== "string" || (health.pid !== undefined && (typeof health.pid !== "number" || !Number.isFinite(health.pid))))
+                return result("RUNTIME_INVALID_HEALTH");
+            return health.version === input.expectedVersion ? result("RUNTIME_READY", "pass") : result("RUNTIME_VERSION_MISMATCH", "warn");
+        })();
+        return await Promise.race([work, deadline]);
+    }
+    catch {
+        return result(controller.signal.aborted ? "RUNTIME_TIMEOUT" : "RUNTIME_UNREACHABLE");
+    }
+    finally {
+        clearTimeout(timeout);
+        controller.abort();
+    }
+}

package/bin/lib/mcpJob.js

@@ -1,5 +1,7 @@
 import { openSse, sseUrlWithCursor } from "./sse.js";
 import { normalizeTerminalStatus } from "../../lib/jobStatus.js";
+import { fetchServer } from "./client.js";
+const JOB_TRACKING_TIMEOUT_MESSAGE = "Job tracking expired; upstream completion is unknown. Inspect history before retrying.";
 export class McpJobError extends Error {
     code;
     status;
@@ -54,7 +56,7 @@ async function responseError(response) {
 }
 async function submitJob(opts, signal) {
     try {
-        const response = await fetch(`${baseUrl(opts.serverBase)}${opts.postPath ?? "/api/mcp/generate"}`, {
+        const response = await fetchServer(opts.serverBase, opts.postPath ?? "/api/mcp/generate", {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ ...opts.body, kind: opts.kind, requestId: opts.requestId }),
@@ -121,26 +123,33 @@ function matchingOutcome(event, opts) {
         }
         else {
             const envErr = asRecord(envelope.error);
+            const code = typeof envErr?.code === "string" ? envErr.code
+                : typeof data.code === "string" ? data.code : fallbackCode(phase);
             return {
                 kind: "error",
-                error: new McpJobError(typeof envErr?.code === "string" ? envErr.code
-                    : typeof data.code === "string" ? data.code
-                        : fallbackCode(phase), errorMessage(data)),
+                error: code === "JOB_TRACKING_TIMEOUT"
+                    ? new McpJobError(code, JOB_TRACKING_TIMEOUT_MESSAGE, { status: 504 })
+                    : new McpJobError(code, errorMessage(data)),
             };
         }
     }
     if (event.event === "done")
         return doneResult(data);
     if (event.event === "error") {
+        const code = typeof data.code === "string" ? data.code : "MCP_JOB_FAILED";
         return {
             kind: "error",
-            error: new McpJobError(typeof data.code === "string" ? data.code : "MCP_JOB_FAILED", typeof data.message === "string" ? data.message : "MCP job failed"),
+            error: code === "JOB_TRACKING_TIMEOUT"
+                ? new McpJobError(code, JOB_TRACKING_TIMEOUT_MESSAGE, { status: 504 })
+                : new McpJobError(code, typeof data.message === "string" ? data.message : "MCP job failed"),
         };
     }
     return null;
 }
 async function consumeStream(stream, opts) {
-    let lastEventId;
+    // Keep the server's pre-job bookmark until an event is actually observed.
+    // This makes an EOF before the first frame recoverable without reposting.
+    let lastEventId = stream.initialEventId;
     try {
         for await (const event of stream.events) {
             if (event.id !== undefined)
@@ -160,6 +169,9 @@ function terminalResult(job) {
     const meta = asRecord(job.meta) ?? {};
     const normalized = normalizeTerminalStatus(status);
     if (normalized === "error") {
+        if (job.errorCode === "JOB_TRACKING_TIMEOUT") {
+            return new McpJobError("JOB_TRACKING_TIMEOUT", JOB_TRACKING_TIMEOUT_MESSAGE, { status: 504 });
+        }
         return new McpJobError(typeof job.errorCode === "string" ? job.errorCode : "MCP_JOB_FAILED", typeof meta.message === "string" ? meta.message : "MCP job failed");
     }
     // A canceled job is terminal too. Falling through would report the generic
@@ -179,7 +191,7 @@ function terminalResult(job) {
 }
 async function recoverReplayGap(opts, signal) {
     try {
-        const response = await fetch(`${baseUrl(opts.serverBase)}/api/inflight?includeTerminal=1`, { signal });
+        const response = await fetchServer(opts.serverBase, "/api/inflight?includeTerminal=1", { signal });
         if (!response.ok)
             throw await responseError(response);
         const envelope = asRecord(await response.json()) ?? {};

package/bin/lib/output.js

@@ -78,6 +78,9 @@ export function exitCodeForError(e) {
     const err = e;
     if (err?.code === "SERVER_UNREACHABLE")
         return 3;
+    if (err?.status === 401 || err?.status === 403 || ["LAN_TOKEN_REQUIRED", "LOCAL_HOST_REJECTED",
+        "LOCAL_ORIGIN_REJECTED", "SERVER_ACCESS_DENIED"].includes(err?.code ?? ""))
+        return 4;
     if (err?.code === "APIKEY_DISABLED")
         return 4;
     if (err?.code === "AUTH_CHATGPT_EXPIRED" || err?.code === "OAUTH_UNAVAILABLE")

package/bin/lib/platform.js

@@ -1,6 +1,6 @@
 // Cross-platform helpers (Windows / macOS / Linux / WSL).
 // Keep this file tiny & dependency-free. Node 18+ only.
-import { spawn, execSync } from "node:child_process";
+import { spawn, execFileSync, execSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { errInfo } from "../../lib/errInfo.js";
 export const isWin = process.platform === "win32";
@@ -52,21 +52,24 @@ export function spawnBin(name, args, opts = {}) {
  */
 export function openUrl(url) {
     try {
-        if (isMac) {
-            execSync(`open ${JSON.stringify(url)}`, { stdio: "ignore" });
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return { ok: false, error: "only http(s) URLs can be opened" };
         }
-        else if (isWin) {
-            execSync(`cmd /c start "" ${JSON.stringify(url)}`, { stdio: "ignore" });
+        if (isMac) {
+            execFileSync("open", [url], { stdio: "ignore" });
         }
-        else if (isWsl()) {
-            // WSL: hand off to Windows via powershell
-            execSync(`powershell.exe -NoProfile -Command Start-Process ${JSON.stringify(url)}`, { stdio: "ignore" });
+        else if (isWin || isWsl()) {
+            // Only base64 data varies; URL punctuation never enters PowerShell syntax.
+            const encoded = Buffer.from(url, "utf8").toString("base64");
+            const command = `$u=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}')); Start-Process -FilePath $u -ErrorAction Stop`;
+            execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(command, "utf16le").toString("base64")], { stdio: "ignore", windowsHide: true });
         }
         else {
             if (!hasDesktopSession()) {
                 return { ok: false, error: "no desktop session (DISPLAY/WAYLAND_DISPLAY unset)" };
             }
-            execSync(`xdg-open ${JSON.stringify(url)}`, { stdio: "ignore" });
+            execFileSync("xdg-open", [url], { stdio: "ignore" });
         }
         return { ok: true };
     }