@infersec/conduit 1.106.0 → 1.108.0

package/dist/cli.js

@@ -10,7 +10,7 @@ import path$1, { join, win32, posix, dirname, resolve as resolve$1, basename, se
 import * as require$$3$4 from 'node:fs';
 import require$$3__default, { existsSync, createWriteStream, statSync, readFileSync, appendFileSync, writeFileSync, createReadStream } from 'node:fs';
 import process$3, { platform, hrtime, execPath, execArgv } from 'node:process';
-import crypto from 'node:crypto';
+import crypto, { randomUUID } from 'node:crypto';
 import require$$0$h, { Readable, Transform, PassThrough, getDefaultHighWaterMark, Duplex, Writable } from 'node:stream';
 import require$$1$a, { setDefaultResultOrder } from 'node:dns';
 import require$$0$9 from 'os';
@@ -21288,6 +21288,42 @@ object$1({
     name: ResourceNameSchema
 });
 
+const FitMethodSchema = _enum$1(["gguf-header", "model-config", "parameter-heuristic"]);
+const FitConfidenceSchema = _enum$1(["high", "low", "medium"]);
+object$1({
+    architecture: string$2().nullable(),
+    contextTrainTokens: number$1().int().positive().nullable(),
+    embeddingLength: number$1().int().positive().nullable(),
+    headCount: number$1().int().positive().nullable(),
+    headCountKV: number$1().int().positive().nullable(),
+    headDim: number$1().int().positive().nullable(),
+    layerCount: number$1().int().positive().nullable(),
+    method: FitMethodSchema,
+    probedAt: string$2(),
+    unresolved: boolean$1().optional()
+});
+const FitMemoryDomainKindSchema = _enum$1(["gpu", "system", "unified"]);
+const FitMemoryDomainSchema = object$1({
+    capacityBytes: number$1().int().nonnegative(),
+    domainId: string$2(),
+    kind: FitMemoryDomainKindSchema,
+    label: string$2(),
+    remainingBytes: number$1().int(),
+    requiredBytes: number$1().int().nonnegative(),
+    reserveBytes: number$1().int().nonnegative()
+});
+object$1({
+    confidence: FitConfidenceSchema,
+    contextTokens: number$1().int().positive(),
+    deficitBytes: number$1().int().nonnegative(),
+    domains: array(FitMemoryDomainSchema),
+    engine: LLMEngineSchema,
+    fits: boolean$1(),
+    limitingDomain: string$2().nullable(),
+    method: FitMethodSchema,
+    totalRequiredBytes: number$1().int().nonnegative()
+});
+
 const ENGINE_API_COMPATIBILITY = {
     exllamav3: {
         nativeAnthropicMessages: false,
@@ -21620,6 +21656,7 @@ const ModelEndpointCallConfigSchema = object$1({
     description: string$2().min(1),
     endpointId: string$2().min(1),
     inputSchema: record(string$2(), unknown()).optional(),
+    maxTokens: number$1().int().positive().optional(),
     outputSchema: record(string$2(), unknown()).optional(),
     systemPrompt: string$2().optional(),
     type: literal("model-endpoint-call")
@@ -21628,6 +21665,7 @@ const ModelSourceCallConfigSchema = object$1({
     description: string$2().min(1),
     groupId: ULIDSchema.optional(),
     inputSchema: record(string$2(), unknown()).optional(),
+    maxTokens: number$1().int().positive().optional(),
     outputSchema: record(string$2(), unknown()).optional(),
     sourceId: ULIDSchema.optional(),
     systemPrompt: string$2().optional(),
@@ -123295,6 +123333,181 @@ async function downloadFileWithRange({ accessToken, filePath, fileSize, modelSlu
     throw new Error(errorMessage);
 }
 
+const RESTORE_RETRY_ATTEMPTS = 50;
+const RESTORE_RETRY_DELAY_MS = 5;
+function errorCode(error) {
+    if (typeof error === "object" && error !== null) {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return null;
+}
+function isFileExistsError(error) {
+    return errorCode(error) === "EEXIST";
+}
+function isFileNotFoundError(error) {
+    return errorCode(error) === "ENOENT";
+}
+async function readLockContents({ lockFilePath }) {
+    try {
+        const raw = await readFile(lockFilePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (typeof data.acquiredAt !== "number" || typeof data.token !== "string")
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+async function observeLock({ lockFilePath }) {
+    const [contents, stats] = await Promise.all([
+        readLockContents({ lockFilePath }),
+        stat(lockFilePath).catch(error => {
+            if (isFileNotFoundError(error))
+                return null;
+            throw error;
+        })
+    ]);
+    return {
+        contents,
+        exists: stats !== null,
+        mtimeAgeMs: stats ? Date.now() - stats.mtimeMs : null
+    };
+}
+/**
+ * Remove a lock file only if it is the exact instance that was observed and
+ * verified. The candidate is first renamed to a unique quarantine path
+ * (rename is atomic, so exactly one competing process can isolate a given
+ * instance); the quarantined file is then re-verified against the expected
+ * identity. A mismatch means a replacement lock was captured by the rename -
+ * it is renamed back into place rather than deleted.
+ *
+ * Residual race: a restore rename could theoretically clobber a third lock
+ * created in the microsecond window while the replacement sat in quarantine.
+ * Files alone cannot provide a fully linearizable compare-and-delete; closing
+ * that window entirely would require an OS-level lock primitive (flock).
+ */
+async function removeVerifiedLockInstance({ isTargetInstance, lockFilePath, logger, quarantinePrefix }) {
+    const quarantinePath = `${lockFilePath}.${quarantinePrefix}-${process.pid}-${randomUUID()}`;
+    try {
+        await rename(lockFilePath, quarantinePath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error))
+            return false;
+        throw error;
+    }
+    const quarantined = await observeLock({ lockFilePath: quarantinePath });
+    if (isTargetInstance(quarantined)) {
+        await rm(quarantinePath, { force: true });
+        return true;
+    }
+    // A replacement lock was captured - restore it before continuing
+    for (let attempt = 1;; attempt++) {
+        try {
+            await rename(quarantinePath, lockFilePath);
+            return false;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code !== "ENOTEMPTY" && code !== "EEXIST" && code !== "EPERM")
+                throw error;
+            if (attempt >= RESTORE_RETRY_ATTEMPTS) {
+                logger.warn("Failed restoring quarantined replacement lock", {
+                    lockFilePath,
+                    quarantinePath
+                });
+                return false;
+            }
+            await new Promise(resolve => setTimeout(resolve, RESTORE_RETRY_DELAY_MS));
+        }
+    }
+}
+/**
+ * Acquire an exclusive cross-process file lock. Creation uses the "wx" flag
+ * so the check-and-create step is atomic: concurrent processes can never both
+ * observe a missing lock file and both claim it. Each acquisition owns a
+ * unique token; only a lock whose stored token matches the holder's handle
+ * may be released by that holder. An active (non-stale) lock is never broken
+ * because a waiter timed out - the waiter fails instead.
+ *
+ * Staleness is judged per observed instance: a parsed lock is stale when its
+ * recorded acquisition age exceeds staleMs; an unparseable lock (possible
+ * mid-write observation) is stale only when its mtime is itself old, so a
+ * fresh lock can never be quarantined off the back of a partial read.
+ */
+async function acquireExclusiveFileLock({ lockFilePath, logger, pollIntervalMs, staleMs, timeoutMs }) {
+    await mkdir(dirname(lockFilePath), { recursive: true });
+    const token = `${process.pid}-${randomUUID()}`;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            const contents = { acquiredAt: Date.now(), token };
+            await writeFile(lockFilePath, JSON.stringify(contents), { flag: "wx" });
+            logger.info("Acquired download lock", { lockFilePath });
+            return { lockFilePath, token };
+        }
+        catch (error) {
+            if (!isFileExistsError(error))
+                throw error;
+        }
+        const observation = await observeLock({ lockFilePath });
+        if (!observation.exists) {
+            // Lock vanished between create and read - retry creation now
+            continue;
+        }
+        const parsedAge = observation.contents !== null ? Date.now() - observation.contents.acquiredAt : null;
+        const staleByContents = parsedAge !== null && parsedAge >= staleMs;
+        const staleByMtime = observation.contents === null &&
+            observation.mtimeAgeMs !== null &&
+            observation.mtimeAgeMs >= staleMs;
+        if (staleByContents) {
+            const observedToken = observation.contents?.token;
+            logger.info("Stale download lock found, breaking", { lockFilePath });
+            await removeVerifiedLockInstance({
+                isTargetInstance: candidate => candidate.contents?.token === observedToken,
+                lockFilePath,
+                logger,
+                quarantinePrefix: "stale"
+            });
+            continue;
+        }
+        if (staleByMtime) {
+            logger.info("Unreadable stale download lock found, breaking", { lockFilePath });
+            await removeVerifiedLockInstance({
+                isTargetInstance: candidate => candidate.contents === null &&
+                    candidate.mtimeAgeMs !== null &&
+                    candidate.mtimeAgeMs >= staleMs,
+                lockFilePath,
+                logger,
+                quarantinePrefix: "stale"
+            });
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Failed acquiring download lock within ${timeoutMs}ms: ${lockFilePath}`);
+        }
+        logger.info("Download lock held by another process, waiting", {
+            lockAgeMs: parsedAge ?? observation.mtimeAgeMs,
+            lockFilePath
+        });
+        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+}
+async function releaseExclusiveFileLock({ handle }) {
+    // Removal is verified against the handle's token at quarantine time, so
+    // a replacement lock created after this holder's release/read can never
+    // be unlinked, and a lock already gone is a no-op
+    await removeVerifiedLockInstance({
+        isTargetInstance: candidate => candidate.contents?.token === handle.token,
+        lockFilePath: handle.lockFilePath,
+        logger: { info: () => { }, warn: () => { } },
+        quarantinePrefix: "release"
+    });
+}
+
 const EXLLAMAV3_EXECUTABLE = process.env.EXLLAMAV3_EXECUTABLE ?? "python3";
 const SERVER_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "server.py");
 const DEFAULT_EXLLAMAV3_CONTEXT_LENGTH = 4096;
@@ -123370,7 +123583,6 @@ async function startLlamacpp({ enginePort, targetDirectory }) {
             console.warn(`[llamacpp] Multimodal enabled but no projector file found in ${targetDirectory}. ` +
                 "Vision functionality will not work.");
         }
-        args.push("--special");
     }
     if (process.env.LLAMACPP_REASONING === "off") {
         args.push("--reasoning", "off");
@@ -123505,6 +123717,7 @@ class ModelManager extends EventEmitter {
     healthPollInterval = null;
     lastEngineError = null;
     lifecycleState = "stopped";
+    downloadLockHandle = null;
     stopRequested = false;
     modelsDirectory;
     constructor({ contextLength, engineConfig, enginePort, engineType, logger, model, root }) {
@@ -123822,35 +124035,13 @@ class ModelManager extends EventEmitter {
         return join(this.modelsDirectory, `${this.uniqueName}.lock`);
     }
     async acquireDownloadLock() {
-        await mkdir(this.modelsDirectory, { recursive: true });
-        if (existsSync(this.lockFilePath)) {
-            const age = await this.getLockAge();
-            if (age !== null && age < DOWNLOAD_LOCK_TIMEOUT_MS) {
-                this.logger.info("Download lock held by another process, waiting", {
-                    lockAgeMs: age,
-                    lockFilePath: this.lockFilePath
-                });
-                await this.waitForDownloadLock();
-            }
-            else {
-                this.logger.info("Stale download lock found, breaking", {
-                    lockFilePath: this.lockFilePath
-                });
-                await this.releaseDownloadLock();
-            }
-        }
-        await writeFile(this.lockFilePath, JSON.stringify({ acquiredAt: Date.now() }));
-        this.logger.info("Acquired download lock", { lockFilePath: this.lockFilePath });
-    }
-    async getLockAge() {
-        try {
-            const raw = await readFile(this.lockFilePath, "utf-8");
-            const data = JSON.parse(raw);
-            return Date.now() - data.acquiredAt;
-        }
-        catch {
-            return null;
-        }
+        this.downloadLockHandle = await acquireExclusiveFileLock({
+            lockFilePath: this.lockFilePath,
+            logger: this.logger,
+            pollIntervalMs: DOWNLOAD_LOCK_POLL_INTERVAL_MS,
+            staleMs: DOWNLOAD_LOCK_TIMEOUT_MS,
+            timeoutMs: DOWNLOAD_LOCK_TIMEOUT_MS
+        });
     }
     recordEngineError(err) {
         this.lifecycleState = "errored";
@@ -123858,27 +124049,11 @@ class ModelManager extends EventEmitter {
         this.emit("engineError", err);
     }
     async releaseDownloadLock() {
-        try {
-            await unlink(this.lockFilePath);
-        }
-        catch {
-            // already released
-        }
-    }
-    async waitForDownloadLock() {
-        const start = Date.now();
-        while (Date.now() - start < DOWNLOAD_LOCK_TIMEOUT_MS) {
-            await new Promise(resolve => setTimeout(resolve, DOWNLOAD_LOCK_POLL_INTERVAL_MS));
-            if (!existsSync(this.lockFilePath)) {
-                return;
-            }
-            const age = await this.getLockAge();
-            if (age === null || age >= DOWNLOAD_LOCK_TIMEOUT_MS) {
-                await this.releaseDownloadLock();
-                return;
-            }
-        }
-        await this.releaseDownloadLock();
+        const handle = this.downloadLockHandle;
+        if (!handle)
+            return;
+        this.downloadLockHandle = null;
+        await releaseExclusiveFileLock({ handle });
     }
     bindEngineProcessEvents(processManager) {
         let hasTerminated = false;
@@ -137056,6 +137231,59 @@ function registerModelsCommands({ program }) {
         }
         console.log(`Cleared ${targets.length} model(s), freed ${formatBytes(totalBytes)}`);
     });
+    models
+        .command("download")
+        .description("Pre-download a HuggingFace model into the local cache")
+        .requiredOption("--slug <slug>", "Fully qualified model slug, optionally with a quantization variant (owner/repo:Q4_K_M)")
+        .option("--format <format>", "Model format (gguf, safetensors, pytorch, ...)", "gguf")
+        .option("--root <path>", "Root directory (or ROOT_DIRECTORY env)")
+        .option("--token <token>", "HuggingFace access token (or HF_TOKEN env)")
+        .action(async (options) => {
+        const slug = options.slug?.trim() ?? "";
+        if (!slug.includes("/")) {
+            console.error("Slug must be a fully qualified owner/repo slug");
+            process.exitCode = 1;
+            return;
+        }
+        const format = LLMModelFormatSchema.safeParse(options.format);
+        if (!format.success) {
+            console.error(`Invalid format "${options.format}". Must be one of: ${LLMModelFormatSchema.options.join(", ")}`);
+            process.exitCode = 1;
+            return;
+        }
+        const huggingFaceToken = options.token?.trim() || null;
+        const model = {
+            format: format.data,
+            id: slug,
+            multimodalEnabled: false,
+            source: {
+                modelSecret: huggingFaceToken,
+                slug,
+                type: "huggingface"
+            },
+            taskType: "text-generation"
+        };
+        const rootDirectory = getRootDirectory(options.root);
+        const modelsDir = join(rootDirectory, "models");
+        const uniqueName = createModelStorageKey(model);
+        const targetDirectory = join(modelsDir, uniqueName);
+        console.log(`Downloading ${slug} (${format.data})`);
+        console.log(`  Target: ${targetDirectory}`);
+        try {
+            await downloadModelViaHuggingFace({
+                format: model.format,
+                huggingFaceToken,
+                modelSlug: slug,
+                progressFilePath: join(modelsDir, `${uniqueName}.progress.json`),
+                targetDirectory
+            });
+            console.log(`Model cached: ${targetDirectory}`);
+        }
+        catch (err) {
+            console.error(`Failed downloading model: ${asError(err).message}`);
+            process.exitCode = 1;
+        }
+    });
 }
 
 function parseAllowList(raw) {

package/dist/cli.sea.cjs

@@ -21303,6 +21303,42 @@ object$1({
     name: ResourceNameSchema
 });
 
+const FitMethodSchema = _enum$1(["gguf-header", "model-config", "parameter-heuristic"]);
+const FitConfidenceSchema = _enum$1(["high", "low", "medium"]);
+object$1({
+    architecture: string$2().nullable(),
+    contextTrainTokens: number$1().int().positive().nullable(),
+    embeddingLength: number$1().int().positive().nullable(),
+    headCount: number$1().int().positive().nullable(),
+    headCountKV: number$1().int().positive().nullable(),
+    headDim: number$1().int().positive().nullable(),
+    layerCount: number$1().int().positive().nullable(),
+    method: FitMethodSchema,
+    probedAt: string$2(),
+    unresolved: boolean$1().optional()
+});
+const FitMemoryDomainKindSchema = _enum$1(["gpu", "system", "unified"]);
+const FitMemoryDomainSchema = object$1({
+    capacityBytes: number$1().int().nonnegative(),
+    domainId: string$2(),
+    kind: FitMemoryDomainKindSchema,
+    label: string$2(),
+    remainingBytes: number$1().int(),
+    requiredBytes: number$1().int().nonnegative(),
+    reserveBytes: number$1().int().nonnegative()
+});
+object$1({
+    confidence: FitConfidenceSchema,
+    contextTokens: number$1().int().positive(),
+    deficitBytes: number$1().int().nonnegative(),
+    domains: array(FitMemoryDomainSchema),
+    engine: LLMEngineSchema,
+    fits: boolean$1(),
+    limitingDomain: string$2().nullable(),
+    method: FitMethodSchema,
+    totalRequiredBytes: number$1().int().nonnegative()
+});
+
 const ENGINE_API_COMPATIBILITY = {
     exllamav3: {
         nativeAnthropicMessages: false,
@@ -21635,6 +21671,7 @@ const ModelEndpointCallConfigSchema = object$1({
     description: string$2().min(1),
     endpointId: string$2().min(1),
     inputSchema: record(string$2(), unknown()).optional(),
+    maxTokens: number$1().int().positive().optional(),
     outputSchema: record(string$2(), unknown()).optional(),
     systemPrompt: string$2().optional(),
     type: literal("model-endpoint-call")
@@ -21643,6 +21680,7 @@ const ModelSourceCallConfigSchema = object$1({
     description: string$2().min(1),
     groupId: ULIDSchema.optional(),
     inputSchema: record(string$2(), unknown()).optional(),
+    maxTokens: number$1().int().positive().optional(),
     outputSchema: record(string$2(), unknown()).optional(),
     sourceId: ULIDSchema.optional(),
     systemPrompt: string$2().optional(),
@@ -123310,6 +123348,181 @@ async function downloadFileWithRange({ accessToken, filePath, fileSize, modelSlu
     throw new Error(errorMessage);
 }
 
+const RESTORE_RETRY_ATTEMPTS = 50;
+const RESTORE_RETRY_DELAY_MS = 5;
+function errorCode(error) {
+    if (typeof error === "object" && error !== null) {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return null;
+}
+function isFileExistsError(error) {
+    return errorCode(error) === "EEXIST";
+}
+function isFileNotFoundError(error) {
+    return errorCode(error) === "ENOENT";
+}
+async function readLockContents({ lockFilePath }) {
+    try {
+        const raw = await require$$0$m.readFile(lockFilePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (typeof data.acquiredAt !== "number" || typeof data.token !== "string")
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+async function observeLock({ lockFilePath }) {
+    const [contents, stats] = await Promise.all([
+        readLockContents({ lockFilePath }),
+        require$$0$m.stat(lockFilePath).catch(error => {
+            if (isFileNotFoundError(error))
+                return null;
+            throw error;
+        })
+    ]);
+    return {
+        contents,
+        exists: stats !== null,
+        mtimeAgeMs: stats ? Date.now() - stats.mtimeMs : null
+    };
+}
+/**
+ * Remove a lock file only if it is the exact instance that was observed and
+ * verified. The candidate is first renamed to a unique quarantine path
+ * (rename is atomic, so exactly one competing process can isolate a given
+ * instance); the quarantined file is then re-verified against the expected
+ * identity. A mismatch means a replacement lock was captured by the rename -
+ * it is renamed back into place rather than deleted.
+ *
+ * Residual race: a restore rename could theoretically clobber a third lock
+ * created in the microsecond window while the replacement sat in quarantine.
+ * Files alone cannot provide a fully linearizable compare-and-delete; closing
+ * that window entirely would require an OS-level lock primitive (flock).
+ */
+async function removeVerifiedLockInstance({ isTargetInstance, lockFilePath, logger, quarantinePrefix }) {
+    const quarantinePath = `${lockFilePath}.${quarantinePrefix}-${process.pid}-${crypto.randomUUID()}`;
+    try {
+        await require$$0$m.rename(lockFilePath, quarantinePath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error))
+            return false;
+        throw error;
+    }
+    const quarantined = await observeLock({ lockFilePath: quarantinePath });
+    if (isTargetInstance(quarantined)) {
+        await require$$0$m.rm(quarantinePath, { force: true });
+        return true;
+    }
+    // A replacement lock was captured - restore it before continuing
+    for (let attempt = 1;; attempt++) {
+        try {
+            await require$$0$m.rename(quarantinePath, lockFilePath);
+            return false;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code !== "ENOTEMPTY" && code !== "EEXIST" && code !== "EPERM")
+                throw error;
+            if (attempt >= RESTORE_RETRY_ATTEMPTS) {
+                logger.warn("Failed restoring quarantined replacement lock", {
+                    lockFilePath,
+                    quarantinePath
+                });
+                return false;
+            }
+            await new Promise(resolve => setTimeout(resolve, RESTORE_RETRY_DELAY_MS));
+        }
+    }
+}
+/**
+ * Acquire an exclusive cross-process file lock. Creation uses the "wx" flag
+ * so the check-and-create step is atomic: concurrent processes can never both
+ * observe a missing lock file and both claim it. Each acquisition owns a
+ * unique token; only a lock whose stored token matches the holder's handle
+ * may be released by that holder. An active (non-stale) lock is never broken
+ * because a waiter timed out - the waiter fails instead.
+ *
+ * Staleness is judged per observed instance: a parsed lock is stale when its
+ * recorded acquisition age exceeds staleMs; an unparseable lock (possible
+ * mid-write observation) is stale only when its mtime is itself old, so a
+ * fresh lock can never be quarantined off the back of a partial read.
+ */
+async function acquireExclusiveFileLock({ lockFilePath, logger, pollIntervalMs, staleMs, timeoutMs }) {
+    await require$$0$m.mkdir(path$1.dirname(lockFilePath), { recursive: true });
+    const token = `${process.pid}-${crypto.randomUUID()}`;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            const contents = { acquiredAt: Date.now(), token };
+            await require$$0$m.writeFile(lockFilePath, JSON.stringify(contents), { flag: "wx" });
+            logger.info("Acquired download lock", { lockFilePath });
+            return { lockFilePath, token };
+        }
+        catch (error) {
+            if (!isFileExistsError(error))
+                throw error;
+        }
+        const observation = await observeLock({ lockFilePath });
+        if (!observation.exists) {
+            // Lock vanished between create and read - retry creation now
+            continue;
+        }
+        const parsedAge = observation.contents !== null ? Date.now() - observation.contents.acquiredAt : null;
+        const staleByContents = parsedAge !== null && parsedAge >= staleMs;
+        const staleByMtime = observation.contents === null &&
+            observation.mtimeAgeMs !== null &&
+            observation.mtimeAgeMs >= staleMs;
+        if (staleByContents) {
+            const observedToken = observation.contents?.token;
+            logger.info("Stale download lock found, breaking", { lockFilePath });
+            await removeVerifiedLockInstance({
+                isTargetInstance: candidate => candidate.contents?.token === observedToken,
+                lockFilePath,
+                logger,
+                quarantinePrefix: "stale"
+            });
+            continue;
+        }
+        if (staleByMtime) {
+            logger.info("Unreadable stale download lock found, breaking", { lockFilePath });
+            await removeVerifiedLockInstance({
+                isTargetInstance: candidate => candidate.contents === null &&
+                    candidate.mtimeAgeMs !== null &&
+                    candidate.mtimeAgeMs >= staleMs,
+                lockFilePath,
+                logger,
+                quarantinePrefix: "stale"
+            });
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Failed acquiring download lock within ${timeoutMs}ms: ${lockFilePath}`);
+        }
+        logger.info("Download lock held by another process, waiting", {
+            lockAgeMs: parsedAge ?? observation.mtimeAgeMs,
+            lockFilePath
+        });
+        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+}
+async function releaseExclusiveFileLock({ handle }) {
+    // Removal is verified against the handle's token at quarantine time, so
+    // a replacement lock created after this holder's release/read can never
+    // be unlinked, and a lock already gone is a no-op
+    await removeVerifiedLockInstance({
+        isTargetInstance: candidate => candidate.contents?.token === handle.token,
+        lockFilePath: handle.lockFilePath,
+        logger: { info: () => { }, warn: () => { } },
+        quarantinePrefix: "release"
+    });
+}
+
 const EXLLAMAV3_EXECUTABLE = process.env.EXLLAMAV3_EXECUTABLE ?? "python3";
 const SERVER_SCRIPT = path$1.join(path$1.dirname(require$$0$l.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.sea.cjs', document.baseURI).href)))), "server.py");
 const DEFAULT_EXLLAMAV3_CONTEXT_LENGTH = 4096;
@@ -123385,7 +123598,6 @@ async function startLlamacpp({ enginePort, targetDirectory }) {
             console.warn(`[llamacpp] Multimodal enabled but no projector file found in ${targetDirectory}. ` +
                 "Vision functionality will not work.");
         }
-        args.push("--special");
     }
     if (process.env.LLAMACPP_REASONING === "off") {
         args.push("--reasoning", "off");
@@ -123520,6 +123732,7 @@ class ModelManager extends EventEmitter {
     healthPollInterval = null;
     lastEngineError = null;
     lifecycleState = "stopped";
+    downloadLockHandle = null;
     stopRequested = false;
     modelsDirectory;
     constructor({ contextLength, engineConfig, enginePort, engineType, logger, model, root }) {
@@ -123837,35 +124050,13 @@ class ModelManager extends EventEmitter {
         return path$1.join(this.modelsDirectory, `${this.uniqueName}.lock`);
     }
     async acquireDownloadLock() {
-        await require$$0$m.mkdir(this.modelsDirectory, { recursive: true });
-        if (require$$3$4.existsSync(this.lockFilePath)) {
-            const age = await this.getLockAge();
-            if (age !== null && age < DOWNLOAD_LOCK_TIMEOUT_MS) {
-                this.logger.info("Download lock held by another process, waiting", {
-                    lockAgeMs: age,
-                    lockFilePath: this.lockFilePath
-                });
-                await this.waitForDownloadLock();
-            }
-            else {
-                this.logger.info("Stale download lock found, breaking", {
-                    lockFilePath: this.lockFilePath
-                });
-                await this.releaseDownloadLock();
-            }
-        }
-        await require$$0$m.writeFile(this.lockFilePath, JSON.stringify({ acquiredAt: Date.now() }));
-        this.logger.info("Acquired download lock", { lockFilePath: this.lockFilePath });
-    }
-    async getLockAge() {
-        try {
-            const raw = await require$$0$m.readFile(this.lockFilePath, "utf-8");
-            const data = JSON.parse(raw);
-            return Date.now() - data.acquiredAt;
-        }
-        catch {
-            return null;
-        }
+        this.downloadLockHandle = await acquireExclusiveFileLock({
+            lockFilePath: this.lockFilePath,
+            logger: this.logger,
+            pollIntervalMs: DOWNLOAD_LOCK_POLL_INTERVAL_MS,
+            staleMs: DOWNLOAD_LOCK_TIMEOUT_MS,
+            timeoutMs: DOWNLOAD_LOCK_TIMEOUT_MS
+        });
     }
     recordEngineError(err) {
         this.lifecycleState = "errored";
@@ -123873,27 +124064,11 @@ class ModelManager extends EventEmitter {
         this.emit("engineError", err);
     }
     async releaseDownloadLock() {
-        try {
-            await require$$0$m.unlink(this.lockFilePath);
-        }
-        catch {
-            // already released
-        }
-    }
-    async waitForDownloadLock() {
-        const start = Date.now();
-        while (Date.now() - start < DOWNLOAD_LOCK_TIMEOUT_MS) {
-            await new Promise(resolve => setTimeout(resolve, DOWNLOAD_LOCK_POLL_INTERVAL_MS));
-            if (!require$$3$4.existsSync(this.lockFilePath)) {
-                return;
-            }
-            const age = await this.getLockAge();
-            if (age === null || age >= DOWNLOAD_LOCK_TIMEOUT_MS) {
-                await this.releaseDownloadLock();
-                return;
-            }
-        }
-        await this.releaseDownloadLock();
+        const handle = this.downloadLockHandle;
+        if (!handle)
+            return;
+        this.downloadLockHandle = null;
+        await releaseExclusiveFileLock({ handle });
     }
     bindEngineProcessEvents(processManager) {
         let hasTerminated = false;
@@ -157286,6 +157461,59 @@ function registerModelsCommands({ program }) {
         }
         console.log(`Cleared ${targets.length} model(s), freed ${formatBytes(totalBytes)}`);
     });
+    models
+        .command("download")
+        .description("Pre-download a HuggingFace model into the local cache")
+        .requiredOption("--slug <slug>", "Fully qualified model slug, optionally with a quantization variant (owner/repo:Q4_K_M)")
+        .option("--format <format>", "Model format (gguf, safetensors, pytorch, ...)", "gguf")
+        .option("--root <path>", "Root directory (or ROOT_DIRECTORY env)")
+        .option("--token <token>", "HuggingFace access token (or HF_TOKEN env)")
+        .action(async (options) => {
+        const slug = options.slug?.trim() ?? "";
+        if (!slug.includes("/")) {
+            console.error("Slug must be a fully qualified owner/repo slug");
+            process.exitCode = 1;
+            return;
+        }
+        const format = LLMModelFormatSchema.safeParse(options.format);
+        if (!format.success) {
+            console.error(`Invalid format "${options.format}". Must be one of: ${LLMModelFormatSchema.options.join(", ")}`);
+            process.exitCode = 1;
+            return;
+        }
+        const huggingFaceToken = options.token?.trim() || null;
+        const model = {
+            format: format.data,
+            id: slug,
+            multimodalEnabled: false,
+            source: {
+                modelSecret: huggingFaceToken,
+                slug,
+                type: "huggingface"
+            },
+            taskType: "text-generation"
+        };
+        const rootDirectory = getRootDirectory(options.root);
+        const modelsDir = path$1.join(rootDirectory, "models");
+        const uniqueName = createModelStorageKey(model);
+        const targetDirectory = path$1.join(modelsDir, uniqueName);
+        console.log(`Downloading ${slug} (${format.data})`);
+        console.log(`  Target: ${targetDirectory}`);
+        try {
+            await downloadModelViaHuggingFace({
+                format: model.format,
+                huggingFaceToken,
+                modelSlug: slug,
+                progressFilePath: path$1.join(modelsDir, `${uniqueName}.progress.json`),
+                targetDirectory
+            });
+            console.log(`Model cached: ${targetDirectory}`);
+        }
+        catch (err) {
+            console.error(`Failed downloading model: ${asError(err).message}`);
+            process.exitCode = 1;
+        }
+    });
 }
 
 function parseAllowList(raw) {

package/dist/modelManagement/ModelManager.d.ts

@@ -22,6 +22,7 @@ export declare class ModelManager extends EventEmitter<ModelManagerEvents> {
     private healthPollInterval;
     private lastEngineError;
     private lifecycleState;
+    private downloadLockHandle;
     private stopRequested;
     protected readonly modelsDirectory: string;
     constructor({ contextLength, engineConfig, enginePort, engineType, logger, model, root }: {
@@ -52,10 +53,8 @@ export declare class ModelManager extends EventEmitter<ModelManagerEvents> {
     private startHealthPoll;
     private get lockFilePath();
     private acquireDownloadLock;
-    private getLockAge;
     private recordEngineError;
     private releaseDownloadLock;
-    private waitForDownloadLock;
     private bindEngineProcessEvents;
     private startEngineProcess;
 }

package/dist/modelManagement/downloadLock.d.ts

@@ -0,0 +1,32 @@
+interface LockLogger {
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+}
+export interface DownloadLockHandle {
+    lockFilePath: string;
+    token: string;
+}
+/**
+ * Acquire an exclusive cross-process file lock. Creation uses the "wx" flag
+ * so the check-and-create step is atomic: concurrent processes can never both
+ * observe a missing lock file and both claim it. Each acquisition owns a
+ * unique token; only a lock whose stored token matches the holder's handle
+ * may be released by that holder. An active (non-stale) lock is never broken
+ * because a waiter timed out - the waiter fails instead.
+ *
+ * Staleness is judged per observed instance: a parsed lock is stale when its
+ * recorded acquisition age exceeds staleMs; an unparseable lock (possible
+ * mid-write observation) is stale only when its mtime is itself old, so a
+ * fresh lock can never be quarantined off the back of a partial read.
+ */
+export declare function acquireExclusiveFileLock({ lockFilePath, logger, pollIntervalMs, staleMs, timeoutMs }: {
+    lockFilePath: string;
+    logger: LockLogger;
+    pollIntervalMs: number;
+    staleMs: number;
+    timeoutMs: number;
+}): Promise<DownloadLockHandle>;
+export declare function releaseExclusiveFileLock({ handle }: {
+    handle: DownloadLockHandle;
+}): Promise<void>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@infersec/conduit",
   "description": "End user conduit agent for connecting local LLMs to the cloud.",
-  "version": "1.106.0",
+  "version": "1.108.0",
   "bin": {
     "infersec-conduit": "./dist/cli.js"
   },