@camstack/addon-ai 0.4.2 → 0.4.4

package/dist/addon.mjs

@@ -1,13 +1,13 @@
 import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import { createHash } from "node:crypto";
-import { promisify } from "node:util";
+import { connect, createServer } from "node:net";
 import * as fs from "node:fs";
-import { createReadStream } from "node:fs";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { promisify } from "node:util";
 import { brotliCompress, gzip } from "node:zlib";
 import * as fsp from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { createServer } from "node:net";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp$1 = Object.defineProperty;
@@ -12500,6 +12500,18 @@ var LlmGenerateBaseInputSchema = object({
 * Resource ceiling = llama-server flags + idleStopMinutes ONLY (no RSS
 * watchdog — operator decision #3).
 */
+/**
+* A companion artifact that MUST land beside the main GGUF: the `mmproj`
+* projector of a vision model, or shards 2..N of a split GGUF. Carried on the
+* REF rather than looked up at install time, so what the operator approved in
+* the preview is exactly what the node downloads.
+*/
+var ManagedModelExtraFileSchema = object({
+	url: string(),
+	filename: string(),
+	sizeBytes: number$1(),
+	sha256: string().optional()
+});
 var ManagedModelRefSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("catalog"),
@@ -12508,7 +12520,11 @@ var ManagedModelRefSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("url"),
 		url: string(),
-		sha256: string().optional()
+		sha256: string().optional(),
+		/** Picker/status label; the file basename when absent. */
+		label: string().optional(),
+		sizeBytes: number$1().optional(),
+		extraFiles: array(ManagedModelExtraFileSchema).optional()
 	}),
 	object({
 		kind: literal("path"),
@@ -12569,11 +12585,39 @@ var ManagedRuntimeConfigSchema = object({
 		"q4_1",
 		"q4_0"
 	]).optional(),
+	/**
+	* Escape hatch for llama-server flags this schema does NOT model — `--jinja`
+	* (which most vision chat templates need and some language-only models
+	* dislike), `--cont-batching`, `--rope-scaling`, …
+	*
+	* It is NOT a second place to set the flags above. A token that collides
+	* with a typed field is REJECTED at start, naming the field that owns it
+	* (`assertNoOwnedFlags`), because two knobs writing the same argv is exactly
+	* the "two switches that disagree" failure this repo has already shipped
+	* twice (D62).
+	*/
+	extraArgs: array(string()).default([]),
 	/** Else lazy: first generate boots it. */
 	autoStart: boolean().default(false),
 	/** 0 = never; frees RAM after quiet periods. */
 	idleStopMinutes: number$1().int().default(30)
 });
+/**
+* Where a multi-GB install currently is. A single 0..1 fraction cannot answer
+* "is it stuck?" for an install that is three files (shards + mmproj) followed
+* by a sha256 pass over 22 GB — during which the fraction sat at 1.0 and the
+* node looked hung. Phase + file + bytes is the smallest shape that does.
+*/
+var LlmDownloadProgressSchema = object({
+	phase: _enum(["downloading", "verifying"]),
+	/** The artifact currently moving, e.g. `mmproj-F16.gguf`. */
+	file: string(),
+	fileIndex: number$1().int(),
+	fileCount: number$1().int(),
+	/** Across the WHOLE install, not the current file. */
+	downloadedBytes: number$1(),
+	totalBytes: number$1().optional()
+});
 var LlmRuntimeStatusSchema = object({
 	/** Status is ALWAYS node-qualified. */
 	nodeId: string(),
@@ -12590,6 +12634,8 @@ var LlmRuntimeStatusSchema = object({
 	modelPath: string().optional(),
 	modelId: string().optional(),
 	downloadProgress: number$1().min(0).max(1).optional(),
+	/** Detail behind `downloadProgress`; present for the same lifetime. */
+	download: LlmDownloadProgressSchema.optional(),
 	lastError: string().optional(),
 	crashesInWindow: number$1(),
 	/** Child RSS (sampled best-effort). */
@@ -12600,7 +12646,14 @@ var LlmNodeModelSchema = object({
 	file: string(),
 	sizeBytes: number$1(),
 	catalogId: string().optional(),
-	installedAt: number$1().optional()
+	installedAt: number$1().optional(),
+	/**
+	* Absolute path on the node. Present so a file that is on disk but matches
+	* no catalog entry — a custom Hugging Face install, or a GGUF the operator
+	* copied in by hand — is still SELECTABLE, as a `{kind:'path'}` ref. Without
+	* it the picker could list such a file and do nothing with it.
+	*/
+	path: string().optional()
 });
 var LlmRuntimeDiskUsageSchema = object({
 	nodeId: string(),
@@ -12693,9 +12746,12 @@ var LlmProfileSchema = object({
 	systemPrompt: string().optional(),
 	/** Total generation bound — the only one a unary call has. */
 	timeoutMs: number$1().int().positive().default(6e4),
-	/** Wait for response headers only. */
+	/** The TCP handshake only — "is the port even open". NOT the wait for
+	*  response headers: on the LM Studio / llama-server wire those are written
+	*  once the model has finished loading, so they belong to the bound below. */
 	connectTimeoutMs: number$1().int().positive().default(1e4),
-	/** Accepted, but no output yet — a cold GPU load lives here. */
+	/** Accepted, but no output yet — response headers included, because a cold
+	*  GPU load is exactly what happens before them. */
 	firstTokenTimeoutMs: number$1().int().positive().default(12e4),
 	/** Output started then stopped. */
 	idleTimeoutMs: number$1().int().positive().default(6e4),
@@ -12758,6 +12814,36 @@ var ManagedModelCatalogEntrySchema = object({
 	/** Vision models: companion projector file. */
 	mmprojUrl: string().optional()
 });
+/**
+* The outcome of turning one operator-typed Hugging Face reference into a
+* download plan. A RESULT, never a throw: "this repo has 24 quantizations and
+* I will not pick for you" is a normal answer the UI has to render, not an
+* exception.
+*
+* `candidates` is the whole reason the refusal is usable — every string in it
+* is a tag that resolves when pasted back as `<org>/<repo>:<TAG>`.
+*/
+var HfModelResolutionSchema = discriminatedUnion("ok", [object({
+	ok: literal(true),
+	/** Ready to hand to `installModel` unchanged. */
+	model: ManagedModelRefSchema,
+	label: string(),
+	repo: string(),
+	quantization: string(),
+	purpose: _enum(["text", "vision"]),
+	totalBytes: number$1(),
+	/** mmproj + shards, for the preview: an operator approving 23 GB should
+	*  see that 0.9 GB of it is a projector they did not name. */
+	extraFilenames: array(string())
+}), object({
+	ok: literal(false),
+	code: string(),
+	message: string(),
+	candidates: array(string()).optional(),
+	/** Set when the refusal was only the ceiling: re-calling with
+	*  `maxBytes: requiredBytes` is the operator's explicit override. */
+	requiredBytes: number$1().optional()
+})]);
 var LlmRuntimeNodeSchema = object({
 	nodeId: string(),
 	reachable: boolean(),
@@ -12825,6 +12911,25 @@ var llmCapability = {
 		listModelCatalog: method(object({}), array(ManagedModelCatalogEntrySchema)),
 		listRuntimeNodes: method(object({}), array(LlmRuntimeNodeSchema)),
 		listNodeModels: method(object({ nodeId: string() }), array(LlmNodeModelSchema)),
+		/**
+		* One typed Hugging Face reference → a pinned, verified `ManagedModelRef`.
+		*
+		* Runs on the HUB, not on the target node: resolution needs egress to
+		* huggingface.co, and an agent that cannot reach it still installs fine
+		* through the model-distributor relay. Nothing is downloaded here — this is
+		* a tree read plus a HEAD, so the operator sees the size, the quantization
+		* and the mmproj BEFORE approving a multi-GB pull.
+		*/
+		resolveModelRef: method(object({
+			/** `https://huggingface.co/<org>/<repo>/resolve/main/<f>.gguf`,
+			*  `<org>/<repo>/<f>.gguf`, `<org>/<repo>` or `<org>/<repo>:<QUANT>`. */
+			ref: string(),
+			/** Explicit ceiling override, in bytes. Absent = the built-in ceiling. */
+			maxBytes: number$1().positive().optional()
+		}), HfModelResolutionSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		installModel: method(object({
 			nodeId: string(),
 			model: ManagedModelRefSchema
@@ -14728,13 +14833,81 @@ var NcRuleActionsSchema = object({
 	*/
 	buttons: array(NcRuleNotificationButtonSchema).max(8).optional()
 });
+/**
+* "This rule applies only while `deviceId` is in one of `states`."
+*
+* The states are the DEVICE's own vocabulary — `AlarmState` for a panel,
+* `on`/`off` for a switch — not a normalised set, because normalising would
+* make the condition lie about devices whose states have no equivalent.
+*
+* An unreadable state does NOT match: see the engine's fail-closed gate. A
+* condition that fired on "I could not read it" would be worse than no gate.
+*/
+var NcDeviceStateConditionSchema = object({
+	deviceId: number$1().int(),
+	/** Any of these matches. */
+	states: array(string().min(1)).min(1)
+});
+/**
+* "This rule applies only while scene `sceneId` is `matched` / `diverged`."
+*
+* A GATE, not a trigger. `occupancy` and `audio` each DISCRIMINATE their rule —
+* carrying one makes the rule fire on that subject and nothing else. Scene is
+* the other shape entirely, the `deviceState` shape: it narrows a rule that
+* already has a trigger ("tell me about a person at the front door, but only
+* while the bin is still out"). That is why it composes with every delivery
+* instead of owning one, and why no new `NcDelivery` member and no new subject
+* kind exist for it — see D159.
+*
+* ── Identity ───────────────────────────────────────────────────────────────
+* `sceneId` is `SceneMonitor.id`, a `randomUUID()` minted by `createScene` —
+* globally unique, so it needs no device to disambiguate it. `deviceId` is
+* carried as a HINT for the editor and for the log line, never as part of the
+* lookup key: a rule whose hint drifted must still gate correctly.
+*
+* ── Which boolean ──────────────────────────────────────────────────────────
+* `latched` ABSENT means "whatever the scene itself says" — `SceneMonitor.emit`
+* already declares which boolean drives notification rules, and a second knob
+* that could disagree with it is exactly the D62 failure. Set it only to
+* override one rule against the scene's own default.
+*
+*  - LIVE reading (`emit`/`latched` resolve to live): passes iff
+*    `verdict === requiredState`. `unknown` — no reference for this light, view
+*    shifted, no snapshot — passes NEITHER. A scene that cannot judge is not
+*    evidence, in either direction.
+*  - LATCHED reading: passes iff `latched === (requiredState === 'diverged')`.
+*    The latch is a durable fact about the past ("it has diverged since I armed
+*    it"), so a camera that has gone dark does not clear it — that is the whole
+*    reason the operator asked for a latch.
+*
+* The gate reads an in-memory mirror (`NcSceneStateCache`) refreshed OFF the
+* event path, never the cap: D49. A mirror that has never loaded, or a scene it
+* does not carry, reads absent and the rule does NOT fire — fail closed, and
+* said out loud in the log rather than dropped in silence.
+*/
+var NcSceneConditionSchema = object({
+	/** `SceneMonitor.id` — the uuid the cap mints. The whole lookup key. */
+	sceneId: string().min(1),
+	/** The camera the scene lives on. A hint for the editor and the log line. */
+	deviceId: number$1().int().optional(),
+	/** The state the scene must be in for the rule to fire. */
+	requiredState: _enum(["matched", "diverged"]),
+	/**
+	* Read the LATCH (`true`) or the LIVE verdict (`false`). Absent = follow the
+	* scene's own `emit` field, which is the only place that decision belongs.
+	*/
+	latched: boolean().optional()
+});
 var NcConditionsSchema = object({
 	/** Gate on ANOTHER device's current state (the alarm armed, a switch on). */
-	deviceState: object({
-		deviceId: number$1().int(),
-		/** Any of these matches. */
-		states: array(string().min(1)).min(1)
-	}).optional(),
+	deviceState: NcDeviceStateConditionSchema.optional(),
+	/**
+	* Gate on a SCENE's state — "only while the bin is still out". Composes with
+	* every trigger (detection, occupancy, audio, sensor, package, track-end);
+	* unlike `occupancy`/`audio` it discriminates nothing. See
+	* {@link NcSceneCondition} and D159.
+	*/
+	scene: NcSceneConditionSchema.optional(),
 	/** Device scope — absent = all devices. */
 	devices: array(number$1()).optional(),
 	/** Detector class names (any overlap with the record's class set). */
@@ -15372,6 +15545,7 @@ var NcConditionDescriptorSchema = object({
 		"occupancy",
 		"audio",
 		"deviceState",
+		"scene",
 		"systemEvent"
 	]),
 	operator: _enum([
@@ -17895,6 +18069,17 @@ var maxSessionHoldMsField = {
 	default: 12e4,
 	step: 5e3
 };
+/**
+* Quiet period that closes an `audioMode: 'on-motion'` audio window. Floor of
+* 5s so a rearm can never degenerate into per-event stream churn; default 90s
+* comfortably outlives the gap between two PIR wakes on a battery camera.
+*/
+var audioMotionWindowMsField = {
+	min: 5e3,
+	max: 6e5,
+	default: 9e4,
+	step: 5e3
+};
 var motionFpsField = {
 	min: 1,
 	max: 30,
@@ -18071,6 +18256,27 @@ var RunnerCameraConfigSchema = object({
 	* resolved `CameraDetectionConfig`.
 	*/
 	maxSessionHoldMs: number$1().min(maxSessionHoldMsField.min).max(maxSessionHoldMsField.max).optional(),
+	/**
+	* Orchestrator-side quiet period (ms) that closes an `audioMode:
+	* 'on-motion'` audio window, measured from the LAST motion event.
+	*
+	* This exists because the falling edge cannot be relied on. Camera-native
+	* providers emit motion as a RISING EDGE ONLY (Reolink's Baichuan push and
+	* its email-push SMTP path both emit `detected: true` and never the
+	* counterpart); only the frame-diff analyzer emits falls. So on an
+	* onboard-only camera a window that closed only on `detected: false` never
+	* closed at all, and `on-motion` silently behaved as `always-on` — on a
+	* battery camera, the one failure mode the mode exists to prevent.
+	*
+	* Every motion event rearms this timer WITHOUT restarting the stream, so a
+	* burst of re-fires costs nothing. A falling edge, when one does arrive,
+	* still closes earlier via `motionCooldownMs` — whichever comes first wins.
+	*
+	* Not consumed by the runner: carried here so it shares the per-camera
+	* device-settings surface with `motionCooldownMs`, exactly like
+	* `maxSessionHoldMs`.
+	*/
+	audioMotionWindowMs: number$1().min(audioMotionWindowMsField.min).max(audioMotionWindowMsField.max).optional(),
 	motionFps: number$1().min(motionFpsField.min).max(motionFpsField.max).default(motionFpsField.default),
 	detectionFps: number$1().min(detectionFpsField.min).max(detectionFpsField.max).default(detectionFpsField.default),
 	motionStreamId: string(),
@@ -18166,7 +18372,7 @@ var RunnerCameraConfigSchema = object({
 	*/
 	inferenceDevices: array(RunnerInferenceDeviceSchema).readonly().optional()
 });
-motionFpsField.min, motionFpsField.max, motionFpsField.step, motionFpsField.default, detectionFpsField.min, detectionFpsField.max, detectionFpsField.step, detectionFpsField.default, motionCooldownMsField.min, motionCooldownMsField.max, motionCooldownMsField.step, motionCooldownMsField.default, maxSessionHoldMsField.min, maxSessionHoldMsField.max, maxSessionHoldMsField.step, maxSessionHoldMsField.default, occupancyRecheckSecField.min, occupancyRecheckSecField.max, occupancyRecheckSecField.step, occupancyRecheckSecField.default, occupancyRecheckFramesField.min, occupancyRecheckFramesField.max, occupancyRecheckFramesField.step, occupancyRecheckFramesField.default;
+motionFpsField.min, motionFpsField.max, motionFpsField.step, motionFpsField.default, detectionFpsField.min, detectionFpsField.max, detectionFpsField.step, detectionFpsField.default, motionCooldownMsField.min, motionCooldownMsField.max, motionCooldownMsField.step, motionCooldownMsField.default, maxSessionHoldMsField.min, maxSessionHoldMsField.max, maxSessionHoldMsField.step, maxSessionHoldMsField.default, audioMotionWindowMsField.min, audioMotionWindowMsField.max, audioMotionWindowMsField.step, audioMotionWindowMsField.default, occupancyRecheckSecField.min, occupancyRecheckSecField.max, occupancyRecheckSecField.step, occupancyRecheckSecField.default, occupancyRecheckFramesField.min, occupancyRecheckFramesField.max, occupancyRecheckFramesField.step, occupancyRecheckFramesField.default;
 /**
 * Runtime load summary returned by `getLocalLoad`. Used by the orchestrator's
 * load-balancing levels (L2 capacity-based, L3 hardware-aware) to decide
@@ -24572,6 +24778,33 @@ method(object({
 *  as `unknown`, never guessed. A day reference scored against an IR frame
 *  collapses the cosine and would latch a false alarm every single night. */
 var SceneConditionSchema = string();
+/**
+* What a scene does when the CURRENT light has no reference of its own.
+*
+* The lighting variants are not equally likely to exist. Almost every operator
+* captures daylight and then never stands outside at 22:00 to capture IR, and a
+* scene that is only ever going to be asked about a daytime question ("is the
+* bin still on the kerb at 08:00") does not need a night reference at all. The
+* night half must therefore be OPTIONAL, and optional means the scene keeps
+* working without it rather than degrading into a permanent complaint.
+*
+* - `skip` (default) — the check in that light is not made. Not a verdict, not
+*   an alarm, not even an `unknown`: the live state simply stays whatever the
+*   last covered light left it at, the latch is untouched, and the hysteresis
+*   run is neither spent nor cleared. The scene resumes by itself at first
+*   light. This is the only behaviour under which "I never captured IR" is a
+*   configuration choice instead of a nightly fault.
+* - `judge-anyway` — score against the OTHER conditions' references. Available
+*   for cameras whose IR frame is close enough to daylight (a floodlit
+*   driveway, an always-white-light doorbell), and wrong for everything else:
+*   cross-condition cosines are not comparable, so a day reference against a
+*   true IR frame collapses and the scene reports a theft at 21:40.
+*
+* Never applies when the scene has NO comparable reference at all — that is
+* "not armed yet", it is reported as `no-reference-for-condition`, and silence
+* there would hide a scene the operator never finished setting up.
+*/
+var SceneUncoveredPolicySchema = _enum(["skip", "judge-anyway"]);
 /** `matched` = the baseline is what we see; `diverged` = it demonstrably is not;
 *  `unknown` = we cannot judge (no reference for this condition, encoder model
 *  changed, view shifted, no snapshot). `unknown` is a real value, not a null,
@@ -24627,6 +24860,9 @@ var SceneCheckSchema = discriminatedUnion("mode", [object({
 	hysteresisCount: number$1().int().positive()
 })]);
 var SCENE_DEFAULT_ANCHOR_THRESHOLD = .85;
+/** Night is OPTIONAL. A scene with only a daylight reference sits the IR hours
+*  out in silence rather than reporting a fault every night. */
+var SCENE_DEFAULT_UNCOVERED_POLICY = "skip";
 /**
 * Vision-model adjudication of a candidate flip. Field names deliberately
 * mirror `NcConfirmSchema` so an operator meets one vocabulary, not two.
@@ -24693,6 +24929,21 @@ var SceneMonitorSchema = object({
 	*  automation can react to the bin coming back without the operator's own
 	*  alarm silently clearing itself. */
 	autoRestore: boolean().default(false),
+	/** What to do when the current light has no reference of its own. See
+	*  {@link SceneUncoveredPolicySchema} — the default makes night OPTIONAL. */
+	onUncoveredCondition: SceneUncoveredPolicySchema.default(SCENE_DEFAULT_UNCOVERED_POLICY),
+	/**
+	* The light whose checks are currently being SAT OUT under
+	* `onUncoveredCondition: 'skip'` — `null` when the scene is checking normally.
+	*
+	* Engine-reported and advisory only: it moves no verdict, no latch and no
+	* hysteresis. It exists so the card can say *"night (IR) — checks paused,
+	* nothing captured in this light"* in the same calm voice as the coverage
+	* line, because the alternative is a scene that silently stops answering
+	* after sunset with nothing anywhere saying why. A skipped check must never
+	* read as a broken one.
+	*/
+	suspendedCondition: SceneConditionSchema.nullable().default(null),
 	/** Named cause when `verdict === 'unknown'`. */
 	unavailable: SceneUnavailableSchema.nullable(),
 	/** Conditions that have at least one comparable reference — the coverage line
@@ -24736,6 +24987,7 @@ DeviceType.Camera, method(object({ deviceId: number$1() }), SceneMonitorStatusSc
 		minObservationSpacingSec: number$1().int().min(0).max(3600).optional(),
 		anchorThreshold: number$1().min(0).max(1).optional(),
 		autoRestore: boolean().optional(),
+		onUncoveredCondition: SceneUncoveredPolicySchema.optional(),
 		/** `null` clears the vision-model adjudicator. */
 		confirm: SceneConfirmSchema.nullable().optional()
 	})
@@ -27967,6 +28219,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"llm.resolveModelRef": {
+		capName: "llm",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"llm.setDefault": {
 		capName: "llm",
 		capScope: "system",
@@ -45675,7 +45933,7 @@ function inferDocMediaType(uriOrName) {
 	for (const [ext, media] of Object.entries(KNOWN_DOC_EXTENSIONS)) if (lower.endsWith(`.${ext}`)) return media;
 	return "application/octet-stream";
 }
-function basename$1(uriOrName) {
+function basename$2(uriOrName) {
 	const parts = uriOrName.split("/");
 	const last = parts[parts.length - 1];
 	return last && last.length > 0 ? last : void 0;
@@ -45705,7 +45963,7 @@ function annotationToSource({ annotation, generateId: generateId3 }) {
 				url: uri,
 				...fileCitation.file_name != null ? { title: fileCitation.file_name } : {}
 			};
-			const filename = (_c = fileCitation.file_name) != null ? _c : basename$1(uri);
+			const filename = (_c = fileCitation.file_name) != null ? _c : basename$2(uri);
 			const mediaType = inferDocMediaType(uri);
 			return {
 				type: "source",
@@ -45794,7 +46052,7 @@ function builtinToolResultToSources({ block, generateId: generateId3 }) {
 					});
 					continue;
 				}
-				const filename = (_h = entry.file_name) != null ? _h : basename$1(uri);
+				const filename = (_h = entry.file_name) != null ? _h : basename$2(uri);
 				const mediaType = inferDocMediaType(uri);
 				sources.push({
 					type: "source",
@@ -68783,6 +69041,108 @@ createIdGenerator({
 	size: 24
 });
 //#endregion
+//#region src/client/connect-probe.ts
+/**
+* "Is this endpoint accepting connections?" — and deliberately nothing else.
+*
+* ## Why this exists as its own step
+*
+* The `llm` taxonomy has always claimed a CONNECT bound distinct from the
+* FIRST-TOKEN one, on the grounds that they are different faults with different
+* remedies. The implementation did not honour that: it armed the 10 s connect
+* timer around the wait for HTTP RESPONSE HEADERS. On the wire this repo talks
+* to most — LM Studio / llama-server — the headers are the LAST thing that
+* happens before the first token: the server accepts the socket, reads the
+* request, loads the model into the GPU (minutes for qwen3-vl), and only then
+* writes a status line. So a cold load was reported as
+* `unavailable: the endpoint did not accept the connection within 10s`, and the
+* operator was sent to check a base URL that was correct. It cost two live
+* debugging sessions.
+*
+* A TCP handshake is the only thing that answers the connect question without
+* ambiguity, so that is what this probes: a closed port fails at once with
+* `ECONNREFUSED`, a black-holed address burns the whole bound, and a listening
+* endpoint says yes in a millisecond on a LAN — whatever it plans to do next.
+*
+* The socket is closed immediately. This is a probe, not the request; the real
+* call dials its own connection through the library's `fetch` a moment later.
+* That gap is a theoretical race (the port could shut in between) and a real
+* one would surface as the ordinary network error it is.
+*/
+var defaultConnectImpl = (endpoint) => connect({
+	host: endpoint.host,
+	port: endpoint.port
+});
+/**
+* The TCP endpoint a base URL points at, or `null` when there is not one.
+*
+* `null` is "do not probe", never "the endpoint is down": a profile whose URL
+* this cannot parse must fail on the real request with the real reason, not on
+* a guess made here.
+*/
+function tcpEndpointOf(baseUrl) {
+	let url;
+	try {
+		url = new URL(baseUrl);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	const port = url.port === "" ? url.protocol === "https:" ? 443 : 80 : Number(url.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+	const host = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
+	return host.length === 0 ? null : {
+		host,
+		port
+	};
+}
+/**
+* Dial, and report which of the three things happened.
+*
+* Never rejects — the caller is `LlmClient`, which owes its own callers a
+* RESULT rather than a throw. `signal` is honoured so that an operator who
+* closes the page does not leave a socket dialling for the rest of the bound.
+*/
+function probeTcpConnect(endpoint, timeoutMs, signal, connectImpl = defaultConnectImpl) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let socket = null;
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			socket?.destroy();
+			resolve(outcome);
+		};
+		const timer = setTimeout(() => settle({ kind: "timeout" }), timeoutMs);
+		timer.unref?.();
+		const onAbort = () => settle({
+			kind: "error",
+			message: "the connection attempt was cancelled"
+		});
+		signal.addEventListener("abort", onAbort, { once: true });
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		try {
+			socket = connectImpl(endpoint);
+		} catch (error) {
+			settle({
+				kind: "error",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return;
+		}
+		socket.once("connect", () => settle({ kind: "connected" }));
+		socket.once("error", (error) => settle({
+			kind: "error",
+			message: error.message
+		}));
+	});
+}
+//#endregion
 //#region src/client/llm-client.ts
 /**
 * `LlmClient` — the ONE file in this repo allowed to import the LLM library.
@@ -68847,6 +69207,19 @@ function baseUrlFor$1(profile) {
 	return profile.kind === "openai" ? OPENAI_DEFAULT_BASE_URL$1 : null;
 }
 /**
+* Where to knock, for the connect probe.
+*
+* Wider than {@link baseUrlFor}: an Anthropic or Google profile with an
+* explicit `baseUrl` (a LAN proxy, a gateway) is just as probe-able as an
+* openai-compatible one. Only a profile that relies on a vendor's built-in
+* endpoint yields `null` — the client never learns that URL, and inventing one
+* to probe would be probing a different host from the one the call uses.
+*/
+function probeEndpointFor(profile) {
+	const baseUrl = profile.baseUrl !== void 0 && profile.baseUrl.length > 0 ? trimSlash(profile.baseUrl) : baseUrlFor$1(profile);
+	return baseUrl === null ? null : tcpEndpointOf(baseUrl);
+}
+/**
 * Build the provider instance for a profile.
 *
 * Returns `null` when the profile cannot be served — a missing base URL on an
@@ -69105,7 +69478,7 @@ function createLlmClient(deps = {}) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
 					ok: false,
 					code: "timeout",
-					message: `timed out after ${String(timeoutMs)}ms`
+					message: `no answer within ${String(Math.round(timeoutMs / 1e3))}s — a cold model can take minutes to load; warm it or raise the profile's total timeout`
 				};
 				const mapped = mapLibraryError(error);
 				return {
@@ -69119,41 +69492,91 @@ function createLlmClient(deps = {}) {
 			if (!SUPPORTED_KINDS.has(request.profile.kind)) return { kind: "unsupported" };
 			const model = modelFor(request.profile);
 			if (model === null) return { kind: "unsupported" };
-			const connect = new AbortController();
-			const onOuterAbort = () => connect.abort();
+			const endpoint = probeEndpointFor(request.profile);
+			if (endpoint !== null) {
+				const probe = await probeTcpConnect(endpoint, opts.connectTimeoutMs, request.signal, deps.connectImpl ?? defaultConnectImpl);
+				if (probe.kind === "timeout") return {
+					kind: "connect-timeout",
+					timeoutMs: opts.connectTimeoutMs
+				};
+				if (probe.kind === "error") return {
+					kind: "network",
+					message: request.signal.aborted ? "the call was cancelled" : probe.message
+				};
+				opts.onConnected?.();
+			}
+			const firstChunkBound = new AbortController();
+			const onOuterAbort = () => firstChunkBound.abort();
 			request.signal.addEventListener("abort", onOuterAbort, { once: true });
-			const connectTimer = setTimeout(() => connect.abort(), opts.connectTimeoutMs);
-			connectTimer.unref?.();
+			const firstChunkTimer = setTimeout(() => firstChunkBound.abort(), opts.firstTokenTimeoutMs);
+			firstChunkTimer.unref?.();
+			let streamFailure;
 			try {
-				const stream = streamText({
+				const iterator = chunksFrom(streamText({
 					model,
 					messages: messagesFor(request),
 					...instructionsFor(request),
 					...callSettingsFor(request),
 					...structuredOutputFor(request),
-					abortSignal: AbortSignal.any([request.signal, connect.signal])
-				});
-				await stream.response;
+					abortSignal: AbortSignal.any([request.signal, firstChunkBound.signal]),
+					onError: ({ error }) => {
+						streamFailure = error;
+					}
+				}))[Symbol.asyncIterator]();
+				const first = await iterator.next();
+				if (streamFailure !== void 0) {
+					const mapped = mapLibraryError(streamFailure);
+					return {
+						kind: "provider-error",
+						code: mapped.code,
+						message: mapped.message
+					};
+				}
+				if (firstChunkBound.signal.aborted) return request.signal.aborted ? {
+					kind: "network",
+					message: "the call was cancelled"
+				} : {
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
+				};
 				return {
 					kind: "open",
-					chunks: chunksFrom(stream)
+					chunks: resumeFrom(first, iterator)
 				};
 			} catch (error) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
-					kind: "connect-timeout",
-					timeoutMs: opts.connectTimeoutMs
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
 				};
+				const mapped = mapLibraryError(error);
 				return {
-					kind: "network",
-					message: mapLibraryError(error).message
+					kind: "provider-error",
+					code: mapped.code,
+					message: mapped.message
 				};
 			} finally {
-				clearTimeout(connectTimer);
+				clearTimeout(firstChunkTimer);
 				request.signal.removeEventListener("abort", onOuterAbort);
 			}
 		}
 	};
 }
+/**
+* Hand back a stream whose first chunk has already been pulled.
+*
+* `openStream` has to consume one chunk to know the model started — that is
+* what its bound measures — and the caller must still receive it. Replaying it
+* here is what keeps "the first token is the load signal" true for the reader.
+*/
+async function* resumeFrom(first, iterator) {
+	if (first.done === true) return;
+	yield first.value;
+	for (;;) {
+		const next = await iterator.next();
+		if (next.done === true) return;
+		yield next.value;
+	}
+}
 async function* chunksFrom(stream) {
 	for await (const text of stream.textStream) if (text.length > 0) yield {
 		kind: "token",
@@ -69499,7 +69922,7 @@ function httpProfileConfigSchema(opts) {
 					min: 500,
 					default: 1e4,
 					unit: "ms",
-					description: "Waiting for response headers — i.e. \"is the port even open\"."
+					description: "The TCP handshake — i.e. \"is the port even open\". A closed port fails at once; only a black hole spends the whole bound."
 				},
 				{
 					type: "number",
@@ -69508,7 +69931,7 @@ function httpProfileConfigSchema(opts) {
 					min: 1e3,
 					default: 12e4,
 					unit: "ms",
-					description: "Accepted but silent. A cold GPU load lives here and can take minutes."
+					description: "Accepted but silent — response headers included, since a model writes them once it has loaded. A cold GPU load lives here and can take minutes. The test chat waits exactly this long."
 				},
 				{
 					type: "number",
@@ -69836,6 +70259,469 @@ function resolveProfile(profiles, defaults, input) {
 	};
 }
 //#endregion
+//#region src/runtime/hf-ref.ts
+/**
+* Hugging Face model references — parse, then resolve against the HF API.
+*
+* The operator types ONE string and gets a fully-pinned download plan. That is
+* the whole surface: this is not an HF browser, and it deliberately cannot
+* discover a model for you — it can only turn a reference you already have
+* into something the node can fetch and verify.
+*
+* ## Why resolution can REFUSE
+*
+* A GGUF repo is not one model. `unsloth/Qwen3.6-35B-A3B-GGUF` ships 25
+* quantizations between 10 GB and 50 GB, and none of them is named `Q4_K_M`
+* (they are `UD-Q4_K_M`, Unsloth's dynamic quant). Any code that "defaults to
+* Q4_K_M" would either fail or, worse, pick a neighbouring file and hand the
+* operator a model they did not ask for after a 20 GB download. So: a repo
+* with more than one candidate is an ERROR that NAMES the candidates, never a
+* guess. The only silent pick is the mmproj precision (F16 over F32) — that
+* choice costs a few hundred MB of projector, not a different model, and the
+* file it picked is reported back.
+*
+* ## The error taxonomy is read from headers, not from the status
+*
+* Probed live on 2026-08-15: huggingface.co answers **401** both for a gated
+* repo and for a repo that does not exist (it refuses to leak whether a
+* private repo is there). The two are distinguishable only by
+* `x-error-code: GatedRepo`. Reading the status alone would tell a
+* typo'd repo name that it needs a token, which is the wrong instruction.
+*
+* ## What is verified before a byte is downloaded
+*
+* host is huggingface.co · extension is `.gguf` · every file exists in the
+* tree · the split-GGUF shard set is COMPLETE · the total (main + shards +
+* mmproj) is under the ceiling · a HEAD confirms the file is reachable with
+* the credentials at hand and that its size agrees with the tree. The sha256
+* comes free: HF's LFS `oid` IS the sha256 of the file, and `x-linked-etag`
+* repeats it on the HEAD.
+*/
+/** The only hosts a reference may point at. */
+var HF_HOSTS = ["huggingface.co", "www.huggingface.co"];
+var HF_API = "https://huggingface.co/api/models";
+var HF_RESOLVE = "https://huggingface.co";
+/** Where an operator puts a Hugging Face token, named in the gated error. */
+var HF_TOKEN_ENV = "HF_TOKEN";
+var SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function fail(code, message, candidates) {
+	return {
+		code,
+		message,
+		...candidates !== void 0 ? { candidates } : {}
+	};
+}
+function badParse(code, message, candidates) {
+	return {
+		ok: false,
+		error: fail(code, message, candidates)
+	};
+}
+var EXPECTED = "expected https://huggingface.co/<org>/<repo>/resolve/main/<file>.gguf, or <org>/<repo>/<file>.gguf, or <org>/<repo>[:<QUANT>]";
+/**
+* Reference string → a repo/file reference. Pure: no network, no environment.
+* Every rejection names the form that WAS expected, because the operator is
+* pasting from a browser and a bare "invalid" tells them nothing.
+*/
+function parseHfRef(input) {
+	const raw = input.trim();
+	if (raw === "") return badParse("malformed", `empty model reference — ${EXPECTED}`);
+	return raw.includes("://") ? parseUrlForm(raw) : parseBareForm(raw);
+}
+function parseUrlForm(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		return badParse("malformed", `not a URL: ${raw} — ${EXPECTED}`);
+	}
+	if (!HF_HOSTS.includes(url.hostname)) return badParse("not-huggingface", `only huggingface.co models can be installed this way; got host "${url.hostname}"`);
+	const parts = url.pathname.split("/").filter((p) => p !== "");
+	const marker = parts.findIndex((p) => p === "resolve" || p === "blob");
+	if (marker !== 2 || parts.length < marker + 3) return badParse("malformed", `unrecognised Hugging Face URL: ${raw} — ${EXPECTED}`);
+	return finishParse(`${String(parts[0])}/${String(parts[1])}`, String(parts[marker + 1]), parts.slice(marker + 2).join("/"), raw);
+}
+function parseBareForm(raw) {
+	const [beforeTag, ...tagRest] = raw.split(":");
+	const body = String(beforeTag);
+	if (tagRest.length > 1) return badParse("malformed", `too many ":" in ${raw} — ${EXPECTED}`);
+	const quant = tagRest[0]?.trim();
+	const parts = body.split("/");
+	if (parts.length < 2) return badParse("malformed", `not an <org>/<repo> reference: ${raw} — ${EXPECTED}`);
+	if (parts.some((p) => p === "" || p === "." || p === "..")) return badParse("malformed", `illegal path segment in ${raw} — ${EXPECTED}`);
+	const org = String(parts[0]);
+	const name = String(parts[1]);
+	if (!SEGMENT_RE.test(org) || !SEGMENT_RE.test(name)) return badParse("malformed", `illegal repo name in ${raw} — ${EXPECTED}`);
+	const repo = `${org}/${name}`;
+	if (parts.length === 2) {
+		if (quant !== void 0 && quant === "") return badParse("malformed", `empty quantization tag in ${raw} — ${EXPECTED}`);
+		return {
+			ok: true,
+			ref: {
+				kind: "repo",
+				repo,
+				revision: "main",
+				...quant !== void 0 ? { quant } : {}
+			}
+		};
+	}
+	if (quant !== void 0) return badParse("malformed", `a quantization tag cannot follow an explicit file: ${raw}`);
+	return finishParse(repo, "main", parts.slice(2).join("/"), raw);
+}
+function finishParse(repo, revision, filePath, raw) {
+	if (filePath.split("/").some((p) => p === "" || p === "." || p === "..")) return badParse("malformed", `illegal path segment in ${raw} — ${EXPECTED}`);
+	if (!filePath.toLowerCase().endsWith(".gguf")) return badParse("not-gguf", `the managed local runtime loads GGUF only; "${filePath}" is not a .gguf file`);
+	return {
+		ok: true,
+		ref: {
+			kind: "file",
+			repo,
+			revision,
+			filePath
+		}
+	};
+}
+/** `-00001-of-00002` — llama.cpp's split-GGUF naming. */
+var SHARD_RE = /^(.*)-(\d{5})-of-(\d{5})$/;
+/**
+* One `-`-delimited segment that is a quantization, e.g. `Q4_K_M`, `IQ2_XXS`,
+* `BF16`, `fp16`. The `FP` spellings are not cosmetic: `Qwen/*-GGUF` names its
+* unquantized file `…-fp16.gguf`, and a tag list that cannot name it offers
+* the operator a suggestion that does not parse.
+*/
+var QUANT_RE = /^(?:I?Q\d[A-Z0-9_]*|TQ\d_\d|BF16|FP?16|FP?32|FP8|MXFP4(?:_MOE)?)$/i;
+/** Shard coordinates of a split GGUF filename, or `null` when unsharded. */
+function shardInfoOf(filename) {
+	const m = SHARD_RE.exec(stripGguf(filename));
+	if (m === null) return null;
+	return {
+		stem: String(m[1]),
+		index: Number(m[2]),
+		total: Number(m[3])
+	};
+}
+function stripGguf(filename) {
+	return filename.replace(/\.gguf$/i, "");
+}
+/**
+* The quantization tag of a GGUF filename, uppercased, `UD-` prefix kept —
+* `''` when the name carries no recognisable tag. Shard coordinates are
+* stripped first so `X-BF16-00001-of-00002.gguf` reads as `BF16`.
+*/
+function quantizationOf(filename) {
+	const segments = (shardInfoOf(filename)?.stem ?? stripGguf(filename)).split("-");
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const seg = String(segments[i]);
+		if (!QUANT_RE.test(seg)) continue;
+		return (i > 0 ? String(segments[i - 1]) : "").toUpperCase() === "UD" ? `UD-${seg.toUpperCase()}` : seg.toUpperCase();
+	}
+	return "";
+}
+function isMmproj(filePath) {
+	return basename$1(filePath).toLowerCase().startsWith("mmproj");
+}
+function basename$1(filePath) {
+	return filePath.slice(filePath.lastIndexOf("/") + 1);
+}
+function dirname(filePath) {
+	const i = filePath.lastIndexOf("/");
+	return i < 0 ? "" : filePath.slice(0, i);
+}
+function headersFor(token) {
+	return {
+		"User-Agent": "CamStack/1.0",
+		...token !== void 0 && token !== "" ? { Authorization: `Bearer ${token}` } : {}
+	};
+}
+/** HF's 401-for-everything is only decodable through `x-error-code`. */
+function authError(response, repo) {
+	const code = response.headers.get("x-error-code") ?? "";
+	if (code === "GatedRepo" || code === "GatedRepoAccessDenied") return fail("gated", `${repo} is a gated Hugging Face repo: accept its licence with your HF account, then set a token in the ${HF_TOKEN_ENV} environment variable on the hub and on the runtime node (${HF_TOKEN_ENV} or HUGGING_FACE_HUB_TOKEN), and restart them.`);
+	return fail("repo-not-found", `${repo} does not exist on huggingface.co, or is private (Hugging Face answers 401 for both). Check the org/repo spelling.`);
+}
+async function readTree(ref, fetchFn, token) {
+	const url = `${HF_API}/${ref.repo}/tree/${ref.revision}?recursive=1`;
+	let response;
+	try {
+		response = await fetchFn(url, {
+			method: "GET",
+			headers: headersFor(token)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `could not reach huggingface.co: ${message(err)}`)
+		};
+	}
+	if (response.status === 401 || response.status === 403) return {
+		ok: false,
+		error: authError(response, ref.repo)
+	};
+	if (response.status === 404) return {
+		ok: false,
+		error: fail("repo-not-found", `${ref.repo} has no revision "${ref.revision}"`)
+	};
+	if (!response.ok) return {
+		ok: false,
+		error: fail("network", `huggingface.co answered ${String(response.status)} for ${ref.repo}`)
+	};
+	let body;
+	try {
+		body = await response.json();
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `unreadable tree for ${ref.repo}: ${message(err)}`)
+		};
+	}
+	if (!Array.isArray(body)) return {
+		ok: false,
+		error: fail("network", `unexpected tree payload for ${ref.repo}`)
+	};
+	return {
+		ok: true,
+		files: body.map(toTreeEntry).filter((e) => e !== null)
+	};
+}
+function toTreeEntry(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const record = { ...raw };
+	if (record["type"] !== "file") return null;
+	const filePath = record["path"];
+	if (typeof filePath !== "string" || !filePath.toLowerCase().endsWith(".gguf")) return null;
+	const lfs = typeof record["lfs"] === "object" && record["lfs"] !== null ? { ...record["lfs"] } : {};
+	const lfsSize = lfs["size"];
+	const oid = lfs["oid"];
+	const plainSize = record["size"];
+	return {
+		path: filePath,
+		sizeBytes: typeof lfsSize === "number" ? lfsSize : typeof plainSize === "number" ? plainSize : 0,
+		...typeof oid === "string" && oid.length === 64 ? { sha256: oid } : {}
+	};
+}
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Files that can be THE model: not a projector, not a follow-on shard. */
+function modelCandidates(files) {
+	return files.filter((f) => {
+		if (isMmproj(f.path)) return false;
+		const shard = shardInfoOf(basename$1(f.path));
+		return shard === null || shard.index === 1;
+	});
+}
+function labelFor(file) {
+	const quant = quantizationOf(basename$1(file.path));
+	return quant === "" ? basename$1(file.path) : quant;
+}
+function selectMain(ref, files) {
+	const candidates = modelCandidates(files);
+	if (ref.kind === "file") {
+		const wanted = ref.filePath.toLowerCase();
+		const hit = files.find((f) => f.path.toLowerCase() === wanted);
+		if (hit === void 0) return {
+			ok: false,
+			error: fail("file-not-found", `${ref.repo} has no file "${ref.filePath}" at revision ${ref.revision}`, candidates.map(labelFor))
+		};
+		return {
+			ok: true,
+			file: hit
+		};
+	}
+	if (candidates.length === 0) return {
+		ok: false,
+		error: fail("not-gguf", `${ref.repo} publishes no GGUF weights (only projectors or no GGUF at all)`)
+	};
+	if (ref.quant !== void 0) {
+		const wanted = ref.quant.toUpperCase();
+		const wantedFile = stripGguf(ref.quant).toUpperCase();
+		const matches = candidates.filter((f) => quantizationOf(basename$1(f.path)) === wanted || stripGguf(basename$1(f.path)).toUpperCase() === wantedFile);
+		if (matches.length === 0) return {
+			ok: false,
+			error: fail("file-not-found", `${ref.repo} has no "${ref.quant}" quantization. Available: ${candidates.map(labelFor).join(", ")}`, dedupe(candidates.map(labelFor)))
+		};
+		const only = matches[0];
+		if (matches.length > 1 || only === void 0) return {
+			ok: false,
+			error: fail("ambiguous", `"${ref.quant}" matches ${String(matches.length)} files in ${ref.repo}: ${matches.map((f) => basename$1(f.path)).join(", ")}. Name the file explicitly.`, matches.map((f) => basename$1(f.path)))
+		};
+		return {
+			ok: true,
+			file: only
+		};
+	}
+	const solo = candidates[0];
+	if (candidates.length > 1 || solo === void 0) {
+		const tags = dedupe(candidates.map(labelFor));
+		return {
+			ok: false,
+			error: fail("ambiguous", `${ref.repo} publishes ${String(candidates.length)} quantizations and picking one for you would be a guess. Re-enter it as ${ref.repo}:<TAG>, or paste the full file URL. Available: ${tags.join(", ")}`, tags)
+		};
+	}
+	return {
+		ok: true,
+		file: solo
+	};
+}
+function dedupe(values) {
+	return [...new Set(values)];
+}
+/** Shards 2..N of `main`, or an error naming the first one that is missing. */
+function collectShards(main, files) {
+	const shard = shardInfoOf(basename$1(main.path));
+	if (shard === null || shard.total <= 1) return {
+		ok: true,
+		shards: []
+	};
+	const dir = dirname(main.path);
+	const out = [];
+	for (let i = 2; i <= shard.total; i++) {
+		const wanted = `${shard.stem}-${String(i).padStart(5, "0")}-of-${String(shard.total).padStart(5, "0")}.gguf`;
+		const full = dir === "" ? wanted : `${dir}/${wanted}`;
+		const hit = files.find((f) => f.path === full);
+		if (hit === void 0) return {
+			ok: false,
+			error: fail("incomplete-shards", `split GGUF is incomplete: ${wanted} is missing from the repo (llama.cpp needs all ${String(shard.total)} shards)`)
+		};
+		out.push(hit);
+	}
+	return {
+		ok: true,
+		shards: out
+	};
+}
+/** F16 over BF16 over F32 over whatever came first — reported, never hidden. */
+var MMPROJ_PREFERENCE = [
+	"F16",
+	"BF16",
+	"F32"
+];
+function selectMmproj(files) {
+	const projectors = files.filter((f) => isMmproj(f.path));
+	if (projectors.length === 0) return null;
+	for (const want of MMPROJ_PREFERENCE) {
+		const hit = projectors.find((f) => quantizationOf(basename$1(f.path)) === want);
+		if (hit !== void 0) return hit;
+	}
+	return projectors[0] ?? null;
+}
+function resolveUrl(repo, revision, filePath) {
+	return `${HF_RESOLVE}/${repo}/resolve/${revision}/${filePath}`;
+}
+async function verifyHead(url, repo, declaredBytes, fetchFn, token) {
+	let response;
+	try {
+		response = await fetchFn(url, {
+			method: "HEAD",
+			redirect: "manual",
+			headers: headersFor(token)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `HEAD ${url} failed: ${message(err)}`)
+		};
+	}
+	if (response.status === 401 || response.status === 403) return {
+		ok: false,
+		error: authError(response, repo)
+	};
+	if (response.status === 404) return {
+		ok: false,
+		error: fail("file-not-found", `${url} is gone (404)`)
+	};
+	if (response.status >= 400) return {
+		ok: false,
+		error: fail("network", `HEAD ${url} answered ${String(response.status)}`)
+	};
+	const linked = response.headers.get("x-linked-size") ?? response.headers.get("content-length");
+	const headBytes = linked === null ? void 0 : Number(linked);
+	if (headBytes !== void 0 && Number.isFinite(headBytes) && headBytes !== declaredBytes) return {
+		ok: false,
+		error: fail("size-mismatch", `huggingface.co reports ${String(headBytes)} bytes for ${url} but its tree declared ${String(declaredBytes)} — refusing to download a file that changed under the reference`)
+	};
+	const etag = response.headers.get("x-linked-etag")?.replace(/"/g, "");
+	return {
+		ok: true,
+		...etag !== void 0 && etag.length === 64 ? { sha256: etag } : {}
+	};
+}
+function toResolved(repo, revision, entry) {
+	return {
+		url: resolveUrl(repo, revision, entry.path),
+		filename: basename$1(entry.path),
+		sizeBytes: entry.sizeBytes,
+		...entry.sha256 !== void 0 ? { sha256: entry.sha256 } : {}
+	};
+}
+function gb$1(bytes) {
+	return `${(bytes / 1e9).toFixed(1)} GB`;
+}
+/** Reference → a pinned, size-checked, HEAD-verified download plan. */
+async function resolveHfRef(ref, deps) {
+	const fetchFn = deps.fetchFn ?? fetch;
+	const maxBytes = deps.maxBytes ?? 21474836480;
+	const tree = await readTree(ref, fetchFn, deps.token);
+	if (!tree.ok) return {
+		ok: false,
+		error: tree.error
+	};
+	const picked = selectMain(ref, tree.files);
+	if (!picked.ok) return {
+		ok: false,
+		error: picked.error
+	};
+	const main = picked.file;
+	const shards = collectShards(main, tree.files);
+	if (!shards.ok) return {
+		ok: false,
+		error: shards.error
+	};
+	const projector = isMmproj(main.path) ? null : selectMmproj(tree.files);
+	const extraEntries = [...shards.shards, ...projector === null ? [] : [projector]];
+	const totalBytes = [main, ...extraEntries].reduce((sum, f) => sum + f.sizeBytes, 0);
+	if (totalBytes > maxBytes) return {
+		ok: false,
+		error: {
+			...fail("too-large", `this install is ${String(totalBytes)} bytes (${gb$1(totalBytes)}), over the ${String(maxBytes)} byte ceiling (${gb$1(maxBytes)}). Raise the ceiling explicitly if the node really has the disk and RAM for it.`),
+			requiredBytes: totalBytes
+		}
+	};
+	const head = await verifyHead(resolveUrl(ref.repo, ref.revision, main.path), ref.repo, main.sizeBytes, fetchFn, deps.token);
+	if (!head.ok) return {
+		ok: false,
+		error: head.error
+	};
+	const mainResolved = toResolved(ref.repo, ref.revision, {
+		...main,
+		...main.sha256 === void 0 && head.sha256 !== void 0 ? { sha256: head.sha256 } : {}
+	});
+	const quantization = quantizationOf(mainResolved.filename);
+	const repoName = ref.repo.slice(ref.repo.indexOf("/") + 1);
+	return {
+		ok: true,
+		resolution: {
+			repo: ref.repo,
+			revision: ref.revision,
+			label: quantization === "" ? repoName : `${repoName} · ${quantization}`,
+			quantization,
+			purpose: projector === null ? "text" : "vision",
+			main: mainResolved,
+			extras: extraEntries.map((e) => toResolved(ref.repo, ref.revision, e)),
+			totalBytes
+		}
+	};
+}
+/** `parseHfRef` then {@link resolveHfRef} — the form the cap method calls. */
+async function resolveHfReference(input, deps) {
+	const parsed = parseHfRef(input);
+	if (!parsed.ok) return {
+		ok: false,
+		error: parsed.error
+	};
+	return resolveHfRef(parsed.ref, deps);
+}
+//#endregion
 //#region src/secrets.ts
 /** Same marker as addon-notifiers/src/secrets.ts — UI contract. */
 var REDACTED_MARKER = "__redacted__";
@@ -70059,6 +70945,64 @@ function createLlmProvider(deps) {
 			}));
 		},
 		listNodeModels: async ({ nodeId }) => requireRuntime(deps.runtime).listLocalModels(nodeId),
+		/**
+		* Hugging Face reference → a pinned `ManagedModelRef`, on the HUB.
+		*
+		* Never throws: a refusal ("this repo has 24 quantizations", "this is
+		* gated", "23 GB is over the ceiling") is an ANSWER the operator has to
+		* read and act on, and turning it into a tRPC error would reduce all of
+		* them to a red toast with no candidate list and no override.
+		*/
+		resolveModelRef: async ({ ref, maxBytes }) => {
+			const token = deps.hfToken?.();
+			const outcome = await resolveHfReference(ref, {
+				...maxBytes !== void 0 ? { maxBytes } : {},
+				...token !== void 0 && token !== "" ? { token } : {}
+			});
+			if (!outcome.ok) {
+				deps.logger?.info("llm model reference refused", { meta: {
+					ref,
+					code: outcome.error.code
+				} });
+				return {
+					ok: false,
+					code: outcome.error.code,
+					message: outcome.error.message,
+					...outcome.error.candidates !== void 0 ? { candidates: [...outcome.error.candidates] } : {},
+					...outcome.error.requiredBytes !== void 0 ? { requiredBytes: outcome.error.requiredBytes } : {}
+				};
+			}
+			const { resolution } = outcome;
+			deps.logger?.info("llm model reference resolved", { meta: {
+				ref,
+				repo: resolution.repo,
+				quantization: resolution.quantization,
+				purpose: resolution.purpose,
+				totalBytes: resolution.totalBytes
+			} });
+			return {
+				ok: true,
+				model: {
+					kind: "url",
+					url: resolution.main.url,
+					...resolution.main.sha256 !== void 0 ? { sha256: resolution.main.sha256 } : {},
+					label: resolution.label,
+					sizeBytes: resolution.main.sizeBytes,
+					extraFiles: resolution.extras.map((e) => ({
+						url: e.url,
+						filename: e.filename,
+						sizeBytes: e.sizeBytes,
+						...e.sha256 !== void 0 ? { sha256: e.sha256 } : {}
+					}))
+				},
+				label: resolution.label,
+				repo: resolution.repo,
+				quantization: resolution.quantization,
+				purpose: resolution.purpose,
+				totalBytes: resolution.totalBytes,
+				extraFilenames: resolution.extras.map((e) => e.filename)
+			};
+		},
 		installModel: async ({ nodeId, model }) => {
 			const runtime = requireRuntime(deps.runtime);
 			try {
@@ -70092,13 +71036,29 @@ function createLlmProvider(deps) {
 //#endregion
 //#region src/runtime/llm-model-catalog.ts
 /**
-* Curated managed-model catalog (operator decision #4): ~2 small text GGUFs
-* (2-4B, Q4) + 1 small vision GGUF with its companion mmproj, sized to the
-* weakest runtime node (the N100 agent). Each entry carries BOTH the LLM-facing
-* picker view (`meta`) and the REUSED download-plane `ModelCatalogEntry`
-* (`entry`) so GGUFs ride `ensureModel` + `model-distributor` untouched — no
-* bespoke fetcher (spec §4.2). Digests/sizes pinned via
-* scratchpad/pin-llm-models.mjs (HF LFS `lfs.oid`).
+* Curated managed-model catalog (operator decision #4). Each entry carries BOTH
+* the LLM-facing picker view (`meta`) and the REUSED download-plane
+* `ModelCatalogEntry` (`entry`) so GGUFs ride `ensureModel` +
+* `model-distributor` untouched — no bespoke fetcher (spec §4.2).
+* Digests/sizes pinned via scratchpad/pin-llm-models.mjs (HF LFS `lfs.oid`,
+* which IS the file's sha256).
+*
+* ## Two tiers, and `minRamBytes` is what separates them
+*
+* The first three entries are sized to the WEAKEST runtime node (the N100
+* agent): 1-4 GB, Q4. `QWEN36_35B` is not — it is 23 GB and only a big node
+* can hold it. The catalog does not refuse to show it; `minRamBytes` is the
+* guidance, and the picker prints the size. Keeping the tiers in one list is
+* deliberate: an operator with a 64 GB box should not have to discover the
+* free-text field to run something real.
+*
+* ## This list is no longer the boundary of what can run
+*
+* Anything on Hugging Face is installable through `llm.resolveModelRef` +
+* `installModel` without a code change ({@link ./hf-ref.ts}). An entry here
+* buys exactly two things over typing the reference: a pinned digest nobody
+* has to re-verify, and a `contextSizeDefault`/`minRamBytes` somebody checked.
+* Add one only when both are true.
 */
 var GIB = 1024 * 1024 * 1024;
 function mb(bytes) {
@@ -70150,30 +71110,117 @@ var LLAMA = textEntry({
 var SMOLVLM_MODEL_BYTES = 1112602656;
 var SMOLVLM_MMPROJ_BYTES = 872303680;
 var SMOLVLM_MMPROJ_URL = "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/mmproj-SmolVLM2-2.2B-Instruct-f16.gguf";
+var SMOLVLM = {
+	meta: {
+		id: "llm-smolvlm2-2.2b-instruct-q4",
+		label: "SmolVLM2 2.2B Instruct (vision)",
+		family: "smolvlm2",
+		purpose: "vision",
+		url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
+		sha256: "0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58",
+		sizeBytes: SMOLVLM_MODEL_BYTES,
+		quantization: "Q4_K_M",
+		minRamBytes: 4 * GIB,
+		contextSizeDefault: 4096,
+		mmprojUrl: SMOLVLM_MMPROJ_URL
+	},
+	entry: {
+		id: "llm-smolvlm2-2.2b-instruct-q4",
+		name: "SmolVLM2 2.2B Instruct (vision)",
+		description: "smolvlm2 · Q4_K_M · +mmproj",
+		formats: { gguf: {
+			url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
+			sizeMB: mb(SMOLVLM_MODEL_BYTES)
+		} },
+		inputSize: {
+			width: 0,
+			height: 0
+		},
+		labels: [],
+		extraFiles: [{
+			url: SMOLVLM_MMPROJ_URL,
+			filename: "mmproj-SmolVLM2-2.2B-Instruct-f16.gguf",
+			sizeMB: mb(SMOLVLM_MMPROJ_BYTES)
+		}]
+	}
+};
+var QWEN3VL2B_MODEL_BYTES = 1107410624;
+var QWEN3VL2B_MMPROJ_BYTES = 819395232;
+var QWEN3VL2B_BASE = "https://huggingface.co/unsloth/Qwen3-VL-2B-Instruct-GGUF/resolve/main";
+var QWEN3VL2B_MMPROJ_URL = `${QWEN3VL2B_BASE}/mmproj-F16.gguf`;
+var QWEN3VL2B_URL = `${QWEN3VL2B_BASE}/Qwen3-VL-2B-Instruct-Q4_K_M.gguf`;
+/**
+* The light vision tier the operator asked for by weight class (~2 GB all in):
+* same Qwen3-VL family as the LM Studio 8B profile already in daily use, so
+* prompts and behaviour carry over — at a tenth of the 35B's disk and a RAM
+* floor a hub-adjacent node can always afford. This is the sensible default
+* for the NC confirm gates and summary judges.
+*/
+var QWEN3VL_2B = {
+	meta: {
+		id: "llm-qwen3-vl-2b-instruct-q4",
+		label: "Qwen3-VL 2B Instruct (vision, light)",
+		family: "qwen3-vl",
+		purpose: "vision",
+		url: QWEN3VL2B_URL,
+		sha256: "858fcf2a39dc73b26dd86592cb0a5f949b59d1edb365d1dea98e46b02e955e56",
+		sizeBytes: QWEN3VL2B_MODEL_BYTES,
+		quantization: "Q4_K_M",
+		minRamBytes: 3 * GIB,
+		contextSizeDefault: 8192,
+		mmprojUrl: QWEN3VL2B_MMPROJ_URL
+	},
+	entry: {
+		id: "llm-qwen3-vl-2b-instruct-q4",
+		name: "Qwen3-VL 2B Instruct (vision, light)",
+		description: "qwen3-vl · Q4_K_M · +mmproj",
+		formats: { gguf: {
+			url: QWEN3VL2B_URL,
+			sizeMB: mb(QWEN3VL2B_MODEL_BYTES)
+		} },
+		inputSize: {
+			width: 0,
+			height: 0
+		},
+		labels: [],
+		extraFiles: [{
+			url: QWEN3VL2B_MMPROJ_URL,
+			filename: "mmproj-F16.gguf",
+			sizeMB: mb(QWEN3VL2B_MMPROJ_BYTES)
+		}]
+	}
+};
+var QWEN36_MODEL_BYTES = 22134528992;
+var QWEN36_MMPROJ_BYTES = 899283680;
+var QWEN36_BASE = "https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/resolve/main";
+var QWEN36_MMPROJ_URL = `${QWEN36_BASE}/mmproj-F16.gguf`;
+var QWEN36_URL = `${QWEN36_BASE}/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf`;
 var LLM_MODEL_CATALOG = [
 	QWEN,
 	LLAMA,
+	SMOLVLM,
+	QWEN3VL_2B,
 	{
 		meta: {
-			id: "llm-smolvlm2-2.2b-instruct-q4",
-			label: "SmolVLM2 2.2B Instruct (vision)",
-			family: "smolvlm2",
+			id: "llm-qwen3.6-35b-a3b-ud-q4",
+			label: "Qwen3.6 35B-A3B (vision)",
+			family: "qwen3.6",
 			purpose: "vision",
-			url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
-			sha256: "0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58",
-			sizeBytes: SMOLVLM_MODEL_BYTES,
-			quantization: "Q4_K_M",
-			minRamBytes: 4 * GIB,
-			contextSizeDefault: 4096,
-			mmprojUrl: SMOLVLM_MMPROJ_URL
+			url: QWEN36_URL,
+			sha256: "ac0e2c1189e055faa36eff361580e79c5bd6f8e76bffb4ce547f167d53e31a61",
+			sizeBytes: QWEN36_MODEL_BYTES,
+			quantization: "UD-Q4_K_M",
+			minRamBytes: 26 * GIB,
+			contextSizeDefault: 32768,
+			mmprojUrl: QWEN36_MMPROJ_URL
 		},
 		entry: {
-			id: "llm-smolvlm2-2.2b-instruct-q4",
-			name: "SmolVLM2 2.2B Instruct (vision)",
-			description: "smolvlm2 · Q4_K_M · +mmproj",
+			id: "llm-qwen3.6-35b-a3b-ud-q4",
+			name: "Qwen3.6 35B-A3B (vision)",
+			description: "qwen3.6 · UD-Q4_K_M · +mmproj",
 			formats: { gguf: {
-				url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
-				sizeMB: mb(SMOLVLM_MODEL_BYTES)
+				url: QWEN36_URL,
+				sizeMB: mb(QWEN36_MODEL_BYTES)
 			} },
 			inputSize: {
 				width: 0,
@@ -70181,9 +71228,9 @@ var LLM_MODEL_CATALOG = [
 			},
 			labels: [],
 			extraFiles: [{
-				url: SMOLVLM_MMPROJ_URL,
-				filename: "mmproj-SmolVLM2-2.2B-Instruct-f16.gguf",
-				sizeMB: mb(SMOLVLM_MMPROJ_BYTES)
+				url: QWEN36_MMPROJ_URL,
+				filename: "mmproj-F16.gguf",
+				sizeMB: mb(QWEN36_MMPROJ_BYTES)
 			}]
 		}
 	}
@@ -70200,19 +71247,25 @@ function entryForRef(ref) {
 	}
 	if (ref.kind === "url") {
 		const id = `llm-custom-${createHash("sha1").update(ref.url).digest("hex").slice(0, 12)}`;
+		const extraFiles = (ref.extraFiles ?? []).map((f) => ({
+			url: f.url,
+			filename: f.filename,
+			sizeMB: mb(f.sizeBytes)
+		}));
 		return { entry: {
 			id,
-			name: id,
+			name: ref.label ?? id,
 			description: "custom GGUF",
 			formats: { gguf: {
 				url: ref.url,
-				sizeMB: 0
+				sizeMB: ref.sizeBytes === void 0 ? 0 : mb(ref.sizeBytes)
 			} },
 			inputSize: {
 				width: 0,
 				height: 0
 			},
-			labels: []
+			labels: [],
+			...extraFiles.length > 0 ? { extraFiles } : {}
 		} };
 	}
 	const id = `llm-path-${createHash("sha1").update(ref.path).digest("hex").slice(0, 12)}`;
@@ -70250,10 +71303,6 @@ function isNonEmptyFile(filePath) {
 function siblingFilesFor(formatEntry) {
 	return formatEntry.isDirectory ? [] : formatEntry.files ?? [];
 }
-/** Resolve a sibling's remote URL relative to the main file's directory. */
-function siblingUrl(mainUrl, sibling) {
-	return mainUrl.replace(/[^/]+$/, sibling);
-}
 /** Build fetch headers, including HF auth token for huggingface.co URLs */
 function buildHeaders(url) {
 	const headers = { "User-Agent": "CamStack/1.0" };
@@ -70306,77 +71355,6 @@ async function downloadFile(url, destPath, onProgress) {
 		throw err;
 	}
 }
-/**
-* Download every file in a HuggingFace directory bundle (e.g.,
-* `.mlpackage` / OpenVINO IR pair) atomically. `knownFiles` lists the
-* relative paths inside the directory; the function fetches each from
-* `${url}/${file}` and renames the staging directory only on full
-* success. Mirrors `ModelDownloadService.downloadDirectory` but
-* exposed as a standalone for catalog-less callers.
-*/
-async function downloadDirectory(url, destDir, knownFiles, onProgress) {
-	const match = url.match(/huggingface\.co\/([^/]+\/[^/]+)\/resolve\/main\/(.+)/);
-	if (!match) throw new Error(`Cannot parse HuggingFace URL: ${url}`);
-	const [, repo, dirPath] = match;
-	const files = (knownFiles ?? []).map((f) => ({
-		relativePath: f,
-		fileUrl: `https://huggingface.co/${repo}/resolve/main/${dirPath}/${f}`
-	}));
-	if (files.length === 0) throw new Error(`Directory bundle requires explicit \`files\` list (got none for ${url})`);
-	const tmpDir = destDir + ".downloading";
-	fs.rmSync(tmpDir, {
-		recursive: true,
-		force: true
-	});
-	fs.mkdirSync(tmpDir, { recursive: true });
-	let totalDownloaded = 0;
-	try {
-		for (const file of files) {
-			const destPath = path$1.join(tmpDir, file.relativePath);
-			fs.mkdirSync(path$1.dirname(destPath), { recursive: true });
-			await downloadFile(file.fileUrl, destPath, (downloaded, _total) => {
-				onProgress?.(totalDownloaded + downloaded, void 0);
-			});
-			totalDownloaded += fs.statSync(destPath).size;
-		}
-		fs.rmSync(destDir, {
-			recursive: true,
-			force: true
-		});
-		fs.renameSync(tmpDir, destDir);
-	} catch (err) {
-		fs.rmSync(tmpDir, {
-			recursive: true,
-			force: true
-		});
-		throw err;
-	}
-}
-/**
-* Resolve a `ModelCatalogEntry` against `modelsDir`: download model file
-* (or directory bundle) + extra files (labels JSON, charset dict, …),
-* skip if already on disk. Returns the local model path.
-*/
-async function ensureModel(modelsDir, entry, format, onProgress) {
-	const formatEntry = entry.formats[format];
-	if (!formatEntry) throw new Error(`Model "${entry.id}" has no ${format} format. Available: ${Object.keys(entry.formats).join(", ")}`);
-	if (entry.extraFiles) for (const extra of entry.extraFiles) await downloadFile(extra.url, path$1.join(modelsDir, extra.filename));
-	const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${format}`;
-	const modelPath = path$1.join(modelsDir, filename);
-	const siblings = siblingFilesFor(formatEntry);
-	if (fs.existsSync(modelPath)) if (formatEntry.isDirectory && !fs.existsSync(path$1.join(modelPath, "Manifest.json"))) fs.rmSync(modelPath, {
-		recursive: true,
-		force: true
-	});
-	else if (siblings.some((f) => !isNonEmptyFile(path$1.join(modelsDir, f)))) {} else return modelPath;
-	fs.mkdirSync(modelsDir, { recursive: true });
-	if (formatEntry.isDirectory) await downloadDirectory(formatEntry.url, modelPath, formatEntry.files, onProgress);
-	else {
-		await downloadFile(formatEntry.url, modelPath, (downloaded, total) => onProgress?.(downloaded, total === 0 ? void 0 : total));
-		for (const sibling of siblings) await downloadFile(siblingUrl(formatEntry.url, sibling), path$1.join(modelsDir, sibling));
-	}
-	return modelPath;
-}
 /** Compute the on-disk path for a given model + format, even when not yet downloaded. */
 function getModelFilePath(modelsDir, entry, format) {
 	const formatEntry = entry.formats[format];
@@ -70420,13 +71398,79 @@ promisify(gzip);
 * Default `RuntimeModelOps` — the ONLY place the reused object-detection model
 * mechanism is imported (the documented `@camstack/system/addon-utils`
 * build-time-dep waiver that addon-post-analysis/addon-pipeline already use).
-* GGUFs ride `ensureModel`/`isModelDownloaded`/`deleteModelFromDisk` untouched
-* (spec §4.2) — no bespoke fetcher.
+* GGUFs ride the SHARED `downloadFile` (atomic `.downloading` + rename, HF
+* token headers, redirect following) — no bespoke fetcher (spec §4.2).
+*
+* ## Why this drives the file loop instead of calling `ensureModel`
+*
+* `ensureModel` downloads `extraFiles` FIRST and passes them NO progress
+* callback. That is invisible for a 40 kB labels JSON and unacceptable here: a
+* GGUF install is a 22 GB main file, up to N shards, and a 0.9 GB mmproj, and
+* under `ensureModel` every byte outside the main file moves in silence. A
+* multi-GB download that reports nothing reads as a hung node — the repo rule
+* is that a branch doing real work says so.
+*
+* So the loop is here, over the SAME `downloadFile`. What is gained: bytes
+* aggregated across the whole install, the name of the file currently moving,
+* and files already on disk excluded from the total rather than counted as
+* instantly-complete.
 */
 var GGUF = "gguf";
+var BYTES_PER_MB = 1024 * 1024;
+/**
+* Main file first, then shards/mmproj. Deliberate: a gated or mistyped URL
+* fails on the file that matters before 0.9 GB of projector is spent on it.
+*/
+function planFiles(modelsDir, entry) {
+	const out = [];
+	const formatEntry = entry.formats[GGUF];
+	if (formatEntry !== void 0) {
+		const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${GGUF}`;
+		out.push({
+			url: formatEntry.url,
+			destPath: path$1.join(modelsDir, filename),
+			filename,
+			expectedBytes: formatEntry.sizeMB * BYTES_PER_MB
+		});
+	}
+	for (const extra of entry.extraFiles ?? []) out.push({
+		url: extra.url,
+		destPath: path$1.join(modelsDir, extra.filename),
+		filename: extra.filename,
+		expectedBytes: extra.sizeMB * BYTES_PER_MB
+	});
+	return out;
+}
 function createDefaultModelOps(modelsDir) {
 	return {
-		ensure: (entry, onProgress) => ensureModel(modelsDir, entry, GGUF, (downloaded, total) => onProgress(total !== void 0 && total > 0 ? downloaded / total : 0)),
+		ensure: async (entry, onProgress) => {
+			if (entry.formats[GGUF] === void 0) throw new Error(`model ${entry.id} declares no gguf format`);
+			const missing = planFiles(modelsDir, entry).filter((f) => !existsSync(f.destPath));
+			const totalBytes = missing.reduce((sum, f) => sum + f.expectedBytes, 0);
+			let carried = 0;
+			for (const [index, file] of missing.entries()) {
+				onProgress({
+					file: file.filename,
+					fileIndex: index + 1,
+					fileCount: missing.length,
+					downloadedBytes: carried,
+					...totalBytes > 0 ? { totalBytes } : {}
+				});
+				await downloadFile(file.url, file.destPath, (downloaded) => {
+					onProgress({
+						file: file.filename,
+						fileIndex: index + 1,
+						fileCount: missing.length,
+						downloadedBytes: carried + downloaded,
+						...totalBytes > 0 ? { totalBytes } : {}
+					});
+				});
+				carried += existsSync(file.destPath) ? statSync(file.destPath).size : file.expectedBytes;
+			}
+			const main = getModelFilePath(modelsDir, entry, GGUF);
+			if (main === null) throw new Error(`no gguf path for model ${entry.id}`);
+			return main;
+		},
 		isDownloaded: (entry) => isModelDownloaded(modelsDir, entry, GGUF),
 		pathFor: (entry) => {
 			const p = getModelFilePath(modelsDir, entry, GGUF);
@@ -70440,6 +71484,387 @@ function createDefaultModelOps(modelsDir) {
 	};
 }
 //#endregion
+//#region src/runtime/crash-policy.ts
+var CrashPolicy = class {
+	opts;
+	crashes = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.opts = opts;
+	}
+	recordCrash(id, now = Date.now()) {
+		const cutoff = now - this.opts.windowMs;
+		const recent = (this.crashes.get(id) ?? []).filter((t) => t >= cutoff);
+		recent.push(now);
+		this.crashes.set(id, recent);
+		if (recent.length >= this.opts.maxCrashes) return {
+			action: "failed",
+			crashesInWindow: recent.length
+		};
+		const streak = recent.length;
+		return {
+			action: "respawn",
+			backoffMs: Math.min(this.opts.maxBackoffMs, 500 * 2 ** Math.min(6, streak - 1)),
+			crashesInWindow: streak
+		};
+	}
+	crashesInWindow(id, now = Date.now()) {
+		const cutoff = now - this.opts.windowMs;
+		return (this.crashes.get(id) ?? []).filter((t) => t >= cutoff).length;
+	}
+	reset(id) {
+		this.crashes.delete(id);
+	}
+};
+var DEFAULT_CRASH_POLICY = {
+	windowMs: 3e5,
+	maxCrashes: 5,
+	maxBackoffMs: 3e4
+};
+//#endregion
+//#region src/runtime/llama-supervisor.ts
+/**
+* `LlamaSupervisor` — single-child llama-server lifecycle on one node. Copies
+* the two proven in-repo patterns: the embedded-Python engine's spawn +
+* SIGTERM→deadline→SIGKILL escalation, and the CrashSupervisor breaker (bounded
+* respawn, never an infinite loop — D6). Guards the async ChildProcess 'error'
+* race the way fork-decode-worker's wrapChild does (7a95ab54): an uncaught late
+* error event must never become an uncaughtException.
+*
+* v1: at most one running child. Resource ceiling = llama-server flags +
+* idleStopMinutes ONLY (no RSS watchdog — operator decision #3).
+*/
+/**
+* Every llama-server flag a TYPED field above already owns, mapped to the
+* field that owns it.
+*
+* This map is the whole reconciliation between the typed tuning surface and
+* the free-text "additional arguments" box. Both exist because neither is
+* sufficient — the typed fields give the common knobs a validated control and
+* a default, and llama.cpp has a hundred flags nobody is going to model — but
+* a flag settable from BOTH is a bug generator: whichever one loses is a
+* control the operator watched do nothing. So the box is an escape hatch for
+* what is NOT modelled, and reaching into it for something that is gets
+* rejected by name.
+*/
+var OWNED_FLAGS = {
+	"-m": "model",
+	"--model": "model",
+	"--host": "fixed to 127.0.0.1",
+	"--port": "assigned by the supervisor",
+	"-c": "contextSize",
+	"--ctx-size": "contextSize",
+	"-ngl": "gpuLayers",
+	"--gpu-layers": "gpuLayers",
+	"--n-gpu-layers": "gpuLayers",
+	"-t": "threads",
+	"--threads": "threads",
+	"--parallel": "parallel",
+	"-np": "parallel",
+	"-b": "batchSize",
+	"--batch-size": "batchSize",
+	"-ub": "ubatchSize",
+	"--ubatch-size": "ubatchSize",
+	"-fa": "flashAttention",
+	"--flash-attn": "flashAttention",
+	"--mlock": "mlock",
+	"--no-mmap": "noMmap",
+	"-ctk": "cacheTypeK",
+	"--cache-type-k": "cacheTypeK",
+	"-ctv": "cacheTypeV",
+	"--cache-type-v": "cacheTypeV",
+	"--mmproj": "the vision model’s projector"
+};
+/**
+* Reject an `extraArgs` list that reaches for a flag a typed field owns.
+* `--flag=value` counts as `--flag`.
+*/
+function checkExtraArgs(extraArgs) {
+	for (const token of extraArgs) {
+		if (!token.startsWith("-")) continue;
+		const flag = token.split("=")[0] ?? token;
+		const owner = OWNED_FLAGS[flag];
+		if (owner !== void 0) return {
+			ok: false,
+			message: `"${flag}" is already set by the runtime field "${owner}" — set it there, not in additional arguments (a flag with two owners is a control that silently does nothing)`
+		};
+	}
+	return { ok: true };
+}
+var HEALTH_GATE_INTERVAL_MS = 500;
+function defaultPickPort() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.on("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const addr = server.address();
+			if (addr === null || typeof addr === "string") {
+				server.close();
+				reject(/* @__PURE__ */ new Error("failed to pick port"));
+				return;
+			}
+			const { port } = addr;
+			server.close(() => resolve(port));
+		});
+	});
+}
+/**
+* The argv, and it is the WHOLE tuning surface of a managed model.
+*
+* Every flag here is one the operator can set on the profile; nothing is
+* hard-coded that a real deployment needs to change. `--host 127.0.0.1` is the
+* one deliberate exception — a managed llama-server is reachable only from the
+* node that started it, and binding it wider would publish an unauthenticated
+* inference endpoint on the LAN.
+*/
+function buildLlamaArgs(cfg, port) {
+	const args = [
+		"-m",
+		cfg.modelPath,
+		"--host",
+		"127.0.0.1",
+		"--port",
+		String(port),
+		"-c",
+		String(cfg.contextSize),
+		"-ngl",
+		String(cfg.gpuLayers),
+		"--parallel",
+		String(cfg.parallel)
+	];
+	if (cfg.threads !== void 0) args.push("-t", String(cfg.threads));
+	if (cfg.batchSize !== void 0) args.push("-b", String(cfg.batchSize));
+	if (cfg.ubatchSize !== void 0) args.push("-ub", String(cfg.ubatchSize));
+	if (cfg.flashAttention === true) args.push("--flash-attn");
+	if (cfg.mlock === true) args.push("--mlock");
+	if (cfg.noMmap === true) args.push("--no-mmap");
+	if (cfg.cacheTypeK !== void 0) args.push("--cache-type-k", cfg.cacheTypeK);
+	if (cfg.cacheTypeV !== void 0) args.push("--cache-type-v", cfg.cacheTypeV);
+	if (cfg.mmprojPath !== void 0) args.push("--mmproj", cfg.mmprojPath);
+	args.push(...cfg.extraArgs ?? []);
+	return args;
+}
+var LlamaSupervisor = class {
+	deps;
+	spawnFn;
+	fetchFn;
+	now;
+	pickPort;
+	healthPollMs;
+	startTimeoutMs;
+	killGraceMs;
+	crashPolicy = new CrashPolicy(DEFAULT_CRASH_POLICY);
+	supervisorId = "llama";
+	child;
+	state = "stopped";
+	cfg;
+	_port;
+	lastError;
+	lastActivity = 0;
+	intentionalStop = false;
+	healthGateTimer;
+	startDeadlineTimer;
+	healthPollTimer;
+	idleTimer;
+	constructor(deps) {
+		this.deps = deps;
+		this.spawnFn = deps.spawnFn ?? spawn;
+		this.fetchFn = deps.fetchFn ?? fetch;
+		this.now = deps.now ?? Date.now;
+		this.pickPort = deps.pickPort ?? defaultPickPort;
+		this.healthPollMs = deps.healthPollMs ?? 15e3;
+		this.startTimeoutMs = deps.startTimeoutMs ?? 12e4;
+		this.killGraceMs = deps.killGraceMs ?? 5e3;
+	}
+	get port() {
+		return this._port;
+	}
+	status() {
+		return {
+			nodeId: this.cfg?.nodeId ?? "unknown",
+			state: this.state,
+			...this.child?.pid !== void 0 ? { pid: this.child.pid } : {},
+			...this._port !== void 0 ? { port: this._port } : {},
+			...this.cfg !== void 0 ? {
+				modelPath: this.cfg.modelPath,
+				modelId: this.cfg.modelId
+			} : {},
+			...this.lastError !== void 0 ? { lastError: this.lastError } : {},
+			crashesInWindow: this.crashPolicy.crashesInWindow(this.supervisorId, this.now())
+		};
+	}
+	noteActivity() {
+		this.lastActivity = this.now();
+	}
+	sameConfig(cfg) {
+		const c = this.cfg;
+		if (c === void 0) return false;
+		return c.modelPath === cfg.modelPath && c.mmprojPath === cfg.mmprojPath && c.contextSize === cfg.contextSize && c.gpuLayers === cfg.gpuLayers && c.threads === cfg.threads && c.parallel === cfg.parallel && c.batchSize === cfg.batchSize && c.ubatchSize === cfg.ubatchSize && c.flashAttention === cfg.flashAttention && c.mlock === cfg.mlock && c.noMmap === cfg.noMmap && c.cacheTypeK === cfg.cacheTypeK && c.cacheTypeV === cfg.cacheTypeV;
+	}
+	async start(cfg) {
+		if (this.state === "ready" && this.sameConfig(cfg)) return this.status();
+		if (this.child !== void 0) await this.stop();
+		this.cfg = cfg;
+		this.lastError = void 0;
+		this.intentionalStop = false;
+		this.crashPolicy.reset(this.supervisorId);
+		await this.spawnChild(cfg);
+		return this.status();
+	}
+	async spawnChild(cfg) {
+		const port = await this.pickPort();
+		this._port = port;
+		this.state = "starting";
+		const child = this.spawnFn(cfg.binaryPath, buildLlamaArgs(cfg, port), { stdio: "pipe" });
+		this.child = child;
+		child.on("error", (err) => {
+			this.deps.logger.warn("llama-server error event", { meta: { error: String(err) } });
+		});
+		child.stdout?.on("data", (chunk) => this.logLines(chunk, false));
+		child.stderr?.on("data", (chunk) => this.logLines(chunk, true));
+		child.on("exit", (code, signal) => this.onExit(code, signal));
+		this.beginHealthGate(port);
+	}
+	logLines(chunk, isErr) {
+		for (const line of chunk.toString().split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed.length === 0) continue;
+			if (isErr) this.deps.logger.warn(trimmed);
+			else this.deps.logger.debug(trimmed);
+		}
+	}
+	beginHealthGate(port) {
+		const deadlineAt = this.now() + this.startTimeoutMs;
+		const poll = async () => {
+			if (this.state !== "starting") return;
+			if (this.now() >= deadlineAt) {
+				this.lastError = `health gate timed out after ${this.startTimeoutMs}ms`;
+				this.deps.logger.warn(this.lastError);
+				this.intentionalStop = true;
+				this.killChild("SIGKILL");
+				this.state = "crashed";
+				return;
+			}
+			const healthy = await this.probeHealth(port);
+			if (this.state !== "starting") return;
+			if (healthy) {
+				this.onReady();
+				return;
+			}
+			this.healthGateTimer = setTimeout(() => void poll(), HEALTH_GATE_INTERVAL_MS);
+			this.healthGateTimer.unref?.();
+		};
+		poll();
+	}
+	async probeHealth(port) {
+		try {
+			return (await this.fetchFn(`http://127.0.0.1:${port}/health`)).status === 200;
+		} catch {
+			return false;
+		}
+	}
+	onReady() {
+		this.clearStartTimers();
+		this.state = "ready";
+		this.lastError = void 0;
+		this.noteActivity();
+		this.startHealthPoll();
+		this.startIdleWatch();
+	}
+	startHealthPoll() {
+		this.healthPollTimer = setInterval(() => {
+			if (this.state !== "ready" || this._port === void 0) return;
+			this.probeHealth(this._port).then((healthy) => {
+				if (!healthy && this.state === "ready") {
+					this.deps.logger.warn("llama-server health poll failed → treating as crash");
+					this.killChild("SIGKILL");
+				}
+			});
+		}, this.healthPollMs);
+		this.healthPollTimer.unref?.();
+	}
+	startIdleWatch() {
+		const cfg = this.cfg;
+		if (cfg === void 0 || cfg.idleStopMinutes <= 0) return;
+		const idleMs = cfg.idleStopMinutes * 6e4;
+		this.idleTimer = setInterval(() => {
+			if (this.state !== "ready") return;
+			if (this.now() - this.lastActivity >= idleMs) {
+				this.deps.logger.info("llama-server idle-stop");
+				this.stop();
+			}
+		}, Math.min(idleMs, 3e4));
+		this.idleTimer.unref?.();
+	}
+	onExit(code, signal) {
+		this.clearAllTimers();
+		this.child = void 0;
+		if (this.intentionalStop) {
+			this.state = "stopped";
+			return;
+		}
+		this.deps.logger.warn("llama-server exited unexpectedly", { meta: {
+			code,
+			signal
+		} });
+		const decision = this.crashPolicy.recordCrash(this.supervisorId, this.now());
+		if (decision.action === "failed") {
+			this.state = "failed";
+			this.lastError = `crash breaker tripped (${decision.crashesInWindow} crashes)`;
+			return;
+		}
+		this.state = "crashed";
+		const cfg = this.cfg;
+		if (cfg === void 0) return;
+		setTimeout(() => {
+			if (this.state !== "crashed") return;
+			this.spawnChild(cfg).catch((err) => {
+				this.lastError = err instanceof Error ? err.message : String(err);
+				this.state = "crashed";
+			});
+		}, decision.backoffMs).unref?.();
+	}
+	killChild(signal) {
+		this.child?.kill(signal);
+	}
+	async stop() {
+		this.intentionalStop = true;
+		this.clearAllTimers();
+		this.crashPolicy.reset(this.supervisorId);
+		const child = this.child;
+		if (child === void 0) {
+			this.state = "stopped";
+			return;
+		}
+		child.kill("SIGTERM");
+		await new Promise((resolve) => {
+			const grace = setTimeout(() => {
+				child.kill("SIGKILL");
+				resolve();
+			}, this.killGraceMs);
+			grace.unref?.();
+			child.once("exit", () => {
+				clearTimeout(grace);
+				resolve();
+			});
+		});
+		this.child = void 0;
+		this.state = "stopped";
+	}
+	clearStartTimers() {
+		if (this.healthGateTimer !== void 0) clearTimeout(this.healthGateTimer);
+		if (this.startDeadlineTimer !== void 0) clearTimeout(this.startDeadlineTimer);
+		this.healthGateTimer = void 0;
+		this.startDeadlineTimer = void 0;
+	}
+	clearAllTimers() {
+		this.clearStartTimers();
+		if (this.healthPollTimer !== void 0) clearInterval(this.healthPollTimer);
+		if (this.idleTimer !== void 0) clearInterval(this.idleTimer);
+		this.healthPollTimer = void 0;
+		this.idleTimer = void 0;
+	}
+};
+//#endregion
 //#region src/runtime/sha256.ts
 /**
 * File sha256 — a local copy of the private `computeSha256` at
@@ -70473,11 +71898,23 @@ function basename(url) {
 function catalogIdForFile(file) {
 	return LLM_MODEL_CATALOG.find((m) => basename(m.meta.url) === file)?.meta.id;
 }
+/**
+* The projector among the extra files — matched by NAME, not by position.
+*
+* `extraFiles[0]` was safe while the only extra a GGUF entry ever had was an
+* mmproj. A split GGUF puts shards 2..N in the same list, so index 0 is now
+* routinely a weights shard, and passing one to `--mmproj` starts llama-server
+* against a file that is not a projector.
+*/
 function mmprojFilename(entry) {
-	return entry.extraFiles?.[0]?.filename;
+	return entry.extraFiles?.find((f) => f.filename.toLowerCase().startsWith("mmproj"))?.filename;
+}
+function gb(bytes) {
+	return `${(bytes / 1e9).toFixed(2)} GB`;
 }
 function createLlmRuntimeProvider(deps) {
 	let downloadProgress;
+	let download;
 	async function resolvePaths(runtime) {
 		const resolution = entryForRef(runtime.model);
 		if (resolution === null) throw new Error("unknown model reference");
@@ -70504,6 +71941,8 @@ function createLlmRuntimeProvider(deps) {
 		return { ok: true };
 	}
 	async function ensureStartedInternal(runtime) {
+		const argCheck = checkExtraArgs(runtime.extraArgs);
+		if (!argCheck.ok) throw new Error(argCheck.message);
 		const binaryPath = await deps.ensureBinary();
 		const paths = await resolvePaths(runtime);
 		const startCfg = {
@@ -70522,16 +71961,78 @@ function createLlmRuntimeProvider(deps) {
 			noMmap: runtime.noMmap,
 			...runtime.cacheTypeK !== void 0 ? { cacheTypeK: runtime.cacheTypeK } : {},
 			...runtime.cacheTypeV !== void 0 ? { cacheTypeV: runtime.cacheTypeV } : {},
+			extraArgs: runtime.extraArgs,
 			idleStopMinutes: runtime.idleStopMinutes,
 			binaryPath
 		};
 		return deps.supervisor.start(startCfg);
 	}
+	/**
+	* sha256 every artifact whose digest the reference pinned — the main file
+	* AND the extras.
+	*
+	* Verifying only the main file was the gap: a truncated or swapped mmproj is
+	* exactly as fatal to llama-server as a bad weights file, and a resolved HF
+	* reference carries a digest for every artifact (LFS `oid`) so there is no
+	* reason to check one and trust the rest.
+	*
+	* This pass reads tens of GB and takes minutes; it is a REPORTED phase, not
+	* a silent tail, because a progress bar frozen at 100% is the shape of a
+	* hang.
+	*/
+	async function verifyDigests(entry, model, startedAt) {
+		if (model.kind !== "url") return;
+		const targets = [];
+		if (model.sha256 !== void 0) targets.push({
+			filePath: deps.modelOps.pathFor(entry),
+			sha256: model.sha256,
+			name: basename(model.url)
+		});
+		for (const extra of model.extraFiles ?? []) {
+			if (extra.sha256 === void 0) continue;
+			targets.push({
+				filePath: deps.modelOps.extraFilePath(entry, extra.filename),
+				sha256: extra.sha256,
+				name: extra.filename
+			});
+		}
+		if (targets.length === 0) return;
+		const sha256 = deps.fileSha256 ?? fileSha256;
+		for (const [index, target] of targets.entries()) {
+			download = {
+				phase: "verifying",
+				file: target.name,
+				fileIndex: index + 1,
+				fileCount: targets.length,
+				downloadedBytes: 0
+			};
+			deps.logger.info("llm model verifying digest", { meta: {
+				nodeId: deps.nodeId,
+				modelId: entry.id,
+				file: target.name
+			} });
+			const digest = await sha256(target.filePath);
+			if (digest !== target.sha256) {
+				deps.logger.error("llm model digest mismatch; discarding the download", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					file: target.name,
+					expected: target.sha256,
+					actual: digest,
+					elapsedMs: Date.now() - startedAt
+				} });
+				await deps.modelOps.delete(entry);
+				await fsp.rm(target.filePath, { force: true });
+				throw new Error(`sha256 mismatch for ${target.name}: expected ${target.sha256}, got ${digest}`);
+			}
+		}
+	}
 	function status() {
 		return {
 			...deps.supervisor.status(),
 			nodeId: deps.nodeId,
-			...downloadProgress !== void 0 ? { downloadProgress } : {}
+			...downloadProgress !== void 0 ? { downloadProgress } : {},
+			...download !== void 0 ? { download } : {}
 		};
 	}
 	return {
@@ -70599,24 +72100,91 @@ function createLlmRuntimeProvider(deps) {
 			await deps.supervisor.stop();
 		},
 		status: async () => status(),
+		/**
+		* Install a model on THIS node.
+		*
+		* Loud on purpose. This is the longest-running operation the addon has —
+		* tens of minutes for a 23 GB vision model — and until now it emitted not
+		* one log line, so an install that stalled on a gated URL or a full disk
+		* was indistinguishable from one that was simply slow. Every phase
+		* transition is a line, and every line carries the node.
+		*/
 		installModel: async ({ model }) => {
 			const resolution = entryForRef(model);
 			if (resolution === null) throw new Error("unknown model reference");
-			if (resolution.localPathOverride !== void 0) return;
+			if (resolution.localPathOverride !== void 0) {
+				deps.logger.info("llm model is pre-provisioned; nothing to download", { meta: {
+					nodeId: deps.nodeId,
+					path: resolution.localPathOverride
+				} });
+				return;
+			}
+			const { entry } = resolution;
+			const declaredBytes = model.kind === "url" ? model.sizeBytes : void 0;
+			const startedAt = Date.now();
+			deps.logger.info("llm model install started", { meta: {
+				nodeId: deps.nodeId,
+				modelId: entry.id,
+				url: entry.formats.gguf?.url,
+				extraFiles: (entry.extraFiles ?? []).map((f) => f.filename),
+				...declaredBytes !== void 0 ? {
+					declaredBytes,
+					declaredSize: gb(declaredBytes)
+				} : {}
+			} });
 			downloadProgress = 0;
+			download = {
+				phase: "downloading",
+				file: "",
+				fileIndex: 0,
+				fileCount: 0,
+				downloadedBytes: 0
+			};
+			let lastLoggedDecile = -1;
 			try {
-				await deps.modelOps.ensure(resolution.entry, (frac) => {
-					downloadProgress = frac;
-				});
-				if (model.kind === "url" && model.sha256 !== void 0) {
-					const filePath = deps.modelOps.pathFor(resolution.entry);
-					if (await (deps.fileSha256 ?? fileSha256)(filePath) !== model.sha256) {
-						await deps.modelOps.delete(resolution.entry);
-						throw new Error(`sha256 mismatch for ${model.url}`);
+				await deps.modelOps.ensure(entry, (progress) => {
+					const fraction = progress.totalBytes !== void 0 && progress.totalBytes > 0 ? Math.min(1, progress.downloadedBytes / progress.totalBytes) : void 0;
+					downloadProgress = fraction;
+					download = {
+						phase: "downloading",
+						file: progress.file,
+						fileIndex: progress.fileIndex,
+						fileCount: progress.fileCount,
+						downloadedBytes: progress.downloadedBytes,
+						...progress.totalBytes !== void 0 ? { totalBytes: progress.totalBytes } : {}
+					};
+					const decile = fraction === void 0 ? -1 : Math.floor(fraction * 10);
+					if (decile > lastLoggedDecile) {
+						lastLoggedDecile = decile;
+						deps.logger.info("llm model download progress", { meta: {
+							nodeId: deps.nodeId,
+							modelId: entry.id,
+							file: progress.file,
+							fileIndex: progress.fileIndex,
+							fileCount: progress.fileCount,
+							downloadedBytes: progress.downloadedBytes,
+							downloaded: gb(progress.downloadedBytes),
+							...progress.totalBytes !== void 0 ? { total: gb(progress.totalBytes) } : {}
+						} });
 					}
-				}
+				});
+				await verifyDigests(entry, model, startedAt);
+				deps.logger.info("llm model install complete", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					elapsedMs: Date.now() - startedAt
+				} });
+			} catch (err) {
+				deps.logger.error("llm model install failed", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					elapsedMs: Date.now() - startedAt,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				throw err;
 			} finally {
 				downloadProgress = void 0;
+				download = void 0;
 			}
 		},
 		deleteModel: async ({ file }) => {
@@ -70630,6 +72198,7 @@ function createLlmRuntimeProvider(deps) {
 				return {
 					file: f.file,
 					sizeBytes: f.sizeBytes,
+					path: path$1.join(deps.modelsDir, f.file),
 					...catalogId !== void 0 ? { catalogId } : {}
 				};
 			});
@@ -70736,6 +72305,7 @@ async function assembleAi(deps) {
 		...deps.runtimeApi !== void 0 ? { runtime: createRuntimeClient(deps.runtimeApi) } : {},
 		...deps.distributeModel !== void 0 ? { distributeModel: deps.distributeModel } : {},
 		catalog: LLM_MODEL_CATALOG.map((m) => m.meta),
+		hfToken: () => process.env["HF_TOKEN"] ?? process.env["HUGGING_FACE_HUB_TOKEN"],
 		logger: deps.logger.child("llm")
 	});
 	registrations.push({
@@ -70752,329 +72322,6 @@ async function assembleAi(deps) {
 	};
 }
 //#endregion
-//#region src/runtime/crash-policy.ts
-var CrashPolicy = class {
-	opts;
-	crashes = /* @__PURE__ */ new Map();
-	constructor(opts) {
-		this.opts = opts;
-	}
-	recordCrash(id, now = Date.now()) {
-		const cutoff = now - this.opts.windowMs;
-		const recent = (this.crashes.get(id) ?? []).filter((t) => t >= cutoff);
-		recent.push(now);
-		this.crashes.set(id, recent);
-		if (recent.length >= this.opts.maxCrashes) return {
-			action: "failed",
-			crashesInWindow: recent.length
-		};
-		const streak = recent.length;
-		return {
-			action: "respawn",
-			backoffMs: Math.min(this.opts.maxBackoffMs, 500 * 2 ** Math.min(6, streak - 1)),
-			crashesInWindow: streak
-		};
-	}
-	crashesInWindow(id, now = Date.now()) {
-		const cutoff = now - this.opts.windowMs;
-		return (this.crashes.get(id) ?? []).filter((t) => t >= cutoff).length;
-	}
-	reset(id) {
-		this.crashes.delete(id);
-	}
-};
-var DEFAULT_CRASH_POLICY = {
-	windowMs: 3e5,
-	maxCrashes: 5,
-	maxBackoffMs: 3e4
-};
-//#endregion
-//#region src/runtime/llama-supervisor.ts
-/**
-* `LlamaSupervisor` — single-child llama-server lifecycle on one node. Copies
-* the two proven in-repo patterns: the embedded-Python engine's spawn +
-* SIGTERM→deadline→SIGKILL escalation, and the CrashSupervisor breaker (bounded
-* respawn, never an infinite loop — D6). Guards the async ChildProcess 'error'
-* race the way fork-decode-worker's wrapChild does (7a95ab54): an uncaught late
-* error event must never become an uncaughtException.
-*
-* v1: at most one running child. Resource ceiling = llama-server flags +
-* idleStopMinutes ONLY (no RSS watchdog — operator decision #3).
-*/
-var HEALTH_GATE_INTERVAL_MS = 500;
-function defaultPickPort() {
-	return new Promise((resolve, reject) => {
-		const server = createServer();
-		server.on("error", reject);
-		server.listen(0, "127.0.0.1", () => {
-			const addr = server.address();
-			if (addr === null || typeof addr === "string") {
-				server.close();
-				reject(/* @__PURE__ */ new Error("failed to pick port"));
-				return;
-			}
-			const { port } = addr;
-			server.close(() => resolve(port));
-		});
-	});
-}
-/**
-* The argv, and it is the WHOLE tuning surface of a managed model.
-*
-* Every flag here is one the operator can set on the profile; nothing is
-* hard-coded that a real deployment needs to change. `--host 127.0.0.1` is the
-* one deliberate exception — a managed llama-server is reachable only from the
-* node that started it, and binding it wider would publish an unauthenticated
-* inference endpoint on the LAN.
-*/
-function buildLlamaArgs(cfg, port) {
-	const args = [
-		"-m",
-		cfg.modelPath,
-		"--host",
-		"127.0.0.1",
-		"--port",
-		String(port),
-		"-c",
-		String(cfg.contextSize),
-		"-ngl",
-		String(cfg.gpuLayers),
-		"--parallel",
-		String(cfg.parallel)
-	];
-	if (cfg.threads !== void 0) args.push("-t", String(cfg.threads));
-	if (cfg.batchSize !== void 0) args.push("-b", String(cfg.batchSize));
-	if (cfg.ubatchSize !== void 0) args.push("-ub", String(cfg.ubatchSize));
-	if (cfg.flashAttention === true) args.push("--flash-attn");
-	if (cfg.mlock === true) args.push("--mlock");
-	if (cfg.noMmap === true) args.push("--no-mmap");
-	if (cfg.cacheTypeK !== void 0) args.push("--cache-type-k", cfg.cacheTypeK);
-	if (cfg.cacheTypeV !== void 0) args.push("--cache-type-v", cfg.cacheTypeV);
-	if (cfg.mmprojPath !== void 0) args.push("--mmproj", cfg.mmprojPath);
-	return args;
-}
-var LlamaSupervisor = class {
-	deps;
-	spawnFn;
-	fetchFn;
-	now;
-	pickPort;
-	healthPollMs;
-	startTimeoutMs;
-	killGraceMs;
-	crashPolicy = new CrashPolicy(DEFAULT_CRASH_POLICY);
-	supervisorId = "llama";
-	child;
-	state = "stopped";
-	cfg;
-	_port;
-	lastError;
-	lastActivity = 0;
-	intentionalStop = false;
-	healthGateTimer;
-	startDeadlineTimer;
-	healthPollTimer;
-	idleTimer;
-	constructor(deps) {
-		this.deps = deps;
-		this.spawnFn = deps.spawnFn ?? spawn;
-		this.fetchFn = deps.fetchFn ?? fetch;
-		this.now = deps.now ?? Date.now;
-		this.pickPort = deps.pickPort ?? defaultPickPort;
-		this.healthPollMs = deps.healthPollMs ?? 15e3;
-		this.startTimeoutMs = deps.startTimeoutMs ?? 12e4;
-		this.killGraceMs = deps.killGraceMs ?? 5e3;
-	}
-	get port() {
-		return this._port;
-	}
-	status() {
-		return {
-			nodeId: this.cfg?.nodeId ?? "unknown",
-			state: this.state,
-			...this.child?.pid !== void 0 ? { pid: this.child.pid } : {},
-			...this._port !== void 0 ? { port: this._port } : {},
-			...this.cfg !== void 0 ? {
-				modelPath: this.cfg.modelPath,
-				modelId: this.cfg.modelId
-			} : {},
-			...this.lastError !== void 0 ? { lastError: this.lastError } : {},
-			crashesInWindow: this.crashPolicy.crashesInWindow(this.supervisorId, this.now())
-		};
-	}
-	noteActivity() {
-		this.lastActivity = this.now();
-	}
-	sameConfig(cfg) {
-		const c = this.cfg;
-		if (c === void 0) return false;
-		return c.modelPath === cfg.modelPath && c.mmprojPath === cfg.mmprojPath && c.contextSize === cfg.contextSize && c.gpuLayers === cfg.gpuLayers && c.threads === cfg.threads && c.parallel === cfg.parallel && c.batchSize === cfg.batchSize && c.ubatchSize === cfg.ubatchSize && c.flashAttention === cfg.flashAttention && c.mlock === cfg.mlock && c.noMmap === cfg.noMmap && c.cacheTypeK === cfg.cacheTypeK && c.cacheTypeV === cfg.cacheTypeV;
-	}
-	async start(cfg) {
-		if (this.state === "ready" && this.sameConfig(cfg)) return this.status();
-		if (this.child !== void 0) await this.stop();
-		this.cfg = cfg;
-		this.lastError = void 0;
-		this.intentionalStop = false;
-		this.crashPolicy.reset(this.supervisorId);
-		await this.spawnChild(cfg);
-		return this.status();
-	}
-	async spawnChild(cfg) {
-		const port = await this.pickPort();
-		this._port = port;
-		this.state = "starting";
-		const child = this.spawnFn(cfg.binaryPath, buildLlamaArgs(cfg, port), { stdio: "pipe" });
-		this.child = child;
-		child.on("error", (err) => {
-			this.deps.logger.warn("llama-server error event", { meta: { error: String(err) } });
-		});
-		child.stdout?.on("data", (chunk) => this.logLines(chunk, false));
-		child.stderr?.on("data", (chunk) => this.logLines(chunk, true));
-		child.on("exit", (code, signal) => this.onExit(code, signal));
-		this.beginHealthGate(port);
-	}
-	logLines(chunk, isErr) {
-		for (const line of chunk.toString().split("\n")) {
-			const trimmed = line.trim();
-			if (trimmed.length === 0) continue;
-			if (isErr) this.deps.logger.warn(trimmed);
-			else this.deps.logger.debug(trimmed);
-		}
-	}
-	beginHealthGate(port) {
-		const deadlineAt = this.now() + this.startTimeoutMs;
-		const poll = async () => {
-			if (this.state !== "starting") return;
-			if (this.now() >= deadlineAt) {
-				this.lastError = `health gate timed out after ${this.startTimeoutMs}ms`;
-				this.deps.logger.warn(this.lastError);
-				this.intentionalStop = true;
-				this.killChild("SIGKILL");
-				this.state = "crashed";
-				return;
-			}
-			const healthy = await this.probeHealth(port);
-			if (this.state !== "starting") return;
-			if (healthy) {
-				this.onReady();
-				return;
-			}
-			this.healthGateTimer = setTimeout(() => void poll(), HEALTH_GATE_INTERVAL_MS);
-			this.healthGateTimer.unref?.();
-		};
-		poll();
-	}
-	async probeHealth(port) {
-		try {
-			return (await this.fetchFn(`http://127.0.0.1:${port}/health`)).status === 200;
-		} catch {
-			return false;
-		}
-	}
-	onReady() {
-		this.clearStartTimers();
-		this.state = "ready";
-		this.lastError = void 0;
-		this.noteActivity();
-		this.startHealthPoll();
-		this.startIdleWatch();
-	}
-	startHealthPoll() {
-		this.healthPollTimer = setInterval(() => {
-			if (this.state !== "ready" || this._port === void 0) return;
-			this.probeHealth(this._port).then((healthy) => {
-				if (!healthy && this.state === "ready") {
-					this.deps.logger.warn("llama-server health poll failed → treating as crash");
-					this.killChild("SIGKILL");
-				}
-			});
-		}, this.healthPollMs);
-		this.healthPollTimer.unref?.();
-	}
-	startIdleWatch() {
-		const cfg = this.cfg;
-		if (cfg === void 0 || cfg.idleStopMinutes <= 0) return;
-		const idleMs = cfg.idleStopMinutes * 6e4;
-		this.idleTimer = setInterval(() => {
-			if (this.state !== "ready") return;
-			if (this.now() - this.lastActivity >= idleMs) {
-				this.deps.logger.info("llama-server idle-stop");
-				this.stop();
-			}
-		}, Math.min(idleMs, 3e4));
-		this.idleTimer.unref?.();
-	}
-	onExit(code, signal) {
-		this.clearAllTimers();
-		this.child = void 0;
-		if (this.intentionalStop) {
-			this.state = "stopped";
-			return;
-		}
-		this.deps.logger.warn("llama-server exited unexpectedly", { meta: {
-			code,
-			signal
-		} });
-		const decision = this.crashPolicy.recordCrash(this.supervisorId, this.now());
-		if (decision.action === "failed") {
-			this.state = "failed";
-			this.lastError = `crash breaker tripped (${decision.crashesInWindow} crashes)`;
-			return;
-		}
-		this.state = "crashed";
-		const cfg = this.cfg;
-		if (cfg === void 0) return;
-		setTimeout(() => {
-			if (this.state !== "crashed") return;
-			this.spawnChild(cfg).catch((err) => {
-				this.lastError = err instanceof Error ? err.message : String(err);
-				this.state = "crashed";
-			});
-		}, decision.backoffMs).unref?.();
-	}
-	killChild(signal) {
-		this.child?.kill(signal);
-	}
-	async stop() {
-		this.intentionalStop = true;
-		this.clearAllTimers();
-		this.crashPolicy.reset(this.supervisorId);
-		const child = this.child;
-		if (child === void 0) {
-			this.state = "stopped";
-			return;
-		}
-		child.kill("SIGTERM");
-		await new Promise((resolve) => {
-			const grace = setTimeout(() => {
-				child.kill("SIGKILL");
-				resolve();
-			}, this.killGraceMs);
-			grace.unref?.();
-			child.once("exit", () => {
-				clearTimeout(grace);
-				resolve();
-			});
-		});
-		this.child = void 0;
-		this.state = "stopped";
-	}
-	clearStartTimers() {
-		if (this.healthGateTimer !== void 0) clearTimeout(this.healthGateTimer);
-		if (this.startDeadlineTimer !== void 0) clearTimeout(this.startDeadlineTimer);
-		this.healthGateTimer = void 0;
-		this.startDeadlineTimer = void 0;
-	}
-	clearAllTimers() {
-		this.clearStartTimers();
-		if (this.healthPollTimer !== void 0) clearInterval(this.healthPollTimer);
-		if (this.idleTimer !== void 0) clearInterval(this.idleTimer);
-		this.healthPollTimer = void 0;
-		this.idleTimer = void 0;
-	}
-};
-//#endregion
 //#region src/settings-store-port.ts
 function createApiSettingsStorePort(api) {
 	return {
@@ -71582,10 +72829,27 @@ async function runTestChatStream(deps, request, emit, signal) {
 		kind: "status",
 		phase: "connecting"
 	});
+	let modelWaitStartedAt = null;
 	const opened = await deps.openStream(streamRequest, {
 		signal,
-		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS
+		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS,
+		firstTokenTimeoutMs: request.firstTokenTimeoutMs,
+		onConnected: () => {
+			modelWaitStartedAt = deps.now();
+			emit({
+				kind: "status",
+				phase: "first-token-wait"
+			});
+		}
 	});
+	/**
+	* What is LEFT of the first-token budget.
+	*
+	* The response headers and the first token are one wait spent two ways, so
+	* they draw on one budget: the page says "up to Ns" and that has to be the
+	* whole truth, not N per stage.
+	*/
+	const remainingFirstTokenMs = () => modelWaitStartedAt === null ? request.firstTokenTimeoutMs : Math.max(1, request.firstTokenTimeoutMs - (deps.now() - modelWaitStartedAt));
 	if (opened.kind === "connect-timeout") {
 		await fail({
 			code: "unavailable",
@@ -71606,6 +72870,20 @@ async function runTestChatStream(deps, request, emit, signal) {
 		});
 		return;
 	}
+	if (opened.kind === "provider-error") {
+		await fail({
+			code: opened.code,
+			message: opened.message
+		}, "ai test chat: provider refused the request — turn dropped", {
+			code: opened.code,
+			error: opened.message
+		});
+		return;
+	}
+	if (opened.kind === "first-token-timeout") {
+		await failFirstToken();
+		return;
+	}
 	const streamed = opened.kind === "open";
 	emit({
 		kind: "meta",
@@ -71631,7 +72909,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			kind: "status",
 			phase: "first-token-wait"
 		});
-		const raced = await withDeadline(deps.generateOnce(streamRequest), request.firstTokenTimeoutMs);
+		const raced = await withDeadline(deps.generateOnce(streamRequest), remainingFirstTokenMs());
 		if (signal.aborted) {
 			deps.logger.info("ai test chat: client aborted mid-generation", withTags({}));
 			return;
@@ -71689,7 +72967,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			deps.logger.info("ai test chat: client aborted mid-stream — provider call torn down", { ...withTags({ sawFirstToken }) });
 			return;
 		}
-		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : request.firstTokenTimeoutMs);
+		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : remainingFirstTokenMs());
 		if (next.kind === "timeout") {
 			if (!sawFirstToken) {
 				await failFirstToken();
@@ -71861,7 +73139,7 @@ var AiAddon = class extends BaseAddon {
 		const settingsPort = api !== void 0 ? createApiSettingsStorePort(api) : createMemorySettingsStorePort();
 		if (api === void 0) logger.warn("addon-ai: no ctx.api — profiles are in-memory only");
 		const binDir = path$1.join(ctx.nodeDataDir, "bin");
-		const { ensureLlamaServer } = await import("./ensure-llama-server-v65evjK2.mjs").then((n) => n.r);
+		const { ensureLlamaServer } = await import("./ensure-llama-server-COC6iveo.mjs").then((n) => n.r);
 		const assembly = await assembleAi({
 			nodeId: ownNodeId,
 			isHub,
@@ -71949,7 +73227,11 @@ var AiAddon = class extends BaseAddon {
 				...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {},
 				...request.temperature !== void 0 ? { temperature: request.temperature } : {},
 				signal: opts.signal
-			}, { connectTimeoutMs: opts.connectTimeoutMs }),
+			}, {
+				connectTimeoutMs: opts.connectTimeoutMs,
+				firstTokenTimeoutMs: opts.firstTokenTimeoutMs,
+				onConnected: opts.onConnected
+			}),
 			generateOnce: async (request) => {
 				const base = {
 					profileId: request.profile.id,
@@ -72018,4 +73300,4 @@ var AiAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { resolveRetryPolicy as A, AiAddon, AiAddon as default, __commonJSMin as B, createDefaultModelOps as C, AI_ADDON_ID as D, entryForRef as E, LlmProfileKindSchema as F, boolean as I, number$1 as L, require_token_util as M, require_token_error as N, createLlmProvider as O, LlmErrorCodeSchema as P, object as R, fileSha256 as S, catalogById as T, __exportAll as V, createApiSettingsStorePort as _, renderTranscript as a, createRuntimeClient as b, TEST_CHAT_CONSUMER as c, TEST_CHAT_MAX_FIRST_TOKEN_TIMEOUT_MS as d, TEST_CHAT_MIN_VISION_INPUT_TOKENS as f, encodeEvent as g, TestChatRequestSchema as h, pickTrackMedia as i, createLlmClient as j, CONSUMER_RETRY_POLICY as k, TEST_CHAT_DEFAULT_FIRST_TOKEN_TIMEOUT_MS as l, TestChatEventSchema as m, runTestChatStream as n, resolveImage as o, TEST_CHAT_PREFIX as p, TRACK_MEDIA_PREFERENCE as r, TEST_CHAT_CONNECT_TIMEOUT_MS as s, createTestChatPlaneHandler as t, TEST_CHAT_IDLE_TIMEOUT_MS as u, createMemorySettingsStorePort as v, LLM_MODEL_CATALOG as w, createLlmRuntimeProvider as x, LlamaSupervisor as y, string as z };
+export { resolveRetryPolicy as A, AiAddon, AiAddon as default, __commonJSMin as B, createDefaultModelOps as C, AI_ADDON_ID as D, entryForRef as E, LlmProfileKindSchema as F, boolean as I, number$1 as L, require_token_util as M, require_token_error as N, createLlmProvider as O, LlmErrorCodeSchema as P, object as R, LlamaSupervisor as S, catalogById as T, __exportAll as V, createApiSettingsStorePort as _, renderTranscript as a, createLlmRuntimeProvider as b, TEST_CHAT_CONSUMER as c, TEST_CHAT_MAX_FIRST_TOKEN_TIMEOUT_MS as d, TEST_CHAT_MIN_VISION_INPUT_TOKENS as f, encodeEvent as g, TestChatRequestSchema as h, pickTrackMedia as i, createLlmClient as j, CONSUMER_RETRY_POLICY as k, TEST_CHAT_DEFAULT_FIRST_TOKEN_TIMEOUT_MS as l, TestChatEventSchema as m, runTestChatStream as n, resolveImage as o, TEST_CHAT_PREFIX as p, TRACK_MEDIA_PREFERENCE as r, TEST_CHAT_CONNECT_TIMEOUT_MS as s, createTestChatPlaneHandler as t, TEST_CHAT_IDLE_TIMEOUT_MS as u, createMemorySettingsStorePort as v, LLM_MODEL_CATALOG as w, fileSha256 as x, createRuntimeClient as y, string as z };