@juspay/neurolink 9.95.2 → 10.0.0

package/dist/cli/commands/proxy.d.ts

@@ -13,6 +13,32 @@ import type { CommandModule } from "yargs";
 import type { Hono } from "hono";
 import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export declare function processLooksLikeProxySupervisor(pid: number, expectedStartTimeIso?: string): Promise<boolean>;
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
 export declare function createProxyStartApp(params: {
     neurolink: ProxyNeurolinkRuntime["neurolink"];

package/dist/cli/commands/proxy.js

@@ -41,6 +41,14 @@ const _require = createRequire(import.meta.url);
 const PROXY_VERSION = packageJson.version;
 const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
+// Allowed drift between a pid's OS-reported start time and the persisted
+// ProxySupervisorState.startTime before processLooksLikeProxySupervisor
+// treats it as a confident mismatch (recycled pid). Generous on purpose:
+// `supervisorStartedAt` is captured inside runLaunchdProxySupervisor, which
+// runs after Node has already booted and done setup, so it always lags the
+// OS-level fork/exec by a little — a tight tolerance would produce false
+// mismatches on a slow/cold-started machine.
+const PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS = 10_000;
 const PROXY_UPDATE_CONTROL_TOKEN = process.env.NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN?.trim() ||
     crypto.randomUUID();
 // =============================================================================
@@ -98,23 +106,131 @@ function getProcessStatus(pid) {
     }
 }
 /**
- * Best-effort check that a pid actually belongs to a neurolink proxy process,
- * so a stale/recycled supervisor pid is never mistaken for a live supervisor
- * and signalled. Returns false when the process cannot be confirmed as ours.
+ * Read a single `ps -o <field>=` field for `pid`, off the event loop (async
+ * `execFile`, not `execFileSync`) and bounded by a short timeout, so a
+ * hung/zombie `ps` invocation can never block the event loop or hang the
+ * (often uninstall-path) async caller. Shared by {@link getProcessStartTime}
+ * and {@link processLooksLikeProxySupervisor}, which both read a single
+ * `ps -o <field>=` column for the same pid.
+ *
+ * Returns null — never throws — on any error, timeout, or empty output, so
+ * callers uniformly treat "couldn't read" as "can't confirm either way"
+ * rather than distinguishing the failure mode.
  */
-async function processLooksLikeProxySupervisor(pid) {
+async function readPsField(pid, field) {
     try {
-        const { execFileSync } = await import("node:child_process");
-        const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        const { stdout } = await withTimeout(execFileAsync("ps", ["-p", String(pid), "-o", `${field}=`], {
             encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return /neurolink/i.test(args);
+        }), 2000, `ps -o ${field}= timed out for pid ${pid}`);
+        const trimmed = stdout.trim();
+        return trimmed || null;
     }
     catch {
-        // `ps` unavailable or the pid vanished — do not signal an unverified pid.
+        return null;
+    }
+}
+/**
+ * Best-effort, macOS-only (uninstall is macOS-only) read of `pid`'s
+ * OS-reported start time via `ps -o lstart=`, which prints a fixed-width
+ * `Www Mmm dd hh:mm:ss yyyy` timestamp — the same shape `Date`'s parser
+ * already understands (it's the format `Date#toString()` itself produces
+ * modulo the trailing timezone). Returns null (never throws) when `ps`
+ * fails or its output doesn't parse, so callers can tell "confirmed
+ * mismatch" apart from "couldn't confirm either way".
+ */
+async function getProcessStartTime(pid) {
+    const out = await readPsField(pid, "lstart");
+    if (!out) {
+        return null;
+    }
+    // `ps -o lstart=` prints the OS start time in the machine's LOCAL timezone
+    // with no offset, e.g. "Sun Jul 19 20:12:41 2026". Parse the components and
+    // build the Date via the local-time constructor rather than relying on the
+    // engine's implementation-defined parsing of non-ISO date strings. The
+    // result is the same absolute instant the supervisor persisted as an
+    // ISO-UTC string, so the drift comparison against it is timezone-safe.
+    const m = out.match(/^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/);
+    if (!m) {
+        return null;
+    }
+    const monthIndex = [
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+    ].indexOf(m[1]);
+    if (monthIndex < 0) {
+        return null;
+    }
+    const parsed = new Date(Number(m[6]), monthIndex, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export async function processLooksLikeProxySupervisor(pid, expectedStartTimeIso) {
+    const args = await readPsField(pid, "args");
+    if (args === null) {
+        // `ps` unavailable, timed out, or the pid vanished — do not signal an
+        // unverified pid.
+        return false;
+    }
+    // `/neurolink/i` alone is too broad: any process whose args merely
+    // *mention* "neurolink" (e.g. a shell running in a directory named
+    // "neurolink", an editor with a neurolink file open) would match, and a
+    // stale/recycled pid running such a process could then be SIGTERM'd/
+    // SIGKILL'd by `ensureSupervisorStoppedBeforeClear` during uninstall.
+    // Require the actual proxy-supervisor invocation — both "neurolink" AND
+    // the "proxy" subcommand present in args.
+    if (!(/neurolink/i.test(args) && /\bproxy\b/i.test(args))) {
         return false;
     }
+    if (!expectedStartTimeIso) {
+        return true;
+    }
+    const expected = new Date(expectedStartTimeIso);
+    if (Number.isNaN(expected.getTime())) {
+        return true; // recorded startTime itself is unparseable — can't confirm a mismatch
+    }
+    const actual = await getProcessStartTime(pid);
+    if (!actual) {
+        return true; // ps -o lstart= unavailable/unparseable — can't confirm a mismatch
+    }
+    const driftMs = Math.abs(actual.getTime() - expected.getTime());
+    return driftMs <= PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS;
 }
 /**
  * Ensure any supervisor recorded in state is actually stopped before its state
@@ -124,14 +240,17 @@ async function processLooksLikeProxySupervisor(pid) {
  * the uninstall instead of silently discarding the record.
  */
 async function ensureSupervisorStoppedBeforeClear() {
-    const pid = loadProxySupervisorState()?.pid;
+    const supervisorState = loadProxySupervisorState();
+    const pid = supervisorState?.pid;
     if (!pid || getProcessStatus(pid) === "not_running") {
         return true;
     }
     // Guard against a stale/recycled pid: only signal a process that still looks
     // like a neurolink proxy supervisor, so uninstall never terminates an
-    // unrelated, same-user process that inherited the recorded pid.
-    if (!(await processLooksLikeProxySupervisor(pid))) {
+    // unrelated, same-user process that inherited the recorded pid. Also cross-
+    // checks the pid's actual OS start time against the recorded
+    // supervisorState.startTime (see processLooksLikeProxySupervisor).
+    if (!(await processLooksLikeProxySupervisor(pid, supervisorState?.startTime))) {
         return true;
     }
     try {

package/dist/cli/factories/commandFactory.d.ts

@@ -192,6 +192,13 @@ export declare class CLICommandFactory {
      * objects independently.
      */
     private static buildCsvOptionsFromArgv;
+    /**
+     * Build video processor options from CLI argv. Shared by executeGenerate,
+     * executeStream and executeBatch, which previously built byte-for-byte
+     * identical `videoOptions` objects independently (mirrors
+     * {@link buildCsvOptionsFromArgv}).
+     */
+    private static buildVideoOptionsFromArgv;
     /**
      * Build output configuration for generate request
      */

package/dist/cli/factories/commandFactory.js

@@ -2438,6 +2438,20 @@ export class CLICommandFactory {
             parseTimeoutMs: argv.csvParseTimeoutMs,
         };
     }
+    /**
+     * Build video processor options from CLI argv. Shared by executeGenerate,
+     * executeStream and executeBatch, which previously built byte-for-byte
+     * identical `videoOptions` objects independently (mirrors
+     * {@link buildCsvOptionsFromArgv}).
+     */
+    static buildVideoOptionsFromArgv(argv) {
+        return {
+            frames: argv.videoFrames,
+            quality: argv.videoQuality,
+            format: argv.videoFormat,
+            transcribeAudio: argv.transcribeAudio,
+        };
+    }
     /**
      * Build output configuration for generate request
      */
@@ -2677,12 +2691,7 @@ export class CLICommandFactory {
                     password: CLICommandFactory.resolvePdfPassword(argv),
                 },
                 csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
-                videoOptions: {
-                    frames: argv.videoFrames,
-                    quality: argv.videoQuality,
-                    format: argv.videoFormat,
-                    transcribeAudio: argv.transcribeAudio,
-                },
+                videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
                 output: outputConfig,
                 provider: enhancedOptions.provider,
                 model: enhancedOptions.model,
@@ -2932,12 +2941,7 @@ export class CLICommandFactory {
                 password: CLICommandFactory.resolvePdfPassword(argv),
             },
             csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
-            videoOptions: {
-                frames: argv.videoFrames,
-                quality: argv.videoQuality,
-                format: argv.videoFormat,
-                transcribeAudio: argv.transcribeAudio,
-            },
+            videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
             provider: enhancedOptions.provider,
             model: enhancedOptions.model,
             temperature: enhancedOptions.temperature,
@@ -3411,6 +3415,7 @@ export class CLICommandFactory {
             // see createBatchCommand — so `argv.file` can never be set here; no
             // exclusion needed to protect the (differently-named) positional.
             validateCliInputFiles(argv);
+            validateCsvMaxRows(argv);
             const batchImages = CLICommandFactory.processCliImages(argv.image);
             const batchCsvFiles = CLICommandFactory.processCliCSVFiles(argv.csv);
             const batchPdfFiles = CLICommandFactory.processCliPDFFiles(argv.pdf);
@@ -3469,6 +3474,12 @@ export class CLICommandFactory {
                 logger.alwaysStderr(chalk.yellow("⚠️  Multimodal files (--image/--csv/--pdf/--video) are attached to ALL prompts in this batch."));
                 spinner?.start();
             }
+            // Resolve the PDF password once for the whole batch. resolvePdfPassword
+            // emits a "visible in shell history" stderr warning when the flag is set;
+            // it must fire once per run (like generate/stream), not once per prompt.
+            const batchPdfPassword = batchPdfFiles?.length
+                ? CLICommandFactory.resolvePdfPassword(argv)
+                : undefined;
             for (let i = 0; i < prompts.length; i++) {
                 if (spinner) {
                     spinner.text = `Processing ${i + 1}/${prompts.length}: ${prompts[i].substring(0, 30)}...`;
@@ -3518,18 +3529,15 @@ export class CLICommandFactory {
                         // unlike generate/stream, so an empty options object here is
                         // pure noise on every prompt of every batch run.
                         ...(batchCsvFiles?.length && {
-                            csvOptions: {
-                                maxRows: argv.csvMaxRows,
-                                formatStyle: argv.csvFormat,
+                            csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
+                        }),
+                        ...(batchPdfFiles?.length && {
+                            pdfOptions: {
+                                password: batchPdfPassword,
                             },
                         }),
                         ...(batchVideoFiles?.length && {
-                            videoOptions: {
-                                frames: argv.videoFrames,
-                                quality: argv.videoQuality,
-                                format: argv.videoFormat,
-                                transcribeAudio: argv.transcribeAudio,
-                            },
+                            videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
                         }),
                         provider: enhancedOptions.provider,
                         model: enhancedOptions.model,

package/dist/cli/utils/inputValidation.d.ts

@@ -21,6 +21,7 @@ export declare const CLI_SOFT_LIMITS_MB: {
     readonly IMAGE_MAX_MB: 10;
     readonly CSV_MAX_MB: 50;
     readonly PDF_MAX_MB: 100;
+    readonly PDF_SOFT_MAX_MB: 50;
     readonly VIDEO_MAX_MB: 500;
 };
 /**

package/dist/cli/utils/inputValidation.js

@@ -27,6 +27,11 @@ export const CLI_SOFT_LIMITS_MB = {
     IMAGE_MAX_MB: 10,
     CSV_MAX_MB: 50,
     PDF_MAX_MB: 100,
+    // Distinct from PDF_MAX_MB above (which mirrors the processor's true
+    // 100MB hard cap in lib/processors/config/sizeLimits.ts and is kept here
+    // for backward compatibility). Docs promise a 50MB *warning* threshold
+    // specifically for --pdf — wire warnAtMB to this value, not the hard cap.
+    PDF_SOFT_MAX_MB: 50,
     VIDEO_MAX_MB: 500,
 };
 // `file://` is intentionally excluded here: it addresses a local path, so it
@@ -165,7 +170,7 @@ export function validateCliInputFiles(argv) {
         {
             option: "--pdf",
             value: argv.pdf,
-            warnAtMB: CLI_SOFT_LIMITS_MB.PDF_MAX_MB,
+            warnAtMB: CLI_SOFT_LIMITS_MB.PDF_SOFT_MAX_MB,
         },
         {
             option: "--video",

package/dist/core/constants.d.ts

@@ -122,6 +122,9 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    MIN_SCALE: number;
+    DEFAULT_SCALE: number;
+    PAGE_COUNT_TIMEOUT_MS: number;
     DEFAULT_MAX_CANVAS_PIXELS: number;
     MIN_EFFECTIVE_SCALE: number;
 };

package/dist/core/constants.js

@@ -220,6 +220,16 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Lower bound for the render scale factor (#297). Below this the render is
+    // effectively unreadable; enforcing it makes the documented 0.1–10 range real
+    // (previously only scale <= 0 was rejected).
+    MIN_SCALE: 0.1,
+    // Default render scale (#297). Lowered from 2 → 1.5 to roughly halve the
+    // per-page canvas memory while staying legible for OCR/vision.
+    DEFAULT_SCALE: 1.5,
+    // Timeout (ms) for the accurate pdf-parse page-count probe (#287); on timeout
+    // the processor falls back to the regex estimate rather than blocking.
+    PAGE_COUNT_TIMEOUT_MS: 5000,
     // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
     // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
     // uniformly downscaled to stay under this instead of allocating gigabytes.

package/dist/lib/core/constants.d.ts

@@ -122,6 +122,9 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    MIN_SCALE: number;
+    DEFAULT_SCALE: number;
+    PAGE_COUNT_TIMEOUT_MS: number;
     DEFAULT_MAX_CANVAS_PIXELS: number;
     MIN_EFFECTIVE_SCALE: number;
 };

package/dist/lib/core/constants.js

@@ -220,6 +220,16 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Lower bound for the render scale factor (#297). Below this the render is
+    // effectively unreadable; enforcing it makes the documented 0.1–10 range real
+    // (previously only scale <= 0 was rejected).
+    MIN_SCALE: 0.1,
+    // Default render scale (#297). Lowered from 2 → 1.5 to roughly halve the
+    // per-page canvas memory while staying legible for OCR/vision.
+    DEFAULT_SCALE: 1.5,
+    // Timeout (ms) for the accurate pdf-parse page-count probe (#287); on timeout
+    // the processor falls back to the regex estimate rather than blocking.
+    PAGE_COUNT_TIMEOUT_MS: 5000,
     // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
     // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
     // uniformly downscaled to stay under this instead of allocating gigabytes.

package/dist/lib/types/file.d.ts

@@ -95,6 +95,8 @@ export type FileProcessingResult = {
         estimatedPages?: number | null;
         provider?: string;
         apiType?: PDFAPIType;
+        /** Provider's citations requirement for visual PDF analysis (#349). */
+        requiresCitations?: boolean | "auto";
         officeFormat?: OfficeDocumentType;
         pageCount?: number;
         slideCount?: number;
@@ -210,6 +212,14 @@ export type PDFProviderConfig = {
     maxSizeMB: number;
     maxPages: number;
     supportsNative: boolean;
+    /**
+     * Whether this provider needs source citations enabled for visual PDF
+     * analysis (#349). `"auto"` = enable when the request requires visual
+     * grounding (currently Bedrock's Converse document blocks); `false` = the
+     * provider handles PDFs without an explicit citations flag. Surfaced on
+     * `FileProcessingResult.metadata.requiresCitations` so downstream provider
+     * adapters can act on it instead of the value being dead config.
+     */
     requiresCitations: boolean | "auto";
     apiType: PDFAPIType;
 };
@@ -405,10 +415,32 @@ export type PDFImageConversionOptions = {
     maxCanvasPixels?: number;
     /** Password for an encrypted PDF (passed to the underlying renderer) (#258). */
     password?: string;
+    /** Per-page progress callback invoked as each page is rendered (#302). */
+    onProgress?: (progress: PDFImageConversionProgress) => void | Promise<void>;
+};
+/** Progress reported per page during streaming conversion (#302). */
+export type PDFImageConversionProgress = {
+    /** Number of pages successfully converted so far. */
+    pagesConverted: number;
+    /** Total pages in the document (known up-front from the renderer). */
+    totalPages: number;
+    /** Elapsed time since conversion started, in milliseconds. */
+    elapsedMs: number;
+};
+/** A single streamed page result (#302). `error` is set when that page failed. */
+export type PDFImagePage = {
+    /** 1-based page index. */
+    pageIndex: number;
+    /** Base64-encoded PNG for the page (empty string when `error` is set). */
+    image: string;
+    /** Byte size of the rendered PNG (0 when `error` is set). */
+    imageSizeBytes: number;
+    /** Populated when this page failed to render (#294). */
+    error?: string;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
-    /** Array of base64-encoded PNG images (one per page) */
+    /** Array of base64-encoded PNG images (one per successfully converted page) */
     images: string[];
     /** Number of pages converted */
     pageCount: number;
@@ -416,6 +448,11 @@ export type PDFImageConversionResult = {
     conversionTimeMs: number;
     /** Any warnings during conversion */
     warnings?: string[];
+    /** Per-page failures — present only when some pages failed to render (#294). */
+    errors?: Array<{
+        page: number;
+        error: string;
+    }>;
 };
 /** Options for filename sanitization. */
 export type SanitizeFileNameOptions = {

package/dist/lib/utils/fileDetector.js

@@ -25,7 +25,7 @@ import { CSVProcessor } from "./csvProcessor.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
 import { withTimeout } from "./errorHandling.js";
-import { redactUrlForError, sanitizeErrorCause } from "./logSanitize.js";
+import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
 /**
@@ -54,22 +54,40 @@ const DEFAULT_RETRY_DELAY = 1000; // milliseconds
 const URL_CONTENT_TYPE_TTL_MS = 60_000;
 const URL_CONTENT_TYPE_CACHE_MAX_SIZE = 512;
 const urlContentTypeCache = new Map();
+/**
+ * Build the Map key for `urlContentTypeCache`. Delegates to the shared
+ * {@link normalizeUrlForCache} — this is a module-level, process-lifetime
+ * cache, so it must strip presigned-URL auth/signature query params (see
+ * `SENSITIVE_URL_QUERY_PARAM_DENYLIST`) the same way `ImageCache.normalizeUrl`
+ * does, folding a short hash of the stripped params into the key whenever any
+ * were present so two different presigned URLs for the same path don't
+ * collide and serve each other's cached content-type across auth contexts.
+ * Also strips tracking/analytics params first, so two URLs differing only by
+ * tracking noise (e.g. `utm_source`) still hit the same cache entry instead
+ * of missing each other. Falls back to the raw URL if it isn't a parseable
+ * absolute URL. Shared by both `getCachedUrlContentType` and
+ * `setCachedUrlContentType` so lookups and writes always agree on the key.
+ */
+function cacheKeyForUrl(url) {
+    return normalizeUrlForCache(url);
+}
 function getCachedUrlContentType(url, now) {
-    const hit = urlContentTypeCache.get(url);
+    const key = cacheKeyForUrl(url);
+    const hit = urlContentTypeCache.get(key);
     if (hit && hit.expiresAt > now) {
         // Bump recency: Map iteration order follows insertion order, and the
         // eviction below deletes the *first* key, so a plain `get` on a hot
         // entry would leave it first in line for eviction despite being the
         // most recently used. Re-inserting turns the size-bounded FIFO below
         // into an actual LRU.
-        urlContentTypeCache.delete(url);
-        urlContentTypeCache.set(url, hit);
+        urlContentTypeCache.delete(key);
+        urlContentTypeCache.set(key, hit);
         return hit.contentType;
     }
     if (hit) {
         // Entry exists but its TTL has passed — treat as a miss and evict it
         // immediately rather than serving (or retaining) stale data.
-        urlContentTypeCache.delete(url);
+        urlContentTypeCache.delete(key);
     }
     return undefined;
 }
@@ -89,7 +107,8 @@ function setCachedUrlContentType(url, contentType, now) {
     if (!contentType) {
         return;
     }
-    urlContentTypeCache.set(url, {
+    const key = cacheKeyForUrl(url);
+    urlContentTypeCache.set(key, {
         contentType,
         expiresAt: now + URL_CONTENT_TYPE_TTL_MS,
     });
@@ -1413,6 +1432,50 @@ export class FileDetector {
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
+        // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
+        // body. content-length is advisory (chunked responses omit it), so a
+        // missing/invalid header — or a server that refuses HEAD — falls through to
+        // the streaming byte guard below; only a genuine oversize rejection stops
+        // the GET from ever running.
+        //
+        // #323: skip the pre-flight entirely when this exact URL was recently seen
+        // (its Content-Type is still cached, whether from a prior loadFromURL GET
+        // or a MimeTypeStrategy HEAD) — issuing a fresh HEAD here would defeat the
+        // whole point of that cache. The streaming byte guard in the GET below
+        // still enforces maxSize even without a pre-flight, so this doesn't remove
+        // the oversize protection — it only skips the redundant round-trip for a
+        // URL we've already been talking to within the last 60s.
+        if (getCachedUrlContentType(url, Date.now()) === undefined) {
+            try {
+                const head = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "HEAD",
+                    headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                    bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                });
+                // Drain/close the (empty) HEAD body so the connection can be reused.
+                await head.body.dump();
+                // Only trust `content-length` on a genuine 2xx response. A non-2xx
+                // HEAD (redirect the dispatcher didn't follow, 403/404/405 "HEAD not
+                // allowed", 5xx, …) can still carry a stale/irrelevant
+                // `content-length` header — enforcing size off of that would reject
+                // (or silently pass) based on the wrong body. Treat any non-2xx HEAD
+                // as if the header were missing and fall through to the streaming
+                // GET guard below, which enforces maxSize independently either way.
+                if (head.statusCode >= 200 && head.statusCode < 300) {
+                    const declaredLength = Number(head.headers["content-length"]);
+                    if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
+                        throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && /File too large/.test(error.message)) {
+                    throw error;
+                }
+                logger.debug(`[FileDetector] HEAD pre-flight skipped for ${redactUrlForError(url)}: ${sanitizeErrorCause(error).message}`);
+            }
+        }
         return withRetry(async () => {
             try {
                 const response = await request(url, {

package/dist/lib/utils/imageCache.d.ts

@@ -33,8 +33,16 @@ export declare class ImageCache {
      */
     private parseConfigValue;
     /**
-     * Normalize URL for consistent cache key generation
-     * Removes tracking parameters and normalizes the URL
+     * Normalize URL for consistent cache key generation.
+     *
+     * Delegates to the shared {@link normalizeUrlForCache} — this normalized
+     * URL is used as the in-memory Map key (see `get`/`set` below), which lives
+     * for the process lifetime, so both tracking-param noise and presigned-URL
+     * auth/signature secrets must be stripped consistently with
+     * `fileDetector.cacheKeyForUrl`'s identical requirement. See
+     * `stripSensitiveUrlParamsForCacheKey`'s doc comment for why a naive
+     * strip-only approach (no hash suffix) would be a correctness bug, not just
+     * a hygiene one.
      */
     private normalizeUrl;
     /**