Router that virtually distributes inference across connected devices in the home.
Go
Editable engine arguments, and browser access follows the engine's CORS policy
Noah (Terve) Tervalon0df32b0d8610
diff --git a/README.md b/README.mdindex 47c1bbe..2ccba4d 100644--- a/README.md+++ b/README.md@@ -221,22 +221,25 @@ Each entry assumes the ones before it.most users need.3. **[Managing engines](docs/engine-lifecycle.mdx)** — install, start, stop,update, and uninstall engines; what PAIR restores after you quit or relaunch.-4. **[Terminal interface](docs/terminal-interface.mdx)** — the same tasks from a+4. **[Engine settings](docs/engine-settings.mdx)** — change an engine's ports and+ its launch command, on this machine or a paired one, and give a browser access+ to your models.+5. **[Terminal interface](docs/terminal-interface.mdx)** — the same tasks from aterminal, for a machine with no desktop environment. Skip it if every machineyou run has a desktop.-5. **[Troubleshooting](docs/troubleshooting.mdx)** — worth skimming once before+6. **[Troubleshooting](docs/troubleshooting.mdx)** — worth skimming once beforeyou need it, so you know where the diagnostics live. Alongside it,**[Known issues](docs/known-issues.mdx)** lists the significant limitations weare already aware of, and**[Collecting and sanitizing logs](docs/log-collection.mdx)** covers preparinga log you can share.-6. **[Architecture](docs/architecture.mdx)** — the process model, how a request is+7. **[Architecture](docs/architecture.mdx)** — the process model, how a request isrouted, and where the trust boundaries are. Read this before changinganything, or if you want to know why PAIR behaves the way it does.-7. **[Building and running](docs/building.mdx)** — prerequisites, building from+8. **[Building and running](docs/building.mdx)** — prerequisites, building fromsource, running the services without the desktop application, and writingyour own client against the JSON-RPC API.-8. **[Developer guide](docs/developing.mdx)** — read this before contributing:+9. **[Developer guide](docs/developing.mdx)** — read this before contributing:where the code lives, how a change travels through the layers, and theconventions the project enforces.diff --git a/desktop/docs/architecture.md b/desktop/docs/architecture.mdindex 32e1aa2..0874b5f 100644--- a/desktop/docs/architecture.md+++ b/desktop/docs/architecture.md@@ -144,12 +144,16 @@ Personal AI Router uses commands down and events up:Renderer stores fetch domain snapshots at startup and then subscribe to pushevents. Engine lifecycle and model commands do not return replacement state.The centralized pending-actions store is the only optimistic renderer state for-engine operations.+engine operations, and it covers applying engine settings as well: that call+waits for the owning node's stop, rebind, restart, and readiness checks before+returning an operation receipt. Settings snapshots supply the authoritative state+and progress while the call is in flight.Important push domains include:- `nodes:upsert` / `nodes:remove`;- `engines:state-changed`;+- `engines:settings-changed` / `engines:settings-disconnected`;- `engines:progress-changed` / `engines:progress-cleared`;- `metrics:update`;- `workloads:upsert` / `workloads:remove`;@@ -193,6 +197,35 @@ repository [`SECURITY.md`](../../SECURITY.md).Engine lifecycle and model operations flow through the broker's `engine:*`relay to `nvpair-engine-manager`. The renderer identifies engines with theclosed `EngineType` union and narrows external strings with `isEngineType()`.+`engineManagerName()` / `engineTypeFromManagerName()` are the one place that+translation to and from the engine manager's own spelling lives.++### Engine settings++Server port, proxy port, and the engine arguments are one authoritative+record owned by the node running the engine. The broker exposes it as+`engines:get-settings`, `engines:preview-settings`, and+`engines:apply-settings`; a request naming another node is relayed to that+peer's engine manager, so a clustered device is edited exactly like the local+one.++Preview validates without persisting or touching a process. Apply journals the+accepted revision, then stops, rebinds the proxy, and restarts as needed; its+response is only an acknowledgement, and the outcome arrives as an+`engines:settings-changed` snapshot. A revision mismatch is rejected rather than+merged, and an operation interrupted by a crash is recovered from the journal at+startup. The deadline ladder for all of this is declared once in+`nvpair-ui-broker/enginesettings.go`, each rung with headroom over the layer it+waits on.++Launch arguments and environment values pass through literally, without a+per-engine option catalog. Semantic validation is limited to managed networking+and CORS. The owning node rejects managed CORS origin changes relayed from a peer;+ordinary environment assignments can be edited locally or by a pinned peer.++`engine:set-port` remains a separate port-only RPC for the TUI. It runs the same+authoritative settings operation rather than forwarding to the engine manager,+so both entry points validate, restart, and persist identically.The Ollama and LM Studio proxies are cluster-aware. For model-bearing inference,each proxy first keeps only nodes whose per-engine discovery inventory advertises@@ -269,6 +302,16 @@ cannot yet be reported are centralized in- Node telemetry is read from `/v1/node-info` at each discovered node'sadvertised port.+Browser access is decided by the engines, not by the proxies. A proxy passes+through the upstream engine's CORS headers and its refusals, and adds no+permissive default, so a web page reaches a model through PAIR only where the+engine would have allowed it directly. A request that fans out across the+cluster needs every engine that responded to allow the origin; an engine that+denied it fails the request rather than returning a partial model list, while an+engine that was unreachable is excluded instead of failing it. Preflights carry+a short non-zero `Access-Control-Max-Age` so a browser is not re-fanning out on+every request.+Inference prompts, messages, chunks, and response bodies must not be logged.## Builddiff --git a/desktop/docs/frontend-api.md b/desktop/docs/frontend-api.mdindex 4d8c66b..63037d0 100644--- a/desktop/docs/frontend-api.md+++ b/desktop/docs/frontend-api.md@@ -78,11 +78,31 @@ They do not imply a WebSocket connection. Browser clients are not supported.- `getInitialState()` returns engine statuses, models, active progress, and availableupdates.- `toggle`, `install`, `uninstall`, and `update` manage engine lifecycle.-- `setPorts` applies engine and proxy port changes.- `pullModel`, `loadModel`, `unloadModel`, `deleteModel`, and`setModelExpiry` manage models.- `searchHub(engineType)` returns the curated model catalog for an engine.- `onStateChanged`, `onProgress`, and `onProgressRemove` expose backend truth.+- `getSettings(target)` reads the owning node's authoritative settings snapshot+ (server port, proxy port, engine arguments) for one engine.+- `previewSettings(request)` validates a draft against the owner without+ persisting or touching a process, returning normalized settings, per-field+ errors, any port conflict, and whether applying restarts or rebinds.+- `applySettings(request)` commits a draft and waits for the owner's stop,+ rebind, and restart/readiness operation before returning its receipt. This+ can take minutes (Ollama permits ten minutes for readiness; the desktop call+ allows fourteen minutes). The receipt identifies the accepted operation;+ use `onSettingsChanged` for its authoritative applied or failed state. Once+ durably accepted, the owner continues even if the caller disconnects or+ loses the response; reload the snapshot before retrying.+- `onSettingsChanged(callback)` reports a settings snapshot for any node — the+ only source of applied settings state.+- `onSettingsDisconnected(callback)` reports that a node's settings authority+ became unreachable, so its cached snapshot is stale.++Port and launch changes work on a clustered peer as well as the local device,+with one exception: **managed CORS origin settings** are local-only. The owning+node rejects a change to browser access policy relayed from a peer. Other+environment assignments pass through without an engine-option catalog.`EngineCommandPayload.command` supports:@@ -91,7 +111,6 @@ They do not imply a WebSocket connection. Browser clients are not supported.- `installAll`;- `uninstall`;- `update`;-- `setPorts`;- `pullModel`;- `loadModel`;- `unloadModel`;@@ -133,6 +152,9 @@ Commands return no state. Renderer stores update from| `cluster:cancel-invite` | `{ inviteId }` | `Invite` || `cluster:abandon-if-solo` | `void` | `null` || `engines:get-initial` | `void` | `EngineInitialState` |+| `engines:get-settings` | `EngineSettingsTarget` | `EngineSettingsSnapshot` |+| `engines:preview-settings` | `EngineSettingsRequest` | `EngineSettingsPreview` |+| `engines:apply-settings` | `EngineSettingsRequest` | `EngineSettingsReceipt` || `engine:command` | `EngineCommandPayload` | `null` || `engine:search-hub` | `{ engineType }` | `EngineHubSearchResponse` || `errors:get-initial` | `void` | `ServiceError[]` |@@ -147,6 +169,8 @@ Commands return no state. Renderer stores update from| `nodes:remove` | node ID || `nodes:changed` | `ClusterNode[]` || `engines:state-changed` | `EngineStatePatch` |+| `engines:settings-changed` | `EngineSettingsSnapshot` |+| `engines:settings-disconnected` | `{ nodeId }` || `engines:progress-changed` | `EngineProgress` || `engines:progress-cleared` | `{ key }` || `metrics:update` | `NodeItemMetrics` |diff --git a/desktop/docs/service-contract-exceptions.json b/desktop/docs/service-contract-exceptions.jsonindex b5e638b..90ae4ee 100644--- a/desktop/docs/service-contract-exceptions.json+++ b/desktop/docs/service-contract-exceptions.json@@ -1,7 +1,11 @@{"$comment": "Intentionally unintegrated JSON-RPC methods for desktop ↔ services contract checks. Each ignoredMethods entry needs a current technical reason. Edit by hand; run npm run service-contracts:write to refresh docs/services-api.md after services/ changes.","ignoredMethods": {- "schedule:priority": "Broker-internal. nvpair-job-scheduler emits a per-engine priority snapshot ({engine, nodes, ranks?} — ordered node ids plus each node's pending count) to nvpair-ui-broker, which forwards it to each nvpair-proxy instance via node/set-priority; each proxy then layers its own optimistic burst reservations on that baseline. PAIR consumes the routing result rather than this notification, and must not mirror the pending/reservation accounting.",+ "engine:settings-projection": "Broker-to-engine-manager full settings projection for the pinned peer subscription hub. Consumed by Manager.handleSettingsMessage; the desktop consumes engine:settings-changed instead.",+ "engine:settings-reply": "Correlated broker-to-engine-manager reply to the pinned peer settings relay and the configure operation's narrow proxy rebind callback. Consumed by settingsRelay.reply, never a renderer event.",+ "engine:settings-request": "Engine-manager-to-broker correlated request for settings get/preview/apply or a validated operation's proxy rebind. Consumed by Broker.handleSettingsRelay.",+ "engine:settings-cancel": "Engine-manager-to-broker cancellation for a disconnected or revoked peer request. Consumed by Broker.forwardEngineNotification; accepted operations complete under the target's independent deadline.",+ "schedule:priority": "Broker-internal. nvpair-job-scheduler emits a per-engine priority snapshot ({engine, nodes, ranks?} — ordered node ids plus each node's pending count) to nvpair-ui-broker, which forwards it to nvpair-proxy via node/set-priority; the process then layers its shared optimistic burst reservations on that baseline. PAIR consumes the routing result rather than this notification, and must not mirror the pending/reservation accounting.","engine:restore-enabled": "Broker-internal startup restoration. nvpair-ui-broker emits engine:restore-enabled directly to its supervised engine-manager after the managed Ollama port gate and on manager respawn; it is not a renderer/UI notification.","ollama-proxy:ready": "Consumed, not missing: the broker relays it and normalizeBrokerProxy (modular-supervisor.ts) strips the `ollama-proxy:` prefix, so the bridge handles the de-prefixed `ready` (sets proxyPort). The literal `ollama-proxy:ready` is intentionally absent from our TS — extractor limitation, not a gap.","lmstudio-proxy:ready": "Consumed, not missing: the LM Studio counterpart of ollama-proxy:ready, de-prefixed by the same normalizeBrokerProxy loop. It only became visible to the checker when METHOD_RE started accepting hyphens in a namespace segment; before that the whole lmstudio-proxy:* surface was silently unmatched.",diff --git a/desktop/docs/services-api.md b/desktop/docs/services-api.mdindex e7fea69..3d6b66a 100644--- a/desktop/docs/services-api.md+++ b/desktop/docs/services-api.md@@ -16,10 +16,18 @@- none ✅### Requests the backend handles but the bridge never calls (unused capability)+- ⚠️ nvpair-engine-manager → engine:configure-launch+- ⚠️ nvpair-engine-manager → engine:configured-ports- ⚠️ nvpair-engine-manager → engine:describe- ⚠️ nvpair-engine-manager → engine:errors+- ⚠️ nvpair-engine-manager → engine:get-launch- ⚠️ nvpair-engine-manager → engine:logs+- ⚠️ nvpair-engine-manager → engine:preview-launch+- ⚠️ nvpair-engine-manager → engine:remote-apply-settings+- ⚠️ nvpair-engine-manager → engine:remote-get-settings+- ⚠️ nvpair-engine-manager → engine:remote-preview-settings- ⚠️ nvpair-engine-manager → engine:restart+- ⚠️ nvpair-engine-manager → engine:set-port- ⚠️ nvpair-engine-manager → internal:set-reserved-port- ⚠️ nvpair-job-scheduler → scheduler:get-interval- ⚠️ nvpair-job-scheduler → scheduler:get-status@@ -34,6 +42,8 @@- ⚠️ nvpair-proxy → node/selected- ⚠️ nvpair-proxy → node/set-local-backend- ⚠️ nvpair-ui-broker → discovery:unsubscribe+- ⚠️ nvpair-ui-broker → engine:configure-launch+- ⚠️ nvpair-ui-broker → engine:set-port- ⚠️ nvpair-ui-broker → engine:set-reserved-port- ⚠️ nvpair-ui-broker → engine:unsubscribe- ⚠️ nvpair-ui-broker → internal:set-reserved-port@@ -41,6 +51,7 @@- ⚠️ nvpair-ui-broker → lmstudio-proxy:set-port- ⚠️ nvpair-ui-broker → lmstudio-proxy:unsubscribe- ⚠️ nvpair-ui-broker → ollama-proxy:get-status+- ⚠️ nvpair-ui-broker → ollama-proxy:set-port- ⚠️ nvpair-ui-broker → ollama-proxy:unsubscribe- ⚠️ nvpair-ui-broker → workloads:unsubscribe@@ -80,27 +91,36 @@| `engine:pull-progress` | notification (we consume) | ✅ yes || `engine:ready` | notification (we consume) | ✅ yes || `engine:remote-progress` | notification (we consume) | ✅ yes |+| `engine:settings-changed` | notification (we consume) | ✅ yes |+| `engine:settings-disconnected` | notification (we consume) | ✅ yes || `engine:state-changed` | notification (we consume) | ✅ yes || `errors:clear` | notification (we consume) | ✅ yes || `errors:report` | notification (we consume) | ✅ yes || `engine:action` | request (we call) | ✅ yes |+| `engine:configure-launch` | request (we call) | ⚠️ not called |+| `engine:configured-ports` | request (we call) | ⚠️ not called || `engine:describe` | request (we call) | ⚠️ not called || `engine:errors` | request (we call) | ⚠️ not called || `engine:get-installed` | request (we call) | ✅ yes |+| `engine:get-launch` | request (we call) | ⚠️ not called || `engine:install` | request (we call) | ✅ yes || `engine:logs` | request (we call) | ⚠️ not called || `engine:models` | request (we call) | ✅ yes || `engine:prepare-shutdown` | request (we call) | ✅ yes |+| `engine:preview-launch` | request (we call) | ⚠️ not called |+| `engine:remote-apply-settings` | request (we call) | ⚠️ not called || `engine:remote-delete-model` | request (we call) | ✅ yes || `engine:remote-get-installed` | request (we call) | ✅ yes |+| `engine:remote-get-settings` | request (we call) | ⚠️ not called || `engine:remote-install` | request (we call) | ✅ yes || `engine:remote-load-model` | request (we call) | ✅ yes |+| `engine:remote-preview-settings` | request (we call) | ⚠️ not called || `engine:remote-pull-model` | request (we call) | ✅ yes || `engine:remote-start` | request (we call) | ✅ yes || `engine:remote-stop` | request (we call) | ✅ yes || `engine:remote-unload-model` | request (we call) | ✅ yes || `engine:restart` | request (we call) | ⚠️ not called |-| `engine:set-port` | request (we call) | ✅ yes |+| `engine:set-port` | request (we call) | ⚠️ not called || `engine:start` | request (we call) | ✅ yes || `engine:status` | request (we call) | ✅ yes || `engine:stop` | request (we call) | ✅ yes |@@ -227,19 +247,26 @@| `app:ready` | notification (we consume) | ✅ yes || `discovery:nodes-changed` | notification (we consume) | ✅ yes || `engine:restore-enabled` | notification (we consume) | ➖ ignored |+| `engine:settings-changed` | notification (we consume) | ✅ yes |+| `engine:settings-projection` | notification (we consume) | ➖ ignored |+| `engine:settings-reply` | notification (we consume) | ➖ ignored || `errors:clear` | notification (we consume) | ✅ yes || `errors:report` | notification (we consume) | ✅ yes || `errors:update` | notification (we consume) | ✅ yes || `lmstudio-proxy:ready` | notification (we consume) | ➖ ignored |-| `ollama-proxy:ready` | notification (we consume) | ✅ yes |+| `ollama-proxy:ready` | notification (we consume) | ➖ ignored || `workloads:upsert` | notification (we consume) | ✅ yes || `connection/cluster-auto-sync` | request (we call) | ➖ ignored || `connection/cluster-identity` | request (we call) | ✅ yes || `discovery:get-nodes` | request (we call) | ✅ yes || `discovery:subscribe` | request (we call) | ✅ yes || `discovery:unsubscribe` | request (we call) | ⚠️ not called |+| `engine:apply-settings` | request (we call) | ✅ yes |+| `engine:configure-launch` | request (we call) | ⚠️ not called |+| `engine:get-settings` | request (we call) | ✅ yes || `engine:install` | request (we call) | ✅ yes |-| `engine:set-port` | request (we call) | ✅ yes |+| `engine:preview-settings` | request (we call) | ✅ yes |+| `engine:set-port` | request (we call) | ⚠️ not called || `engine:set-reserved-port` | request (we call) | ⚠️ not called || `engine:start` | request (we call) | ✅ yes || `engine:subscribe` | request (we call) | ✅ yes |@@ -257,7 +284,7 @@| `node/updated` | request (we call) | ✅ yes || `nodes/list` | request (we call) | ✅ yes || `ollama-proxy:get-status` | request (we call) | ⚠️ not called |-| `ollama-proxy:set-port` | request (we call) | ✅ yes |+| `ollama-proxy:set-port` | request (we call) | ⚠️ not called || `ollama-proxy:subscribe` | request (we call) | ✅ yes || `ollama-proxy:unsubscribe` | request (we call) | ⚠️ not called || `ready` | request (we call) | ✅ yes |diff --git a/desktop/docs/services-backend.md b/desktop/docs/services-backend.mdindex fe7ca6c..23b8253 100644--- a/desktop/docs/services-backend.md+++ b/desktop/docs/services-backend.md@@ -119,6 +119,7 @@ reserved for inference clients.| `ollama-proxy:ready` / `lmstudio-proxy:ready` | Record engine proxy port | `engines:state-changed` || proxy `node/*` | Update per-engine node presence; the advertised port is the peer's promoted proxy port (not the engine's private loopback port) | node and engine pushes || `engine:ready` / `engine:state-changed` | Update engine facts and models | `engines:state-changed` |+| `engine:settings-changed` | Validate and republish the owning node's settings snapshot | `engines:settings-changed` || `engine:install-progress` / `engine:remote-progress` | Update operation progress | engine progress pushes || `errors:update` | Replace the error snapshot | `errors:update` || `cluster:invite-received` | Parse inbound invite | `cluster:invite-received` |@@ -152,6 +153,31 @@ Local engine operations include install, start, stop, uninstall, update, portchanges, and model actions. Remote cluster operations use the engine manager'sremote control surface where supported.+### Engine settings++Ports and the engine arguments are one authoritative, revisioned record owned by+the node running the engine. The broker exposes `engine:{get,preview,apply}-settings`+and relays a request naming another node to that peer's engine manager, so a+clustered device is edited like the local one. Preview validates without+persisting or starting anything; apply journals the accepted revision, then+stops, rebinds the proxy, and restarts as needed, and returns only an+acknowledgement — the outcome arrives as an `engine:settings-changed`+notification, which Personal AI Router republishes as `engines:settings-changed`.+A revision mismatch is rejected rather than merged, and an operation interrupted+by a crash is recovered from the journal at the next startup.++`engine:configure-launch` is refused at the broker's client surface with+`-32601`: reaching the engine manager directly would skip the journal, the port+reservation, and the proxy rebind that apply owns. `engine:set-port` is the+port-only entry point the TUI uses; the broker intercepts it and runs the same+authoritative operation rather than forwarding it, so both callers validate,+restart, and persist identically.++Launch arguments and environment values pass through literally without an+engine-option catalog. Only managed networking and CORS are semantically+validated. Managed CORS origin-list and boolean-control changes must originate on the owning node; other+environment assignments can also be changed by a pinned peer.+`engine:stop` (and its cluster `ec` equivalent) reclaims an orphan a prior runleft on the engine's own managed port, terminating it only when that PID isrunning the binary NVPAIR manages. A genuinely foreign listener on a differentdiff --git a/desktop/docs/services-parity.md b/desktop/docs/services-parity.mdindex 6e50054..c0b8cbc 100644--- a/desktop/docs/services-parity.md+++ b/desktop/docs/services-parity.md@@ -32,7 +32,7 @@ history.| Workloads | Complete after subscription | Local and peer workload events feed one Electron catalog || Cluster pairing | Complete | PIN pairing, identity, membership, leave, and removal || Cluster transport security | Backend-owned | Node-to-node transport security, including the proxies' cluster-mTLS inference ingress, is entirely backend; Personal AI Router implements none |-| Settings | Partial | Cluster identity settings are used; inert settings are not surfaced |+| Settings | Partial | Cluster identity plus per-engine ports and engine arguments, local and remote; inert backend settings are not surfaced || Model catalog search | Electron-owned | Curated Ollama and LM Studio catalogs are fetched in Electron main |## Supervision@@ -188,8 +188,16 @@ terminal backend notifications. It never treats optimistic state asauthoritative.Remote cluster support includes status, install, start, stop, model pull, and-remote model load, unload (eject), and delete via the `ec` surface. Uninstall,-update, and port changes remain local-only.+remote model load, unload (eject), and delete via the `ec` surface. Uninstall+and update remain local-only.++Server port, proxy port, and engine arguments are one authoritative record owned+by the node running the engine, read and written through the broker's+`engines:{get,preview,apply}-settings` channels. A request naming another node+is relayed to that peer, so a clustered device is edited like the local one. The+one exception is managed CORS origin settings: the owning node rejects a change to+browser access policy relayed from a peer. Other environment assignments pass+through literally, with no maintained catalog of engine options or variables.## Models@@ -413,6 +421,13 @@ PIN, so UI copy must not present the PIN as a strong authenticator.Personal AI Router uses node settings for persisted cluster identity and friendly namesynchronization.+Per-engine settings are separate and owned by `nvpair-engine-manager`: the+server port, the proxy port, and the engine arguments, persisted as a manifest+override that survives a restart. The broker owns the combined operation —+journal, validation, stop, proxy rebind, restart, and crash recovery — so both+the full editor and the port-only `engine:set-port` RPC used by the TUI go+through the same path.+Backend settings with no active behavior are intentionally not exposed in theUI. A setting should be surfaced only when a backend component consumes it andits effect is observable.diff --git a/desktop/src/electron/redact-log.ts b/desktop/src/electron/redact-log.tsindex 84c7b70..2cb7c64 100644--- a/desktop/src/electron/redact-log.ts+++ b/desktop/src/electron/redact-log.ts@@ -2,35 +2,47 @@// SPDX-License-Identifier: Apache-2.0/**- * Strips pairing secrets out of subprocess output before it reaches any log- * sink.+ * Strips pairing secrets and engine launch text out of subprocess output+ * before it reaches any log sink.** `nvpair-cluster-manager` returns the six-digit pairing PIN in its* `cluster:invite-node` result and carries it on the `Invite` payload of- * `cluster:invite-received` / `cluster:invite-expired`. Those frames travel the- * broker's stdout, which the supervisor mirrors into the in-memory service log,- * the on-disk `nvpair.jsonl`, and the user-shareable debug-log export. The PIN- * must not survive into any of them.+ * `cluster:invite-received` / `cluster:invite-expired`. Engine settings carry+ * the user's launch command and environment on `launchText`, `launch_args`,+ * and `launch_env` — a hand-written command line that can name private paths+ * or credentials. Those frames travel the broker's stdout, which the+ * supervisor mirrors into the in-memory service log, the on-disk+ * `nvpair.jsonl`, and the user-shareable debug-log export. None of them may+ * survive into any of those.+ *+ * The key names are deliberately specific. A worker-spawn diagnostic logs its+ * own `bin` and `args`, which are PAIR's binaries and flags and are exactly+ * what a support log is for, so this must not match a generic `args` or `env`.*/const REDACTED = '[redacted]'/** JSON keys whose values never belong in a log sink. */-const SENSITIVE_KEYS = new Set(['pin'])+const SENSITIVE_KEYS = new Set(['pin', 'launchText', 'launch_args', 'launch_env'])++/** Quoted key forms, so a line with none of them is returned untouched. */+const SENSITIVE_KEY_HINTS = [...SENSITIVE_KEYS].map(key => `"${key}"`)/**- * Linear-time (no nested quantifier) fallback for output that is not valid- * JSON, so a malformed frame cannot smuggle a PIN past the parsed path.+ * In malformed JSON, the end of a value cannot be trusted: quotes may be+ * escaped, arrays may be nested, and any value may be truncated. Preserve only+ * the diagnostic prefix before the first sensitive field and redact its entire+ * tail. Matching the key alone also keeps this fallback linear-time.*/-const QUOTED_SENSITIVE_VALUE = /"pin"(\s*):(\s*)"[^"]*"/g+const QUOTED_SENSITIVE_KEY = new RegExp(`"(${[...SENSITIVE_KEYS].join('|')})"\\s*:`)function redactValue(value: unknown): unknown {if (Array.isArray(value)) return value.map(redactValue)if (value !== null && typeof value === 'object') {const out: Record<string, unknown> = {}for (const [key, inner] of Object.entries(value)) {- // A null value means "no PIN on this payload"; keep that visible- // rather than implying a secret was present.+ // A null value means the payload carried nothing here; keep that+ // visible rather than implying a secret was present.out[key] = SENSITIVE_KEYS.has(key) && inner !== null ? REDACTED : redactValue(inner)}return out@@ -39,12 +51,13 @@ function redactValue(value: unknown): unknown {}export function redactSensitiveLogText(text: string): string {- if (!text.includes('"pin"')) return text+ if (!SENSITIVE_KEY_HINTS.some(hint => text.includes(hint))) return texttry {const parsed: unknown = JSON.parse(text)return JSON.stringify(redactValue(parsed))} catch {- return text.replace(QUOTED_SENSITIVE_VALUE, `"pin"$1:$2"${REDACTED}"`)+ const match = QUOTED_SENSITIVE_KEY.exec(text)+ return match ? `${text.slice(0, match.index)}"${match[1]}":"${REDACTED}"` : text}}diff --git a/desktop/src/electron/service-bridge/empty-handlers.ts b/desktop/src/electron/service-bridge/empty-handlers.tsindex bc8bf60..14fd3d8 100644--- a/desktop/src/electron/service-bridge/empty-handlers.ts+++ b/desktop/src/electron/service-bridge/empty-handlers.ts@@ -11,16 +11,21 @@ import {MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS} from '@/shared/constants/modular-runtime'import getErrorString from '@/shared/utils/get-error-string'+import { engineManagerName } from '@/shared/utils/engines'import { getEngineHubModels } from '@/electron/model-hub'import { getModularSupervisor } from './modular-supervisor'+import {+ parseEngineSettings,+ parseEngineSettingsPreview,+ parseEngineSettingsReceipt+} from './engine-settings'import {getModularBridgeState,- isProxyEngine,isUpstreamUnreachableError,parseServiceErrors,parseWorkloadsInitial} from './modular-state'-import type { ProxyEngine } from './modular-state'+import type { JsonObject, JsonValue } from './json-rpc-subprocess'import { emptyInvite, parseClusterNodes, parseInvite, parseNodeIdentity } from './cluster-json'import { removeManualNodeEntry, resolveManualNodeKey } from './manual-nodes-store'@@ -53,10 +58,6 @@ function booleanValue(value: JsonValue | undefined): boolean {return typeof value === 'boolean' ? value : false}-function numberValue(value: JsonValue | undefined): number {- return typeof value === 'number' ? value : 0-}-/** Relay a `cluster:*` / `nodes:*` request to nvpair-cluster-manager via the broker. */function callCluster(method: string,@@ -82,16 +83,6 @@ async function getClusterMembers(): Promise<ClusterNode[]> {}}-/** Map our `EngineType` onto the `nvpair-engine-manager` engine identifier. */-export function engineManagerEngineName(engineType: EngineType): string {- return engineType === 'lm-studio' ? 'lmstudio' : engineType-}--/** The proxy engine for a wire `EngineType`, or null for loopback-only engines. */-function proxyEngineFor(engineType: EngineType): ProxyEngine | null {- return isProxyEngine(engineType) ? engineType : null-}-async function handleGetSelfId(): Promise<string | null> {const state = getModularBridgeState()const identity = await getClusterIdentity()@@ -164,263 +155,6 @@ async function toggleLocalEngine(engine: string, engineType: EngineType): Promis}}-/**- * Set a local engine's HTTP server port. `nvpair-engine-manager`'s `engine:set-port`- * **persists** the chosen port as a per-user manifest override (the single source- * of truth, restored on restart) and applies it live: a running engine is bounced- * onto the new port, a stopped one just records it, and setting the port back to- * the bundled default drops the override. Awaited because the RPC returns only- * after the rebind completes; its terminal `engine:state-changed` clears the- * optimistic op below.- *- * A **running adopted** engine (one PAIR attached to instead of launching) is- * refused by the backend — PAIR can't move a process it didn't start — so we clear- * the optimistic op and surface a clear "stop it in its own app first" error.- * Remaining start-options limitation (env/args) is documented in- * docs/services-parity.md#engine-lifecycle.- */-async function applyEnginePort(- engine: string,- engineType: EngineType,- port: number-): Promise<void> {- const supervisor = getModularSupervisor()- const state = getModularBridgeState()- // Optimistic spinner during the rebind round-trip; the engine-manager's- // terminal engine:state-changed (running or stopped) clears it.- state.beginLocalEngineOp(engineType, 'starting')- try {- await supervisor.callProcess(- 'broker',- 'engine:set-port',- { engine, port },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- } catch (err) {- // Refused on a running adopted engine (and any other set-port failure):- // no engine:state-changed follows, so clear the optimistic op now instead- // of leaving a spinner up until the idle-timeout.- state.failLocalEngineOp(engine, 'start')- supervisor.reportError(- `Failed to set ${engine} port: ${getErrorString(err)}`,- 'error',- `engine-cmd:setPort:${engine}`- )- }-}--/**- * Set the local Ollama proxy's listen port. Routed through the broker's- * `ollama-proxy:set-port` relay, which persists the port (`proxy-port.json`,- * restored on restart), live-rebinds the proxy, and **steers it clear of any- * running engine port** (engines win — a bumped proxy surfaces a sticky- * `warning` on the errors pipeline). The proxy re-emits `ollama-proxy:ready`- * with the actually-bound port, which- * the bridge already folds into `status.proxyPort`, so success needs no further- * action here beyond surfacing a failure.- */-async function applyProxyPort(proxyEngine: ProxyEngine, port: number): Promise<void> {- const supervisor = getModularSupervisor()- if (!Number.isInteger(port) || port < 1 || port > 65535) {- supervisor.reportError(- `Invalid proxy port ${port}: must be between 1 and 65535.`,- 'warning',- `engine-cmd:setPort:proxy:${proxyEngine}`- )- return- }- try {- await supervisor.callProxy(proxyEngine, 'set-port', { port })- } catch (err) {- supervisor.reportError(- `Failed to set the ${proxyEngine} proxy port: ${getErrorString(err)}`,- 'error',- `engine-cmd:setPort:proxy:${proxyEngine}`- )- }-}--/**- * Apply the engine server port and/or proxy port for the local node in one safe- * transaction. The UI sends only the ports that changed; this picks an ordering- * so the engine and proxy never fight over a port mid-flight — including a full- * swap (server↔proxy).- *- * The backend has no atomic multi-port API, so we serialize the steps here:- * - **single port** → the focused `applyEnginePort` / `applyProxyPort` helper;- * - **both, engine stopped** → persist the engine port (no start, respecting- * the user's stopped state), then rebind the proxy;- * - **both, running, no collision** → bounce the engine onto its new port- * first (the failure-prone step — a running *adopted* engine is refused —- * so the proxy is left untouched if it throws), then rebind the proxy;- * - **both, running, collision/swap** → stop the engine to free its port, move- * the proxy (the engine's old port is now free for the proxy's target),- * persist the engine's new port, then start it back up.- *- * Every success path ends in an `engine:set-port` / `doStart` / `<engine>-proxy:ready`- * that re-emits authoritative state, which clears the optimistic op and snaps- * the UI inputs to backend truth. On failure we clear the optimistic op and- * report, so the UI reverts to the real ports.- */-async function applyEnginePorts(- engine: string,- engineType: EngineType,- enginePort: number | undefined,- proxyPort: number | undefined-): Promise<void> {- const supervisor = getModularSupervisor()- const state = getModularBridgeState()-- const wantEngine = typeof enginePort === 'number'- const wantProxy = typeof proxyPort === 'number'- if (!wantEngine && !wantProxy) return-- const proxyEngine = proxyEngineFor(engineType)- if (wantProxy && !proxyEngine) {- supervisor.reportError(- `The ${engineType} engine has no cluster proxy port to set.`,- 'warning',- `engine-cmd:setPorts:proxy:${engineType}`- )- return- }-- const validPort = (port: number): boolean =>- Number.isInteger(port) && port >= 1 && port <= 65535-- if (wantEngine && !validPort(enginePort)) {- supervisor.reportError(- `Invalid server port ${enginePort}: must be between 1 and 65535.`,- 'warning',- `engine-cmd:setPorts:${engine}`- )- return- }- if (wantProxy && !validPort(proxyPort)) {- supervisor.reportError(- `Invalid proxy port ${proxyPort}: must be between 1 and 65535.`,- 'warning',- `engine-cmd:setPorts:proxy:${engineType}`- )- return- }- if (wantEngine && wantProxy && enginePort === proxyPort) {- supervisor.reportError(- 'The server and proxy ports must be different.',- 'warning',- `engine-cmd:setPorts:${engine}`- )- return- }-- // Single-port changes delegate to the focused helpers (they own their own- // optimistic op + error reporting).- if (wantEngine && !wantProxy) {- await applyEnginePort(engine, engineType, enginePort)- return- }- if (wantProxy && !wantEngine && proxyEngine) {- await applyProxyPort(proxyEngine, proxyPort)- return- }-- // Both changed past this point (the single-port cases returned above);- // narrow the optional inputs to numbers for the rest of the transaction.- if (typeof enginePort !== 'number' || typeof proxyPort !== 'number') return- // wantProxy is true here, so proxyEngine was verified non-null above.- if (!proxyEngine) return-- // Both changed. Read the live engine state to detect a transient collision- // (the engine wants the proxy's current port, or the proxy wants the- // engine's current port) that requires serializing through a stop.- const currentProxy = state.getProxyPort(proxyEngine)- let engineRunning = false- let currentEnginePort = 0- try {- const status = objectValue(- await supervisor.callProcess('broker', 'engine:status', { engine })- )- engineRunning = booleanValue(status?.running)- currentEnginePort = numberValue(status?.port)- } catch {- // Status read failed — treat as stopped and take the safe persist path.- engineRunning = false- }-- state.beginLocalEngineOp(engineType, 'starting')- try {- if (!engineRunning) {- // Nothing is bound: persist the engine port (no start), then rebind- // the proxy. set-port on a stopped engine emits engine:state-changed- // (running:false, new port), which clears the optimistic op.- await supervisor.callProcess(- 'broker',- 'engine:set-port',- {- engine,- port: enginePort- },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- await supervisor.callProxy(proxyEngine, 'set-port', { port: proxyPort })- return- }-- const collision = enginePort === currentProxy || proxyPort === currentEnginePort- if (!collision) {- // Engine first (a running adopted engine is refused here, leaving the- // proxy untouched), then rebind the proxy.- await supervisor.callProcess(- 'broker',- 'engine:set-port',- {- engine,- port: enginePort- },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- await supervisor.callProxy(proxyEngine, 'set-port', { port: proxyPort })- return- }-- // Collision / swap: stop first so neither bind races the other.- await supervisor.callProcess(- 'broker',- 'engine:stop',- { engine },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- // The stop's engine:state-changed cleared the optimistic op — re-assert- // it so the UI keeps a spinner through the rest of the transaction.- state.beginLocalEngineOp(engineType, 'starting')- await supervisor.callProxy(proxyEngine, 'set-port', { port: proxyPort })- await supervisor.callProcess(- 'broker',- 'engine:set-port',- {- engine,- port: enginePort- },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- await supervisor.callProcess(- 'broker',- 'engine:start',- { engine },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- } catch (err) {- // No engine:state-changed follows a refused/failed step, so clear the- // optimistic op now and report — the UI reverts to the real ports.- state.failLocalEngineOp(engine, 'start')- supervisor.reportError(- `Failed to apply ${engine} ports: ${getErrorString(err)}`,- 'error',- `engine-cmd:setPorts:${engine}`- )- }-}-/*** Dispatch a UI engine command to the local `nvpair-engine-manager`. Lifecycle and* model operations are **fire-and-forget**: the engine-manager runs each in its@@ -433,7 +167,7 @@ async function applyEnginePorts(function routeEngineManagerCommand(payload: WsInvokeRequest<'engine:command'>): void {const supervisor = getModularSupervisor()const state = getModularBridgeState()- const engine = engineManagerEngineName(payload.engineType)+ const engine = engineManagerName(payload.engineType)// Use the engine-manager's stable error key. If the manager already reported// the operation failure, nvpair-errors upserts this fallback instead of showing// a duplicate; admission/transport failures still get a visible error.@@ -508,14 +242,6 @@ function routeEngineManagerCommand(payload: WsInvokeRequest<'engine:command'>):case 'toggle':void toggleLocalEngine(engine, payload.engineType)break- case 'setPorts':- // Both ports persist on this node: the engine HTTP server port via- // engine:set-port (manifest override), the proxy port via the broker's- // proxy:set-port (which steers it clear of running engine ports). The- // bridge diffs + orders them safely (incl. swaps). Local only — the- // backend exposes no remote port control.- void applyEnginePorts(engine, payload.engineType, payload.enginePort, payload.proxyPort)- breakcase 'pullModel':// Pulls need UI feedback the backend doesn't emit (progress + failure),// so the supervisor owns the optimistic-progress + awaited-completion@@ -611,14 +337,15 @@ async function toggleRemoteEngine(* Dispatch a UI engine command to a remote peer via `nvpair-engine-manager`'s* `engine:remote-*` client methods (cluster-scoped mTLS `ec` surface). Install,* start/stop, pull, and model load/unload/delete are supported remotely;- * uninstall, update, and port changes remain local-only.+ * uninstall and update remain local-only. Ports are not commands at all — they+ * travel the settings channels, which do reach a peer.* (optimistic status, awaited completion, authoritative refresh) lives on the* supervisor because the backend settles these ops only via the RPC reply, never* a terminal notification.*/function routeRemoteEngineCommand(payload: WsInvokeRequest<'engine:command'>): void {const supervisor = getModularSupervisor()- const engine = engineManagerEngineName(payload.engineType)+ const engine = engineManagerName(payload.engineType)const nodeId = payload.nodeIdconst refuseRemote = (detail: string): void => {@@ -644,11 +371,6 @@ function routeRemoteEngineCommand(payload: WsInvokeRequest<'engine:command'>): v`${payload.command} is only available on the local node — remote uninstall/update is not supported yet.`)break- case 'setPorts':- refuseRemote(- 'Port changes only apply to this machine — remote engine port control is not supported.'- )- breakcase 'deleteModel':case 'loadModel':case 'unloadModel':@@ -964,6 +686,31 @@ const EMPTY_SERVICE_BRIDGE_HANDLERS: BridgeHandlerMap = {'cluster:abandon-if-solo': () => handleClusterAbandonIfSolo(),'engines:get-initial': () => getModularBridgeState().getEngineInitialState(),+ 'engines:get-settings': async payload =>+ parseEngineSettings(+ await getModularSupervisor().callProcess(+ 'broker',+ 'engine:get-settings',+ payload ? { ...payload } : undefined+ )+ ),+ 'engines:preview-settings': async payload =>+ parseEngineSettingsPreview(+ await getModularSupervisor().callProcess(+ 'broker',+ 'engine:preview-settings',+ payload ? { ...payload, settings: { ...payload.settings } } : undefined+ )+ ),+ 'engines:apply-settings': async payload =>+ parseEngineSettingsReceipt(+ await getModularSupervisor().callProcess(+ 'broker',+ 'engine:apply-settings',+ payload ? { ...payload, settings: { ...payload.settings } } : undefined,+ MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS+ )+ ),'engine:command': payload => handleEngineCommand(payload),'engine:search-hub': payload =>payload ? getEngineHubModels(payload.engineType) : { models: [] },diff --git a/desktop/src/electron/service-bridge/engine-settings.ts b/desktop/src/electron/service-bridge/engine-settings.tsnew file mode 100644index 0000000..bc74bf6--- /dev/null+++ b/desktop/src/electron/service-bridge/engine-settings.ts@@ -0,0 +1,102 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++import type {+ EngineSettingsConfig,+ EngineSettingsSnapshot,+ EngineSettingsPreview,+ EngineSettingsReceipt,+ EngineSettingsTarget+} from '@/shared/types/engine-settings'+import { engineTypeFromManagerName } from '@/shared/utils/engines'+import type { JsonObject, JsonValue } from './json-rpc-subprocess'++function object(value: JsonValue | undefined): JsonObject {+ if (!value || typeof value !== 'object' || Array.isArray(value))+ throw new Error('This device does not support engine settings.')+ return value+}+function text(value: JsonValue | undefined): string {+ return typeof value === 'string' ? value : ''+}+function number(value: JsonValue | undefined): number {+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)+ throw new Error('Invalid engine settings response.')+ return value+}+function flag(value: JsonValue | undefined): boolean {+ if (typeof value !== 'boolean') throw new Error('Invalid engine settings response.')+ return value+}+function isSettingsEngine(value: JsonValue | undefined): value is EngineSettingsTarget['engine'] {+ return typeof value === 'string' && engineTypeFromManagerName(value) !== null+}+function isSnapshotPhase(value: JsonValue | undefined): value is EngineSettingsSnapshot['phase'] {+ return isReceiptPhase(value) || value === 'idle'+}+function isReceiptPhase(value: JsonValue | undefined): value is EngineSettingsReceipt['phase'] {+ return value === 'applying' || value === 'succeeded' || value === 'failed'+}+function config(value: JsonValue | undefined): EngineSettingsConfig {+ const row = object(value)+ return {+ serverPort: number(row.serverPort),+ proxyPort: number(row.proxyPort),+ launchText: text(row.launchText)+ }+}+export function parseEngineSettings(value: JsonValue | undefined): EngineSettingsSnapshot {+ const row = object(value)+ const engine = row.engine+ const phase = row.phase+ if (!isSettingsEngine(engine) || !isSnapshotPhase(phase) || !text(row.epoch))+ throw new Error('Invalid engine settings response.')+ return {+ nodeId: text(row.nodeId),+ engine,+ phase,+ epoch: text(row.epoch),+ sequence: number(row.sequence),+ revision: number(row.revision),+ appliedRevision: number(row.appliedRevision),+ settings: config(row.settings),+ effectiveServerPort: number(row.effectiveServerPort),+ effectiveProxyPort: number(row.effectiveProxyPort),+ running: flag(row.running),+ adopted: flag(row.adopted),+ editable: flag(row.editable),+ reason: text(row.reason),+ // Preserve the target's argument format so incompatible devices stay read-only.+ format: text(row.format),+ error: text(row.error),+ requestId: text(row.requestId)+ }+}+export function parseEngineSettingsPreview(value: JsonValue | undefined): EngineSettingsPreview {+ const row = object(value)+ const errors: Record<string, string> = {}+ if (row.errors)+ for (const [key, value] of Object.entries(object(row.errors))) errors[key] = text(value)+ const conflict = row.conflict ? object(row.conflict) : undefined+ return {+ settings: config(row.settings),+ revision: number(row.revision),+ errors,+ restart: flag(row.restart),+ rebind: flag(row.rebind),+ ...(conflict+ ? {+ conflict: {+ serverPort: number(conflict.serverPort),+ launchPort: number(conflict.launchPort)+ }+ }+ : {})+ }+}+export function parseEngineSettingsReceipt(value: JsonValue | undefined): EngineSettingsReceipt {+ const row = object(value)+ const phase = row.phase+ if (!isReceiptPhase(phase)) throw new Error('Invalid operation receipt.')+ return { revision: number(row.revision), phase }+}diff --git a/desktop/src/electron/service-bridge/modular-state.ts b/desktop/src/electron/service-bridge/modular-state.tsindex ee178d3..151f174 100644--- a/desktop/src/electron/service-bridge/modular-state.ts+++ b/desktop/src/electron/service-bridge/modular-state.ts@@ -22,7 +22,12 @@ import {MODULAR_SUPERSEDE_MIN_AGE_MS} from '@/shared/constants/modular-runtime'import { WorkloadStates } from '@/shared/constants/workloads'-import { isEngineType, emptyEngineStatus } from '@/shared/utils/engines'+import {+ emptyEngineStatus,+ engineManagerName,+ engineTypeFromManagerName,+ isEngineType+} from '@/shared/utils/engines'import { engineProgressKey } from '@/shared/utils/engine-progress'import { workloadKey } from '@/shared/utils/workloads'import { currentPlatform, platformDisplayName } from '@/shared/utils/platform'@@ -313,7 +318,7 @@ function parseServiceError(value: JsonValue | undefined): ServiceError | null {// `EngineType` union so the renderer's retry/display logic recognizes it.// Unknown ids fall through unchanged (no retry affordance will match).const engineType = stringValue(obj.engineType)- if (engineType) error.engineType = engineManagerEngineType(engineType) ?? engineType+ if (engineType) error.engineType = engineTypeFromManagerName(engineType) ?? engineTypeconst operation = stringValue(obj.operation)if (operation) error.operation = operationconst modelName = stringValue(obj.modelName)@@ -357,7 +362,7 @@ function parseWorkload(value: JsonValue | undefined): Workload | null {// The workload-manager stamps the engine-manager id (`lmstudio`); map it onto// our closed `EngineType` union (`lm-studio`) before narrowing so LM Studio// jobs are not silently dropped.- const engine = engineManagerEngineType(stringValue(obj.engine))+ const engine = engineTypeFromManagerName(stringValue(obj.engine))if (!engine) return nullconst stateValue = stringValue(obj.state)if (!isWorkloadState(stateValue)) return null@@ -409,33 +414,13 @@ function pendingEngineOpIdleTimeoutMs(status: EngineProcessStatus): number {return status === 'installing' ? INSTALL_PENDING_OP_IDLE_TIMEOUT_MS : PENDING_OP_IDLE_TIMEOUT_MS}-/**- * Map a `nvpair-engine-manager` engine identifier onto our closed `EngineType`- * union. The engine-manager uses `lmstudio`; we use `lm-studio`.- */-function engineManagerEngineType(name: string): EngineType | null {- const normalized = name === 'lmstudio' ? 'lm-studio' : name- return isEngineType(normalized) ? normalized : null-}--/**- * Inverse of {@link engineManagerEngineType} for the proxy engines: our closed- * union uses `lm-studio`; engine-manager (and the `modelsByEngine` map keys) use- * `lmstudio`. Ollama is spelled the same on both sides.- */-function proxyEngineToManagerName(engine: ProxyEngine): string {- return engine === 'lm-studio' ? 'lmstudio' : engine-}-/*** The set of models a node reports loaded in memory for an engine, read from* `ModularNode.loadedByEngine` (enriched from the backend's per-engine- * `loadedByEngine`). Keyed by engine-manager name, so `lm-studio` maps- * to `lmstudio`; any other type is spelled the same on both sides.+ * `loadedByEngine`), whose keys use the engine-manager's spelling.*/function loadedNamesForEngine(node: ModularNode | undefined, engineType: EngineType): Set<string> {- const managerName = engineType === 'lm-studio' ? 'lmstudio' : engineType- return new Set(node?.loadedByEngine[managerName] ?? [])+ return new Set(node?.loadedByEngine[engineManagerName(engineType)] ?? [])}function sameStringList(left: string[], right: string[]): boolean {@@ -1377,7 +1362,7 @@ class ModularBridgeState {applyEngineManagerStatus(params: JsonValue | undefined): void {const obj = objectValue(params)if (!obj) return- const engineType = engineManagerEngineType(stringValue(obj.engine))+ const engineType = engineTypeFromManagerName(stringValue(obj.engine))if (!engineType) returnthis.engineManagerFacts.set(engineType, {@@ -1416,7 +1401,9 @@ class ModularBridgeState {*/failLocalEngineOp(engineManagerEngine: string, operation: string): void {if (operation !== 'start' && operation !== 'install' && operation !== 'uninstall') return- const engineType = engineManagerEngineType(engineManagerEngine)+ const engineType =+ engineTypeFromManagerName(engineManagerEngine) ??+ (isEngineType(engineManagerEngine) ? engineManagerEngine : null)if (!engineType) returnthis.clearLocalEngineOp(engineType)}@@ -1538,7 +1525,7 @@ class ModularBridgeState {const obj = objectValue(params)if (!obj) returnconst nodeId = stringValue(obj.node)- const engineType = engineManagerEngineType(stringValue(obj.engine))+ const engineType = engineTypeFromManagerName(stringValue(obj.engine))if (!nodeId || !engineType) returnconst op = stringValue(obj.op)@@ -1789,7 +1776,7 @@ class ModularBridgeState {for (const entry of list) {const engineObj = objectValue(entry)if (!engineObj) continue- const engineType = engineManagerEngineType(stringValue(engineObj.engine))+ const engineType = engineTypeFromManagerName(stringValue(engineObj.engine))if (!engineType || !isProxyEngine(engineType)) continuethis.remoteEngineFacts.set(this.remoteOpKey(nodeId, engineType), {installed: booleanValue(engineObj.installed),@@ -1848,7 +1835,7 @@ class ModularBridgeState {* — no double-sourcing.*/modelPullTarget(engineManagerEngine: string): EngineType | null {- return engineManagerEngineType(engineManagerEngine)+ return engineTypeFromManagerName(engineManagerEngine)}/**@@ -1989,7 +1976,7 @@ class ModularBridgeState {// engine serves none (NOT the cross-engine union). Mirrors// noderec.DirectoryNode.EngineModels.if (Object.keys(node.modelsByEngine).length > 0) {- return node.modelsByEngine[proxyEngineToManagerName(engine)] ?? []+ return node.modelsByEngine[engineManagerName(engine)] ?? []}// Fallback for a pre-attribution peer: the flat union is unattributed, so// attribute it only when exactly one proxy engine is active on the node,@@ -2128,7 +2115,7 @@ class ModularBridgeState {if (!nodeId) returnconst obj = objectValue(params)if (!obj) return- const engineType = engineManagerEngineType(stringValue(obj.engine))+ const engineType = engineTypeFromManagerName(stringValue(obj.engine))if (!engineType) returnconst stage = stringValue(obj.stage) || 'installing'@@ -2216,7 +2203,7 @@ class ModularBridgeState {if (!nodeId) returnconst obj = objectValue(params)if (!obj) return- const engineType = engineManagerEngineType(stringValue(obj.engine))+ const engineType = engineTypeFromManagerName(stringValue(obj.engine))if (!engineType) returnconst model = this.localPullModels.get(engineType)@@ -2445,7 +2432,7 @@ class ModularBridgeState {if (merged.id === this.selfId && existing) {const unionChanged = !sameStringList(existing.models, merged.models)for (const engine of PROXY_ENGINES) {- const managerEngine = proxyEngineToManagerName(engine)+ const managerEngine = engineManagerName(engine)const hadEngine = managerEngine in existing.modelsByEngineconst hasEngine = managerEngine in merged.modelsByEngineconst attributionChanged =diff --git a/desktop/src/electron/service-bridge/modular-supervisor.ts b/desktop/src/electron/service-bridge/modular-supervisor.tsindex fac10a0..680b169 100644--- a/desktop/src/electron/service-bridge/modular-supervisor.ts+++ b/desktop/src/electron/service-bridge/modular-supervisor.ts@@ -26,9 +26,10 @@ import {type ProxyEngine} from './modular-state'import { emitBridgePush } from './broadcaster'+import { parseEngineSettings } from './engine-settings'import { resolvePullCatchError } from './pull-error-handling'import { serviceLogLevel } from './service-log-level'-import { engineManagerEngineName } from './empty-handlers'+import { engineManagerName, engineTypeFromManagerName } from '@/shared/utils/engines'import { isFirstRun } from '@/electron/config/ui-config'import { parseClusterNodes, parseInvite, parseNodeIdentity } from './cluster-json'import { startNodeInfoPoller, stopNodeInfoPoller } from './node-info-poller'@@ -291,16 +292,10 @@ function emptyLocalEngineBridge(): LocalEngineBridge {return { running: false, port: 0, bridgedId: '', bridgedPort: 0, selfWarned: false }}-/** Translate our `EngineType` into the engine-manager's engine id. */-function engineManagerId(engine: ProxyEngine): string {- return engine === 'lm-studio' ? 'lmstudio' : engine-}-/** Translate an engine-manager engine id into a proxy engine, or null. */function proxyEngineFromManagerId(id: string): ProxyEngine | null {- if (id === 'ollama') return 'ollama'- if (id === 'lmstudio') return 'lm-studio'- return null+ const engine = engineTypeFromManagerName(id)+ return engine && isProxyEngine(engine) ? engine : null}/** The broker relay namespace fronting an engine's reverse proxy. */@@ -1156,7 +1151,7 @@ class ModularSupervisor {if (status.nodeId !== selfId) continueif (status.processStatus !== 'stopped' && status.processStatus !== 'running') continue- const engine = engineManagerEngineName(status.engineType)+ const engine = engineManagerName(status.engineType)// A stopped engine will emit `engine:state-changed` on start, which// clears this optimistic op; a running engine's start is a backend// no-op (no state event), so we skip the op to avoid a stuck spinner —@@ -1610,6 +1605,25 @@ class ModularSupervisor {}private handleEngineManagerNotification(notification: JsonRpcNotification): void {+ if (notification.method === 'engine:settings-changed') {+ try {+ emitBridgePush('engines:settings-changed', parseEngineSettings(notification.params))+ } catch {+ /* Unsupported peer version. */+ }+ return+ }+ if (notification.method === 'engine:settings-disconnected') {+ const params = notification.params+ if (+ params &&+ typeof params === 'object' &&+ !Array.isArray(params) &&+ typeof params.nodeId === 'string'+ )+ emitBridgePush('engines:settings-disconnected', { nodeId: params.nodeId })+ return+ }if (notification.method === 'engine:ready') {void this.hydrateEngineManager()return@@ -2035,7 +2049,7 @@ class ModularSupervisor {}const generation = this.beginModelRefresh(engine)this.callProcess('broker', 'engine:action', {- engine: engineManagerId(engine),+ engine: engineManagerName(engine),action: 'list_models'}).then(result => {diff --git a/desktop/src/electron/service-bridge/node-info-poller.ts b/desktop/src/electron/service-bridge/node-info-poller.tsindex b2baf96..ea83af1 100644--- a/desktop/src/electron/service-bridge/node-info-poller.ts+++ b/desktop/src/electron/service-bridge/node-info-poller.ts@@ -286,12 +286,7 @@ async function probeHost(}/** Remember the address that answered, and merge the telemetry it reported. */-function accept(- nodeId: string,- host: string,- port: number,- parsed: JsonValue-): void {+function accept(nodeId: string, host: string, port: number, parsed: JsonValue): void {pollChoices.set(nodeId, { host, walkedAt: 0 })noteAnswering(nodeId, nodeInfoUrl(host, port))getModularBridgeState().mergeNodeInfoResponse(nodeId, parsed)diff --git a/desktop/src/shared/constants/engines.ts b/desktop/src/shared/constants/engines.tsindex 3a1472c..5904ae6 100644--- a/desktop/src/shared/constants/engines.ts+++ b/desktop/src/shared/constants/engines.ts@@ -15,6 +15,17 @@ export const EngineTypes = ['ollama', 'lm-studio'] as const// appearing the moment its type exists.export const EnabledEngineTypes: EngineType[] = ['ollama', 'lm-studio'] as const+/**+ * How `nvpair-engine-manager` spells each engine on the wire. Only LM Studio+ * differs from PAIR's `EngineType`; every other engine is identical on both+ * sides. This is the single translation table — use `engineManagerName()` and+ * `engineTypeFromManagerName()` rather than re-deriving it from a literal.+ */+export const EngineManagerNames = {+ ollama: 'ollama',+ 'lm-studio': 'lmstudio'+} as const satisfies Record<EngineType, string>+export const EngineSources = ['bundled', 'detected', 'installed'] as constexport const EngineDisplayNames: Record<EngineType, string> = {diff --git a/desktop/src/shared/constants/modular-runtime.ts b/desktop/src/shared/constants/modular-runtime.tsindex 2fdaefd..412827c 100644--- a/desktop/src/shared/constants/modular-runtime.ts+++ b/desktop/src/shared/constants/modular-runtime.ts@@ -62,9 +62,13 @@ export const MODULAR_NODE_INFO_SELF_HOST = '127.0.0.1'export const MODULAR_STARTUP_READY_TIMEOUT_MS = 15_000// Awaited engine lifecycle calls can include the bundled Ollama manifest's-// 10-minute readiness probe (for example a running engine:set-port rebind).-// Keep the desktop JSON-RPC envelope bounded but outside that backend budget.-export const MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS = 11 * 60_000+// 10-minute readiness probe and the broker's combined settings operation. The+// shared enginesettings/timeouts.go defines the ladder above that probe:+// 10.5 minutes for configure, 11 minutes for the owner-side+// operation, 12 for a client call, 13 for a call relayed on a peer's behalf.+// This envelope is the outermost rung and has to outlast all of them, or a+// desktop timeout would report failure for an operation still running.+export const MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS = 14 * 60_000// Upper bound for a local model load/unload/delete action. A delete on an// engine whose manifest declares `restart_after` (LM Studio) does not replydiff --git a/desktop/src/shared/types/engine-api.ts b/desktop/src/shared/types/engine-api.tsindex 351f5c5..9187e65 100644--- a/desktop/src/shared/types/engine-api.ts+++ b/desktop/src/shared/types/engine-api.ts@@ -44,7 +44,6 @@ export type EngineCommandType =| 'installAll'| 'uninstall'| 'update'- | 'setPorts'| 'pullModel'| 'loadModel'| 'unloadModel'@@ -57,17 +56,6 @@ export interface EngineCommandPayload {engineType: EngineTypenodeId: stringmodel?: string- /**- * `setPorts` only. The engine HTTP server port to apply. Omitted when the- * server port did not change so the bridge sends only what the user edited.- */- enginePort?: number- /**- * `setPorts` only. The proxy listen port to apply. Omitted when the proxy- * port did not change. When both ports change the bridge orders the- * transaction so the engine and proxy never fight over a port (incl. swaps).- */- proxyPort?: numberexpiry?: string}diff --git a/desktop/src/shared/types/engine-settings.ts b/desktop/src/shared/types/engine-settings.tsnew file mode 100644index 0000000..02311a3--- /dev/null+++ b/desktop/src/shared/types/engine-settings.ts@@ -0,0 +1,56 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++export interface EngineSettingsConfig {+ serverPort: number+ proxyPort: number+ /** Arguments and leading environment assignments, without an executable/subcommand. */+ launchText: string+}++import type { EngineManagerName } from '@/shared/types/engines'++export interface EngineSettingsTarget {+ nodeId: string+ /** Engine-manager spelling — the settings contract is relayed verbatim. */+ engine: EngineManagerName+}++export interface EngineSettingsRequest extends EngineSettingsTarget {+ expectedRevision: number+ requestId?: string+ settings: EngineSettingsConfig+ resolution?: 'server' | 'launch'+}++export interface EngineSettingsSnapshot extends EngineSettingsTarget {+ revision: number+ appliedRevision: number+ sequence: number+ epoch: string+ settings: EngineSettingsConfig+ effectiveServerPort: number+ effectiveProxyPort: number+ running: boolean+ adopted: boolean+ editable: boolean+ reason: string+ format: string+ phase: 'idle' | 'applying' | 'succeeded' | 'failed'+ error: string+ requestId: string+}++export interface EngineSettingsPreview {+ settings: EngineSettingsConfig+ revision: number+ conflict?: { serverPort: number; launchPort: number }+ errors: Record<string, string>+ restart: boolean+ rebind: boolean+}++export interface EngineSettingsReceipt {+ revision: number+ phase: 'applying' | 'succeeded' | 'failed'+}diff --git a/desktop/src/shared/types/engines.ts b/desktop/src/shared/types/engines.tsindex 54a228b..863c415 100644--- a/desktop/src/shared/types/engines.ts+++ b/desktop/src/shared/types/engines.ts@@ -2,6 +2,7 @@// SPDX-License-Identifier: Apache-2.0import {+ EngineManagerNames,EngineOperationTypes,EngineProcessStatuses,EngineSources,@@ -21,6 +22,14 @@ import {*/export type EngineType = (typeof EngineTypes)[number]+/**+ * An engine identifier in `nvpair-engine-manager`'s spelling, as it appears in+ * JSON-RPC params and notification payloads. Convert at the boundary with+ * `engineManagerName()` / `engineTypeFromManagerName()`; keep `EngineType`+ * everywhere inside PAIR.+ */+export type EngineManagerName = (typeof EngineManagerNames)[EngineType]+export type EngineSource = (typeof EngineSources)[number]export interface EngineStatusData {diff --git a/desktop/src/shared/types/ws-channels.ts b/desktop/src/shared/types/ws-channels.tsindex 07398ea..1592376 100644--- a/desktop/src/shared/types/ws-channels.ts+++ b/desktop/src/shared/types/ws-channels.ts@@ -30,6 +30,13 @@ import type {EngineStatePatch} from '@/shared/types/engine-api'import type { EngineProgress, EngineType } from '@/shared/types/engines'+import type {+ EngineSettingsTarget,+ EngineSettingsRequest,+ EngineSettingsSnapshot,+ EngineSettingsPreview,+ EngineSettingsReceipt+} from '@/shared/types/engine-settings'import type { AppInitialSnapshot, ClusterInitialSnapshot } from '@/shared/types/bootstrap'import type { ServiceError } from '@/shared/types/errors'import type { NodeItem } from '@/shared/types/nodes'@@ -91,6 +98,9 @@ export interface WsInvokeChannelMap {// Engines'engines:get-initial': { request: void; response: EngineInitialState }+ 'engines:get-settings': { request: EngineSettingsTarget; response: EngineSettingsSnapshot }+ 'engines:preview-settings': { request: EngineSettingsRequest; response: EngineSettingsPreview }+ 'engines:apply-settings': { request: EngineSettingsRequest; response: EngineSettingsReceipt }'engine:command': { request: EngineCommandPayload; response: null }'engine:search-hub': { request: { engineType: EngineType }; response: EngineHubSearchResponse }@@ -119,6 +129,8 @@ export interface WsPushChannelMap {// Engines'engines:state-changed': EngineStatePatch+ 'engines:settings-changed': EngineSettingsSnapshot+ 'engines:settings-disconnected': { nodeId: string }'engines:progress-changed': EngineProgress'engines:progress-cleared': { key: string }diff --git a/desktop/src/shared/utils/engines.ts b/desktop/src/shared/utils/engines.tsindex e6d8098..e8a6bd0 100644--- a/desktop/src/shared/utils/engines.ts+++ b/desktop/src/shared/utils/engines.ts@@ -1,8 +1,14 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-import { EngineTypes, ModelExpiries } from '@/shared/constants/engines'-import { EngineModels, EngineStatusData, EngineType, ModelExpiry } from '@/shared/types/engines'+import { EngineManagerNames, EngineTypes, ModelExpiries } from '@/shared/constants/engines'+import {+ EngineManagerName,+ EngineModels,+ EngineStatusData,+ EngineType,+ ModelExpiry+} from '@/shared/types/engines'const ENGINE_TYPE_SET: ReadonlySet<string> = new Set(EngineTypes)/**@@ -15,6 +21,22 @@ export function isEngineType(v: string | undefined): v is EngineType {return typeof v === 'string' && ENGINE_TYPE_SET.has(v)}+/** Spell an `EngineType` the way `nvpair-engine-manager` does on the wire. */+export function engineManagerName(engine: EngineType): EngineManagerName {+ return EngineManagerNames[engine]+}++const ENGINE_TYPE_BY_MANAGER_NAME: ReadonlyMap<string, EngineType> = new Map(+ EngineTypes.map(engine => [EngineManagerNames[engine], engine])+)+/**+ * Narrow an engine id arriving from `nvpair-engine-manager` into an+ * `EngineType`, or null for an engine this build does not ship.+ */+export function engineTypeFromManagerName(name: string): EngineType | null {+ return ENGINE_TYPE_BY_MANAGER_NAME.get(name) ?? null+}+const MODEL_EXPIRY_SET: ReadonlySet<string> = new Set(ModelExpiries)/** Runtime type guard — validates a string is a known ModelExpiry. */export function isModelExpiry(v: string | undefined): v is ModelExpiry {diff --git a/desktop/src/ui/api/engine-api.ts b/desktop/src/ui/api/engine-api.tsindex 69fd71a..71d8f16 100644--- a/desktop/src/ui/api/engine-api.ts+++ b/desktop/src/ui/api/engine-api.ts@@ -16,8 +16,33 @@ import type {} from '@/shared/types/engine-api'import type { EngineProgress, EngineType } from '@/shared/types/engines'import { usePendingActionsStore } from '@/ui/stores/pending-actions.store'+import type {+ EngineSettingsTarget,+ EngineSettingsRequest,+ EngineSettingsSnapshot,+ EngineSettingsPreview,+ EngineSettingsReceipt+} from '@/shared/types/engine-settings'export interface IEngineApi {+ /** Read the owning node's authoritative settings snapshot for one engine. */+ getSettings(target: EngineSettingsTarget): Promise<EngineSettingsSnapshot>+ /**+ * Validate a draft against the owner without persisting or touching any+ * process: returns the normalized settings, per-field errors, any port+ * conflict, and whether applying would restart or rebind.+ */+ previewSettings(request: EngineSettingsRequest): Promise<EngineSettingsPreview>+ /**+ * Commit a draft. The receipt only acknowledges that the owner accepted the+ * operation — completion arrives on `onSettingsChanged`, because a stop,+ * rebind, and restart outlive the call.+ */+ applySettings(request: EngineSettingsRequest): Promise<EngineSettingsReceipt>+ /** A settings snapshot changed on some node — the only source of applied state. */+ onSettingsChanged(callback: (snapshot: EngineSettingsSnapshot) => void): () => void+ /** A node's settings authority became unreachable; its cached snapshot is stale. */+ onSettingsDisconnected(callback: (target: { nodeId: string }) => void): () => void/** Fetch initial engine state: statuses, models, progress, and update availability. */getInitialState(): Promise<EngineInitialState>@@ -27,16 +52,6 @@ export interface IEngineApi {install(engineType: EngineType, nodeId: string): void/** Uninstall an engine from a node without removing downloaded models. */uninstall(engineType: EngineType, nodeId: string): void- /**- * Apply the engine server port and/or proxy port on a node in one safe- * transaction. Pass only the ports that changed; the bridge orders the- * operations so the engine and proxy never collide (including a full swap).- */- setPorts(- engineType: EngineType,- nodeId: string,- ports: { enginePort?: number; proxyPort?: number }- ): void/** Pull (download) a model on a node. */pullModel(engineType: EngineType, nodeId: string, model: string): void/** Load a model into memory on a node. */@@ -70,6 +85,11 @@ function fireCommand(transport: ServiceTransport, payload: EngineCommandPayload)export function createEngineApi(transport: ServiceTransport): IEngineApi {return {+ getSettings: target => transport.invoke('engines:get-settings', target),+ previewSettings: request => transport.invoke('engines:preview-settings', request),+ applySettings: request => transport.invoke('engines:apply-settings', request),+ onSettingsChanged: cb => transport.subscribePush('engines:settings-changed', cb),+ onSettingsDisconnected: cb => transport.subscribePush('engines:settings-disconnected', cb),getInitialState: () => transport.invoke('engines:get-initial'),toggle: (engineType, nodeId) =>@@ -78,14 +98,6 @@ export function createEngineApi(transport: ServiceTransport): IEngineApi {fireCommand(transport, { command: 'install', engineType, nodeId }),uninstall: (engineType, nodeId) =>fireCommand(transport, { command: 'uninstall', engineType, nodeId }),- setPorts: (engineType, nodeId, ports) =>- fireCommand(transport, {- command: 'setPorts',- engineType,- nodeId,- enginePort: ports.enginePort,- proxyPort: ports.proxyPort- }),pullModel: (engineType, nodeId, model) =>fireCommand(transport, { command: 'pullModel', engineType, nodeId, model }),loadModel: (engineType, nodeId, model) =>diff --git a/desktop/src/ui/components/BackendRow/BackendHeader.tsx b/desktop/src/ui/components/BackendRow/BackendHeader.tsxindex cceebe3..d54bd62 100644--- a/desktop/src/ui/components/BackendRow/BackendHeader.tsx+++ b/desktop/src/ui/components/BackendRow/BackendHeader.tsx@@ -147,7 +147,7 @@ export function BackendHeader({{isUnavailable && (<DismissibleTooltip slotContent="This node hasn't reported this engine's status.">- <Flex align="center" className="ml-2" style={{ minHeight: 32 }}>+ <Flex align="center" className="ml-2 h-7"><Text kind="body/regular/sm" className="text-subtle-color">Unavailable</Text>@@ -181,18 +181,23 @@ export function BackendHeader({<Flexalign="center"gap="1"- className="ml-2 min-w-0 max-w-[min(100%,28rem)]"- style={{ minHeight: 32 }}+ className="ml-2 h-7 min-w-0 max-w-[min(100%,28rem)]"><span className="min-w-0"><Textkind="body/regular/sm"- className="truncate block mt-1 capitalize"+ className="truncate block capitalize">{fullStatus}</Text></span>- <span className="spinner-element" role="status" aria-label="" />+ <Flex align="center" justify="center" className="h-7 w-7 shrink-0">+ <span+ className="spinner-element-medium"+ role="status"+ aria-label={fullStatus}+ />+ </Flex></Flex></DismissibleTooltip>)@@ -207,14 +212,16 @@ export function BackendHeader({const isStartDisabled = !prereqsMet && backend.processStatus !== 'running'const toggle = (- <Switch- size="small"- checked={backend.processStatus === 'running'}- onCheckedChange={onToggle}- onClick={e => e.stopPropagation()}- disabled={disabled || isStartDisabled}- aria-label={`${backend.processStatus === 'running' ? 'Stop' : 'Start'} ${backend.displayName}`}- />+ <Flex align="center" justify="center" className="h-7 w-7 shrink-0">+ <Switch+ size="small"+ checked={backend.processStatus === 'running'}+ onCheckedChange={onToggle}+ onClick={e => e.stopPropagation()}+ disabled={disabled || isStartDisabled}+ aria-label={`${backend.processStatus === 'running' ? 'Stop' : 'Start'} ${backend.displayName}`}+ />+ </Flex>)if (isStartDisabled) {diff --git a/desktop/src/ui/components/BackendRow/BackendPorts.tsx b/desktop/src/ui/components/BackendRow/BackendPorts.tsxdeleted file mode 100644index 3d876ae..0000000--- a/desktop/src/ui/components/BackendRow/BackendPorts.tsx+++ /dev/null@@ -1,98 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--import { Button, Flex } from '@nvidia/foundations-react-core'-import { Check } from '@/ui/components/icons'-import { PortRow } from './PortRow'--export function BackendPorts({- proxyPort,- serverPort,- changed,- disabled,- isLocalNode,- showServerPort,- onServerChange,- onProxyChange,- onApply-}: {- proxyPort: string- serverPort: string- /** True when either port differs from the backend-reported value. */- changed: boolean- disabled: boolean- isLocalNode: boolean- showServerPort: boolean- onServerChange: (v: string) => void- onProxyChange: (v: string) => void- onApply: () => void-}) {- return (- // align="end" bottom-aligns the (label-less) Apply button with the port- // inputs, which sit below their labels.- <Flex- gap="6"- align="end"- style={{- opacity: disabled ? 0.5 : 1,- pointerEvents: disabled ? 'none' : 'auto'- }}- >- {/* The proxy port persists via the broker's <engine>-proxy:set-port- (steered clear of running engine ports), so it is editable on the- local node. Only the proxy-fronted engines (Ollama, LM Studio)- report a proxy port; other engines report none. Remote nodes are- read-only — set-port only rebinds the local broker's proxy. */}- {proxyPort &&- (isLocalNode ? (- <PortRow- label="Proxy"- port={proxyPort}- disabled={disabled}- onPortChange={onProxyChange}- />- ) : (- <PortRow label="Proxy" port={proxyPort} readOnly />- ))}- {showServerPort &&- (isLocalNode ? (- <PortRow- label="Server"- port={serverPort}- disabled={disabled}- onPortChange={onServerChange}- />- ) : (- // Remote nodes are read-only (the engine-manager only- // mutates the local node), so show the value statically- // instead of a disabled input.- <PortRow label="Server" port={serverPort} readOnly />- ))}-- {/* One apply on the same row: the bridge diffs the ports and runs a- single safe transaction (proxy and/or engine, incl. a swap), so- the user never has to apply two rows in the right order. */}- {isLocalNode && (- <Button- kind="primary"- color="brand"- size="small"- onClick={onApply}- disabled={disabled || !changed}- >- {disabled ? (- <Flex align="center" gap="2">- <span className="spinner-element" role="status" aria-label="" />- Applying…- </Flex>- ) : (- <Flex align="center" gap="2">- <Check style={{ fontSize: 16 }} />- Apply ports- </Flex>- )}- </Button>- )}- </Flex>- )-}diff --git a/desktop/src/ui/components/BackendRow/BackendRow.tsx b/desktop/src/ui/components/BackendRow/BackendRow.tsxindex a1b399d..f3c1623 100644--- a/desktop/src/ui/components/BackendRow/BackendRow.tsx+++ b/desktop/src/ui/components/BackendRow/BackendRow.tsx@@ -5,13 +5,13 @@ import { useCallback, useEffect, useMemo, useState } from 'react'import { Divider, Stack } from '@nvidia/foundations-react-core'import type { BackendInfo } from '@/ui/types/engine-info'import type { EngineProcessStatus } from '@/shared/types/engines'-import { EngineCapabilities } from '@/ui/constants/engine-capabilities'+import { engineProgressKey } from '@/shared/utils/engine-progress'import { useConnectionStore } from '@/ui/stores/connection.store'import { useEngineModelsStore } from '@/ui/stores/engine-models.store'import { useEngineStatusStore } from '@/ui/stores/engine-status.store'import { useNodesStore } from '@/ui/stores/nodes.store'-import { useErrorsStore } from '@/ui/stores/errors.store'+import { useEngineProgressStore } from '@/ui/stores/engine-progress.store'import { usePendingActionsStore } from '@/ui/stores/pending-actions.store'import type { EngineCommandType } from '@/shared/types/engine-api'@@ -21,17 +21,8 @@ import { ModelSection } from '@/ui/components/ModelManager/ModelSection'import { BackendHeader } from './BackendHeader'import { BackendFooter } from './BackendFooter'import { BackendUpdateBanner } from './BackendUpdateBanner'-import { EditState } from '@/ui/types/engine-edit-state'-import { PortsSection } from './PortsSection'-/** Strip non-digits and parse; returns NaN for empty/invalid input. */-function parsePort(raw: string): number {- return parseInt((raw || '').replace(/[^0-9]/g, ''), 10)-}--function isValidPort(port: number): boolean {- return Number.isFinite(port) && port >= 1 && port <= 65535-}+import { EngineSettingsSection } from './EngineSettingsSection'/*** The transitional status to display while an optimistic lifecycle command is@@ -69,39 +60,8 @@ export function BackendRow({/** False when the service never reported this node/engine pair (placeholder status). */statusKnown: boolean}) {- const [edit, setEdit] = useState<EditState>({- serverPort: String(backend.port ?? ''),- proxyPort: String(backend.proxyPort ?? '')- })-- const addLocalError = useErrorsStore(state => state.addLocalError)-- useEffect(() => {- setEdit(prev => ({ ...prev, serverPort: String(backend.port ?? '') }))- }, [backend.port])-- useEffect(() => {- setEdit(prev => ({ ...prev, proxyPort: String(backend.proxyPort ?? '') }))- }, [backend.proxyPort])-const [expanded, setExpanded] = useState(false)const [confirmUninstall, setConfirmUninstall] = useState(false)- const [confirmPorts, setConfirmPorts] = useState(false)-- const caps = EngineCapabilities[backend.type]-- const serverPortChanged = useMemo(- () => caps.hasEnginePort && edit.serverPort !== String(backend.port ?? ''),- [caps.hasEnginePort, edit.serverPort, backend.port]- )-- const proxyPortChanged = useMemo(- () => Boolean(edit.proxyPort) && edit.proxyPort !== String(backend.proxyPort ?? ''),- [edit.proxyPort, backend.proxyPort]- )-- const portsChanged = serverPortChanged || proxyPortChanged-const installProgress = useEngineProgressStore(s => {const installKey = engineProgressKey({nodeId,@@ -191,66 +151,6 @@ export function BackendRow({window.pairApi.engines.toggle(backend.type, nodeId)}, [backend.type, nodeId])- // Snap the inputs back to backend truth. After firing an apply we reset here- // so the fields always reflect what the service reports: on success the- // engine:state-changed / proxy:ready push updates the value; on failure no- // push arrives and the input stays at the last-known-good value (the revert).- const resetPortsToBackend = useCallback(() => {- setEdit({- serverPort: String(backend.port ?? ''),- proxyPort: String(backend.proxyPort ?? '')- })- }, [backend.port, backend.proxyPort])-- const validateAndConfirmPorts = useCallback(() => {- if (!serverPortChanged && !proxyPortChanged) return- if (serverPortChanged && !isValidPort(parsePort(edit.serverPort))) {- addLocalError('Enter a valid server port (1–65535).')- return- }- if (proxyPortChanged && !isValidPort(parsePort(edit.proxyPort))) {- addLocalError('Enter a valid proxy port (1–65535).')- return- }- // Guard the one collision the backend cannot resolve atomically yet: a- // single transaction setting the server and proxy to the same port.- if (- serverPortChanged &&- proxyPortChanged &&- parsePort(edit.serverPort) === parsePort(edit.proxyPort)- ) {- addLocalError('Server and proxy ports must be different.')- return- }- setConfirmPorts(true)- }, [serverPortChanged, proxyPortChanged, edit.serverPort, edit.proxyPort, addLocalError])-- const handleApplyPorts = useCallback(() => {- const enginePort = serverPortChanged ? parsePort(edit.serverPort) : undefined- const proxyPort = proxyPortChanged ? parsePort(edit.proxyPort) : undefined- if (enginePort === undefined && proxyPort === undefined) return- window.pairApi.engines.setPorts(backend.type, nodeId, { enginePort, proxyPort })- resetPortsToBackend()- }, [- serverPortChanged,- proxyPortChanged,- edit.serverPort,- edit.proxyPort,- backend.type,- nodeId,- resetPortsToBackend- ])-- const portsConfirmMessage = useMemo(() => {- if (serverPortChanged && proxyPortChanged) {- return 'Changing the server and proxy ports will restart the engine and proxy.'- }- if (serverPortChanged) {- return 'Changing the server port will restart the engine.'- }- return 'Changing the proxy port will restart the proxy.'- }, [serverPortChanged, proxyPortChanged])-const handleInstall = useCallback(() => {window.pairApi.engines.install(backend.type, nodeId)}, [backend.type, nodeId])@@ -272,8 +172,8 @@ export function BackendRow({setExpanded(prev => !prev)}, [isUnavailable])- // Install/start/stop and model pull work on clustered peers; uninstall,- // update, port edits, and model load/delete remain local-only.+ // Install/start/stop, model pull, and the settings editor work on clustered+ // peers; uninstall, update, and model load/delete remain local-only.const controlsDisabled = isTransitioningconst content = expanded ? (@@ -288,16 +188,12 @@ export function BackendRow({<ModelSection backend={displayBackend} nodeId={nodeId} disabled={isTransitioning} />)}- {canShowAccordions && (caps.hasEnginePort || edit.proxyPort) && (- <PortsSection- edit={edit}- portsChanged={portsChanged}- anyLoading={isTransitioning}- isLocalNode={isLocalNode}- caps={caps}- onApplyPorts={validateAndConfirmPorts}- onServerChange={v => setEdit(prev => ({ ...prev, serverPort: v }))}- onProxyChange={v => setEdit(prev => ({ ...prev, proxyPort: v }))}+ {canShowAccordions && (+ <EngineSettingsSection+ key={`${nodeId}:${backend.type}`}+ nodeId={nodeId}+ engineType={backend.type}+ disabled={isTransitioning}/>)}@@ -341,15 +237,6 @@ export function BackendRow({confirmColor="danger"onConfirm={handleUninstall}/>-- <ConfirmModal- open={confirmPorts}- onOpenChange={setConfirmPorts}- title="Apply ports"- message={portsConfirmMessage}- confirmLabel="Confirm"- onConfirm={handleApplyPorts}- /></>)}diff --git a/desktop/src/ui/components/BackendRow/EngineSettingsSection.tsx b/desktop/src/ui/components/BackendRow/EngineSettingsSection.tsxnew file mode 100644index 0000000..bc03835--- /dev/null+++ b/desktop/src/ui/components/BackendRow/EngineSettingsSection.tsx@@ -0,0 +1,350 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++import { useEffect, useRef, useState } from 'react'+import {+ Button,+ Flex,+ FormField,+ ModalContent,+ ModalDialog,+ ModalHeading,+ ModalRoot,+ Stack,+ Text,+ TextArea,+ TextInput+} from '@nvidia/foundations-react-core'+import type { EngineType } from '@/shared/types/engines'+import type {+ EngineSettingsConfig,+ EngineSettingsRequest,+ EngineSettingsSnapshot+} from '@/shared/types/engine-settings'+import {+ engineSettingsKey,+ useEngineSettingsStore,+ watchEngineSettings+} from '@/ui/stores/engine-settings.store'+import { useConnectionStore } from '@/ui/stores/connection.store'+import { usePendingActionsStore } from '@/ui/stores/pending-actions.store'+import { ConfirmModal } from '@/ui/components/ConfirmModal'+import getErrorString from '@/shared/utils/get-error-string'+import { engineManagerName } from '@/shared/utils/engines'++interface Draft {+ serverPort: string+ proxyPort: string+ launchText: string+}+const asDraft = (config: EngineSettingsConfig): Draft => ({+ ...config,+ serverPort: String(config.serverPort),+ proxyPort: String(config.proxyPort)+})+const sameDraft = (a: Draft, b: Draft): boolean =>+ a.serverPort === b.serverPort && a.proxyPort === b.proxyPort && a.launchText === b.launchText++export function EngineSettingsSection({+ nodeId,+ engineType,+ disabled+}: {+ nodeId: string+ engineType: EngineType+ disabled: boolean+}) {+ const engine = engineManagerName(engineType)+ const target = { nodeId, engine }+ const entry = useEngineSettingsStore(state => state.entries[engineSettingsKey(target)])+ const snapshot = entry?.snapshot+ const connected = useConnectionStore(state => state.connected)+ const isLocalNode = useConnectionStore(state => state.selfId === nodeId)+ const [base, setBase] = useState<EngineSettingsSnapshot>()+ const [draft, setDraft] = useState<Draft>({ serverPort: '', proxyPort: '', launchText: '' })+ const [errorDialog, setErrorDialog] = useState('')+ const [confirmation, setConfirmation] = useState<EngineSettingsRequest>()+ const [checking, setChecking] = useState(false)+ const generation = useRef(0)+ // Response correlation, not loading state: which of this editor's requests+ // a terminal snapshot belongs to, so another editor's result never resets+ // this draft. Operation progress lives in the pending-actions store.+ const submitted = useRef('')+ const serverPortEdited = useRef(false)+ const dirty = !!base && !sameDraft(draft, asDraft(base.settings))+ const stale =+ !!base &&+ !!snapshot &&+ (base.revision !== snapshot.revision || base.epoch !== snapshot.epoch)+ const applying =+ usePendingActionsStore(state => state.isSettingsPending(nodeId, engineType)) ||+ snapshot?.phase === 'applying'+ const readOnly =+ !connected ||+ !!entry?.unavailable ||+ !snapshot?.editable ||+ snapshot.format !== 'pair-arguments-v1'+ const locked = readOnly || disabled || applying++ useEffect(() => watchEngineSettings(), [])+ useEffect(() => {+ generation.current+++ if (connected) void useEngineSettingsStore.getState().reload({ nodeId, engine })+ else useEngineSettingsStore.getState().disconnect()+ }, [nodeId, engine, connected])++ useEffect(() => {+ if (!snapshot) return+ const ownResult =+ !!submitted.current &&+ submitted.current === snapshot.requestId &&+ (snapshot.phase === 'succeeded' || snapshot.phase === 'failed')+ if (!base || !dirty || ownResult) {+ setBase(snapshot)+ setDraft(asDraft(snapshot.settings))+ if (ownResult) {+ submitted.current = ''+ if (snapshot.error) setErrorDialog(snapshot.error)+ }+ }+ }, [snapshot, base, dirty])++ function change(field: keyof Draft, value: string): void {+ generation.current+++ if (field === 'serverPort') serverPortEdited.current = true+ setDraft(current => ({ ...current, [field]: value }))+ }+ function reportError(message: string): void {+ generation.current+++ setChecking(false)+ setErrorDialog(message)+ }+ async function check(commit = false): Promise<void> {+ if (!base || locked || errorDialog || confirmation || checking) return+ if (stale) {+ if (commit)+ reportError('Settings changed elsewhere. Reload saved settings before applying.')+ return+ }+ const id = ++generation.current+ const serverPort = Number(draft.serverPort)+ const proxyPort = Number(draft.proxyPort)+ if (+ ![serverPort, proxyPort].every(+ port => Number.isInteger(port) && port >= 1 && port <= 65535+ )+ ) {+ if (commit) reportError('Enter ports from 1 to 65535.')+ return+ }+ if (commit) setChecking(true)+ const useServerPort = serverPortEdited.current+ const request: EngineSettingsRequest = {+ ...target,+ expectedRevision: base.revision,+ settings: { serverPort, proxyPort, launchText: draft.launchText },+ resolution: useServerPort ? 'server' : 'launch'+ }+ try {+ const result = await window.pairApi.engines.previewSettings(request)+ if (generation.current !== id) return+ if (result.conflict) {+ if (commit)+ reportError(+ 'The server ports do not match. Update the server port and try again.'+ )+ return+ }+ if (Object.keys(result.errors).length) {+ if (commit) reportError(Object.values(result.errors).join(' '))+ return+ }+ // Keep the user's command formatting unless the port field needs+ // to update it. Quiet blur validation never adds text or dialogs.+ setDraft(current => ({+ ...asDraft(result.settings),+ launchText: useServerPort ? result.settings.launchText : current.launchText+ }))+ serverPortEdited.current = false+ if (commit) {+ const confirmedRequest = {+ ...request,+ settings: result.settings,+ resolution: undefined,+ requestId: crypto.randomUUID()+ }+ if (result.restart) setConfirmation(confirmedRequest)+ else await apply(confirmedRequest)+ }+ } catch (cause) {+ if (commit && generation.current === id) reportError(getErrorString(cause))+ } finally {+ if (commit) setChecking(false)+ }+ }+ function reloadDraft(): void {+ generation.current+++ serverPortEdited.current = false+ if (snapshot) {+ setBase(snapshot)+ setDraft(asDraft(snapshot.settings))+ }+ setConfirmation(undefined)+ void useEngineSettingsStore.getState().reload(target)+ }+ async function apply(request: EngineSettingsRequest): Promise<void> {+ const requestId = request.requestId ?? crypto.randomUUID()+ submitted.current = requestId+ const pending = usePendingActionsStore.getState()+ // Hold the controls from the send until the backend's first snapshot+ // for this request, after which snapshot.phase is authoritative.+ pending.beginSettings(nodeId, engineType, requestId)+ try {+ await useEngineSettingsStore.getState().apply({ ...request, requestId })+ } catch (cause) {+ pending.endSettings(nodeId, engineType, requestId)+ reportError(getErrorString(cause))+ }+ }++ return (+ <details className="pair-accordion translucent-bg-accordion">+ <summary className="pair-accordion-summary">+ <Text kind="body/semibold/sm">Settings</Text>+ </summary>+ <Stack gap="3" className="p-3">+ {!applying && (entry?.unavailable || readOnly) && (+ <Text kind="body/regular/sm">+ {entry?.unavailable ||+ snapshot?.reason ||+ 'Waiting for this device’s settings. Older devices require an update to support editing.'}+ </Text>+ )}+ {!readOnly && !isLocalNode && (+ <Text kind="body/regular/sm">+ Ports and options can be changed from here. Managed CORS origin settings+ must be changed on the device running the engine.+ </Text>+ )}+ <Flex gap="3">+ <FormField slotLabel="Server port">+ <TextInput+ size="small"+ aria-label="Server port"+ value={draft.serverPort}+ onValueChange={value => change('serverPort', value)}+ onBlur={() => {+ if (dirty) void check()+ }}+ disabled={locked}+ inputMode="numeric"+ />+ </FormField>+ <FormField slotLabel="Proxy port">+ <TextInput+ size="small"+ aria-label="Proxy port"+ value={draft.proxyPort}+ onValueChange={value => change('proxyPort', value)}+ onBlur={() => {+ if (dirty) void check()+ }}+ disabled={locked}+ inputMode="numeric"+ />+ </FormField>+ </Flex>+ <FormField slotLabel="Engine arguments">+ <TextArea+ size="small"+ aria-label="Engine arguments"+ placeholder="Engine arguments; optional NAME=value assignments first"+ value={draft.launchText}+ onValueChange={value => change('launchText', value)}+ onBlur={() => {+ if (dirty) void check()+ }}+ resizeable="auto"+ rows={4}+ maxLength={16384}+ disabled={locked}+ className="font-mono"+ />+ </FormField>+ <Flex gap="2" justify="end">+ <Button kind="secondary" size="small" disabled={applying} onClick={reloadDraft}>+ {dirty || stale ? 'Reload saved settings' : 'Refresh'}+ </Button>+ <Button+ kind="primary"+ color="brand"+ size="small"+ disabled={locked || checking || (!dirty && snapshot?.phase !== 'failed')}+ className="relative"+ aria-label="Apply"+ aria-busy={applying || checking}+ // Keep focus in the field being edited. A primary-button+ // press would otherwise blur it first, and that blur+ // fires its own `check()` — the click then arrives while+ // `checking` is true and is dropped.+ onPointerDown={event => {+ if (event.button === 0) event.preventDefault()+ }}+ onClick={() => void check(true)}+ >+ <span className={applying || checking ? 'invisible' : undefined}>+ Apply+ </span>+ {(applying || checking) && (+ <span+ className="absolute inset-0 flex items-center justify-center"+ aria-hidden="true"+ >+ <span className="spinner-element-small" />+ </span>+ )}+ </Button>+ </Flex>+ </Stack>+ <ModalRoot+ open={!!errorDialog}+ onOpenChange={open => {+ if (!open) setErrorDialog('')+ }}+ >+ <ModalDialog>+ <ModalContent className="no-drag-elements max-content-modal">+ <ModalHeading>Could not apply engine settings</ModalHeading>+ <Stack gap="4">+ <Text kind="body/regular/sm" role="alert">+ {errorDialog}+ </Text>+ <Flex justify="end">+ <Button+ kind="primary"+ color="brand"+ size="small"+ onClick={() => setErrorDialog('')}+ >+ OK+ </Button>+ </Flex>+ </Stack>+ </ModalContent>+ </ModalDialog>+ </ModalRoot>+ <ConfirmModal+ open={!!confirmation}+ onOpenChange={open => {+ if (!open) setConfirmation(undefined)+ }}+ title="Restart engine?"+ confirmLabel="Restart"+ message="Applying these arguments will restart your engine, continue?"+ onConfirm={() => {+ if (confirmation) void apply(confirmation)+ }}+ />+ </details>+ )+}diff --git a/desktop/src/ui/components/BackendRow/PortRow.tsx b/desktop/src/ui/components/BackendRow/PortRow.tsxdeleted file mode 100644index 4e4bacf..0000000--- a/desktop/src/ui/components/BackendRow/PortRow.tsx+++ /dev/null@@ -1,51 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--import { Flex, Stack, Text, TextInput } from '@nvidia/foundations-react-core'--export function PortRow({- label,- port,- disabled,- onPortChange,- readOnly-}: {- label: string- port: string- /** Unused when `readOnly`. Disables the input while a port op is in flight. */- disabled?: boolean- /** Unused when `readOnly`. */- onPortChange?: (value: string) => void- /** Render the value as static text (no input) — e.g. a remote node's ports. */- readOnly?: boolean-}) {- const controls = readOnly ? (- // Match the editable input's height (size="small" ≈ 30px) so a static- // value lines up vertically with an adjacent editable field.- <Flex align="center" style={{ minHeight: 30 }}>- <Text kind="body/semibold/sm">{port || '—'}</Text>- </Flex>- ) : (- <TextInput- value={port}- onValueChange={onPortChange}- disabled={disabled}- size="small"- className="w-18 min-w-18"- />- )-- if (!label) {- return controls- }-- return (- <Stack gap="1">- <Text kind="body/regular/sm" style={{ minWidth: 42 }}>- {label}- </Text>-- {controls}- </Stack>- )-}diff --git a/desktop/src/ui/components/BackendRow/PortsSection.tsx b/desktop/src/ui/components/BackendRow/PortsSection.tsxdeleted file mode 100644index 353ac45..0000000--- a/desktop/src/ui/components/BackendRow/PortsSection.tsx+++ /dev/null@@ -1,48 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--import { Text } from '@nvidia/foundations-react-core'-import { BackendPorts } from './BackendPorts'-import { EditState } from '@/ui/types/engine-edit-state'-import type { EngineCaps } from '@/ui/types/engine-manifest'--export function PortsSection({- edit,- portsChanged,- anyLoading,- isLocalNode,- caps,- onApplyPorts,- onServerChange,- onProxyChange-}: {- edit: EditState- portsChanged: boolean- anyLoading: boolean- isLocalNode: boolean- caps: EngineCaps- onApplyPorts: () => void- onServerChange: (v: string) => void- onProxyChange: (v: string) => void-}) {- return (- <details className="pair-accordion translucent-bg-accordion">- <summary className="pair-accordion-summary">- <Text kind="body/semibold/sm">Ports</Text>- </summary>- <div className="p-3">- <BackendPorts- proxyPort={edit.proxyPort}- serverPort={edit.serverPort}- changed={portsChanged}- disabled={anyLoading}- isLocalNode={isLocalNode}- showServerPort={caps.hasEnginePort}- onServerChange={onServerChange}- onProxyChange={onProxyChange}- onApply={onApplyPorts}- />- </div>- </details>- )-}diff --git a/desktop/src/ui/components/NodeList/NodeEnginesInline.tsx b/desktop/src/ui/components/NodeList/NodeEnginesInline.tsxindex b8a909d..8dfafe4 100644--- a/desktop/src/ui/components/NodeList/NodeEnginesInline.tsx+++ b/desktop/src/ui/components/NodeList/NodeEnginesInline.tsx@@ -114,31 +114,32 @@ export default function NodeEnginesInline({ nodeId }: { nodeId: string }) {gap="2"className="shrink-0 no-drag-elements pair-engines-inline">- {isTransitioning ? (- <span- className="spinner-element-medium ml-2"- role="status"- aria-label=""- />- ) : (- <Switch- size="small"- checked={b.status === 'running'}- onCheckedChange={() => handleToggle(b.type)}- disabled={isRemote && isDisconnected}- title={- isRemote && isDisconnected- ? 'Node is disconnected'- : `${b.status === 'running' ? 'Stop' : 'Start'} ${b.name}`- }- className="-mr-1"- aria-label={- isRemote && isDisconnected- ? 'Node is disconnected'- : `${b.status === 'running' ? 'Stop' : 'Start'} ${b.name}`- }- />- )}+ <Flex align="center" justify="center" className="h-4 w-7 shrink-0 -mr-1">+ {isTransitioning ? (+ <span+ className="spinner-element-medium"+ role="status"+ aria-label=""+ />+ ) : (+ <Switch+ size="small"+ checked={b.status === 'running'}+ onCheckedChange={() => handleToggle(b.type)}+ disabled={isRemote && isDisconnected}+ title={+ isRemote && isDisconnected+ ? 'Node is disconnected'+ : `${b.status === 'running' ? 'Stop' : 'Start'} ${b.name}`+ }+ aria-label={+ isRemote && isDisconnected+ ? 'Node is disconnected'+ : `${b.status === 'running' ? 'Stop' : 'Start'} ${b.name}`+ }+ />+ )}+ </Flex><Textkind="body/regular/sm"className="cursor-pointer"diff --git a/desktop/src/ui/stores/engine-settings.store.ts b/desktop/src/ui/stores/engine-settings.store.tsnew file mode 100644index 0000000..a6a6eb7--- /dev/null+++ b/desktop/src/ui/stores/engine-settings.store.ts@@ -0,0 +1,128 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++import { create } from 'zustand'+import type {+ EngineSettingsRequest,+ EngineSettingsSnapshot,+ EngineSettingsTarget+} from '@/shared/types/engine-settings'+import getErrorString from '@/shared/utils/get-error-string'++export const engineSettingsKey = (target: EngineSettingsTarget): string =>+ `${target.nodeId}:${target.engine}`++interface SettingsEntry {+ snapshot?: EngineSettingsSnapshot+ unavailable?: string+ arrival: number+}+interface SettingsStore {+ entries: Record<string, SettingsEntry>+ receive: (snapshot: EngineSettingsSnapshot) => void+ disconnect: (nodeId?: string) => void+ reload: (target: EngineSettingsTarget) => Promise<void>+ apply: (request: EngineSettingsRequest) => Promise<void>+}++export const useEngineSettingsStore = create<SettingsStore>((set, get) => ({+ entries: {},+ receive: snapshot => {+ const key = engineSettingsKey(snapshot)+ const current = get().entries[key]+ if (+ current?.snapshot?.epoch === snapshot.epoch &&+ (current.snapshot.sequence > snapshot.sequence ||+ (current.snapshot.sequence === snapshot.sequence && !current.unavailable))+ )+ return+ set(state => ({+ entries: {+ ...state.entries,+ [key]: { snapshot, arrival: (current?.arrival ?? 0) + 1 }+ }+ }))+ },+ disconnect: nodeId =>+ set(state => ({+ entries: Object.fromEntries(+ Object.entries(state.entries).map(([key, entry]) => [+ key,+ !nodeId || key.startsWith(`${nodeId}:`)+ ? {+ ...entry,+ unavailable: 'Device disconnected. Reconnect to edit settings.',+ arrival: entry.arrival + 1+ }+ : entry+ ])+ )+ })),+ reload: async target => {+ const key = engineSettingsKey(target)+ const arrival = get().entries[key]?.arrival ?? 0+ try {+ const snapshot = await window.pairApi.engines.getSettings(target)+ // A push/disconnect after this read began wins, including a new authority epoch.+ if ((get().entries[key]?.arrival ?? 0) !== arrival) return+ get().receive({ ...snapshot, nodeId: target.nodeId })+ set(state => ({+ entries: {+ ...state.entries,+ [key]: { ...state.entries[key], unavailable: undefined }+ }+ }))+ } catch (error) {+ if ((get().entries[key]?.arrival ?? 0) !== arrival) return+ set(state => ({+ entries: {+ ...state.entries,+ [key]: {+ ...state.entries[key],+ arrival,+ unavailable: `Settings unavailable: ${getErrorString(error)}`+ }+ }+ }))+ }+ },+ apply: async request => {+ try {+ // Receipts acknowledge operations; only a full snapshot updates+ // durable state, and engines:settings-changed delivers that on its+ // own. Re-reading here would just race the push.+ await window.pairApi.engines.applySettings(request)+ } catch (error) {+ // A transport failure leaves no push to wait for, so read back+ // whatever the device can still report — including nothing.+ await get().reload(request)+ throw error+ }+ }+}))++let consumers = 0+let unsubscribe: Array<() => void> = []+/** Subscribe before fetching a baseline. All open editors share one push listener. */+export function watchEngineSettings(): () => void {+ if (consumers++ === 0)+ unsubscribe = [+ window.pairApi.engines.onSettingsChanged(snapshot =>+ useEngineSettingsStore.getState().receive(snapshot)+ ),+ window.pairApi.engines.onSettingsDisconnected(({ nodeId }) =>+ useEngineSettingsStore.getState().disconnect(nodeId)+ )+ ]+ // Closing the last editor says nothing about any device, so cached+ // snapshots stay as they are. `disconnect` is reserved for a real+ // engines:settings-disconnected push and for losing the service+ // connection. An editor unmounts whenever its engine starts installing,+ // so flagging every node here would mislabel the whole cluster.+ return () => {+ if (--consumers === 0) {+ unsubscribe.forEach(stop => stop())+ unsubscribe = []+ }+ }+}diff --git a/desktop/src/ui/stores/pending-actions.store.ts b/desktop/src/ui/stores/pending-actions.store.tsindex c5e2497..4b1e1a2 100644--- a/desktop/src/ui/stores/pending-actions.store.ts+++ b/desktop/src/ui/stores/pending-actions.store.ts@@ -32,7 +32,7 @@ import { EngineCapabilities } from '@/ui/constants/engine-capabilities'import type { EngineCommandPayload, EngineCommandType } from '@/shared/types/engine-api'import type { EngineProcessStatus, EngineType } from '@/shared/types/engines'import type { ServiceStatus } from '@/shared/types/ipc-channels'-import { isEngineType } from '@/shared/utils/engines'+import { engineTypeFromManagerName, isEngineType } from '@/shared/utils/engines'import { useEngineStatusStore } from '@/ui/stores/engine-status.store'/** Re-enable a control after this long if no superseding push ever arrives. */@@ -69,11 +69,29 @@ const MODEL_COMMANDS: ReadonlySet<EngineCommandType> = new Set<EngineCommandType'deleteModel'])+/**+ * Operations this store covers. Applying engine settings travels its own+ * `engines:apply-settings` channel rather than `engine:command`, but it needs+ * the same cover between the click and the backend's first push, so it is+ * tracked here instead of growing a second optimistic mechanism.+ */+type PendingOperation = EngineCommandType | 'applySettings'++/**+ * Read a stored operation back as an engine command. A settings apply keeps its+ * own key and is read through `isSettingsPending`, so it can never appear under+ * a lifecycle or model key.+ */+function asCommand(action: PendingOperation | undefined): EngineCommandType | undefined {+ return action === undefined || action === 'applySettings' ? undefined : action+}+interface PendingAction {nodeId: stringengineType: EngineType- action: EngineCommandType+ action: PendingOperationmodel?: string+ requestId?: string/*** Engine process status captured when a lifecycle command fired. The entry* clears on the first `engines:state-changed` whose status differs from@@ -106,6 +124,10 @@ function modelKey(nodeId: string, engineType: EngineType, model: string): stringreturn `${nodeId}:${engineType}:model:${model}`}+function settingsKey(nodeId: string, engineType: EngineType): string {+ return `${nodeId}:${engineType}:settings`+}+interface PendingActionsState {pending: Map<string, PendingAction>/** Record an optimistic pending entry for a fired command. No-op for non-lifecycle/non-model commands. */@@ -118,6 +140,16 @@ interface PendingActionsState {engineType: EngineType,model: string): EngineCommandType | undefined+ /**+ * Cover an engine settings apply from the click until the backend's first+ * snapshot for it. From there `snapshot.phase === 'applying'` is authoritative,+ * so this entry only has to outlast one round trip.+ */+ beginSettings(nodeId: string, engineType: EngineType, requestId: string): void+ /** Release the cover when validation refuses the change before it is sent. */+ endSettings(nodeId: string, engineType: EngineType, requestId: string): void+ /** Whether a settings apply is in flight and not yet reflected in a snapshot. */+ isSettingsPending(nodeId: string, engineType: EngineType): booleaninitialize(): voidcleanup(): void}@@ -175,10 +207,33 @@ export const usePendingActionsStore = create<PendingActionsState>((set, get) =>},getLifecyclePending: (nodeId, engineType) =>- get().pending.get(lifecycleKey(nodeId, engineType))?.action,+ asCommand(get().pending.get(lifecycleKey(nodeId, engineType))?.action),getModelPending: (nodeId, engineType, model) =>- get().pending.get(modelKey(nodeId, engineType, model))?.action,+ asCommand(get().pending.get(modelKey(nodeId, engineType, model))?.action),++ beginSettings: (nodeId, engineType, requestId) => {+ if (connectorStatus === 'disconnected') return+ const next = new Map(get().pending)+ next.set(settingsKey(nodeId, engineType), {+ nodeId,+ engineType,+ action: 'applySettings',+ requestId,+ expiresAt: Date.now() + PENDING_TIMEOUT_MS+ })+ set({ pending: next })+ },++ endSettings: (nodeId, engineType, requestId) => {+ const key = settingsKey(nodeId, engineType)+ if (get().pending.get(key)?.requestId !== requestId) return+ const next = new Map(get().pending)+ next.delete(key)+ set({ pending: next })+ },++ isSettingsPending: (nodeId, engineType) => get().pending.has(settingsKey(nodeId, engineType)),initialize: () => {// Guard against double-subscribe: initialize() runs on connect and again@@ -242,6 +297,13 @@ export const usePendingActionsStore = create<PendingActionsState>((set, get) =>if (!progress.model) returnclearKeys([modelKey(progress.nodeId, progress.engineType, progress.model)])}),+ window.pairApi.engines.onSettingsChanged(snapshot => {+ // The snapshot's own phase takes over from here.+ const engineType = engineTypeFromManagerName(snapshot.engine)+ if (!engineType) return+ const key = settingsKey(snapshot.nodeId, engineType)+ if (get().pending.get(key)?.requestId === snapshot.requestId) clearKeys([key])+ }),window.pairApi.errors.onUpdate(errors => {const toClear: string[] = []for (const e of errors) {diff --git a/desktop/src/ui/types/engine-edit-state.ts b/desktop/src/ui/types/engine-edit-state.tsdeleted file mode 100644index 67229c4..0000000--- a/desktop/src/ui/types/engine-edit-state.ts+++ /dev/null@@ -1,7 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--export type EditState = {- serverPort: string- proxyPort: string-}diff --git a/desktop/src/ui/utils/welcome-install.ts b/desktop/src/ui/utils/welcome-install.tsindex 490e76a..e1b897a 100644--- a/desktop/src/ui/utils/welcome-install.ts+++ b/desktop/src/ui/utils/welcome-install.ts@@ -3,9 +3,20 @@import type { ServiceError } from '@/shared/types/errors'import type { EngineProcessStatus, EngineStatusData, EngineType } from '@/shared/types/engines'+import { engineTypeFromManagerName, isEngineType } from '@/shared/utils/engines'type WelcomeInstallOutcome = 'pending' | 'complete' | 'failed'+/**+ * A `ServiceError.engineType` reaches us in either spelling: the backend stamps+ * the engine-manager id, while errors PAIR raises itself already use+ * `EngineType`. Null for an absent or unrecognized engine.+ */+function errorEngineType(value: string | undefined): EngineType | null {+ if (!value) return null+ return engineTypeFromManagerName(value) ?? (isEngineType(value) ? value : null)+}+export function isWelcomeEngineInstalled(status: EngineProcessStatus | undefined): boolean {return status === 'running' || status === 'stopped'}@@ -60,8 +71,8 @@ export function targetForInstallError(error: ServiceError,targets: readonly EngineType[]): EngineType | null {- const explicit = error.engineType === 'lmstudio' ? 'lm-studio' : error.engineType- if (explicit && targets.includes(explicit as EngineType)) return explicit as EngineType+ const explicit = errorEngineType(error.engineType)+ if (explicit && targets.includes(explicit)) return explicitconst text = `${error.id} ${error.message}`.toLowerCase()return (@@ -82,8 +93,9 @@ export function isTargetInstallError(targets: readonly EngineType[]): boolean {if (error.nodeId && error.nodeId !== nodeId) return false- const errorEngine = error.engineType === 'lmstudio' ? 'lm-studio' : error.engineType- if (errorEngine && !targets.includes(errorEngine as EngineType)) return false+ // An engine we cannot resolve is not one of the targets either.+ const errorEngine = errorEngineType(error.engineType)+ if (error.engineType && (!errorEngine || !targets.includes(errorEngine))) return falsereturn (error.operation === 'install' ||error.id.toLowerCase().includes('install') ||diff --git a/desktop/tests/modular/engine-port-timeout.test.ts b/desktop/tests/modular/engine-port-timeout.test.tsdeleted file mode 100644index 0c4631e..0000000--- a/desktop/tests/modular/engine-port-timeout.test.ts+++ /dev/null@@ -1,99 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--import { beforeEach, describe, expect, it, vi } from 'vitest'--const mocks = vi.hoisted(() => ({- state: {- getSelfId: vi.fn(() => 'local-node'),- getProxyPort: vi.fn(() => 11434),- beginLocalEngineOp: vi.fn(),- failLocalEngineOp: vi.fn()- },- supervisor: {- hasProcess: vi.fn(() => true),- callProcess: vi.fn(),- callProxy: vi.fn(),- sendProcess: vi.fn(),- reportError: vi.fn()- }-}))--vi.mock('@/electron/service-bridge/modular-supervisor', () => ({- getModularSupervisor: () => mocks.supervisor-}))-vi.mock('@/electron/service-bridge/modular-state', () => ({- getModularBridgeState: () => mocks.state,- isProxyEngine: (value: string) => value === 'ollama' || value === 'lm-studio',- isUpstreamUnreachableError: () => false,- parseServiceErrors: () => []-}))-vi.mock('@/electron/model-hub', () => ({ getEngineHubModels: vi.fn() }))--import { handleServiceBridgeInvoke } from '@/electron/service-bridge/empty-handlers'-import { MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS } from '@/shared/constants/modular-runtime'--describe('engine port lifecycle timeout', () => {- beforeEach(() => {- vi.clearAllMocks()- mocks.state.getSelfId.mockReturnValue('local-node')- mocks.state.getProxyPort.mockReturnValue(11434)- mocks.supervisor.hasProcess.mockReturnValue(true)- mocks.supervisor.callProcess.mockResolvedValue({})- mocks.supervisor.callProxy.mockResolvedValue({})- })-- it('keeps a single engine-port rebind outside the backend readiness budget', async () => {- await handleServiceBridgeInvoke('engine:command', {- command: 'setPorts',- engineType: 'ollama',- nodeId: 'local-node',- enginePort: 11435- })-- await vi.waitFor(() =>- expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(- 'broker',- 'engine:set-port',- { engine: 'ollama', port: 11435 },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- )- expect(MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS).toBe(11 * 60_000)- })-- it('uses the same bounded allowance across a collision-safe stop, rebind, and restart', async () => {- mocks.supervisor.callProcess.mockImplementation(async (_name: string, method: string) =>- method === 'engine:status' ? { running: true, port: 1235 } : {}- )-- await handleServiceBridgeInvoke('engine:command', {- command: 'setPorts',- engineType: 'ollama',- nodeId: 'local-node',- enginePort: 11434,- proxyPort: 1235- })-- await vi.waitFor(() =>- expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(- 'broker',- 'engine:start',- { engine: 'ollama' },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- )- expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(- 'broker',- 'engine:stop',- { engine: 'ollama' },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(- 'broker',- 'engine:set-port',- { engine: 'ollama', port: 11434 },- MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS- )- })-})diff --git a/desktop/tests/modular/engine-settings-bridge.test.ts b/desktop/tests/modular/engine-settings-bridge.test.tsnew file mode 100644index 0000000..c356ab4--- /dev/null+++ b/desktop/tests/modular/engine-settings-bridge.test.ts@@ -0,0 +1,116 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++import { beforeEach, describe, expect, it, vi } from 'vitest'++const mocks = vi.hoisted(() => ({+ state: {+ getSelfId: vi.fn(() => 'local-node'),+ getProxyPort: vi.fn(() => 11434),+ beginLocalEngineOp: vi.fn(),+ failLocalEngineOp: vi.fn()+ },+ supervisor: {+ hasProcess: vi.fn(() => true),+ callProcess: vi.fn(),+ callProxy: vi.fn(),+ sendProcess: vi.fn(),+ reportError: vi.fn()+ }+}))++vi.mock('@/electron/service-bridge/modular-supervisor', () => ({+ getModularSupervisor: () => mocks.supervisor+}))+vi.mock('@/electron/service-bridge/modular-state', () => ({+ getModularBridgeState: () => mocks.state,+ isProxyEngine: (value: string) => value === 'ollama' || value === 'lm-studio',+ isUpstreamUnreachableError: () => false,+ parseServiceErrors: () => []+}))+vi.mock('@/electron/model-hub', () => ({ getEngineHubModels: vi.fn() }))++import { handleServiceBridgeInvoke } from '@/electron/service-bridge/empty-handlers'+import { MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS } from '@/shared/constants/modular-runtime'++const baseline = {+ nodeId: 'local-node',+ engine: 'ollama',+ revision: 4,+ appliedRevision: 4,+ epoch: 'epoch',+ sequence: 1,+ phase: 'idle',+ format: 'pair-arguments-v1',+ settings: { serverPort: 1235, proxyPort: 11434, launchText: 'managed serve' },+ effectiveServerPort: 1235,+ effectiveProxyPort: 11434,+ running: true,+ adopted: false,+ editable: true+}++describe('unified settings bridge', () => {+ beforeEach(() => {+ vi.clearAllMocks()+ mocks.supervisor.callProcess.mockImplementation(async (_name: string, method: string) =>+ method === 'engine:get-settings' ? baseline : { revision: 5, phase: 'succeeded' }+ )+ })++ // Applying settings can stop, rebind, and restart an engine, so it needs+ // the lifecycle deadline rather than the default request timeout.+ it('sends one node-owned apply with a lifecycle deadline', async () => {+ const receipt = await handleServiceBridgeInvoke('engines:apply-settings', {+ nodeId: 'local-node',+ engine: 'ollama',+ expectedRevision: 4,+ requestId: 'request',+ settings: { serverPort: 11434, proxyPort: 1235, launchText: 'managed serve' }+ })+ expect(receipt).toEqual({ revision: 5, phase: 'succeeded' })+ expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(+ 'broker',+ 'engine:apply-settings',+ expect.objectContaining({+ engine: 'ollama',+ expectedRevision: 4,+ settings: { serverPort: 11434, proxyPort: 1235, launchText: 'managed serve' }+ }),+ MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS+ )+ expect(mocks.supervisor.callProxy).not.toHaveBeenCalled()+ expect(mocks.supervisor.callProcess.mock.calls.map(call => call[1])).toEqual([+ 'engine:apply-settings'+ ])+ })++ it('addresses a remote node through the same broker relay', async () => {+ await handleServiceBridgeInvoke('engines:apply-settings', {+ nodeId: 'remote-node',+ engine: 'ollama',+ expectedRevision: 4,+ requestId: 'request',+ settings: { ...baseline.settings, proxyPort: 12000 }+ })+ expect(mocks.supervisor.callProcess).toHaveBeenCalledWith(+ 'broker',+ 'engine:apply-settings',+ expect.objectContaining({+ nodeId: 'remote-node',+ settings: { ...baseline.settings, proxyPort: 12000 }+ }),+ MODULAR_ENGINE_LIFECYCLE_CALL_TIMEOUT_MS+ )+ })++ it('validates full snapshots and reports unsupported older devices', async () => {+ mocks.supervisor.callProcess.mockResolvedValue({})+ await expect(+ handleServiceBridgeInvoke('engines:get-settings', {+ nodeId: 'remote',+ engine: 'ollama'+ })+ ).rejects.toThrow()+ })+})diff --git a/desktop/tests/modular/engine-settings-state.test.ts b/desktop/tests/modular/engine-settings-state.test.tsnew file mode 100644index 0000000..b07a31c--- /dev/null+++ b/desktop/tests/modular/engine-settings-state.test.ts@@ -0,0 +1,243 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import {+ useEngineSettingsStore,+ engineSettingsKey,+ watchEngineSettings+} from '@/ui/stores/engine-settings.store'+import { usePendingActionsStore } from '@/ui/stores/pending-actions.store'+import type { EngineSettingsSnapshot } from '@/shared/types/engine-settings'+import { redactSensitiveLogText } from '@/electron/redact-log'++const target = { nodeId: 'remote', engine: 'ollama' } as const+const baseline: EngineSettingsSnapshot = {+ ...target,+ revision: 1,+ appliedRevision: 1,+ epoch: 'one',+ sequence: 1,+ settings: { serverPort: 1235, proxyPort: 11434, launchText: 'managed serve' },+ effectiveServerPort: 1235,+ effectiveProxyPort: 11434,+ running: true,+ adopted: false,+ editable: true,+ reason: '',+ format: 'pair-arguments-v1',+ phase: 'idle',+ error: '',+ requestId: ''+}+const key = engineSettingsKey(target)+const store = useEngineSettingsStore+const getSettings = vi.fn()+const applySettings = vi.fn()++describe('engine settings snapshot ordering and pending operations', () => {+ beforeEach(() => {+ store.setState({ entries: {} })+ vi.stubGlobal('window', { pairApi: { engines: { getSettings, applySettings } } })+ getSettings.mockResolvedValue(baseline)+ applySettings.mockResolvedValue({ revision: 2, phase: 'succeeded' })+ })+ afterEach(() => vi.unstubAllGlobals())++ it('ignores older frames and marks identical reconnect baselines available', () => {+ store.getState().receive({ ...baseline, sequence: 3, revision: 2 })+ store.getState().receive(baseline)+ expect(store.getState().entries[key].snapshot?.revision).toBe(2)+ store.getState().disconnect('remote')+ expect(store.getState().entries[key].unavailable).toBeTruthy()+ store.getState().receive({ ...baseline, sequence: 3, revision: 2 })+ expect(store.getState().entries[key].unavailable).toBeUndefined()+ })++ it('a newer push epoch beats a delayed initial read', async () => {+ let finish: (snapshot: EngineSettingsSnapshot) => void = () => {}+ getSettings.mockImplementationOnce(+ () =>+ new Promise<EngineSettingsSnapshot>(resolve => {+ finish = resolve+ })+ )+ const loading = store.getState().reload(target)+ store.getState().receive({ ...baseline, epoch: 'two', revision: 9 })+ finish(baseline)+ await loading+ expect(store.getState().entries[key].snapshot?.epoch).toBe('two')+ })++ it('acknowledgement alone cannot fabricate an applied snapshot', async () => {+ store.getState().receive(baseline)+ await store.getState().apply({+ ...target,+ expectedRevision: 1,+ requestId: 'request',+ settings: { ...baseline.settings, launchText: 'different' }+ })+ expect(store.getState().entries[key].snapshot?.revision).toBe(1)+ // The settings push carries the applied snapshot; re-reading here would+ // only race it.+ expect(getSettings).not.toHaveBeenCalled()+ })++ it('a failed transport reads back and exposes unavailable status', async () => {+ applySettings.mockRejectedValueOnce(new Error('disconnected'))+ getSettings.mockRejectedValueOnce(new Error('offline'))+ await expect(+ store.getState().apply({+ ...target,+ expectedRevision: 1,+ requestId: 'request',+ settings: baseline.settings+ })+ ).rejects.toThrow('disconnected')+ expect(store.getState().entries[key].unavailable).toContain('offline')+ })++ it('shares subscriptions and releases them when the last editor closes', () => {+ const stop = vi.fn()+ const subscribe = vi.fn(() => stop)+ vi.stubGlobal('window', {+ pairApi: {+ engines: { onSettingsChanged: subscribe, onSettingsDisconnected: subscribe }+ }+ })+ const a = watchEngineSettings(),+ b = watchEngineSettings()+ expect(subscribe).toHaveBeenCalledTimes(2)+ a()+ expect(stop).not.toHaveBeenCalled()+ b()+ expect(stop).toHaveBeenCalledTimes(2)+ })++ it('closing an editor leaves other devices editable and resubscribes on reopen', () => {+ const receivers: Array<(snapshot: EngineSettingsSnapshot) => void> = []+ vi.stubGlobal('window', {+ pairApi: {+ engines: {+ onSettingsChanged: (fn: (snapshot: EngineSettingsSnapshot) => void) => {+ receivers.push(fn)+ return () => {}+ },+ onSettingsDisconnected: () => () => {}+ }+ }+ })+ store.getState().receive(baseline)+ // An engine that starts installing unmounts its own editor; that must+ // not report every device in the cluster as disconnected.+ watchEngineSettings()()+ expect(store.getState().entries[key].unavailable).toBeUndefined()+ expect(store.getState().entries[key].snapshot?.revision).toBe(1)++ const reopened = watchEngineSettings()+ receivers.at(-1)?.({ ...baseline, sequence: 2, revision: 4 })+ expect(store.getState().entries[key].snapshot?.revision).toBe(4)+ expect(store.getState().entries[key].unavailable).toBeUndefined()+ reopened()+ })+})++describe('settings applies use the shared pending-actions cover', () => {+ let deliver: (snapshot: EngineSettingsSnapshot) => void = () => {}++ beforeEach(() => {+ const noop = (): void => {}+ vi.stubGlobal('window', {+ pairApi: {+ engines: {+ onStateChanged: () => noop,+ onProgress: () => noop,+ onSettingsChanged: (fn: (snapshot: EngineSettingsSnapshot) => void) => {+ deliver = fn+ return noop+ }+ },+ errors: { onUpdate: () => noop }+ }+ })+ usePendingActionsStore.getState().initialize()+ })+ afterEach(() => {+ usePendingActionsStore.getState().cleanup()+ vi.unstubAllGlobals()+ })++ it('holds from the send until the first snapshot, then yields to phase', () => {+ const pending = usePendingActionsStore.getState()+ expect(pending.isSettingsPending('remote', 'ollama')).toBe(false)++ pending.beginSettings('remote', 'ollama', 'current-request')+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'ollama')).toBe(true)++ // Another engine on the same device is untouched.+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'lm-studio')).toBe(+ false+ )++ deliver({ ...baseline, phase: 'applying', requestId: 'older-request' })+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'ollama')).toBe(true)+ deliver({ ...baseline, phase: 'idle' })+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'ollama')).toBe(true)+ deliver({ ...baseline, phase: 'applying', requestId: 'current-request' })+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'ollama')).toBe(false)+ })++ it('releases the cover when validation refuses before sending', () => {+ const pending = usePendingActionsStore.getState()+ pending.beginSettings('remote', 'lm-studio', 'current-request')+ pending.endSettings('remote', 'lm-studio', 'older-request')+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'lm-studio')).toBe(+ true+ )+ pending.endSettings('remote', 'lm-studio', 'current-request')+ expect(usePendingActionsStore.getState().isSettingsPending('remote', 'lm-studio')).toBe(+ false+ )+ })+})++describe('launch text redaction', () => {+ const frame = JSON.stringify({+ result: {+ settings: { launchText: 'exe --unknown private-value' },+ launch_args: ['private-value'],+ launch_env: ['VALUE=private-value']+ }+ })++ it('omits launch text, arguments, and environment from process logs', () => {+ expect(redactSensitiveLogText(frame)).not.toContain('private-value')+ })++ it('omits them from a frame truncated mid-value', () => {+ expect(redactSensitiveLogText(frame.slice(0, -1))).not.toContain('private-value')+ expect(+ redactSensitiveLogText('{"result":{"launch_env":["VALUE=private-value"')+ ).not.toContain('private-value')+ })++ it('still redacts the pairing PIN', () => {+ expect(redactSensitiveLogText('{"result":{"pin":"123456"}}')).not.toContain('123456')+ expect(redactSensitiveLogText('garbage {"pin": "123456"')).not.toContain('123456')+ })++ // A worker's own command line is what a support log is for, so the+ // redaction must not reach a generic args/env key.+ it('keeps worker spawn diagnostics intact', () => {+ const spawn = JSON.stringify({+ msg: 'spawning worker',+ bin: 'nvpair-node-scanner',+ args: ['--ipc', '--log-level=debug'],+ env: { NVPAIR_LOG: 'debug' }+ })+ expect(redactSensitiveLogText(spawn)).toBe(spawn)+ expect(redactSensitiveLogText('plain text with no json at all')).toBe(+ 'plain text with no json at all'+ )+ })+})diff --git a/desktop/tests/modular/install-state.test.ts b/desktop/tests/modular/install-state.test.tsindex 7f501af..0a89cc3 100644--- a/desktop/tests/modular/install-state.test.ts+++ b/desktop/tests/modular/install-state.test.ts@@ -20,6 +20,31 @@ afterEach(() => {})describe('LM Studio install state', () => {+ it.each(['lmstudio', 'lm-studio'])('clears failed operations for %s', engineId => {+ const state = getModularBridgeState()+ const statuses: EngineProcessStatus[] = []+ unsubscribe = subscribePush(event => {+ if (+ event.channel === 'engines:state-changed' &&+ event.payload.engineType === 'lm-studio' &&+ event.payload.status+ ) {+ statuses.push(event.payload.status.processStatus)+ }+ })+ state.setSelfId('local-node')+ state.applyEngineManagerStatus({+ engine: 'lmstudio',+ installed: false,+ running: false,+ port: 1234+ })+ state.beginLocalEngineOp('lm-studio', 'installing')+ expect(statuses.at(-1)).toBe('installing')+ state.failLocalEngineOp(engineId, 'install')+ expect(statuses.at(-1)).toBe('not-installed')+ })+it('does not revert a quiet install to Download after 90 seconds', () => {vi.useFakeTimers()const state = getModularBridgeState()diff --git a/desktop/tests/modular/pending-actions-delete.test.ts b/desktop/tests/modular/pending-actions-delete.test.tsindex 59e7c8c..fb1640d 100644--- a/desktop/tests/modular/pending-actions-delete.test.ts+++ b/desktop/tests/modular/pending-actions-delete.test.ts@@ -52,7 +52,8 @@ function makeFakeWindow() {stateCb = cbreturn noopUnsub},- onProgress: () => noopUnsub+ onProgress: () => noopUnsub,+ onSettingsChanged: () => noopUnsub},errors: {onUpdate: (cb: (errors: ServiceError[]) => void) => {diff --git a/desktop/tests/modular/pending-actions-service-down.test.ts b/desktop/tests/modular/pending-actions-service-down.test.tsindex 8cb778e..8b1d031 100644--- a/desktop/tests/modular/pending-actions-service-down.test.ts+++ b/desktop/tests/modular/pending-actions-service-down.test.ts@@ -20,7 +20,8 @@ function makeFakeWindow() {pairApi: {engines: {onStateChanged: () => noopUnsub,- onProgress: () => noopUnsub+ onProgress: () => noopUnsub,+ onSettingsChanged: () => noopUnsub},errors: {onUpdate: () => noopUnsubdiff --git a/desktop/tests/modular/redact-log.test.ts b/desktop/tests/modular/redact-log.test.tsindex 3215300..265554c 100644--- a/desktop/tests/modular/redact-log.test.ts+++ b/desktop/tests/modular/redact-log.test.ts@@ -71,12 +71,29 @@ describe('redactSensitiveLogText', () => {expect(redactSensitiveLogText(line)).toBe(line)})+ it.each([+ '{"launchText":"TOKEN=secret',+ '{"pin":"secret',+ '{"pin":123456',+ 'worker: {"launchText":"safe \\" secret',+ '{"launch_env":["VALUE=]secret",',+ '{"launch_args":[["secret"],',+ '{"launchText":"safe", "pin":"secret'+ ])('redacts sensitive tails of malformed frames: %s', frame => {+ const out = redactSensitiveLogText(frame)++ expect(out).not.toContain('secret')+ expect(out).not.toContain('123456')+ expect(out).toContain('[redacted]')+ })+it('is linear-time on hostile input', () => {const hostile = `{"pin":"${'a'.repeat(200_000)}`const start = performance.now()- redactSensitiveLogText(hostile)+ const out = redactSensitiveLogText(hostile)const elapsed = performance.now() - startexpect(elapsed).toBeLessThan(500)+ expect(out.includes('a'.repeat(100))).toBe(false)})})diff --git a/docs/architecture.mdx b/docs/architecture.mdxindex 5e3bca6..d49e4a3 100644--- a/docs/architecture.mdx+++ b/docs/architecture.mdx@@ -687,6 +687,11 @@ The important boundaries are:permissions. JSON-RPC has no independent per-message token.3. **Loopback HTTP.** Local clients can submit sensitive inference content.Listener addresses, browser access, CORS, and host account security matter.+ The proxies add no permissive CORS default: they pass the upstream engine's+ headers and its refusals through, so a web page reaches a model through PAIR+ only where the engine would have allowed it directly, and a cluster-wide+ request needs every engine that answered to allow the origin. Refer to+ [Engine settings](engine-settings.mdx) for allowing an origin.4. **LAN discovery and metadata.** The network can reveal service presence andselected host information. Some enrichment endpoints use plain HTTP.5. **Pairing bootstrap.** A six-digit PIN bootstraps certificate trust. It is adiff --git a/docs/engine-lifecycle.mdx b/docs/engine-lifecycle.mdxindex 81bf01d..0d49227 100644--- a/docs/engine-lifecycle.mdx+++ b/docs/engine-lifecycle.mdx@@ -11,8 +11,10 @@ install and run those engines for you, or work with a copy you already have.This page explains what you can expect when you install, start, stop, update, orremove an engine.-For first-time setup, refer to [Getting started](getting-started.mdx). If-something does not start, refer to [Troubleshooting](troubleshooting.mdx).+For first-time setup, refer to [Getting started](getting-started.mdx). To change+an engine's ports or launch command, refer to+[Engine settings](engine-settings.mdx). If something does not start, refer to+[Troubleshooting](troubleshooting.mdx).## Engine Requirementsdiff --git a/docs/engine-settings.mdx b/docs/engine-settings.mdxnew file mode 100644index 0000000..61ceb7e--- /dev/null+++ b/docs/engine-settings.mdx@@ -0,0 +1,111 @@+{/*+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+SPDX-License-Identifier: Apache-2.0+*/}++# Engine Settings in NVIDIA Personal AI Router++Open a device's Ollama or LM Studio row and expand **Settings**. Edit the server+port, proxy port and engine arguments, then select the green **Apply** button. A paired device+that supports settings can be edited from another device in the cluster.++PAIR fixes the executable, lifecycle commands and loopback address. Unsupported+vendor options can fail at startup.++For installing, starting and updating engines, refer to+[Managing engines](engine-lifecycle.mdx).++## Argument notation++The text contains engine arguments and optional leading environment assignments.+PAIR supplies the executable and startup subcommand. Leave the text empty to use+managed defaults. Tokens are passed directly to the engine, using the same+notation on every operating system.++- Spaces, tabs and line breaks separate unquoted tokens.+- Single quotes enclose literal text. Double quotes enclose literal text with+ two escapes, `\"` and `\\`; any other backslash stays literal, so a Windows+ path such as `C:\new\tools` needs no doubling.+- A quoted and an unquoted part can form one token, as in `--name="two words"`.+ An empty quoted string is an empty argument.+- Nothing is expanded: `$HOME`, `%USERPROFILE%`, `{port}` and `~` are literal,+ and there are no comments, pipelines, redirects or command substitution.+ Unquoted `|`, `&`, `;`, `<`, `>`, a backtick or `$(` is rejected — quote them+ when the engine really wants that character.+- At most 16 KiB and 256 tokens, valid UTF-8.++Environment assignments go first, followed by engine arguments:++```text+OLLAMA_ORIGINS="https://example.com"+--port 1235 --bind 127.0.0.1+```++## Environment variables++Environment assignments are saved and passed literally to the engine on every+launch. PAIR does not maintain a list of supported variables or validate their+engine-specific values. Editing or removing one takes effect at the next launch.++Managed CORS settings, including LM Studio's `--cors` switch, can only be changed+on the device running the engine. A paired device can preserve an existing CORS+policy while changing other settings, but cannot enable, disable or replace it.+Other environment assignments can also be edited from a paired device.++Origin lists need a scheme and a specific host, so bare `localhost` and `*` are+rejected, including wildcards hidden inside extra quotes. Wildcard subdomains+such as `https://*.example.com` and ports such as `http://localhost:*` are supported.+List the origins you want to allow. This is+how you give a web page access to your models: PAIR's local endpoints add no+permissive default of their own, so a browser reaches a model through PAIR only+where the engine would have allowed it directly. For a request that spans the+cluster, every engine that answers has to allow the origin.++An engine does not need a CORS launch option to work with PAIR. The proxy follows+the engine's HTTP responses regardless of how its CORS policy is configured.+If the engine grants no CORS permission, PAIR does not add permission for it.++Startup failures include a bounded excerpt of the engine’s own output. PAIR+redacts supplied values by exact match, but an engine may transform or encode+them. Do not put secrets in launch values.++## Ports and validation++PAIR understands only the networking controls needed to keep engine and proxy+configuration consistent:++| Engine | Server port | Loopback bind | Browser access |+| --- | --- | --- | --- |+| Ollama | `OLLAMA_HOST=127.0.0.1:<port>` | The host in `OLLAMA_HOST` | `OLLAMA_ORIGINS` |+| LM Studio | `--port`, `-p` | `--bind`, `LMS_SERVER_HOST` | `--cors` |++For LM Studio, `--port 1235`, `--port=1235`, `-p 1235`, `-p1235` and `-p=1235`+all synchronize the same server-port field. Conflicting repetitions and invalid+ports are rejected. Write managed short options separately; bundles containing+them are ambiguous and rejected. CORS switches do not take `=true` or `=false`:+add or remove the switch locally. Origin lists are normalized before validation;+conflicting repeated lists are rejected. Other vendor options remain opaque.++Changing the server-port field updates the port in the command. Editing the+command's port updates the numeric field. If both are edited before validation+finishes, the numeric field takes precedence. The server and proxy must use+different ports; a collision opens an error dialog explaining which port+collides. Invalid settings and failed saves also open an error dialog.++Apply validates the complete change. Confirmation is requested only when a running engine+needs to restart. Progress appears as a spinner inside Apply. A running engine+restarts for launch/server changes; changing only the proxy port leaves the+engine running. Stopped engines remain stopped. Saved settings survive restart.++## Concurrent edits++Changes from another device update a clean editor. An unfinished draft stays+intact; applying a stale draft opens an error dialog. **Reload saved settings** deliberately+discards that draft. Failed starts retain the saved settings for correction and+show one error dialog. Validation on leaving a field quietly synchronizes ports;+errors appear only when Apply is selected, without duplicate text below the command.++Offline, unpaired or older devices cannot be edited. A process started outside+PAIR may require stopping it in its own application before changing its launch.+The displayed arguments describe a future PAIR launch, not an external process's+original arguments.diff --git a/fern/docs.yml b/fern/docs.ymlindex 496b83c..956b988 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -31,6 +31,9 @@ navigation:- page: Managing Enginespath: ../docs/engine-lifecycle.mdxslug: engine-lifecycle+ - page: Engine Settings+ path: ../docs/engine-settings.mdx+ slug: engine-settings- page: Terminal Interfacepath: ../docs/terminal-interface.mdxslug: terminal-interfacediff --git a/scripts/spdx-headers.mjs b/scripts/spdx-headers.mjsindex 10e2585..5a293aa 100644--- a/scripts/spdx-headers.mjs+++ b/scripts/spdx-headers.mjs@@ -159,6 +159,14 @@ const SKIPPED_PATHS = [['scripts/collectlogs/testdata/', 'log fixtures the sanitizer tests compare byte for byte'],]+// Go writes a failing fuzz input to <pkg>/testdata/fuzz/<FuzzTarget>/<hash> and+// reads it back verbatim: the first line is a format version and the rest are+// typed literals, so a header would stop the seed from parsing. Matched on the+// path segment rather than added to SKIPPED_PATHS above because the entries are+// named by content hash — no extension or filename rule can describe them, and a+// rooted prefix would need repeating for every package that gains a fuzz target.+const FUZZ_CORPUS = /(^|\/)testdata\/fuzz\//+const LICENSE_TAG = /SPDX-License-Identifier:[ \t]*(\S+)/const COPYRIGHT_TAG = /SPDX-FileCopyrightText:[ \t]*(.+)/const COPYRIGHT_TEXT = /^Copyright \(c\) \d{4}(?:-\d{4})? (.+)$/@@ -168,6 +176,7 @@ function classify(path) {for (const [prefix, reason] of SKIPPED_PATHS) {if (path === prefix || path.startsWith(prefix)) return { skip: reason }}+ if (FUZZ_CORPUS.test(path)) return { skip: 'Go fuzz corpus entry, parsed verbatim by the fuzzing engine' }const name = path.slice(path.lastIndexOf('/') + 1)const dot = name.lastIndexOf('.')diff --git a/services/nvpair-engine-manager/LAUNCH_TEXT.md b/services/nvpair-engine-manager/LAUNCH_TEXT.mdnew file mode 100644index 0000000..12a59b9--- /dev/null+++ b/services/nvpair-engine-manager/LAUNCH_TEXT.md@@ -0,0 +1,169 @@+<!--+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+SPDX-License-Identifier: Apache-2.0+-->++# PAIR engine arguments++The Settings editor uses this notation for local and paired-device engine+configuration. Engine-manager assembles the manifest-owned command; the broker+coordinates its saved revision, proxy port and lifecycle as one operation.++## `pair-arguments-v1` notation++The same notation is used on every target OS. It represents tokens passed+directly to the engine, not a command to paste into a system shell.++- ASCII spaces, tabs and line breaks separate unquoted tokens.+- Single quotes enclose literal text. Double quotes enclose literal text with+ only two escapes: `\"` for a quote and `\\` for a backslash. Other backslashes+ remain literal, including those in a path such as `C:\new\tools`.+- Quoted and unquoted segments may form one token: `--name="two words"`.+ Empty quoted strings represent empty arguments. Quoted line breaks are literal.+- `$HOME`, `%USERPROFILE%`, `{port}` and `~` are not expanded by the parser.+ There are no shell comments, pipelines, redirects or command substitution.+ Unquoted `|`, `&`, `;`, `<`, `>`, backticks and `$(` are rejected. Such values+ can be quoted when they are literal engine arguments.+- Input must be valid UTF-8, at most 16 KiB, with at most 256 tokens.+ Control characters other than tab, CR and LF are rejected, including NUL.+ Errors describe the syntax problem without echoing the submitted text.+- Formatting sorts explicitly configured environment assignments by name, then+ writes the arguments. The executable and startup subcommand are never editable.+ Values are quoted deterministically; inherited environment variables are never+ included. Empty text selects managed defaults. Normalized text has the same+ size bound as input.++For example:++```text+OLLAMA_HOST=127.0.0.1:11435 OLLAMA_ORIGINS="https://example.com"+--port 1235 --bind 127.0.0.1 --future-option "two words"+```++The settings validator checks valid environment assignments, declared loopback+bind/CORS controls, managed port options and conflicts before accepting settings.+The executable and optional startup subcommand come from the trusted manifest.+The `--` terminator and vendor flags retain their token positions for that layer.+Unknown vendor option semantics are not decided by the tokenizer.++## Launch resolution boundary++`resolveProcessLaunch` returns the executable, argv and explicit environment+that `bringUpProcess` uses. `resolveCommandLaunch` returns the executable and+argv for each ordered command-mode start step. Existing trusted manifest+placeholder/path expansion is preserved. The builders do not mutate the+caller's resolution context.++User arguments are combined **after** trusted manifest expansion;+storing user text in `runtime.args` or `runtime.start` would interpret literal+placeholders and environment references. Settings persist literal extra tokens+in host-platform `runtime.launch_args` alongside the managed port. Explicit+editable environment assignments are stored as a replacement array in `runtime.launch_env`,+so editing or removing an assignment cannot leave an old value behind through+manifest merging. These values reach both process and command-mode launches+literally, overriding inherited values. An empty array clears prior explicit+editable assignments (inherited OS environment still applies). Environment names+are not allowlisted. Explicit assignments override manifest defaults, including+values such as Linux Ollama's `LD_LIBRARY_PATH`; omitted defaults are restored+from the manifest. Existing trusted `args`,+`start`, `env`, install and other-platform overrides are preserved.++## Managed fields and preview++`runtime.editable_launch` declares fixed startup arguments, an optional+command-mode `start_index`, and field-binding `controls`. A control describes+its flag/environment names, a `value` format and an optional `implicit` value+for flag presence. Binding syntax and policy are separate: the same parser reads+all formats, while four PAIR fields enforce port, loopback and CORS policy.+See [the schema and examples](MANIFEST.md#top-level-fields).++Ollama binds `OLLAMA_HOST` to `{server.host}:{server.port}` and+`OLLAMA_ORIGINS` to `{cors.origins}`. LM Studio binds `--port`/`-p` to+`{server.port}`, `--bind`/`LMS_SERVER_HOST` to `{server.host}`, and `--cors`+to `{cors.enabled}` with an implicit value of `true`. Managed network values+replace every declared environment alias and use the first flag as canonical+output for edited arguments. All CORS fields are local-only. Proxy ports are+owned and validated by the broker, independently of engine argument syntax.+The proxy always follows standard HTTP CORS responses, including absence of+permission, independently of how an engine configures that policy.+Environment assignments such as `OLLAMA_ORIGINS="http://localhost"` can be added,+edited or removed at the beginning of the text, before engine arguments. Names+use letters, digits and underscores and start with a letter or underscore; duplicate names are invalid+(case-insensitive on Windows). Values support spaces, empty strings and the+same literal quoting as arguments. Origin lists are normalized before validation+and storage, including extra surrounding quotes, scheme/host case and whitespace.+Each nonempty origin requires a scheme and specific host; wildcard subdomains+and ports are allowed, but universal origins, credentials, paths and remaining+quotes are rejected. Conflicting repeated origin lists are invalid. Environment values remain+quoted in normalized commands. `OLLAMA_HOST` continues to synchronize with+the server-port field. The editor contains no executable/subcommand. Removing+a managed option reinserts it. Equals-form ports and repeated identical ports+normalize to one managed value; conflicting duplicate ports are invalid.+Declared short aliases accept `-p 1235`, `-p1235` and `-p=1235`. Ambiguous+short-option bundles containing managed controls are rejected without guessing+unknown vendor options' arities. CORS switches accept no attached value; `--cors=false`+is rejected rather than interpreted differently from the engine.+Disagreement with the numeric field returns an explicit conflict unless the+caller supplies `resolution: "server"` or `"launch"`.+The editor supplies that resolution automatically: a changed server-port field+updates the command; otherwise the command's port updates the field. A final+server/proxy collision is rejected with an explicit collision error dialog.++Other vendor options and environment values pass through literally, including+unknown options, short options, configuration-file options and values that the+engine may reject. PAIR maintains no vendor-option catalog and performs no+type, range or compatibility checks for them. Only the adapter-declared networking and CORS controls+receive semantic validation; vendor support is determined at startup. There are+no guessed network aliases or nested-assignment checks. An adapter must identify+the controls PAIR manages; arbitrary vendor options remain opaque.+Changes to declared CORS origin lists, switches and explicit booleans are local to the engine's device; other+environment assignments can be edited through the same local or pinned-peer API.+On startup failure, PAIR returns a bounded tail of the engine output alongside+the exit/readiness failure. It does not classify vendor messages or interpret+options. Supplied positional/assignment values and explicit environment values+are redacted by exact match; engine-transformed values cannot be guaranteed to+match. Do not put secrets in launch values. Custom output is still excluded from+ongoing exported engine logs, and desktop subprocess logs redact launch text,+argument arrays and environment maps. Successful startup discards the capture.++The effective argv and explicit environment are revalidated immediately before+execution, so saved settings from older versions cannot bypass mandatory checks+on a later start.++The wire key remains `launchText`; snapshots identify the new notation with+`format: "pair-arguments-v1"`. Older clients stay read-only for an unknown format.+Existing component `launch_args`/`launch_env` need no migration. The broker+converts saved `pair-launch-v1` journal commands through the internal preview+request before displaying or replaying them, preserving pending arguments and+ports. The legacy executable check exists only on that conversion path.++The broker-facing internal methods are `engine:get-launch`,+`engine:preview-launch`, `engine:configured-ports` and+`engine:configure-launch`. UI/headless clients use the combined broker API+documented in [ENGINE_SETTINGS.md](../nvpair-ui-broker/ENGINE_SETTINGS.md).++Tests cover grammar and normalization, exact argv received by a real isolated+child process, both lifecycle modes, preservation of override fields, reset to+defaults, platform precedence and replacement of an existing settings file.+The existing engine-manager suite also exercises the JSON-RPC stdio path.++## Networking adapter coverage++The bundled engines are Ollama and LM Studio. The shared parser contains no engine+name checks. Their mandatory networking declarations and all platform variants+are pinned by TestBundledNetworkingControls; adding an engine requires extending+that inventory and reviewing its networking alternatives. Other settings have no catalog.++| Engine | Port/bind controls | CORS controls | Vendor reference |+| --- | --- | --- | --- |+| Ollama | OLLAMA_HOST | OLLAMA_ORIGINS, including vendor quote stripping | [Environment source](https://github.com/ollama/ollama/blob/main/envconfig/config.go) |+| LM Studio | --port / -p; --bind / LMS_SERVER_HOST | --cors (no short alias) | [Server command source](https://github.com/lmstudio-ai/lms/blob/main/src/subcommands/server.ts) |++Remote CORS comparisons use normalized policy. The broker derives the internal+preserveCORS preview guard from the authenticated caller and repeats validation+after acquiring its apply lock, before recording a new desired revision. A peer+cannot bypass this check using a stale ingress check or a client-supplied false flag.++Vendor option semantics can change independently of PAIR. New aliases or networking+controls require a manifest/test update; this is the deliberately bounded portion+of engine behavior PAIR owns.diff --git a/services/nvpair-engine-manager/MANIFEST.md b/services/nvpair-engine-manager/MANIFEST.mdindex 7ae8108..a5f1351 100644--- a/services/nvpair-engine-manager/MANIFEST.md+++ b/services/nvpair-engine-manager/MANIFEST.md@@ -33,8 +33,88 @@ bundled manifest so only `runtime.port` is pinned. (A standalone`LoadRegistry(dirs…)` load still replaces wholesale; the deep-merge applies tothe per-user `engines/` override layer that the service overlays at startup.)+Port changes merge only the port into an existing override. Returning to the+bundled default removes shared and host-platform port overrides while keeping+arguments, environment and unrelated settings. The file is removed only when+the engine identifier is all that remains. A host-platform port override is+updated too if needed, so it cannot shadow the saved shared port at startup.+An invalid existing override is left intact and the save fails.+## Top-level fields+For editable launch settings, `runtime.editable_launch` declares optional+`fixed_args`, command-mode `start_index` (default zero), and `controls` that+bind an engine's syntax to PAIR's policy fields. The bundled manifests reference+[manifest.schema.json](manifest.schema.json) for editor validation. Engine-manager+also validates bindings at load, including cross-control constraints that JSON+Schema does not express. Unknown properties inside `editable_launch` are errors.++```json+"editable_launch": {+ "fixed_args": ["server", "start"],+ "controls": [+ { "flags": ["--port", "-p"], "value": "{server.port}" },+ { "flags": ["--bind"], "env": ["LMS_SERVER_HOST"], "value": "{server.host}" },+ { "flags": ["--cors"], "value": "{cors.enabled}", "implicit": "true" }+ ]+}+```++| Control property | Meaning |+| --- | --- |+| `flags` | Supported flag spellings. The first is the canonical output name; the rest are aliases. |+| `env` | Supported environment names. All share the same binding and validation. |+| `value` | Format binding policy fields, with literal text between them. For example, `{server.host}:{server.port}` or `tcp://{server.host}:{server.port}`. |+| `implicit` | Value supplied by flag presence, such as `true` for `--cors` or `false` for `--no-cors`. Omit for flags that consume a value. Environment sources always consume an explicit value. |++PAIR has a small, fixed policy surface:++| Field | Policy |+| --- | --- |+| `server.port` | Integer 1–65535, synchronized with the server-port field. |+| `server.host` | Managed loopback host, keeping direct engine access behind the proxy. |+| `cors.origins` | Comma-separated origin list, normalized and validated; changes are local-only. |+| `cors.enabled` | Explicit boolean, normalized to `true` or `false`; changes are local-only. |++The **proxy port belongs to the broker**, which creates that listener and validates+port collisions. It is not an engine launch argument or an engine-manifest binding.+The presence of a CORS field identifies a browser-policy control. Engines without+one still work; proxies follow the engine's actual HTTP CORS response.++The tokenizer reads flag/environment syntax, the binding parser extracts fields,+and the field validators enforce policy. All input sources use the same conflict+checks. Launch construction renders those same bindings, with no engine names,+option-kind switches, or separate host:port parser. For example, Ollama uses+`{"env":["OLLAMA_HOST"],"value":"{server.host}:{server.port}"}`.+Bindings can reorder fields or add literal prefixes/brackets without Go changes.+Templates are trusted manifest syntax; user values are never expanded as templates.++Controls must collectively bind every managed server field. Fields within a value+must be unique, separated by literal text, and share ownership: managed server+fields cannot be combined with editable CORS fields. Unknown fields, malformed+formats, duplicate source names and invalid implicit values fail loading.+Implicit values cannot replace managed server fields. Every captured value still+passes the field validator; a format cannot weaken port ranges or loopback policy.++Managed values set every declared environment alias and, when assembling edited+arguments, emit the canonical flag. This prevents inherited network aliases from+overriding the managed values. Short value options accept separate, attached and+equals forms. Ambiguous bundles containing a declared short control are rejected.+A new engine using this grammar needs bindings and tests; a new CLI grammar needs+a shared grammar extension, not an engine-specific branch.++There is no catalog of unrelated vendor options or editable environment names.+Those values pass through literally. Explicit environment assignments override+manifest defaults; omitted defaults remain in effect. The final effective launch+is validated again before execution, including settings saved by earlier versions.++The editor saves literal extra arguments in+host-platform `runtime.launch_args` and explicit environment assignments in+`runtime.launch_env`, after trusted template expansion. Empty arrays clear the+saved arguments or environment assignments. See [LAUNCH_TEXT.md](LAUNCH_TEXT.md) for validation+and [the broker protocol](../nvpair-ui-broker/ENGINE_SETTINGS.md) for application+and recovery. Editing `args`/`start` directly remains trusted manifest authoring.+| Field | Type | Required | Notes ||---|---|---|---|| `engine` | string | yes | Unique id (the key used in `engine:*` calls). |diff --git a/services/nvpair-engine-manager/README.md b/services/nvpair-engine-manager/README.mdindex 8c3dfa3..b401c88 100644--- a/services/nvpair-engine-manager/README.md+++ b/services/nvpair-engine-manager/README.md@@ -93,7 +93,12 @@ to the per-user `engines/` dir that deep-merges onto the bundled manifest, so`runtime.port` becomes the single source of truth and the port is restored onthe next start with no separate store), and applies it — bouncing the engineonto the new port if it was running. Setting the port back to the bundled-default removes the override file. Because the chosen port lives in the+default removes only the shared and host-platform port overrides; the file is+removed only when no other overrides remain. Arguments, environment, install+settings and other platform overrides are preserved. A host-platform port is+updated when necessary so it cannot shadow the saved value on restart.+Malformed override files fail the save instead of being replaced.+Because the chosen port lives in theeffective manifest, restore is automatic: a normal `engine:start` (no explicitport) and the adopt-on-fixed-port path both come up on the retained port.Moving a **running, adopted** engine is **refused** with an error (nothing is@@ -101,6 +106,14 @@ persisted) — NVPAIR can't relocate a process it didn't start; see Adoption bel## Lifecycle+Combined launch/server/proxy edits use the broker's+[engine settings protocol](../nvpair-ui-broker/ENGINE_SETTINGS.md). The worker+checks basic argument syntax and adapter-declared networking/CORS controls+using [`pair-arguments-v1`](LAUNCH_TEXT.md), persists host-platform `launch_args` and `launch_env`+with the port, and holds its operation lock through stop/rebind/start. The+paired engine-control surface relays settings to its local broker and streams+full authoritative snapshots to pinned peers.+```NotInstalled --engine:install--> (HTTPS download + verify-if-pinned + user-mode run) --> StoppedStopped --engine:start----> (adopt if already serving the port, else spawn) --> Running --health--> Runningdiff --git a/services/nvpair-engine-manager/controlserver.go b/services/nvpair-engine-manager/controlserver.goindex b170857..8a23a5f 100644--- a/services/nvpair-engine-manager/controlserver.go+++ b/services/nvpair-engine-manager/controlserver.go@@ -49,10 +49,17 @@ func (s *controlServer) requirePin(h http.HandlerFunc) http.HandlerFunc {return requirePinnedPeer(s.mesh, h)}+// requirePinCaller is requirePin for a handler that also needs to know which+// peer is calling.+func (s *controlServer) requirePinCaller(h pinnedPeerHandler) http.HandlerFunc {+ return requirePinnedCaller(s.mesh, h)+}+// mux builds the ec routes. Split from the listener so tests can exercise the// handlers over httptest without binding a real port.func (s *controlServer) mux() *http.ServeMux {mux := http.NewServeMux()+ s.settingsRoutes(mux)mux.HandleFunc(controlEnginesPath, s.requirePin(s.handleEngines))mux.HandleFunc(controlInstallPath, s.requirePin(s.handleInstall))mux.HandleFunc(controlPullPath, s.requirePin(s.handlePull))diff --git a/services/nvpair-engine-manager/e2e_test.go b/services/nvpair-engine-manager/e2e_test.goindex fc61595..e02187a 100644--- a/services/nvpair-engine-manager/e2e_test.go+++ b/services/nvpair-engine-manager/e2e_test.go@@ -7,6 +7,7 @@ import ("bufio""encoding/json""io"+ settings "nvpair-shared/enginesettings""os""os/exec""path/filepath"@@ -80,6 +81,48 @@ func TestE2EOverStdio(t *testing.T) {waitResult(t, frames, "5", 5*time.Second)}+// Saving a bundled engine's port through the real worker must preserve the+// rest of its override across a new worker process, not just in-memory state.+func TestE2EPortSavePreservesLaunchOverrides(t *testing.T) {+ cfg, home := t.TempDir(), t.TempDir()+ override := map[string]any{+ "engine": "ollama",+ "runtime": map[string]any{+ "args": []string{"serve", "--custom-option"},+ "env": map[string]string{"CUSTOM_SETTING": "retained"},+ },+ }+ for _, dir := range []string{+ filepath.Join(cfg, "Nvidia Corporation", "Personal AI Router", "engines"),+ filepath.Join(home, "Library", "Application Support", "Nvidia Corporation", "Personal AI Router", "engines"),+ } {+ if err := os.MkdirAll(dir, 0o700); err != nil {+ t.Fatal(err)+ }+ if err := writeJSONAtomic(filepath.Join(dir, "ollama.json"), override); err != nil {+ t.Fatal(err)+ }+ }+ first := startE2EManager(t, cfg, home)+ send(t, first.stdin, 1, "engine:set-port", map[string]any{"engine": "ollama", "port": 26001})+ var saved EngineStatus+ if err := json.Unmarshal(waitResult(t, first.frames, "1", 10*time.Second), &saved); err != nil || saved.Port != 26001 || saved.Running {+ t.Fatalf("saved status=%+v, err=%v", saved, err)+ }+ first.stop(t)+ second := startE2EManager(t, cfg, home)+ send(t, second.stdin, 1, "engine:describe", map[string]any{"engine": "ollama"})+ var manifest Manifest+ if err := json.Unmarshal(waitResult(t, second.frames, "1", 10*time.Second), &manifest); err != nil {+ t.Fatal(err)+ }+ platform, ok := manifest.HostPlatform()+ if !ok || platform.Runtime.Port != 26001 || len(platform.Runtime.Args) != 2 || platform.Runtime.Args[1] != "--custom-option" || platform.Runtime.Env["CUSTOM_SETTING"] != "retained" {+ t.Fatalf("worker restart lost settings: %+v", platform)+ }+ second.stop(t)+}+func TestE2EDesiredStateAcrossShutdownRPC(t *testing.T) {cfg := t.TempDir()home := t.TempDir()@@ -287,6 +330,7 @@ func overrideEnv(over map[string]string) []string {}type frame struct {+ Params json.RawMessage `json:"params"`ID json.RawMessage `json:"id"`Method string `json:"method"`Result json.RawMessage `json:"result"`@@ -363,3 +407,60 @@ func waitNotify(t *testing.T, frames <-chan frame, method string, timeout time.D}}}++// Configure can request a parent rebind while both stdio readers continue+// servicing unrelated messages; literal settings survive a fresh worker.+func TestE2ESettingsRebindRelayAndWorkerReload(t *testing.T) {+ cfg, home := t.TempDir(), t.TempDir()+ fixture := settingsExecutor(t, false)+ manifest, _ := fixture.reg.Get("fake")+ for _, dir := range []string{filepath.Join(cfg, "Nvidia Corporation", "Personal AI Router", "engines"), filepath.Join(home, "Library", "Application Support", "Nvidia Corporation", "Personal AI Router", "engines")} {+ writeE2EManifest(t, dir, manifest)+ }+ manager := startE2EManager(t, cfg, home)+ send(t, manager.stdin, 1, "engine:get-installed", nil)+ waitResult(t, manager.frames, "1", 5*time.Second)+ send(t, manager.stdin, 2, "engine:get-launch", map[string]string{"engine": "fake"})+ var launch settings.LaunchState+ if err := json.Unmarshal(waitResult(t, manager.frames, "2", 5*time.Second), &launch); err != nil {+ t.Fatal(err)+ }+ desired := settings.Config{ServerPort: launch.ServerPort, ProxyPort: 54301, LaunchText: `OLLAMA_ORIGINS="http://localhost" PAIR_TEST_LITERAL="$HOME {port}" ` + launch.LaunchText}+ send(t, manager.stdin, 3, "engine:configure-launch", settings.Configure{Engine: "fake", Settings: desired, OperationID: "operation"})+ var relay settings.Relay+ timer := time.NewTimer(5 * time.Second)+ defer timer.Stop()+ waiting := true+ for waiting {+ select {+ case f := <-manager.frames:+ if f.Method == "engine:settings-request" {+ if err := json.Unmarshal(f.Params, &relay); err != nil {+ t.Fatal(err)+ }+ waiting = false+ }+ case <-timer.C:+ t.Fatal("worker never requested parent rebind")+ }+ }+ if relay.Method != "rebind" || relay.Request.RequestID != "operation" || relay.Request.Settings.ProxyPort != 54301 {+ t.Fatalf("bad relay: %+v", relay)+ }+ send(t, manager.stdin, 4, "engine:describe", map[string]string{"engine": "fake"})+ waitResult(t, manager.frames, "4", 5*time.Second)+ notify(t, manager.stdin, "engine:settings-reply", settingsReply{ID: relay.ID, Result: json.RawMessage(`{}`)})+ if err := json.Unmarshal(waitResult(t, manager.frames, "3", 5*time.Second), &launch); err != nil || launch.Running {+ t.Fatalf("configure result %+v %v", launch, err)+ }+ saved := launch.LaunchText+ manager.stop(t)+ restored := startE2EManager(t, cfg, home)+ send(t, restored.stdin, 1, "engine:get-installed", nil)+ waitResult(t, restored.frames, "1", 5*time.Second)+ send(t, restored.stdin, 2, "engine:get-launch", map[string]string{"engine": "fake"})+ if err := json.Unmarshal(waitResult(t, restored.frames, "2", 5*time.Second), &launch); err != nil || launch.LaunchText != saved {+ t.Fatalf("worker reload lost literal settings: %+v %v", launch, err)+ }+ restored.stop(t)+}diff --git a/services/nvpair-engine-manager/executor.go b/services/nvpair-engine-manager/executor.goindex 85ca553..de6bcfd 100644--- a/services/nvpair-engine-manager/executor.go+++ b/services/nvpair-engine-manager/executor.go@@ -5,8 +5,10 @@ package mainimport ("context"+ "encoding/json""fmt""net/http"+ settings "nvpair-shared/enginesettings""os""path/filepath""regexp"@@ -69,6 +71,8 @@ type engineState struct {// layer runs the long ones (install, start) in goroutines so the read// loop stays responsive.type Executor struct {+ settingsHub settings.Hub+ settingsParent func(context.Context, string, settings.Request, string) (json.RawMessage, error)reg *Registryreporter *Reporteremit func(method string, params any)diff --git a/services/nvpair-engine-manager/httpserver.go b/services/nvpair-engine-manager/httpserver.goindex 2c94cba..4cdcc5d 100644--- a/services/nvpair-engine-manager/httpserver.go+++ b/services/nvpair-engine-manager/httpserver.go@@ -113,25 +113,41 @@ func loopbackOnly(h http.Handler) http.HandlerFunc {}}-// requirePinnedPeer gates h on cluster-peer mTLS: the authenticated caller must-// present a certificate this node currently pins. Membership and pins are+// pinnedPeerHandler serves a request whose caller has already been verified,+// receiving that caller's cluster UUID.+type pinnedPeerHandler func(w http.ResponseWriter, r *http.Request, caller string)++// requirePinnedCaller gates h on cluster-peer mTLS: the authenticated caller+// must present a certificate this node currently pins. Membership and pins are// re-derived first, so a cluster joined or left, or a peer paired or removed,// after startup is reflected without a restart.//// Unconditional by design — not "if this node is clustered". VerifyClientPin is// already false for a node that belongs to no cluster, so wrapping it in a// membership test would be the one thing that could reopen the surface.-func requirePinnedPeer(mesh *clustertrust.Mesh, h http.Handler) http.HandlerFunc {+//+// It hands the verified identity to h so that a route needing the caller+// authorizes once, here, rather than re-verifying after reading a request body.+func requirePinnedCaller(mesh *clustertrust.Mesh, h pinnedPeerHandler) http.HandlerFunc {return func(w http.ResponseWriter, r *http.Request) {mesh.Refresh()- if _, ok := mesh.VerifyClientPin(r); !ok {+ caller, ok := mesh.VerifyClientPin(r)+ if !ok {http.Error(w, "forbidden: not a pinned cluster peer", http.StatusForbidden)return}- h.ServeHTTP(w, r)+ h(w, r, caller)}}+// requirePinnedPeer is requirePinnedCaller for routes that do not need the+// caller's identity.+func requirePinnedPeer(mesh *clustertrust.Mesh, h http.Handler) http.HandlerFunc {+ return requirePinnedCaller(mesh, func(w http.ResponseWriter, r *http.Request, _ string) {+ h.ServeHTTP(w, r)+ })+}+// isLoopbackRemote reports whether an http.Request RemoteAddr is a loopback// address.func isLoopbackRemote(remoteAddr string) bool {diff --git a/services/nvpair-engine-manager/launch.go b/services/nvpair-engine-manager/launch.gonew file mode 100644index 0000000..8cccd4c--- /dev/null+++ b/services/nvpair-engine-manager/launch.go@@ -0,0 +1,143 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "fmt"+ "runtime"+ "sort"+ "strings"+)++// launchCommand contains exactly what is handed to exec.Command. Keeping+// resolution here gives the settings preview and actual launch one builder.+// Env is the explicitly configured environment, never the inherited one.+type launchCommand struct {+ Bin string+ Args []string+ Env map[string]string+}++func environmentKey(key string) string {+ if runtime.GOOS == "windows" {+ return strings.ToUpper(key)+ }+ return key+}++func validEnvironmentKey(key string) bool {+ if key == "" {+ return false+ }+ for i, c := range key {+ if c != '_' && !(c >= 'A' && c <= 'Z') && !(c >= 'a' && c <= 'z') && !(i > 0 && c >= '0' && c <= '9') {+ return false+ }+ }+ return true+}++func literalEnvironment(assignments []string) (map[string]string, error) {+ if _, err := formatLaunchText(append([]string{"environment"}, assignments...)); err != nil {+ return nil, err+ }+ env := make(map[string]string, len(assignments))+ seen := make(map[string]bool, len(assignments))+ for _, assignment := range assignments {+ key, value, ok := strings.Cut(assignment, "=")+ if !ok || !validEnvironmentKey(key) {+ return nil, fmt.Errorf("environment variable names must start with a letter or underscore and contain only letters, digits, or underscores")+ }+ if seen[environmentKey(key)] {+ return nil, fmt.Errorf("an environment variable is assigned more than once")+ }+ seen[environmentKey(key)] = true+ env[key] = value+ }+ return env, nil+}++// argumentText omits the manifest-owned executable and startup subcommand.+func (command launchCommand) argumentText(policy *EditableLaunch) (string, error) {+ if policy == nil || len(command.Args) < len(policy.FixedArgs) {+ return "", fmt.Errorf("engine has no editable argument definition")+ }+ return formatLaunchParts(command.Env, command.Args[len(policy.FixedArgs):])+}++func formatLaunchParts(environment map[string]string, args []string) (string, error) {+ keys := make([]string, 0, len(environment))+ for key := range environment {+ keys = append(keys, key)+ }+ sort.Strings(keys)+ tokens := make([]string, 0, len(keys)+1)+ for _, key := range keys {+ // Quote assignment values consistently, including simple values, so+ // normalization does not appear to remove a user's environment quotes.+ value := strings.NewReplacer(`\`, `\\`, `"`, `\"`).Replace(environment[key])+ tokens = append(tokens, key+`="`+value+`"`)+ }+ argv, err := formatLaunchText(args)+ if err != nil {+ return "", err+ }+ if argv != "" {+ tokens = append(tokens, argv)+ }+ text := strings.Join(tokens, " ")+ if _, err := parseLaunchText(text); err != nil {+ return "", err+ }+ return text, nil+}++func resolveProcessLaunch(rt Runtime, binPath string, vars map[string]string) (launchCommand, error) {+ if binPath == "" {+ bin, err := resolvePlaceholders(rt.Bin, vars)+ if err != nil {+ return launchCommand{}, err+ }+ binPath = expandPath(bin)+ }+ // Resolution must not change the caller's context (in particular {bin}).+ resolvedVars := make(map[string]string, len(vars)+1)+ for key, value := range vars {+ resolvedVars[key] = value+ }+ resolvedVars["bin"] = binPath+ args, err := resolveArgs(rt.Args, resolvedVars)+ if err != nil {+ return launchCommand{}, err+ }+ env := make(map[string]string, len(rt.Env))+ for key, value := range rt.Env {+ resolved, err := resolvePlaceholders(value, resolvedVars)+ if err != nil {+ return launchCommand{}, err+ }+ env[key] = resolved+ }+ return applyLiteralLaunch(rt, launchCommand{Bin: binPath, Args: args, Env: env}, resolvedVars)+}++// resolveCommandLaunch preserves manifest expansion for trusted start steps.+// Future user arguments must be added after this step so their values remain+// literal. They must never be placed into the manifest template array.+func resolveCommandLaunch(template []string, vars map[string]string) (launchCommand, error) {+ argv, err := resolveArgs(template, vars)+ if err != nil {+ return launchCommand{}, err+ }+ if len(argv) == 0 {+ return launchCommand{}, nil+ }+ for i := range argv {+ argv[i] = expandPath(argv[i])+ }+ if argv[0] == "" {+ return launchCommand{}, fmt.Errorf("start command executable is empty")+ }+ return launchCommand{Bin: argv[0], Args: argv[1:]}, nil+}diff --git a/services/nvpair-engine-manager/launch_bindings_test.go b/services/nvpair-engine-manager/launch_bindings_test.gonew file mode 100644index 0000000..fd92dac--- /dev/null+++ b/services/nvpair-engine-manager/launch_bindings_test.go@@ -0,0 +1,149 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "encoding/json"+ "os"+ "reflect"+ "slices"+ "strconv"+ "testing"+)++// These synthetic engines exercise different syntax, not per-engine code paths.+// The same fixtures are also usable with the authoring JSON Schema.+func TestDeclarativeLaunchBindings(t *testing.T) {+ data, err := os.ReadFile("testdata/launch-bindings.json")+ if err != nil {+ t.Fatal(err)+ }+ var cases []struct {+ Name string+ Host string+ Definition EditableLaunch+ Input string+ Policy []string+ Invalid []string+ }+ if err := json.Unmarshal(data, &cases); err != nil {+ t.Fatal(err)+ }+ for _, tc := range cases {+ t.Run(tc.Name, func(t *testing.T) {+ if err := tc.Definition.validateControls(); err != nil {+ t.Fatal(err)+ }+ e := settingsExecutor(t, true)+ rt := &settingsState(t, e).plat.Runtime+ rt.EditableLaunch = &tc.Definition+ if tc.Host == "" {+ tc.Host = "127.0.0.1"+ }+ rt.Bind = tc.Host+ request := settingsRequest(t, e)+ request.Settings.LaunchText, request.Resolution = tc.Input+" --unrelated literal", "launch"+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 || preview.Conflict != nil || preview.Settings.ServerPort != 23456 {+ t.Fatalf("%+v", preview)+ }+ policy, err := launchCORSAssignments(preview.Settings.LaunchText, rt.EditableLaunch)+ if err != nil || !slices.Equal(policy, tc.Policy) {+ t.Fatalf("policy=%v, want %v: %v", policy, tc.Policy, err)+ }+ request.Settings = preview.Settings+ if again := previewSettings(t, e, request); !reflect.DeepEqual(preview, again) {+ t.Fatal("preview does not round-trip")+ }+ rt.LaunchArgs, rt.LaunchEnv = &preview.Args, &preview.Env+ launch, err := launchForState(settingsState(t, e), 23456)+ if err != nil {+ t.Fatal(err)+ }+ if err := validateEffectiveLaunch(*rt, launch, tc.Host, "23456"); err != nil {+ t.Fatal(err)+ }+ if !slices.Equal(launch.Args[len(launch.Args)-2:], []string{"--unrelated", "literal"}) {+ t.Fatal("unrelated arguments changed")+ }+ for _, invalid := range tc.Invalid {+ request.Settings.LaunchText = invalid+ if result := previewSettings(t, e, request); len(result.Errors) == 0 {+ t.Fatalf("accepted %q", invalid)+ }+ }+ assertNoSettingsOverride(t, e)+ })+ }+}++func TestManifestLoadRejectsInvalidLaunchBindings(t *testing.T) {+ for _, control := range []string{+ `{"flags":["--x"],"value":"{unknown}"}`,+ `{"flags":["--x"],"value":"{proxy.port}"}`,+ `{"flags":["--x"],"value":"{server.port}{server.host}"}`,+ `{"flags":["--x"],"value":"{server.port}:{server.port}"}`,+ `{"flags":["--x"],"value":"{server.port}:{cors.enabled}"}`,+ `{"flags":["--x"],"value":"{server.port}","implicit":"1234"}`,+ `{"flags":["--x"],"value":"{cors.enabled}","implicit":"maybe"}`,+ `{"env":["X"],"value":"{cors.enabled}","implicit":"true"}`,+ `{"flags":["--x"],"value":"{server.port}","kind":"port"}`,+ `{"flags":["--x"],"value":"{server.port}","values":"typo"}`,+ `{"flags":["--x"],"value":"static"}`,+ `{"flags":["--x"],"value":"{{server.port}}"}`,+ } {+ t.Run(control, func(t *testing.T) {+ // Include otherwise complete bindings so rejection cannot be caused+ // merely by missing managed fields. Exercise the real manifest loader.+ manifest := `{"engine":"fixture","display_name":"Fixture","manifest_version":1,"platforms":{"linux/amd64":{"runtime":{"bin":"fixture","args":[],"editable_launch":{"controls":[{"env":["ADDRESS"],"value":"{server.host}:{server.port}"},` + control + `]}}}}}`+ if _, err := NewRegistry().addManifest("fixture.json", []byte(manifest)); err == nil {+ t.Fatal("invalid binding survived manifest loading")+ }+ })+ }+}++func TestManagedBindingRoundTripsWithOverlappingSeparators(t *testing.T) {+ for _, host := range []string{"127.0.0.1", "::1"} {+ for _, format := range []string{"{server.host}:{server.port}", "{server.port}:{server.host}", "{server.port}0{server.host}", "http://[{server.host}]:{server.port}"} {+ control := LaunchControl{Env: []string{"ENDPOINT"}, Value: format}+ rendered, managed := control.managedValue(host, "23456")+ if !managed {+ t.Fatalf("invalid binding %q", format)+ }+ values := launchValues{host: host}+ normalized, err := values.accept(&control, rendered)+ if err != nil || normalized != rendered || values.serverPort() != 23456 {+ t.Fatalf("format %q host %q: %q (%v)", format, host, normalized, err)+ }+ }+ }+}++func FuzzLaunchBindings(f *testing.F) {+ for _, seed := range [][2]string{+ {"{server.port}", "23456"},+ {"tcp://{server.host}:{server.port}", "tcp://127.0.0.1:23456"},+ {"port={server.port};host={server.host}", "port=23456;host=127.0.0.1"},+ {"{cors.enabled}", "false"},+ {"{cors.origins}", `"*"`},+ } {+ f.Add(seed[0], seed[1])+ }+ f.Fuzz(func(t *testing.T, format, input string) {+ control := LaunchControl{Env: []string{"VALUE"}, Value: format}+ values := launchValues{host: "127.0.0.1"}+ normalized, err := values.accept(&control, input)+ if err != nil {+ return+ }+ again, err := values.accept(&control, normalized)+ if err != nil || again != normalized {+ t.Fatalf("unstable binding normalization: %q -> %q (%v)", normalized, again, err)+ }+ if managed, ok := control.managedValue(values.host, strconv.Itoa(values.serverPort())); ok && managed != normalized {+ t.Fatalf("preview and launch disagree: %q / %q", normalized, managed)+ }+ })+}diff --git a/services/nvpair-engine-manager/launch_controls.go b/services/nvpair-engine-manager/launch_controls.gonew file mode 100644index 0000000..6f5589a--- /dev/null+++ b/services/nvpair-engine-manager/launch_controls.go@@ -0,0 +1,311 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bytes"+ "encoding/json"+ "fmt"+ "regexp"+ "slices"+ "strconv"+ "strings"+ "unicode/utf8"+)++// Launch bindings are strict even though unrelated manifest fields permit+// additive extensions: a misspelled security control must never be ignored.+func (p *EditableLaunch) UnmarshalJSON(data []byte) error {+ type wire EditableLaunch+ var decoded wire+ decoder := json.NewDecoder(bytes.NewReader(data))+ decoder.DisallowUnknownFields()+ if err := decoder.Decode(&decoded); err != nil {+ return err+ }+ *p = EditableLaunch(decoded)+ return nil+}++func (control LaunchControl) flag() string {+ if len(control.Flags) > 0 {+ return control.Flags[0]+ }+ return ""+}++// A value template only binds known policy fields. It is not a shell template+// and never expands user text. Literal separators are regexp-escaped, and every+// captured field passes its policy validator before the value is reconstructed.+type launchBinding struct {+ fields []string+ literals []string+ managed bool+ localOnly bool+}++var bindingToken = regexp.MustCompile(`\{([^{}]+)\}`)+var launchFlagName = regexp.MustCompile(`^(?:-[a-zA-Z]|--[a-zA-Z0-9_-]+)$`)++func (control LaunchControl) binding() (launchBinding, error) {+ binding := launchBinding{}+ if !utf8.ValidString(control.Value) {+ return binding, fmt.Errorf("invalid launch value template")+ }+ matches := bindingToken.FindAllStringSubmatchIndex(control.Value, -1)+ if len(matches) == 0 {+ return binding, fmt.Errorf("launch control value must bind a policy field")+ }+ seen, offset := map[string]bool{}, 0+ for _, match := range matches {+ literal, name := control.Value[offset:match[0]], control.Value[match[2]:match[3]]+ field, known := launchFields[name]+ if !known || seen[name] {+ return binding, fmt.Errorf("unknown or repeated launch policy field %q", name)+ }+ if strings.ContainsAny(literal, "{}") || len(binding.fields) > 0 && literal == "" {+ return binding, fmt.Errorf("launch fields require unambiguous literal separators")+ }+ managed := field.managed != nil+ if len(binding.fields) > 0 && (binding.managed != managed || binding.localOnly != field.localOnly) {+ return binding, fmt.Errorf("a launch control cannot mix fields with different ownership")+ }+ binding.managed, binding.localOnly = managed, field.localOnly+ binding.fields = append(binding.fields, name)+ binding.literals = append(binding.literals, literal)+ seen[name], offset = true, match[1]+ }+ tail := control.Value[offset:]+ if strings.ContainsAny(tail, "{}") {+ return binding, fmt.Errorf("invalid launch value template")+ }+ binding.literals = append(binding.literals, tail)+ if control.Implicit != nil {+ if len(control.Flags) == 0 || binding.managed {+ return binding, fmt.Errorf("implicit values require flags and cannot replace managed server fields")+ }+ if _, err := (&launchValues{}).acceptBinding(binding, *control.Implicit); err != nil {+ return binding, fmt.Errorf("invalid implicit value: %w", err)+ }+ }+ return binding, nil+}++func (control LaunchControl) localOnly() bool {+ binding, err := control.binding()+ return err == nil && binding.localOnly+}++func (p *EditableLaunch) environmentControl(name string) *LaunchControl {+ for i := range p.Controls {+ for _, alias := range p.Controls[i].Env {+ if environmentKey(alias) == environmentKey(name) {+ return &p.Controls[i]+ }+ }+ }+ return nil+}++func (p *EditableLaunch) validateControls() error {+ flags, env, fields := map[string]bool{}, map[string]bool{}, map[string]bool{}+ for _, control := range p.Controls {+ binding, err := control.binding()+ if err != nil {+ return err+ }+ for _, name := range binding.fields {+ fields[name] = true+ }+ if len(control.Flags)+len(control.Env) == 0 {+ return fmt.Errorf("launch controls require a flag or environment source")+ }+ for _, name := range control.Flags {+ if !launchFlagName.MatchString(name) || flags[name] {+ return fmt.Errorf("invalid or duplicate networking option %q", name)+ }+ flags[name] = true+ }+ for _, name := range control.Env {+ key := environmentKey(name)+ if !validEnvironmentKey(name) || env[key] {+ return fmt.Errorf("invalid or duplicate networking environment name")+ }+ env[key] = true+ }+ }+ for name, field := range launchFields {+ if field.managed != nil && !fields[name] {+ return fmt.Errorf("editable launch controls must bind managed field %s", name)+ }+ }+ return nil+}++// Match exact long/short names, equals values and attached short values. A short+// bundle containing a protected option is ambiguous without knowing all other+// vendor options' arities; reject it instead of guessing or letting it bypass us.+func (p *EditableLaunch) readControl(tokens []string, index int) (*LaunchControl, string, int, error) {+ token := tokens[index]+ for ci := range p.Controls {+ control := &p.Controls[ci]+ for _, name := range control.Flags {+ value, attached := "", false+ switch {+ case token == name:+ case strings.HasPrefix(token, name+"="):+ value, attached = token[len(name)+1:], true+ case len(name) == 2 && strings.HasPrefix(token, name) && len(token) > 2:+ value, attached = token[2:], true+ default:+ continue+ }+ if control.Implicit != nil {+ if attached {+ return control, "", index, fmt.Errorf("this option does not take a value")+ }+ return control, *control.Implicit, index, nil+ }+ if !attached {+ index+++ if index >= len(tokens) {+ return control, "", index, fmt.Errorf("a networking option is missing its value")+ }+ value = tokens[index]+ }+ return control, value, index, nil+ }+ }+ if strings.HasPrefix(token, "-") && !strings.HasPrefix(token, "--") && len(token) > 2 {+ for _, control := range p.Controls {+ for _, name := range control.Flags {+ if len(name) == 2 && strings.Contains(token[2:], name[1:]) {+ return nil, "", index, fmt.Errorf("write managed short networking options separately, not in a short-option bundle")+ }+ }+ }+ }+ return nil, "", index, nil+}++// All inputs use the same field-level normalization and conflict detection,+// whether they arrive as a flag, environment alias, or part of a combined value.+type launchValues struct {+ host string+ fields map[string]string+}++func (values *launchValues) accept(control *LaunchControl, value string) (string, error) {+ binding, err := control.binding()+ if err != nil {+ return "", err+ }+ return values.acceptBinding(binding, value)+}++func (values *launchValues) acceptBinding(binding launchBinding, value string) (string, error) {+ // Field grammars disambiguate formats such as port:IPv6-host; unconstrained+ // greedy captures could split on a colon inside the host instead.+ pattern := "(?s)^"+ for i, name := range binding.fields {+ pattern += regexp.QuoteMeta(binding.literals[i]) + "(" + launchFields[name].match(values.host) + ")"+ }+ compiled, err := regexp.Compile(pattern + regexp.QuoteMeta(binding.literals[len(binding.fields)]) + "$")+ if err != nil {+ return "", fmt.Errorf("invalid launch value template")+ }+ parts := compiled.FindStringSubmatch(value)+ if parts == nil {+ return "", fmt.Errorf("value does not match its declared launch format")+ }+ if values.fields == nil {+ values.fields = map[string]string{}+ }+ output := ""+ for i, name := range binding.fields {+ field := launchFields[name]+ normalized, err := field.normalize(parts[i+1], values.host)+ if err != nil {+ return "", err+ }+ key := normalized+ if field.canonical != nil {+ key = field.canonical(key)+ }+ if previous, exists := values.fields[name]; exists && previous != key {+ return "", fmt.Errorf("conflicting values for %s", name)+ }+ values.fields[name] = key+ output += binding.literals[i] + normalized+ }+ return output + binding.literals[len(binding.fields)], nil+}++func (control LaunchControl) managedValue(host, port string) (string, bool) {+ binding, err := control.binding()+ if err != nil || !binding.managed {+ return "", false+ }+ output := ""+ for i, name := range binding.fields {+ output += binding.literals[i] + launchFields[name].managed(host, port)+ }+ return output + binding.literals[len(binding.fields)], true+}++func (values *launchValues) serverPort() int {+ port, _ := strconv.Atoi(values.fields["server.port"])+ return port+}++func (values *launchValues) localPolicy() []string {+ out := []string{}+ for name, value := range values.fields {+ // Preserve presence, including false/empty: omission may restore an unsafe+ // inherited or vendor default value.+ if launchFields[name].localOnly {+ out = append(out, name+"="+value)+ }+ }+ slices.Sort(out)+ return out+}++// Recheck the actual launch, including overrides saved by older PAIR versions.+// Display/preview resolution stays read-only and can still show those settings+// for repair; unsafe persisted aliases must never escape via a later Start.+func validateEffectiveLaunch(rt Runtime, command launchCommand, host, port string) error {+ p := rt.EditableLaunch+ if p == nil {+ return nil+ }+ values := launchValues{host: host}+ for name, value := range command.Env {+ if control := p.environmentControl(name); control != nil {+ if _, err := values.accept(control, value); err != nil {+ return err+ }+ }+ }+ if len(command.Args) < len(p.FixedArgs) || !slices.Equal(command.Args[:len(p.FixedArgs)], p.FixedArgs) {+ return fmt.Errorf("launch does not match its fixed startup arguments")+ }+ args := command.Args[len(p.FixedArgs):]+ for i := 0; i < len(args); i++ {+ control, value, last, err := p.readControl(args, i)+ if err != nil {+ return err+ }+ i = last+ if control != nil {+ if _, err := values.accept(control, value); err != nil {+ return err+ }+ }+ }+ if values.serverPort() != 0 && strconv.Itoa(values.serverPort()) != port {+ return fmt.Errorf("saved launch port does not match the managed server port")+ }+ return nil+}diff --git a/services/nvpair-engine-manager/launch_controls_test.go b/services/nvpair-engine-manager/launch_controls_test.gonew file mode 100644index 0000000..f871899--- /dev/null+++ b/services/nvpair-engine-manager/launch_controls_test.go@@ -0,0 +1,322 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "fmt"+ "reflect"+ "slices"+ "strings"+ "testing"++ settings "nvpair-shared/enginesettings"+)++func TestGenericControlSourcesAndLaunchConstruction(t *testing.T) {+ for _, definition := range []string{+ `[{"value":"{server.port}","env":["SERVER_PORT","PORT_ALIAS"]},{"value":"{server.host}","env":["SERVER_HOST","HOST_ALIAS"]},{"value":"{cors.enabled}","flags":["--browser-access","-c"],"env":["BROWSER_ACCESS","CORS_ALIAS"]}]`,+ `[{"value":"{server.host}:{server.port}","flags":["--listen","-l"],"env":["LISTEN","LISTEN_ALIAS"]},{"value":"{cors.origins}","flags":["--origins","-o"],"env":["ORIGINS","ORIGIN_ALIAS"]}]`,+ } {+ t.Run(definition, func(t *testing.T) {+ e := settingsExecutor(t, true)+ rt := &settingsState(t, e).plat.Runtime+ if err := json.Unmarshal([]byte(definition), &rt.EditableLaunch.Controls); err != nil {+ t.Fatal(err)+ }+ if err := rt.EditableLaunch.validateControls(); err != nil {+ t.Fatal(err)+ }+ request := settingsRequest(t, e)+ request.Resolution = "launch"+ if rt.EditableLaunch.Controls[0].Value == "{server.port}" {+ request.Settings.LaunchText = "PORT_ALIAS=23456 HOST_ALIAS=127.0.0.1 CORS_ALIAS=false --future opaque"+ } else {+ request.Settings.LaunchText = "LISTEN_ALIAS=127.0.0.1:23456 ORIGIN_ALIAS=https://example.test -l127.0.0.1:23456 --future opaque"+ }+ preview := previewSettings(t, e, request)+ if len(preview.Errors) > 0 || preview.Conflict != nil {+ t.Fatalf("%+v", preview)+ }+ rt.LaunchArgs, rt.LaunchEnv = &preview.Args, &preview.Env+ launch, err := launchForState(settingsState(t, e), preview.Settings.ServerPort)+ if err != nil {+ t.Fatal(err)+ }+ if err := validateEffectiveLaunch(*rt, launch, "127.0.0.1", "23456"); err != nil {+ t.Fatal(err)+ }+ for _, control := range rt.EditableLaunch.Controls {+ if value, managed := control.managedValue("127.0.0.1", "23456"); managed {+ for _, env := range control.Env {+ if launch.Env[env] != value {+ t.Fatalf("managed alias %s=%q, want %q", env, launch.Env[env], value)+ }+ }+ }+ }+ if !slices.Equal(launch.Args[len(launch.Args)-2:], []string{"--future", "opaque"}) {+ t.Fatal("opaque arguments changed")+ }+ request.Settings.LaunchText = "BROWSER_ACCESS=true CORS_ALIAS=false"+ if rt.EditableLaunch.Controls[0].Value == "{server.host}:{server.port}" {+ request.Settings.LaunchText = "LISTEN=127.0.0.1:23456 LISTEN_ALIAS=0.0.0.0:23456"+ }+ if result := previewSettings(t, e, request); len(result.Errors) == 0 {+ t.Fatal("contradictory source aliases accepted")+ }+ })+ }+}++func TestSavedControlsCannotBypassLaunchValidation(t *testing.T) {+ for _, command := range []bool{false, true} {+ e := settingsExecutor(t, command)+ rt := settingsState(t, e).plat.Runtime+ request := settingsRequest(t, e)+ launch, err := launchForState(settingsState(t, e), request.Settings.ServerPort)+ if err != nil {+ t.Fatal(err)+ }+ if command {+ launch.Args = append(launch.Args, "-p0")+ } else {+ launch.Env["OLLAMA_ORIGINS"] = `"*"`+ }+ if err := validateEffectiveLaunch(rt, launch, "127.0.0.1", fmt.Sprint(request.Settings.ServerPort)); err == nil {+ t.Fatal("unsafe saved launch accepted")+ }+ if command {+ args := []string{"-p0"}+ rt.LaunchArgs = &args+ } else {+ env := []string{`OLLAMA_ORIGINS="*"`}+ rt.LaunchEnv = &env+ }+ settingsState(t, e).plat.Runtime = rt+ if state, err := e.LaunchSettings("fake"); err != nil || !state.Editable {+ t.Fatalf("saved settings must remain available for repair: %+v %v", state, err)+ }+ err = e.Start(context.Background(), "fake")+ if err == nil || !(strings.Contains(err.Error(), "server port") || strings.Contains(err.Error(), "CORS origins")) {+ t.Fatalf("Start did not reject the unsafe saved networking control: %v", err)+ }+ }+}++func TestBundledNetworkingControls(t *testing.T) {+ reg := loadWithOverrides(t, t.TempDir())+ // Adding a bundled engine requires an explicit networking review and cases.+ wantEngines := []string{"lmstudio", "ollama"}+ names := reg.Names()+ slices.Sort(names)+ if !slices.Equal(names, wantEngines) {+ t.Fatalf("review networking controls for every bundled engine: %v", names)+ }+ for _, name := range names {+ manifest, _ := reg.Get(name)+ for platform, config := range manifest.Platforms {+ t.Run(name+"/"+platform, func(t *testing.T) {+ e := settingsExecutor(t, config.Runtime.modeOrDefault() == "command")+ settingsState(t, e).plat.Runtime = config.Runtime+ policy := config.Runtime.EditableLaunch+ if policy == nil {+ t.Fatal("missing reviewed networking controls")+ }+ var valid, invalid []string+ if name == "lmstudio" {+ if !reflect.DeepEqual(policy.Controls, []LaunchControl{{Value: "{server.port}", Flags: []string{"--port", "-p"}}, {Value: "{server.host}", Flags: []string{"--bind"}, Env: []string{"LMS_SERVER_HOST"}}, {Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"--cors"}}}) {+ t.Fatal("incomplete LM Studio controls")+ }+ valid = []string{"--port 23456", "--port=23456", "-p 23456", "-p23456", "-p=23456", `"-p" "23456"`, "--port 23456 -p23456", "-- -p23456"}+ invalid = []string{"-p0", "-p65536", "-p", "-pno", "--port 23456 -p23457", "-vp23456", "-vp=23456", "--bind 0.0.0.0", "--bind=::", "LMS_SERVER_HOST=0.0.0.0", "--cors=false", "--cors=true", "--cors=", "-- --bind 0.0.0.0"}+ } else {+ if !reflect.DeepEqual(policy.Controls, []LaunchControl{{Value: "{server.host}:{server.port}", Env: []string{"OLLAMA_HOST"}}, {Value: "{cors.origins}", Env: []string{"OLLAMA_ORIGINS"}}}) {+ t.Fatal("incomplete Ollama controls")+ }+ valid = []string{`OLLAMA_HOST="127.0.0.1:23456"`, `OLLAMA_HOST='127.0.0.1:23456'`, "OLLAMA_HOST=127.0.0.1:23456"}+ invalid = []string{"OLLAMA_HOST=0.0.0.0:23456", "OLLAMA_HOST=127.0.0.1:0", "OLLAMA_HOST=127.0.0.1:65536", `OLLAMA_ORIGINS='"*"'`, `OLLAMA_ORIGINS="'*'"`, `OLLAMA_ORIGINS='"http://*"'`, "OLLAMA_ORIGINS=http://localhost,*", "OLLAMA_HOST=127.0.0.1:23456 OLLAMA_HOST=0.0.0.0:23456"}+ }+ for _, text := range valid {+ p := settingsRequest(t, e)+ p.Settings.LaunchText, p.Resolution = text, "launch"+ preview := previewSettings(t, e, p)+ if len(preview.Errors) != 0 || preview.Conflict != nil || preview.Settings.ServerPort != 23456 {+ t.Fatalf("%q: %+v", text, preview)+ }+ p.Settings = preview.Settings+ again := previewSettings(t, e, p)+ if !reflect.DeepEqual(preview, again) {+ t.Fatalf("normalization not stable for %q", text)+ }+ if slices.Contains(preview.Args, "-p") || slices.Contains(preview.Args, "-p23456") {+ t.Fatal("managed alias escaped into user args")+ }+ }+ for _, text := range invalid {+ p := settingsRequest(t, e)+ p.Settings.LaunchText = text+ if result := previewSettings(t, e, p); len(result.Errors) == 0 {+ t.Fatalf("accepted %q: %+v", text, result)+ }+ }+ assertNoSettingsOverride(t, e)+ })+ }+ }+}++func TestNetworkingControlAliasesAreEngineIndependent(t *testing.T) {+ e := settingsExecutor(t, true)+ p := settingsState(t, e).plat.Runtime.EditableLaunch+ p.Controls = []LaunchControl{+ {Value: "{server.port}", Flags: []string{"--listener-port", "--http-port", "-x"}},+ {Value: "{server.host}", Flags: []string{"--listener-address", "--address", "-b"}},+ {Value: "{cors.origins}", Flags: []string{"--origins", "--browser-origins", "-o"}},+ {Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"--browser-access", "--allow-browser", "-c"}},+ }++ for _, text := range []string{"--http-port=23456 -b127.0.0.1 -ohttps://example.test", "-x23456 --address=127.0.0.1 --browser-origins=https://example.test"} {+ request := settingsRequest(t, e)+ request.Settings.LaunchText = text+ request.Resolution = "launch"+ result := previewSettings(t, e, request)+ if len(result.Errors) != 0 || result.Settings.ServerPort != 23456 || !slices.Equal(result.Args, []string{"--origins", "https://example.test"}) {+ t.Fatalf("%q: %+v", text, result)+ }+ }+ for _, text := range []string{"--address=0.0.0.0", "-b0.0.0.0", "--browser-origins=*", "-o*", "-vc", "-vohttps://example.test", "-ohttps://one.test --origins=https://two.test"} {+ request := settingsRequest(t, e)+ request.Settings.LaunchText = text+ if result := previewSettings(t, e, request); len(result.Errors) == 0 {+ t.Fatalf("accepted %q", text)+ }+ }+}++func TestCORSCanonicalization(t *testing.T) {+ for _, text := range []string{`"*"`, `'*'`, `" * "`, `"http://*"`, "http://*:80", "*://*", "https://example.test,*", "https://foo*", "https://*.*", "https://example.test/path", "https://[email protected]", "https://example.test?query", "https://example.test#fragment", "https://example.test:65536", `https://example.test\anything`} {+ if _, err := normalizeCORSOrigins(text); err == nil {+ t.Errorf("accepted %q", text)+ }+ }+ for _, value := range []struct{ input, want string }{+ {`"https://Example.Test"`, "https://example.test"},+ {" https://example.test/ , http://localhost:* ", "https://example.test,http://localhost:*"},+ {"https://*.example.test", "https://*.example.test"},+ {"http://[::1]:1234", "http://[::1]:1234"},+ {"", ""},+ } {+ got, err := normalizeCORSOrigins(value.input)+ if err != nil || got != value.want {+ t.Errorf("%q: %q %v", value.input, got, err)+ }+ }+}++func TestRemoteCORSUsesCanonicalPolicyAndAuthoritativePreview(t *testing.T) {+ for _, command := range []bool{false, true} {+ t.Run(fmt.Sprint(command), func(t *testing.T) {+ e := settingsExecutor(t, command)+ request := settingsRequest(t, e)+ changed := "OLLAMA_ORIGINS=https://example.test"+ if command {+ changed = "--cors"+ }+ request.Settings.LaunchText = changed+ request.PreserveCORS = true+ if _, err := e.PreviewLaunch(request); err == nil {+ t.Fatal("authoritative preview allowed a remote CORS change")+ }+ request.PreserveCORS = false+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ request = settingsRequest(t, e)+ if command {+ request.Settings.LaunchText = "--cors --cors"+ } else {+ request.Settings.LaunchText = `OLLAMA_ORIGINS='"https://EXAMPLE.test/"'`+ }+ request.PreserveCORS = true+ if _, err := e.PreviewLaunch(request); err != nil {+ t.Fatalf("equivalent policy rejected: %v", err)+ }+ request.Settings.LaunchText = ""+ if _, err := e.PreviewLaunch(request); err == nil {+ t.Fatal("remote removal changed policy")+ }+ })+ }+}++// Removing a disabling override may restore permissive inherited/default values.+func TestRemoteCORSCannotRemoveExplicitDisablingValues(t *testing.T) {+ for _, kind := range []string{"cors.enabled", "cors.origins"} {+ t.Run(kind, func(t *testing.T) {+ e := settingsExecutor(t, true)+ policy := settingsState(t, e).plat.Runtime.EditableLaunch+ policy.Controls = append(policy.Controls, LaunchControl{Value: "{" + kind + "}", Env: []string{"BROWSER_POLICY"}})+ request := settingsRequest(t, e)+ request.Settings.LaunchText = "BROWSER_POLICY=false"+ if kind == "cors.origins" {+ request.Settings.LaunchText = "BROWSER_POLICY="+ }+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ request = settingsRequest(t, e)+ request.PreserveCORS = true+ if _, err := e.PreviewLaunch(request); err != nil {+ t.Fatalf("unchanged policy rejected: %v", err)+ }+ request.Settings.LaunchText = ""+ if _, err := e.PreviewLaunch(request); err == nil {+ t.Fatal("remote removal of disabling override accepted")+ }+ })+ }+}++func TestNetworkingManifestRejectsAmbiguousDeclarations(t *testing.T) {+ for _, controls := range [][]LaunchControl{+ {{Value: "{server.port}"}},+ {{Value: "{server.port}", Flags: []string{"--port"}}, {Value: "{server.host}", Flags: []string{"--port"}}},+ {{Value: "{server.port}", Flags: []string{"--port", "--port"}}},+ {{Value: "{server.port}", Flags: []string{"--port", "-p"}}, {Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"-p"}}},+ {{Value: "{server.port}", Env: []string{"PORT"}}, {Value: "{server.host}", Env: []string{"PORT"}}},+ {{Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"--cors=true"}}},+ {{Value: "{unknown}", Flags: []string{"--x"}}},+ {{Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Env: []string{"CORS"}}},+ {{Value: "{server.port}", Flags: []string{"--port"}}},+ } {+ policy := EditableLaunch{Controls: controls}+ if err := policy.validateControls(); err == nil {+ t.Errorf("accepted %+v", policy)+ }+ }++}++func FuzzCORSNormalization(f *testing.F) {+ for _, seed := range []string{`"*"`, "https://*.example.test", "http://localhost:*", "https://example.test"} {+ f.Add(seed)+ }+ f.Fuzz(func(t *testing.T, value string) {+ got, err := normalizeCORSOrigins(value)+ if err != nil {+ return+ }+ again, err := normalizeCORSOrigins(got)+ if err != nil || again != got {+ t.Fatalf("unstable normalization: %q -> %q -> %q", value, got, again)+ }+ if strings.ContainsAny(got, "\"'") {+ t.Fatal("literal quote survives CORS validation")+ }+ })+}++func implicitLaunchValue(value string) *string { return &value }diff --git a/services/nvpair-engine-manager/launch_fields.go b/services/nvpair-engine-manager/launch_fields.gonew file mode 100644index 0000000..93ed98c--- /dev/null+++ b/services/nvpair-engine-manager/launch_fields.go@@ -0,0 +1,118 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "fmt"+ "net/url"+ "regexp"+ "slices"+ "strconv"+ "strings"+)++// These are PAIR's policy fields, independent of any engine or CLI syntax.+// Their validators cannot be weakened by a manifest. Proxy ports belong to the+// broker and are deliberately not injectable into an engine's arguments.+type launchField struct {+ match func(host string) string+ normalize func(value, host string) (string, error)+ canonical func(string) string+ managed func(host, port string) string+ localOnly bool+}++var launchFields = map[string]launchField{+ "server.port": {+ match: func(string) string { return `[+-]?[0-9]+` },+ normalize: normalizeServerPort, managed: func(_, port string) string { return port },+ },+ "server.host": {+ match: regexp.QuoteMeta,+ normalize: normalizeServerHost, managed: func(host, _ string) string { return host },+ },+ "cors.origins": {+ match: func(string) string { return `.*` },+ normalize: func(value, _ string) (string, error) { return normalizeCORSOrigins(value) },+ canonical: func(value string) string { return strings.Join(canonicalCORSPolicy(strings.Split(value, ",")), ",") }, localOnly: true,+ },+ "cors.enabled": {+ match: func(string) string { return `(?i:true|false|t|f|1|0)` },+ normalize: normalizeCORSBoolean, localOnly: true,+ },+}++func normalizeServerPort(value, _ string) (string, error) {+ port, err := strconv.Atoi(value)+ if err != nil || port < 1 || port > 65535 {+ return "", fmt.Errorf("the launch text contains an invalid server port")+ }+ return strconv.Itoa(port), nil+}++func normalizeServerHost(value, host string) (string, error) {+ if value != host {+ return "", fmt.Errorf("the engine bind address is fixed to loopback")+ }+ return host, nil+}++func normalizeCORSBoolean(value, _ string) (string, error) {+ enabled, err := strconv.ParseBool(value)+ if err != nil {+ return "", fmt.Errorf("CORS boolean controls require true or false")+ }+ return strconv.FormatBool(enabled), nil+}++// Canonicalize before validation and before handing values to the engine. This+// closes differences such as Ollama stripping extra quotes around an origin list.+func normalizeCORSOrigins(value string) (string, error) {+ value = strings.Trim(strings.TrimSpace(value), "\"'")+ origins := []string{}+ for _, origin := range strings.Split(value, ",") {+ origin = strings.TrimSpace(origin)+ if origin == "" {+ continue+ }+ scheme, authority, ok := strings.Cut(origin, "://")+ if origin == "*" || authority == "*" || strings.HasPrefix(authority, "*:") {+ return "", fmt.Errorf("CORS origins cannot allow every origin; list each origin that needs access")+ }+ if !ok {+ return "", fmt.Errorf("CORS origins require a URL, for example \"http://localhost\"")+ }+ authority = strings.TrimSuffix(authority, "/")+ if authority == "" || strings.ContainsAny(authority, "/?#@\"'\\ \t\r\n") || strings.Contains(scheme, "*") {+ return "", fmt.Errorf("CORS origins must name a scheme and a specific host without credentials, paths, or quotes")+ }+ // net/url deliberately rejects wildcard ports, which origin matchers+ // support. Parse a numeric stand-in but preserve the declared wildcard.+ parseAuthority := authority+ if strings.HasSuffix(parseAuthority, ":*") {+ parseAuthority = strings.TrimSuffix(parseAuthority, "*") + "1"+ }+ u, err := url.Parse(scheme + "://" + parseAuthority)+ if err != nil || u.Scheme == "" || u.Hostname() == "" {+ return "", fmt.Errorf("invalid CORS origin")+ }+ host := u.Hostname()+ if strings.Contains(host, "*") && !(strings.HasPrefix(host, "*.") && len(host) > 2 && strings.Count(host, "*") == 1) {+ return "", fmt.Errorf("CORS origins cannot allow every origin; use only a specific host or wildcard subdomain")+ }+ if port := u.Port(); port != "" {+ n, err := strconv.Atoi(port)+ if err != nil || n < 1 || n > 65535 {+ return "", fmt.Errorf("invalid CORS origin port")+ }+ }+ origins = append(origins, strings.ToLower(scheme+"://"+authority))+ }+ return strings.Join(origins, ","), nil+}++func canonicalCORSPolicy(values []string) []string {+ slices.Sort(values)+ return slices.Compact(values)+}diff --git a/services/nvpair-engine-manager/launch_test.go b/services/nvpair-engine-manager/launch_test.gonew file mode 100644index 0000000..d2b8eb3--- /dev/null+++ b/services/nvpair-engine-manager/launch_test.go@@ -0,0 +1,160 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "os"+ "path/filepath"+ "reflect"+ "strings"+ "testing"+ "time"+)++// Render the legacy full command only for migration and argv regression tests.+func (command launchCommand) text() (string, error) {+ return formatLaunchParts(command.Env, append([]string{command.Bin}, command.Args...))+}++func TestResolvedLaunchMatchesBundledEngines(t *testing.T) {+ reg := loadWithOverrides(t, t.TempDir())+ vars := map[string]string{"host": "127.0.0.1", "port": "12345", "cli": "/test path/lms", "install_dir": "/test path"}+ for _, engine := range []string{"ollama", "lmstudio"} {+ manifest, ok := reg.Get(engine)+ if !ok {+ t.Fatalf("missing bundled engine %q", engine)+ }+ // Exercise every platform even when running on Windows or macOS, so+ // Linux-only launch environment requirements are covered locally too.+ for platformKey, platform := range manifest.Platforms {+ t.Run(engine+"/"+platformKey, func(t *testing.T) {+ var launch launchCommand+ var err error+ var want []string+ if engine == "ollama" {+ launch, err = resolveProcessLaunch(platform.Runtime, "/test path/ollama", vars)+ want = []string{"OLLAMA_HOST=127.0.0.1:12345", "/test path/ollama", "serve"}+ if strings.HasPrefix(platformKey, "linux/") {+ want = append([]string{"LD_LIBRARY_PATH=/test path/lib/ollama"}, want...)+ }+ } else {+ launch, err = resolveCommandLaunch(platform.Runtime.Start[0], vars)+ want = []string{"/test path/lms", "server", "start", "--port", "12345", "--bind", "127.0.0.1"}+ }+ if err != nil {+ t.Fatal(err)+ }+ text, err := launch.text()+ if err != nil {+ t.Fatal(err)+ }+ got, err := parseLaunchText(text)+ if err != nil || !reflect.DeepEqual(got, want) {+ t.Fatalf("launch description differs from executable inputs: got %#v, want %#v, error %v", got, want, err)+ }+ })+ }+ }+ if _, changed := vars["bin"]; changed {+ t.Fatal("process builder mutated caller's resolution context")+ }+}++func TestLaunchEnvironmentFormattingIsDeterministic(t *testing.T) {+ launch := launchCommand{Bin: "engine", Env: map[string]string{"Z_SETTING": "z", "A_SETTING": "a b"}}+ text, err := launch.text()+ if err != nil || text != `A_SETTING="a b" Z_SETTING="z" engine` {+ t.Fatalf("unstable environment order or quoting: %q, %v", text, err)+ }+}++func TestCommandLaunchRejectsEmptyExecutable(t *testing.T) {+ for _, template := range [][]string{{"", "start"}, {"{cli}", "start"}} {+ if _, err := resolveCommandLaunch(template, map[string]string{"cli": ""}); err == nil {+ t.Fatal("empty executable must fail rather than skip the start command")+ }+ }+}++// The child receives the parser's output directly. This catches escaping+// differences in the real Windows/POSIX argv path, not just parser symmetry.+func TestLaunchTextReachesChildLiterally(t *testing.T) {+ path := filepath.Join(t.TempDir(), "captured args.json")+ want := []string{"", "two words", "日本語", `C:\new\tools\`, `\\server\share`, `a"b`, "$HOME", "%USERPROFILE%", "{port}", "$(ignored)", "line\nbreak"}+ tokens := append([]string{fakeEngineBin, "captureargs", path}, want...)+ text, err := formatLaunchText(tokens)+ if err != nil {+ t.Fatal(err)+ }+ parsed, err := parseLaunchText(text)+ if err != nil {+ t.Fatal(err)+ }+ proc, err := startManagedProc(parsed[0], parsed[1:], nil, nil)+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(proc.stop)+ select {+ case <-proc.done:+ case <-time.After(10 * time.Second):+ t.Fatal("argument-capture child did not exit")+ }+ assertCapturedArgs(t, path, want)+}++func TestLifecycleUsesResolvedLaunchBuilder(t *testing.T) {+ for _, mode := range []string{"process", "command"} {+ t.Run(mode, func(t *testing.T) {+ path := filepath.Join(t.TempDir(), "captured args.json")+ manifest := testEngineManifest(fakeEngineBin)+ for key, platform := range manifest.Platforms {+ platform.Runtime = Runtime{Mode: mode, Bin: fakeEngineBin, Port: 25001,+ Args: []string{"captureargs", path, "{host}", "{port}", "two words", ""},+ Start: [][]string{{fakeEngineBin, "captureargs", path, "{host}", "{port}", "two words", ""}},+ }+ manifest.Platforms[key] = platform+ }+ ex := newTestExecutor(t, manifest)+ if err := ex.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = ex.Stop("fake") })+ // Process mode has no readiness probe here; wait for the short-lived+ // fixture to finish writing before inspecting its actual argv.+ st, err := ex.state("fake")+ if err != nil {+ t.Fatal(err)+ }+ st.mu.Lock()+ proc := st.proc+ st.mu.Unlock()+ if proc != nil {+ select {+ case <-proc.done:+ case <-time.After(10 * time.Second):+ t.Fatal("capture process did not exit")+ }+ }+ assertCapturedArgs(t, path, []string{"127.0.0.1", "25001", "two words", ""})+ })+ }+}++func assertCapturedArgs(t *testing.T, path string, want []string) {+ t.Helper()+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatal(err)+ }+ var got []string+ if err := json.Unmarshal(data, &got); err != nil {+ t.Fatal(err)+ }+ if !reflect.DeepEqual(got, want) {+ t.Fatalf("child received %#v; want %#v", got, want)+ }+}diff --git a/services/nvpair-engine-manager/launchtext.go b/services/nvpair-engine-manager/launchtext.gonew file mode 100644index 0000000..eeb22c7--- /dev/null+++ b/services/nvpair-engine-manager/launchtext.go@@ -0,0 +1,110 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "fmt"+ "strings"+ "unicode"+ "unicode/utf8"+)++const (+ launchTextFormat = "pair-arguments-v1"+ maxLaunchTextBytes = 16 * 1024+ maxLaunchTokens = 256+)++// parseLaunchText tokenizes PAIR's platform-independent launch notation. It+// never expands variables, paths or placeholders and never invokes a shell.+// Single quotes are literal; within double quotes a backslash only escapes+// another backslash or a double quote. Other backslashes stay literal.+// Quoted and unquoted segments may share a token (--flag="two words").+// Adapters declare the managed port/CORS controls checked after tokenization.+// Other argument meanings belong to the engine. Empty text means no user options.+func parseLaunchText(text string) ([]string, error) {+ if len(text) > maxLaunchTextBytes {+ return nil, fmt.Errorf("launch text exceeds %d bytes", maxLaunchTextBytes)+ }+ if !utf8.ValidString(text) {+ return nil, fmt.Errorf("launch text must be valid UTF-8")+ }+ for _, r := range text {+ if unicode.IsControl(r) && r != '\t' && r != '\r' && r != '\n' {+ return nil, fmt.Errorf("launch text contains an unsupported control character")+ }+ }+ var tokens []string+ var token strings.Builder+ var quote byte+ started := false+ appendToken := func() error {+ if !started {+ return nil+ }+ if len(tokens) == maxLaunchTokens {+ return fmt.Errorf("launch text exceeds %d tokens", maxLaunchTokens)+ }+ tokens = append(tokens, token.String())+ token.Reset()+ started = false+ return nil+ }+ for i := 0; i < len(text); i++ {+ c := text[i]+ if quote != 0 {+ if c == quote {+ quote = 0+ } else if quote == '"' && c == '\\' && i+1 < len(text) && (text[i+1] == '"' || text[i+1] == '\\') {+ i+++ token.WriteByte(text[i])+ } else {+ token.WriteByte(c)+ }+ continue+ }+ switch c {+ case ' ', '\t', '\r', '\n':+ if err := appendToken(); err != nil {+ return nil, err+ }+ case '\'', '"':+ quote = c+ started = true+ case '|', '&', ';', '<', '>', '`':+ return nil, fmt.Errorf("shell operators are not supported; quote literal argument values")+ default:+ if c == '$' && i+1 < len(text) && text[i+1] == '(' {+ return nil, fmt.Errorf("command substitution is not supported; quote literal argument values")+ }+ started = true+ token.WriteByte(c)+ }+ }+ if quote != 0 {+ return nil, fmt.Errorf("launch text has an unterminated quote")+ }+ if err := appendToken(); err != nil {+ return nil, err+ }+ return tokens, nil+}++// formatLaunchText produces a deterministic representation that parses back+// into the exact tokens. The result is PAIR syntax, not an OS shell command.+func formatLaunchText(tokens []string) (string, error) {+ quoted := make([]string, len(tokens))+ for i, token := range tokens {+ if token != "" && !strings.ContainsAny(token, " \t\r\n\"'\\|&;<>`$") {+ quoted[i] = token+ } else {+ quoted[i] = `"` + strings.NewReplacer(`\`, `\\`, `"`, `\"`).Replace(token) + `"`+ }+ }+ text := strings.Join(quoted, " ")+ if _, err := parseLaunchText(text); err != nil {+ return "", err+ }+ return text, nil+}diff --git a/services/nvpair-engine-manager/launchtext_test.go b/services/nvpair-engine-manager/launchtext_test.gonew file mode 100644index 0000000..6664697--- /dev/null+++ b/services/nvpair-engine-manager/launchtext_test.go@@ -0,0 +1,88 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "reflect"+ "strings"+ "testing"+)++func TestParseLaunchText(t *testing.T) {+ test := func(name, text string, want []string) {+ t.Run(name, func(t *testing.T) {+ got, err := parseLaunchText(text)+ if err != nil || !reflect.DeepEqual(got, want) {+ t.Fatalf("got %#v, %v; want %#v", got, err, want)+ }+ normalized, err := formatLaunchText(got)+ if err != nil {+ t.Fatal(err)+ }+ again, err := parseLaunchText(normalized)+ if err != nil || !reflect.DeepEqual(again, want) {+ t.Fatalf("round trip changed arguments: %#v, %v", again, err)+ }+ })+ }+ test("empty arguments", "", nil)+ test("blank arguments", " \t\r\n", nil)+ test("env and Windows executable", `OLLAMA_HOST=127.0.0.1:11435 "C:\Program Files\Ollama\ollama.exe" serve`, []string{"OLLAMA_HOST=127.0.0.1:11435", `C:\Program Files\Ollama\ollama.exe`, "serve"})+ test("Windows backslashes", `C:\tools\lms.exe --path 'C:\new\tools\'`, []string{`C:\tools\lms.exe`, "--path", `C:\new\tools\`})+ test("UNC", `'\\server\share\lms.exe' server start`, []string{`\\server\share\lms.exe`, "server", "start"})+ test("quoted segments", `lms --name="two words" --empty=''`, []string{"lms", "--name=two words", "--empty="})+ test("empty arguments", `lms "" ''`, []string{"lms", "", ""})+ test("escaped quotes", `lms "a\"b\\c"`, []string{"lms", `a"b\c`})+ test("multiline", "lms\r\nserver\tstart --name '日本語\n模型'", []string{"lms", "server", "start", "--name", "日本語\n模型"})+ test("literal expansions", `lms $HOME %USERPROFILE% {port} '~' '$(touch nope)'`, []string{"lms", "$HOME", "%USERPROFILE%", "{port}", "~", "$(touch nope)"})+ test("literal operators", "lms '|&;<>`'", []string{"lms", "|&;<>`"})+ test("terminator", `lms -- --port=9000`, []string{"lms", "--", "--port=9000"})+}++func TestParseLaunchTextRejectsInvalidInput(t *testing.T) {+ for _, text := range []string{+ `lms "unterminated`, `lms 'unterminated`, "lms \x00argument",+ "lms \x7f", "lms \xff", `lms | other`, `lms > file`, `lms < file`,+ `lms && other`, `lms ; other`, "lms `other`", `lms $(other)`,+ strings.Repeat("x", maxLaunchTextBytes+1), strings.Repeat("x ", maxLaunchTokens+1),+ } {+ if _, err := parseLaunchText(text); err == nil {+ t.Fatalf("invalid input accepted (%d bytes)", len(text))+ }+ }+ if _, err := parseLaunchText(strings.Repeat("x", maxLaunchTextBytes)); err != nil {+ t.Fatalf("exact byte limit rejected: %v", err)+ }+ if _, err := parseLaunchText(strings.Repeat("x ", maxLaunchTokens)); err != nil {+ t.Fatalf("exact token limit rejected: %v", err)+ }+}++func FuzzLaunchTextRoundTrip(f *testing.F) {+ for _, seed := range []string{+ `lms server start --port=1235`, `"C:\Program Files\Ollama\ollama.exe" serve`,+ `lms '' "日本語" '$HOME' '{port}'`, `lms --name="two words"`,+ } {+ f.Add(seed)+ }+ f.Fuzz(func(t *testing.T, text string) {+ tokens, err := parseLaunchText(text)+ if err != nil {+ return+ }+ formatted, err := formatLaunchText(tokens)+ if err != nil {+ // Canonical escaping may push a valid input beyond the byte limit.+ return+ }+ again, err := parseLaunchText(formatted)+ if err != nil || !reflect.DeepEqual(again, tokens) {+ t.Fatalf("round trip changed tokens: %#v -> %#v (%v)", tokens, again, err)+ }+ stable, err := formatLaunchText(again)+ if err != nil || stable != formatted {+ t.Fatalf("normalization is not stable: %v", err)+ }+ })+}diff --git a/services/nvpair-engine-manager/lifecycle.go b/services/nvpair-engine-manager/lifecycle.goindex c10244b..cea7aa1 100644--- a/services/nvpair-engine-manager/lifecycle.go+++ b/services/nvpair-engine-manager/lifecycle.go@@ -12,6 +12,7 @@ import ("net/http""net/url""os"+ "os/exec""runtime""strconv""strings"@@ -55,8 +56,9 @@ func (e *Executor) waitDetect(engine string, want bool, timeout time.Duration) b// auto-assign a free loopback port); Bind "" => the manifest's// runtime.bind (which itself defaults to loopback).type startOpts struct {- Port int- Bind string+ RequireOwned bool+ Port int+ Bind string}// effectiveBind picks the listen address substituted as {host}: a per-call@@ -139,6 +141,9 @@ func (e *Executor) doStart(ctx context.Context, st *engineState, engine string,}presence := e.reconcilePresence(ctx, engine, st, pathInstalled, port, true)if presence.Identified {+ if opts.RequireOwned {+ return fmt.Errorf("cannot apply launch settings: another process already owns the server port")+ }slog.Info("adopting already-running external engine", "engine", engine, "port", port)st.mu.Lock()st.gen++@@ -195,6 +200,13 @@ func (e *Executor) doStart(ctx context.Context, st *engineState, engine string,e.reporter.clear(unhealthyID(engine))e.emitState(engine)+ st.mu.Lock()+ proc := st.proc+ st.mu.Unlock()+ if proc != nil {+ e.watch(st, engine, proc)+ }+if rt.Health != nil {hctx, cancel := context.WithCancel(context.Background())st.mu.Lock()@@ -218,30 +230,23 @@ func (e *Executor) bringUpProcess(ctx context.Context, st *engineState, engine sst.mu.Lock()binPath := st.binPathst.mu.Unlock()- if binPath == "" {- b, err := resolvePlaceholders(rt.Bin, vars)- if err != nil {- return err- }- binPath = expandPath(b)- }- vars["bin"] = binPath-- args, err := resolveArgs(rt.Args, vars)+ launch, err := resolveProcessLaunch(rt, binPath, vars)if err != nil {return err}- env := make(map[string]string, len(rt.Env))- for k, v := range rt.Env {- rv, err := resolvePlaceholders(v, vars)- if err != nil {- return err- }- env[k] = rv+ if err := validateEffectiveLaunch(rt, launch, vars["host"], vars["port"]); err != nil {+ return err}- proc, err := startManagedProc(binPath, args, env, func(stream, line string) {- st.logs.append(stream, line)+ diagnostics := newStartupOutput(launchDiagnosticArgs(rt), launch.Env)+ defer diagnostics.close()+ proc, err := startManagedProc(launch.Bin, launch.Args, launch.Env, func(stream, line string) {+ _, _ = diagnostics.Write([]byte(line + "\n"))+ // Vendor diagnostics may echo arbitrary custom arguments. Keep those+ // out of exported engine logs; report exit/readiness failures separately.+ if !rt.hasCustomLaunch() {+ st.logs.append(stream, line)+ }})if err != nil {werr := fmt.Errorf("start %s: %w", engine, err)@@ -251,11 +256,24 @@ func (e *Executor) bringUpProcess(ctx context.Context, st *engineState, engine sst.mu.Lock()st.proc = procst.mu.Unlock()- e.watch(st, engine, proc)- if err := e.waitReady(ctx, rt.Ready, port); err != nil {- // Mark stopping so the watcher doesn't report the deliberate kill- // as an unexpected "exited" event.+ readyCtx, readyCancel := context.WithCancel(ctx)+ defer readyCancel()+ go func() {+ select {+ case <-proc.done:+ readyCancel()+ case <-readyCtx.Done():+ }+ }()+ readyErr := e.waitReady(readyCtx, rt.Ready, port)+ select {+ case <-proc.done:+ readyErr = fmt.Errorf("process exited before readiness; check the launch options")+ default:+ }+ if err := readyErr; err != nil {+ // Clean up the failed start before returning its single readiness error.st.mu.Lock()st.stopping = truest.mu.Unlock()@@ -263,7 +281,7 @@ func (e *Executor) bringUpProcess(ctx context.Context, st *engineState, engine sst.mu.Lock()st.proc = nilst.mu.Unlock()- werr := fmt.Errorf("engine %q did not become ready: %w", engine, err)+ werr := fmt.Errorf("engine %q did not become ready: %w", engine, diagnostics.failure(err))e.reportStartFailedUnlessShuttingDown(ctx, engine, werr)e.emitState(engine)return werr@@ -293,16 +311,31 @@ func (e *Executor) bringUpCommand(ctx context.Context, st *engineState, engine s}return startErr}- for _, cmd := range rt.Start {- argv, err := resolveArgs(cmd, vars)+ for index := range rt.Start {+ launch, err := resolveRuntimeCommand(rt, index, vars)if err != nil {e.reportStartFailedUnlessShuttingDown(ctx, engine, err)return cleanup(err)}- for i := range argv {- argv[i] = expandPath(argv[i])+ if launch.Bin == "" {+ continue+ }+ if rt.EditableLaunch != nil && index == rt.EditableLaunch.StartIndex {+ if err := validateEffectiveLaunch(rt, launch, vars["host"], vars["port"]); err != nil {+ return cleanup(err)+ }+ }+ argv := append([]string{launch.Bin}, launch.Args...)+ run := e.runCommand+ if rt.LaunchArgs != nil || rt.LaunchEnv != nil || len(launch.Env) > 0 {+ run = func(ctx context.Context, argv []string) error {+ return runPrivateLaunchCommand(ctx, argv, launch.Env, launchDiagnosticArgs(rt))+ }+ // A vendor command may spawn its daemon and then exit unsuccessfully.+ // Attempt its official cleanup even if the first command failed.+ started = true}- if err := e.runCommand(ctx, argv); err != nil {+ if err := run(ctx, argv); err != nil {werr := fmt.Errorf("start command failed: %w", err)e.reportStartFailedUnlessShuttingDown(ctx, engine, werr)return cleanup(werr)@@ -321,6 +354,28 @@ func (e *Executor) bringUpCommand(ctx context.Context, st *engineState, engine sreturn nil}+// Capture vendor startup diagnostics without interpreting engine options.+func runPrivateLaunchCommand(ctx context.Context, argv []string, environment map[string]string, privateArgs []string) error {+ if len(argv) == 0 {+ return fmt.Errorf("launch executable is missing")+ }+ cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)+ diagnostics := newStartupOutput(privateArgs, environment)+ defer diagnostics.close()+ cmd.Stdout, cmd.Stderr = diagnostics, diagnostics+ if len(environment) > 0 {+ cmd.Env = os.Environ()+ for key, value := range environment {+ cmd.Env = append(cmd.Env, key+"="+value)+ }+ }+ configureSysProcAttr(cmd)+ if err := cmd.Run(); err != nil {+ return diagnostics.failure(fmt.Errorf("launch command failed: %w", err))+ }+ return nil+}+// watch reports an unexpected engine exit (one not initiated by Stop).func (e *Executor) watch(st *engineState, engine string, proc *managedProc) {go func() {@@ -848,6 +903,9 @@ func (e *Executor) reportStartFailed(engine string, err error) {}func (e *Executor) reportStartFailedUnlessShuttingDown(ctx context.Context, engine string, err error) {+ if ctx.Value(settingsApplyContextKey{}) != nil {+ return+ }// CommandContext can surface an exit status instead of context.Canceled on// Windows, so the canceled operation context is the authoritative signal.if e.shuttingDown.Load() && ctx.Err() != nil {diff --git a/services/nvpair-engine-manager/manager.go b/services/nvpair-engine-manager/manager.goindex 80d572b..e12f62d 100644--- a/services/nvpair-engine-manager/manager.go+++ b/services/nvpair-engine-manager/manager.go@@ -61,11 +61,12 @@ type setPortParam struct {// start, stop, restart, action) run in their own goroutine so the read// loop never blocks; the codec serializes the concurrent responses.type Manager struct {- codec *Codec- exec *Executor- peers *peerDirectory- addrs *reach.Chooser- mesh *clustertrust.Mesh // cluster identity + pins for dialing peers' ec surfaces+ settingsRelay settingsRelay+ codec *Codec+ exec *Executor+ peers *peerDirectory+ addrs *reach.Chooser+ mesh *clustertrust.Mesh // cluster identity + pins for dialing peers' ec surfaces// remoteHTTP / readyHTTP are long-lived per-peer mTLS pools. A throwaway// Transport per engine:remote-* call leaked the idle socket. readyHTTP// uses the longer header budget for start/delete (see waitsForEngineReadiness).@@ -78,7 +79,7 @@ func NewManager(codec *Codec, exec *Executor, mesh *clustertrust.Mesh) *Manager// cancel defaults to a no-op so the "shutdown" handler is safe even if// handleMessage is reached before Run() installs the real CancelFunc// (e.g. a unit test calling it directly); Run overwrites it.- return &Manager{+ m := &Manager{codec: codec,exec: exec,peers: newPeerDirectory(),@@ -92,6 +93,9 @@ func NewManager(codec *Codec, exec *Executor, mesh *clustertrust.Mesh) *Manager}),cancel: func() {},}+ m.settingsRelay.send = codec.Notify+ exec.settingsParent = m.settingsRelay.call+ return m}func (m *Manager) Run(ctx context.Context) error {@@ -115,6 +119,7 @@ func (m *Manager) Run(ctx context.Context) error {// on change (load/unload, JIT auto-load, TTL eviction). Bound to ctx: stops// when the read loop exits below.go m.exec.watchLoaded(ctx)+ go m.watchPeerSettings(ctx)err := m.readLoop(ctx)// Cancel first so any in-flight start aborts at its readiness wait,@@ -150,6 +155,9 @@ func (m *Manager) readLoop(ctx context.Context) error {}func (m *Manager) handleMessage(ctx context.Context, msg *Message) {+ if m.handleSettingsMessage(ctx, msg) {+ return+ }if msg.Method == applog.SetLevelMethod {resolved, err := applog.HandleSetLevelParams(msg.Params)if msg.IsRequest() {diff --git a/services/nvpair-engine-manager/manifest.schema.json b/services/nvpair-engine-manager/manifest.schema.jsonnew file mode 100644index 0000000..713b016--- /dev/null+++ b/services/nvpair-engine-manager/manifest.schema.json@@ -0,0 +1,111 @@+{+ "$schema": "http://json-schema.org/draft-07/schema#",+ "title": "PAIR engine manifest launch contract",+ "description": "Validates editable_launch in shared and platform runtime blocks. Other engine manifest fields are validated by engine-manager.",+ "type": "object",+ "properties": {+ "runtime": {+ "$ref": "#/definitions/runtime"+ },+ "platforms": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "runtime": {+ "$ref": "#/definitions/runtime"+ }+ }+ }+ }+ },+ "definitions": {+ "runtime": {+ "type": "object",+ "properties": {+ "editable_launch": {+ "$ref": "#/definitions/editableLaunch"+ }+ }+ },+ "editableLaunch": {+ "type": "object",+ "additionalProperties": false,+ "required": [+ "controls"+ ],+ "properties": {+ "fixed_args": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "start_index": {+ "type": "integer",+ "minimum": 0+ },+ "controls": {+ "type": "array",+ "minItems": 1,+ "items": {+ "$ref": "#/definitions/control"+ }+ }+ }+ },+ "control": {+ "type": "object",+ "additionalProperties": false,+ "required": [+ "value"+ ],+ "anyOf": [+ {+ "required": [+ "flags"+ ]+ },+ {+ "required": [+ "env"+ ]+ }+ ],+ "properties": {+ "flags": {+ "type": "array",+ "minItems": 1,+ "uniqueItems": true,+ "items": {+ "type": "string",+ "pattern": "^(?:-[a-zA-Z]|--[a-zA-Z0-9_-]+)$"+ }+ },+ "env": {+ "type": "array",+ "minItems": 1,+ "uniqueItems": true,+ "items": {+ "type": "string",+ "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"+ }+ },+ "value": {+ "type": "string",+ "pattern": "^(?:[^{}]*\\{(?:server\\.(?:host|port)|cors\\.(?:enabled|origins))\\})+[^{}]*$",+ "description": "Binds policy fields using literal separators; fields must be unique, separated and share ownership. Engine-manager validates these cross-field constraints."+ },+ "implicit": {+ "type": "string",+ "description": "Value supplied by flag presence. Environment sources still take explicit values. Must parse as the declared value and may not bind managed server fields."+ }+ },+ "dependencies": {+ "implicit": [+ "flags"+ ]+ }+ }+ }+}diff --git a/services/nvpair-engine-manager/manifests/lmstudio.json b/services/nvpair-engine-manager/manifests/lmstudio.jsonindex 887e506..964a7cc 100644--- a/services/nvpair-engine-manager/manifests/lmstudio.json+++ b/services/nvpair-engine-manager/manifests/lmstudio.json@@ -1,4 +1,5 @@{+ "$schema": "../manifest.schema.json","engine": "lmstudio","display_name": "LM Studio","manifest_version": 1,@@ -12,6 +13,14 @@"run": ["sh", "-c", "pkill -x lms 2>/dev/null; pkill -x llmster 2>/dev/null; sleep 2; rm -rf \"$HOME/.lmstudio\"; sleep 1; [ -d \"$HOME/.lmstudio\" ] && exit 1; exit 0"]},"runtime": {+ "editable_launch": {+ "fixed_args": ["server", "start"],+ "controls": [+ { "flags": ["--port", "-p"], "value": "{server.port}" },+ { "flags": ["--bind"], "env": ["LMS_SERVER_HOST"], "value": "{server.host}" },+ { "flags": ["--cors"], "value": "{cors.enabled}", "implicit": "true" }+ ]+ },"mode": "command","port": 1235,"bind": "127.0.0.1",diff --git a/services/nvpair-engine-manager/manifests/ollama.json b/services/nvpair-engine-manager/manifests/ollama.jsonindex 6c92513..240eda7 100644--- a/services/nvpair-engine-manager/manifests/ollama.json+++ b/services/nvpair-engine-manager/manifests/ollama.json@@ -1,9 +1,17 @@{+ "$schema": "../manifest.schema.json","engine": "ollama","display_name": "Ollama","manifest_version": 1,"install": { "mode": "user" },"runtime": {+ "editable_launch": {+ "fixed_args": ["serve"],+ "controls": [+ { "env": ["OLLAMA_HOST"], "value": "{server.host}:{server.port}" },+ { "env": ["OLLAMA_ORIGINS"], "value": "{cors.origins}" }+ ]+ },"args": ["serve"],"env": { "OLLAMA_HOST": "{host}:{port}" },"bind": "127.0.0.1",diff --git a/services/nvpair-engine-manager/portoverride_test.go b/services/nvpair-engine-manager/portoverride_test.gonew file mode 100644index 0000000..ad9ee45--- /dev/null+++ b/services/nvpair-engine-manager/portoverride_test.go@@ -0,0 +1,160 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "os"+ "path/filepath"+ "reflect"+ "runtime"+ "testing"+)++func TestSetPortPreservesOtherOverrides(t *testing.T) {+ dir := t.TempDir()+ path := filepath.Join(dir, "ollama.json")+ host := runtime.GOOS + "/" + runtime.GOARCH+ original := map[string]any{+ "engine": "ollama",+ "display_name": "Custom Ollama",+ "custom_counter": json.Number("9007199254740993"),+ "runtime": map[string]any{+ "port": 21001,+ "args": []string{"serve", "--custom-option"},+ "env": map[string]string{"CUSTOM_SETTING": "kept"},+ },+ "platforms": map[string]any{+ host: map[string]any{"runtime": map[string]any{+ "port": 21002, "env": map[string]string{"HOST_SETTING": "kept"},+ }},+ },+ }+ if err := writeJSONAtomic(path, original); err != nil {+ t.Fatal(err)+ }+ ex := newBundledExecutor(t, dir)+ for _, port := range []int{21003, 11434} {+ if _, err := ex.SetPort(context.Background(), "ollama", port); err != nil {+ t.Fatal(err)+ }+ reg := loadWithOverrides(t, dir)+ manifest, _ := reg.Get("ollama")+ platform, _ := manifest.HostPlatform()+ if platform.Runtime.Port != port {+ t.Fatalf("restart restored %d instead of %d", platform.Runtime.Port, port)+ }+ if manifest.DisplayName != "Custom Ollama" ||+ !reflect.DeepEqual(platform.Runtime.Args, []string{"serve", "--custom-option"}) ||+ platform.Runtime.Env["CUSTOM_SETTING"] != "kept" ||+ platform.Runtime.Env["HOST_SETTING"] != "kept" ||+ platform.Runtime.Env["OLLAMA_HOST"] != "{host}:{port}" {+ t.Fatalf("port change lost unrelated overrides or inherited defaults: %+v", platform.Runtime)+ }+ }+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatal(err)+ }+ var saved map[string]any+ if err := json.Unmarshal(data, &saved); err != nil {+ t.Fatal(err)+ }+ if _, pinned := saved["runtime"].(map[string]any)["port"]; pinned {+ t.Fatal("reset retained a shared port override")+ }+ hostRuntime := saved["platforms"].(map[string]any)[host].(map[string]any)["runtime"].(map[string]any)+ if _, pinned := hostRuntime["port"]; pinned {+ t.Fatal("reset retained a host port override")+ }+ var exact map[string]json.RawMessage+ if err := json.Unmarshal(data, &exact); err != nil || string(exact["custom_counter"]) != "9007199254740993" {+ t.Fatalf("unrelated numeric setting lost precision: %s, %v", exact["custom_counter"], err)+ }+}++func TestPersistPortOverridesBundledPlatformPort(t *testing.T) {+ host := runtime.GOOS + "/" + runtime.GOARCH+ raw, err := json.Marshal(map[string]any{+ "engine": "platform-engine", "display_name": "Platform engine", "manifest_version": 1,+ "runtime": map[string]any{"bin": "fake", "port": 22000},+ "platforms": map[string]any{host: map[string]any{"runtime": map[string]any{"port": 22001}}},+ })+ if err != nil {+ t.Fatal(err)+ }+ reg := NewRegistry()+ if _, err := reg.addManifest("test", raw); err != nil {+ t.Fatal(err)+ }+ reg.bundledRaw["platform-engine"] = raw+ ex := NewExecutor(reg, NewReporter(nil), nil, t.TempDir())+ ex.overrideDir = t.TempDir()+ for _, port := range []int{22002, 22001} {+ if err := ex.persistPort("platform-engine", port); err != nil {+ t.Fatal(err)+ }+ reloaded := NewRegistry()+ if _, err := reloaded.addManifest("test", raw); err != nil {+ t.Fatal(err)+ }+ reloaded.bundledRaw["platform-engine"] = raw+ if err := reloaded.LoadOverrideDir(ex.overrideDir); err != nil {+ t.Fatal(err)+ }+ if got := hostPort(t, reloaded, "platform-engine"); got != port {+ t.Fatalf("host default shadowed saved port: got %d, want %d", got, port)+ }+ }+}++func TestPersistPortRefusesMalformedOverrideWithoutClobbering(t *testing.T) {+ for _, data := range []string{+ `{`, `null`, `[]`, `{}`, `{"runtime":{}}`, `{"engine":"another-engine"}`,+ `{"engine":"ollama","runtime":null}`,+ `{"engine":"ollama","platforms":[]}`,+ } {+ t.Run(data, func(t *testing.T) {+ dir := t.TempDir()+ path := filepath.Join(dir, "ollama.json")+ ex := newBundledExecutor(t, dir)+ if err := os.WriteFile(path, []byte(data), 0o600); err != nil {+ t.Fatal(err)+ }+ if _, err := ex.SetPort(context.Background(), "ollama", 23001); err == nil {+ t.Fatal("malformed override was overwritten")+ }+ got, err := os.ReadFile(path)+ if err != nil || string(got) != data {+ t.Fatalf("invalid override changed: %q, %v", got, err)+ }+ if got, _ := ex.Status("ollama"); got.Port != 11434 {+ t.Fatalf("failed persistence changed runtime port: %+v", got)+ }+ })+ }+}++func TestWriteJSONAtomicReplacesExistingFile(t *testing.T) {+ dir := t.TempDir()+ path := filepath.Join(dir, "settings.json")+ for _, port := range []int{24001, 24002} {+ if err := writeJSONAtomic(path, map[string]int{"port": port}); err != nil {+ t.Fatal(err)+ }+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatal(err)+ }+ var got map[string]int+ if err := json.Unmarshal(data, &got); err != nil || got["port"] != port {+ t.Fatalf("replacement not readable: %q, %v", data, err)+ }+ }+ entries, err := os.ReadDir(dir)+ if err != nil || len(entries) != 1 {+ t.Fatalf("atomic writer left temporary files: %v, %v", entries, err)+ }+}diff --git a/services/nvpair-engine-manager/registry.go b/services/nvpair-engine-manager/registry.goindex b44ec6e..b6a79ad 100644--- a/services/nvpair-engine-manager/registry.go+++ b/services/nvpair-engine-manager/registry.go@@ -113,13 +113,16 @@ type Fetch struct {// (e.g. LM Studio's `lms`); liveness = the readiness/health probe,// and Stop.Cmd brings it down.type Runtime struct {- Mode string `json:"mode,omitempty"`- Bin string `json:"bin,omitempty"`- Args []string `json:"args,omitempty"`- Env map[string]string `json:"env,omitempty"`- Port int `json:"port"` // 0 => auto-assign a free loopback port- Bind string `json:"bind,omitempty"` // listen addr, substituted as {host}; "" => 127.0.0.1- Start [][]string `json:"start,omitempty"` // command mode: ordered bring-up commands+ EditableLaunch *EditableLaunch `json:"editable_launch,omitempty"`+ LaunchArgs *[]string `json:"launch_args,omitempty"` // literal arguments after managed fields+ LaunchEnv *[]string `json:"launch_env,omitempty"` // complete literal explicit environment+ Mode string `json:"mode,omitempty"`+ Bin string `json:"bin,omitempty"`+ Args []string `json:"args,omitempty"`+ Env map[string]string `json:"env,omitempty"`+ Port int `json:"port"` // 0 => auto-assign a free loopback port+ Bind string `json:"bind,omitempty"` // listen addr, substituted as {host}; "" => 127.0.0.1+ Start [][]string `json:"start,omitempty"` // command mode: ordered bring-up commands// CLI is the engine's control-CLI path for this platform, referenced// elsewhere as {cli}. It lets the manifest's global actions resolve// to the correct per-OS binary (e.g. lms.exe vs lms).@@ -129,6 +132,22 @@ type Runtime struct {Health *Probe `json:"health,omitempty"`}+type EditableLaunch struct {+ FixedArgs []string `json:"fixed_args"`+ Controls []LaunchControl `json:"controls"`+ StartIndex int `json:"start_index,omitempty"`+}++// LaunchControl binds CLI/environment syntax to PAIR policy fields. Value is a+// format such as "{server.port}" or "{server.host}:{server.port}". Implicit is+// the value supplied by flag presence; environment sources always take a value.+type LaunchControl struct {+ Flags []string `json:"flags,omitempty"`+ Env []string `json:"env,omitempty"`+ Value string `json:"value"`+ Implicit *string `json:"implicit,omitempty"`+}+func (r *Runtime) modeOrDefault() string {if r.Mode == "" {return "process"@@ -136,6 +155,15 @@ func (r *Runtime) modeOrDefault() string {return r.Mode}+// hasCustomLaunch reports whether the user supplied any literal argument or+// environment assignment. A saved override writes both keys, so the untouched+// one persists as an empty — not absent — slice. Emptiness, not nil, is what+// separates a default launch from a customized one.+func (r *Runtime) hasCustomLaunch() bool {+ return (r.LaunchArgs != nil && len(*r.LaunchArgs) > 0) ||+ (r.LaunchEnv != nil && len(*r.LaunchEnv) > 0)+}+// Probe is an HTTP or TCP reachability check. Exactly one of HTTP/TCP// should be set; HTTP wins if both are.type Probe struct {@@ -568,6 +596,33 @@ func (m *Manifest) Validate() error {}func (p *Platform) validate(key string) error {+ if policy := p.Runtime.EditableLaunch; policy != nil {+ if policy.StartIndex < 0 || (p.Runtime.modeOrDefault() == "command" && policy.StartIndex >= len(p.Runtime.Start)) {+ return fmt.Errorf("platform %q: invalid editable launch definition", key)+ }+ if _, err := formatLaunchText(policy.FixedArgs); err != nil {+ return fmt.Errorf("platform %q: invalid fixed launch arguments", key)+ }+ if err := policy.validateControls(); err != nil {+ return fmt.Errorf("platform %q: %w", key, err)+ }+ }+ if args := p.Runtime.LaunchArgs; args != nil {+ if p.Runtime.EditableLaunch == nil {+ return fmt.Errorf("platform %q: launch_args requires editable_launch", key)+ }+ if _, err := formatLaunchText(append([]string{"arguments"}, (*args)...)); err != nil {+ return fmt.Errorf("platform %q: invalid literal launch arguments", key)+ }+ }+ if env := p.Runtime.LaunchEnv; env != nil {+ if p.Runtime.EditableLaunch == nil {+ return fmt.Errorf("platform %q: launch_env requires editable_launch", key)+ }+ if _, err := literalEnvironment(*env); err != nil {+ return fmt.Errorf("platform %q: invalid literal launch environment", key)+ }+ }switch p.Runtime.modeOrDefault() {case "process":if strings.TrimSpace(p.Runtime.Bin) == "" {diff --git a/services/nvpair-engine-manager/remoteclient.go b/services/nvpair-engine-manager/remoteclient.goindex 795caf2..3a19bdf 100644--- a/services/nvpair-engine-manager/remoteclient.go+++ b/services/nvpair-engine-manager/remoteclient.go@@ -46,6 +46,9 @@ type remoteClient struct {// engine back down — for a delete that means the files are gone, the engine is// left stopped, and the caller is told the delete failed.func waitsForEngineReadiness(path, engine string) bool {+ if path == settingsPath+"apply" {+ return true+ }// controlDeletePath: LM Studio's delete_model declares restart_after, so the// peer replies only after the post-delete restart is ready.if path == controlLoadPath {diff --git a/services/nvpair-engine-manager/setport.go b/services/nvpair-engine-manager/setport.goindex 5a9554c..66f0b28 100644--- a/services/nvpair-engine-manager/setport.go+++ b/services/nvpair-engine-manager/setport.go@@ -4,12 +4,14 @@package mainimport (+ "bytes""context""encoding/json""errors""fmt""os""path/filepath"+ "runtime")func canMoveAdoptedEngine(rt Runtime) bool {@@ -94,49 +96,125 @@ func (e *Executor) SetPort(ctx context.Context, engine string, port int) (Engine}// persistPort writes (or removes) the per-engine manifest override that pins-// runtime.port so the chosen port survives a restart. For a bundled engine it-// writes only the {engine, runtime:{port}} delta (which deep-merges onto the-// bundled manifest at load), and removes the override entirely when the port-// is back at the bundled default — keeping the override set minimal. For a-// non-bundled engine (a full manifest that lives only in the override dir) it-// merges the port into the existing file rather than clobbering it. Atomic-// (tmp + rename).+// runtime.port so the chosen port survives a restart. Only the port is owned+// by this operation: arguments, environment and unrelated overrides survive.+// A host-platform port is updated too, when present, because platform values+// take precedence over shared runtime defaults at load time.func (e *Executor) persistPort(engine string, port int) error {+ return e.persistRuntimeConfig(engine, port, nil, nil)+}++// persistRuntimeConfig writes the port override plus, when non-nil, the launch+// argument and environment overrides. A nil slice pointer leaves that override+// exactly as it is on disk; an empty slice clears it to "declared, but empty".+func (e *Executor) persistRuntimeConfig(engine string, port int, args, environment *[]string) error {if e.overrideDir == "" {return fmt.Errorf("no config directory available to persist the port")}- if err := os.MkdirAll(e.overrideDir, 0o755); err != nil {+ if err := os.MkdirAll(e.overrideDir, 0o700); err != nil {return fmt.Errorf("create override dir: %w", err)}+ if err := os.Chmod(e.overrideDir, 0o700); err != nil {+ return fmt.Errorf("restrict override dir: %w", err)+ }path := filepath.Join(e.overrideDir, engine+".json")- delta := map[string]any{"engine": engine, "runtime": map[string]any{"port": port}}-- if def, ok := e.reg.bundledDefaultPort(engine); ok {- // Bundled engine: back to default ⇒ drop the override; else persist- // just the delta so bundled upgrades to everything else still apply.- if def == port {- if err := os.Remove(path); err != nil && !os.IsNotExist(err) {- return fmt.Errorf("remove override: %w", err)- }- return nil+ m := map[string]any{"engine": engine}+ existing, err := os.ReadFile(path)+ if err != nil && !os.IsNotExist(err) {+ return fmt.Errorf("read override: %w", err)+ }+ if err == nil {+ m = nil+ decoder := json.NewDecoder(bytes.NewReader(existing))+ decoder.UseNumber() // unrelated manifest numbers must not lose precision+ if !json.Valid(existing) {+ return fmt.Errorf("override must be a JSON object")+ }+ if err := decoder.Decode(&m); err != nil || m == nil {+ return fmt.Errorf("override must be a JSON object")+ }+ if name, ok := m["engine"].(string); !ok || name != engine {+ return fmt.Errorf("override engine does not match %q", engine)}- return writeJSONAtomic(path, delta)}-- // Non-bundled engine: the full manifest lives only here, so merge the- // port into it rather than overwriting the file with a partial.- existing, err := os.ReadFile(path)+ rt, err := overrideObject(m, "runtime")+ if err != nil {+ return err+ }+ platforms, err := overrideObject(m, "platforms")+ if err != nil {+ return err+ }+ host := runtime.GOOS + "/" + runtime.GOARCH+ platform, err := overrideObject(platforms, host)+ if err != nil {+ return err+ }+ hostRuntime, err := overrideObject(platform, "runtime")if err != nil {- if os.IsNotExist(err) {- return writeJSONAtomic(path, delta)+ return err+ }+ def, bundled := e.reg.bundledDefaultPort(engine)+ if bundled && def == port {+ delete(rt, "port")+ delete(hostRuntime, "port")+ } else {+ rt["port"] = port+ _, hostPort := hostRuntime["port"]+ // A bundled platform-specific port would otherwise shadow the new+ // shared value even when the user's override has no platform block.+ var base struct {+ Platforms map[string]struct {+ Runtime map[string]json.RawMessage `json:"runtime"`+ } `json:"platforms"`}- return fmt.Errorf("read override: %w", err)+ if raw := e.reg.bundledRaw[engine]; len(raw) != 0 {+ if err := json.Unmarshal(raw, &base); err != nil {+ return fmt.Errorf("read bundled port: %w", err)+ }+ }+ if _, bundledHostPort := base.Platforms[host].Runtime["port"]; hostPort || bundledHostPort {+ hostRuntime["port"] = port+ }+ }+ if args != nil {+ literal := append([]string{}, (*args)...)+ hostRuntime["launch_args"] = literal}- var m map[string]any- if err := json.Unmarshal(existing, &m); err != nil {- return fmt.Errorf("parse override %s: %w", path, err)+ if environment != nil {+ hostRuntime["launch_env"] = append([]string{}, (*environment)...)+ }+ setOverrideObject(platform, "runtime", hostRuntime)+ setOverrideObject(platforms, host, platform)+ setOverrideObject(m, "platforms", platforms)+ setOverrideObject(m, "runtime", rt)+ if bundled && len(m) == 1 {+ if err := os.Remove(path); err != nil && !os.IsNotExist(err) {+ return fmt.Errorf("remove override: %w", err)+ }+ return nil+ }+ return writeJSONAtomic(path, m)+}++func overrideObject(parent map[string]any, key string) (map[string]any, error) {+ value, exists := parent[key]+ if !exists {+ return make(map[string]any), nil+ }+ object, ok := value.(map[string]any)+ if !ok || object == nil {+ return nil, fmt.Errorf("override %s must be a JSON object", key)+ }+ return object, nil+}++func setOverrideObject(parent map[string]any, key string, object map[string]any) {+ if len(object) == 0 {+ delete(parent, key)+ } else {+ parent[key] = object}- return writeJSONAtomic(path, deepMerge(m, delta))}// writeJSONAtomic marshals v and writes it to path via a tmp file + rename so@@ -146,10 +224,19 @@ func writeJSONAtomic(path string, v any) error {if err != nil {return err}- tmp := path + ".tmp"- if err := os.WriteFile(tmp, data, 0o644); err != nil {+ file, err := os.CreateTemp(filepath.Dir(path), ".override-*.tmp")+ if err != nil {+ return fmt.Errorf("create override: %w", err)+ }+ tmp := file.Name()+ defer os.Remove(tmp)+ if _, err := file.Write(data); err != nil {+ _ = file.Close()return fmt.Errorf("write override: %w", err)}+ if err := file.Close(); err != nil {+ return fmt.Errorf("close override: %w", err)+ }if err := os.Rename(tmp, path); err != nil {_ = os.Remove(tmp)return fmt.Errorf("rename override: %w", err)diff --git a/services/nvpair-engine-manager/settings.go b/services/nvpair-engine-manager/settings.gonew file mode 100644index 0000000..660c0cf--- /dev/null+++ b/services/nvpair-engine-manager/settings.go@@ -0,0 +1,443 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "fmt"+ "net"+ "reflect"+ "slices"+ "strconv"+ "strings"++ settings "nvpair-shared/enginesettings"+)++func applyLiteralLaunch(rt Runtime, command launchCommand, vars map[string]string) (launchCommand, error) {+ if rt.LaunchEnv != nil {+ env, err := literalEnvironment(*rt.LaunchEnv)+ if err != nil {+ return launchCommand{}, err+ }+ // Explicit assignments override manifest defaults. Omitted defaults+ // continue to resolve from the manifest on every launch.+ for key, template := range rt.Env {+ found := false+ for supplied := range env {+ if environmentKey(supplied) == environmentKey(key) {+ found = true+ break+ }+ }+ if !found {+ value, err := resolvePlaceholders(template, vars)+ if err != nil {+ return launchCommand{}, err+ }+ env[key] = value+ }+ }+ command.Env = env+ }+ p := rt.EditableLaunch+ if p == nil {+ if rt.LaunchArgs != nil {+ return launchCommand{}, fmt.Errorf("this engine has no editable launch definition")+ }+ return command, nil+ }+ if ip := net.ParseIP(vars["host"]); ip == nil || !ip.IsLoopback() {+ return launchCommand{}, fmt.Errorf("configured engines must bind to loopback")+ }+ // Override every declared environment spelling, including inherited aliases.+ // This also makes the default preview agree with subsequent canonical launches.+ for _, control := range p.Controls {+ if value, managed := control.managedValue(vars["host"], vars["port"]); managed {+ for _, name := range control.Env {+ if command.Env == nil {+ command.Env = map[string]string{}+ }+ for supplied := range command.Env {+ if environmentKey(supplied) == environmentKey(name) {+ delete(command.Env, supplied)+ }+ }+ command.Env[name] = value+ }+ }+ }+ if rt.LaunchArgs == nil {+ return command, nil+ }+ command.Args = slices.Clone(p.FixedArgs)+ for _, control := range p.Controls {+ if value, managed := control.managedValue(vars["host"], vars["port"]); managed && control.flag() != "" {+ command.Args = append(command.Args, control.flag(), value)+ }+ }+ command.Args = append(command.Args, (*rt.LaunchArgs)...)++ return command, nil+}++func resolveRuntimeCommand(rt Runtime, index int, vars map[string]string) (launchCommand, error) {+ command, err := resolveCommandLaunch(rt.Start[index], vars)+ if err != nil {+ return launchCommand{}, err+ }+ if rt.EditableLaunch != nil && index == rt.EditableLaunch.StartIndex {+ return applyLiteralLaunch(rt, command, vars)+ }+ return command, nil+}++// launchForState is read-only; callers hold opMu, and neither preview nor a+// settings read probes ports, starts processes or writes configuration.+func launchForState(st *engineState, port int) (launchCommand, error) {+ rt := st.plat.Runtime+ vars := map[string]string{"host": effectiveBind(rt.Bind, ""), "port": strconv.Itoa(port), "install_dir": st.installDir}+ if rt.CLI != "" {+ vars["cli"] = expandPath(rt.CLI)+ }+ st.mu.Lock()+ bin := st.binPath+ st.mu.Unlock()+ if rt.modeOrDefault() == "process" {+ return resolveProcessLaunch(rt, bin, vars)+ }+ index := 0+ if rt.EditableLaunch != nil {+ index = rt.EditableLaunch.StartIndex+ }+ if index < 0 || index >= len(rt.Start) {+ return launchCommand{}, fmt.Errorf("invalid editable start command")+ }+ return resolveRuntimeCommand(rt, index, vars)+}++func (e *Executor) launchStateLocked(engine string, st *engineState) settings.LaunchState {+ st.mu.Lock()+ result := settings.LaunchState{Engine: engine, ServerPort: st.plat.Runtime.Port, EffectivePort: st.port, Running: st.running, Adopted: st.adopted, Format: launchTextFormat}+ st.mu.Unlock()+ command, err := launchForState(st, result.ServerPort)+ if err == nil {+ result.LaunchText, err = command.argumentText(st.plat.Runtime.EditableLaunch)+ }+ switch {+ case err != nil:+ result.Reason = "The engine launch configuration cannot be displayed."+ case st.plat.Runtime.EditableLaunch == nil:+ result.Reason = "This engine does not support launch settings."+ case result.Running && result.Adopted && !canMoveAdoptedEngine(st.plat.Runtime):+ result.Reason = "Stop this engine in its own application before changing settings."+ default:+ result.Editable = true+ }+ return result+}++func (e *Executor) LaunchSettings(engine string) (settings.LaunchState, error) {+ st, err := e.state(engine)+ if err != nil {+ return settings.LaunchState{}, err+ }+ st.opMu.Lock()+ defer st.opMu.Unlock()+ return e.launchStateLocked(engine, st), nil+}++// launchCORSAssignments uses the same mandatory-control reader as preview.+// Compare effective policy, not spelling, quoting, ordering or duplicate flags.+func launchCORSAssignments(text string, policy *EditableLaunch) ([]string, error) {+ if policy == nil {+ return nil, nil+ }+ tokens, err := parseLaunchText(text)+ if err != nil {+ return nil, err+ }+ values := launchValues{}+ accept := func(control *LaunchControl, value string) error {+ if control != nil && control.localOnly() {+ _, err := values.accept(control, value)+ return err+ }+ return nil+ }+ i := 0+ for ; i < len(tokens); i++ {+ key, value, assignment := strings.Cut(tokens[i], "=")+ if !assignment || strings.HasPrefix(key, "-") || strings.ContainsAny(key, "/\\") {+ break+ }+ if err := accept(policy.environmentControl(key), value); err != nil {+ return nil, err+ }+ }+ for ; i < len(tokens); i++ {+ control, value, last, err := policy.readControl(tokens, i)+ if err != nil {+ return nil, err+ }+ i = last+ if err := accept(control, value); err != nil {+ return nil, err+ }+ }+ return values.localPolicy(), nil+}++// RejectRemoteCORSChange keeps changes to browser access policy local to the+// engine's device. Other environment assignments use the normal settings path.+func (e *Executor) RejectRemoteCORSChange(request settings.Request) error {+ st, err := e.state(request.Engine)+ if err != nil {+ // An engine this node does not have has no environment to change, and+ // the relay refuses the unknown engine on its own.+ return nil+ }+ st.opMu.Lock()+ defer st.opMu.Unlock()+ return e.rejectRemoteCORSChangeLocked(st, request)+}++func (e *Executor) rejectRemoteCORSChangeLocked(st *engineState, request settings.Request) error {+ policy := st.plat.Runtime.EditableLaunch+ current, err := launchCORSAssignments(e.launchStateLocked(request.Engine, st).LaunchText, policy)+ if err != nil {+ return err+ }+ requested, err := launchCORSAssignments(request.Settings.LaunchText, policy)+ if err != nil {+ return err+ }+ if !slices.Equal(current, requested) {+ return fmt.Errorf("CORS changes are local-only; edit them on the device running this engine")+ }+ return nil+}++func (e *Executor) PreviewLaunch(p settings.Request) (settings.Preview, error) {+ st, err := e.state(p.Engine)+ if err != nil {+ return settings.Preview{}, err+ }+ st.opMu.Lock()+ defer st.opMu.Unlock()+ if p.PreserveCORS {+ if err := e.rejectRemoteCORSChangeLocked(st, p); err != nil {+ return settings.Preview{}, err+ }+ }+ return e.previewLaunchLocked(st, p), nil+}++func (e *Executor) previewLaunchLocked(st *engineState, request settings.Request) settings.Preview {+ result := settings.Preview{Settings: request.Settings, Args: []string{}, Env: []string{}, Errors: map[string]string{}}+ fail := func(message string) settings.Preview { result.Errors["launchText"] = message; return result }+ if request.Settings.ServerPort < 1 || request.Settings.ServerPort > 65535 {+ result.Errors["serverPort"] = "Enter a server port from 1 to 65535."+ return result+ }+ if err := e.reservedPortError(request.Settings.ServerPort); err != nil {+ result.Errors["serverPort"] = err.Error()+ return result+ }+ rt := st.plat.Runtime+ policy := rt.EditableLaunch+ if policy == nil {+ return fail("This engine does not support launch settings.")+ }+ if request.Resolution != "" && request.Resolution != "server" && request.Resolution != "launch" {+ return fail("Invalid port conflict resolution.")+ }+ base, err := launchForState(st, request.Settings.ServerPort)+ if err != nil {+ return fail("Cannot resolve the engine executable.")+ }+ host := effectiveBind(rt.Bind, "")+ vars := map[string]string{+ "host": host, "port": strconv.Itoa(request.Settings.ServerPort),+ "install_dir": st.installDir, "bin": base.Bin, "cli": expandPath(rt.CLI),+ }+ if ip := net.ParseIP(host); ip == nil || !ip.IsLoopback() {+ return fail("PAIR-managed launch settings require a loopback bind.")+ }+ tokens, err := parseLaunchText(request.Settings.LaunchText)+ if err != nil {+ return fail(err.Error())+ }+ values := launchValues{host: host}+ seenEnv := map[string]bool{}+ for len(tokens) > 0 {+ key, value, assignment := strings.Cut(tokens[0], "=")+ if !assignment || strings.HasPrefix(key, "-") || strings.ContainsAny(key, `/\`) {+ break+ }+ if !validEnvironmentKey(key) {+ return fail("Environment variable names must start with a letter or underscore and contain only letters, digits, or underscores.")+ }+ if seenEnv[environmentKey(key)] {+ return fail("An environment assignment is repeated.")+ }+ seenEnv[environmentKey(key)] = true+ managed := false+ if control := policy.environmentControl(key); control != nil {+ normalized, err := values.accept(control, value)+ if err != nil {+ return fail(err.Error())+ }+ value = normalized+ _, managed = control.managedValue(host, strconv.Itoa(request.Settings.ServerPort))+ }+ if !managed {+ // Omitted manifest defaults remain live; non-networking values stay literal.+ isDefault := false+ for declared, template := range rt.Env {+ if environmentKey(declared) == environmentKey(key) {+ resolved, err := resolvePlaceholders(template, vars)+ isDefault = err == nil && value == resolved+ break+ }+ }+ if !isDefault {+ result.Env = append(result.Env, key+"="+value)+ }+ }++ tokens = tokens[1:]+ }+ // Compatibility for journals created by the earlier full-command editor.+ // New requests contain arguments only; no executable is editable.+ if request.Format == "pair-launch-v1" {+ if len(tokens) < 1+len(policy.FixedArgs) || tokens[0] != base.Bin || !slices.Equal(tokens[1:1+len(policy.FixedArgs)], policy.FixedArgs) {+ return fail("The saved command does not match this engine's startup command.")+ }+ tokens = tokens[1+len(policy.FixedArgs):]+ } else if request.Format != "" && request.Format != launchTextFormat {+ return fail("Unsupported engine argument format.")+ }+ // Every remaining token is validated, including anything after a "--"+ // separator. PAIR appends these after its own managed --port/--bind, so a+ // last-flag-wins engine would honour "-- --bind 0.0.0.0" if the separator+ // ended validation. "--" itself is passed through as a literal argument.+ for i := 0; i < len(tokens); i++ {+ control, value, last, err := policy.readControl(tokens, i)+ if err != nil {+ return fail(err.Error())+ }+ i = last+ if control == nil {+ result.Args = append(result.Args, tokens[i])+ continue+ }+ normalized, err := values.accept(control, value)+ if err != nil {+ return fail(err.Error())+ }+ if _, managed := control.managedValue(host, strconv.Itoa(request.Settings.ServerPort)); !managed {+ result.Args = append(result.Args, control.flag())+ if control.Implicit == nil {+ result.Args = append(result.Args, normalized)+ }+ }+ }++ if values.serverPort() != 0 && values.serverPort() != request.Settings.ServerPort {+ switch request.Resolution {+ case "server":+ case "launch":+ result.Settings.ServerPort = values.serverPort()+ default:+ result.Conflict = &settings.Conflict{ServerPort: request.Settings.ServerPort, LaunchPort: values.serverPort()}+ return result+ }+ }+ if err := e.reservedPortError(result.Settings.ServerPort); err != nil {+ result.Errors["serverPort"] = err.Error()+ return result+ }+ rt.LaunchArgs = &result.Args+ rt.LaunchEnv = &result.Env+ vars["port"] = strconv.Itoa(result.Settings.ServerPort)+ command, err := applyLiteralLaunch(rt, base, vars)+ if err != nil {+ return fail(err.Error())+ }+ result.Settings.LaunchText, err = command.argumentText(policy)+ if err != nil {+ return fail(err.Error())+ }+ current := e.launchStateLocked(request.Engine, st)+ result.Restart = current.Running && (current.ServerPort != result.Settings.ServerPort || current.LaunchText != result.Settings.LaunchText)+ if !current.Editable {+ return fail(current.Reason)+ }+ return result+}++// ConfigureLaunch owns the entire engine operation lock, including the narrow+// parent rebind callback. The parent already holds the node configuration lock;+// that callback must not acquire it again. Explicit ON/OFF intent is untouched.+func (e *Executor) ConfigureLaunch(ctx context.Context, p settings.Configure, rebind func() error) (settings.LaunchState, error) {+ st, err := e.state(p.Engine)+ if err != nil {+ return settings.LaunchState{}, err+ }+ st.opMu.Lock()+ defer st.opMu.Unlock()+ if err := ctx.Err(); err != nil {+ return settings.LaunchState{}, err+ }+ preview := e.previewLaunchLocked(st, settings.Request{Engine: p.Engine, Settings: p.Settings})+ if len(preview.Errors) > 0 || preview.Conflict != nil {+ return settings.LaunchState{}, fmt.Errorf("launch configuration failed authoritative validation")+ }+ // This operation returns its one failure through the settings snapshot.+ // Do not also open the global lifecycle error dialog for the same attempt.+ ctx = context.WithValue(ctx, settingsApplyContextKey{}, true)+ e.reporter.clear(startFailedID(p.Engine))+ e.reporter.clear(exitedID(p.Engine))+ old := e.launchStateLocked(p.Engine, st)+ changed := old.ServerPort != preview.Settings.ServerPort || old.LaunchText != preview.Settings.LaunchText+ // Stop before writing the override file. A stop failure returns with the+ // engine still on its old launch, so persisting first would leave disk on+ // the new one and the next start would silently adopt a configuration the+ // user was told had failed.+ if changed && old.Running {+ if err := e.doStop(st, p.Engine); err != nil {+ return e.launchStateLocked(p.Engine, st), err+ }+ }+ if changed || !reflect.DeepEqual(st.plat.Runtime.LaunchArgs, &preview.Args) || !reflect.DeepEqual(st.plat.Runtime.LaunchEnv, &preview.Env) {+ if err := e.persistRuntimeConfig(p.Engine, preview.Settings.ServerPort, &preview.Args, &preview.Env); err != nil {+ return e.launchStateLocked(p.Engine, st), err+ }+ }+ st.mu.Lock()+ st.plat.Runtime.Port = preview.Settings.ServerPort+ st.plat.Runtime.LaunchArgs = &preview.Args+ st.plat.Runtime.LaunchEnv = &preview.Env+ st.port = preview.Settings.ServerPort+ st.mu.Unlock()+ if err := rebind(); err != nil {+ e.emitState(p.Engine)+ return e.launchStateLocked(p.Engine, st), err+ }+ resume := p.Resume+ if enabled, known, err := e.desired.get(p.Engine); err == nil && known && !enabled && !old.Running {+ resume = false+ }+ if (changed && old.Running) || resume {+ if err := e.doStart(ctx, st, p.Engine, startOpts{RequireOwned: true}); err != nil {+ e.emitState(p.Engine)+ return e.launchStateLocked(p.Engine, st), err+ }+ }+ e.emitState(p.Engine)+ return e.launchStateLocked(p.Engine, st), nil+}++type settingsApplyContextKey struct{}diff --git a/services/nvpair-engine-manager/settings_permissions_test.go b/services/nvpair-engine-manager/settings_permissions_test.gonew file mode 100644index 0000000..1a37298--- /dev/null+++ b/services/nvpair-engine-manager/settings_permissions_test.go@@ -0,0 +1,38 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "os"+ "path/filepath"+ "runtime"+ "testing"+)++func TestSettingsOverrideRestrictsExistingPermissions(t *testing.T) {+ if runtime.GOOS == "windows" {+ t.Skip("POSIX permission bits are not enforced on Windows")+ }+ e := settingsExecutor(t, false)+ if err := os.Chmod(e.overrideDir, 0755); err != nil {+ t.Fatal(err)+ }+ path := filepath.Join(e.overrideDir, "fake.json")+ if err := os.WriteFile(path, []byte(`{"engine":"fake"}`), 0644); err != nil {+ t.Fatal(err)+ }+ environment := []string{"PAIR_TEST=private"}+ if err := e.persistRuntimeConfig("fake", 54321, nil, &environment); err != nil {+ t.Fatal(err)+ }+ for path, want := range map[string]os.FileMode{e.overrideDir: 0700, path: 0600} {+ info, err := os.Stat(path)+ if err != nil {+ t.Fatal(err)+ }+ if got := info.Mode().Perm(); got != want {+ t.Fatalf("%s permissions=%o, want %o", path, got, want)+ }+ }+}diff --git a/services/nvpair-engine-manager/settings_test.go b/services/nvpair-engine-manager/settings_test.gonew file mode 100644index 0000000..00c2968--- /dev/null+++ b/services/nvpair-engine-manager/settings_test.go@@ -0,0 +1,951 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "net"+ "os"+ "path/filepath"+ "reflect"+ "runtime"+ "slices"+ "strings"+ "testing"+ "time"++ settings "nvpair-shared/enginesettings"+)++func settingsExecutor(t *testing.T, command bool) *Executor {+ t.Helper()+ m := testEngineManifest(fakeEngineBin)+ key := runtime.GOOS + "/" + runtime.GOARCH+ p := m.Platforms[key]+ port, err := freePort()+ if err != nil {+ t.Fatal(err)+ }+ p.Runtime.Port = port+ p.Runtime.Args = []string{"serve"}+ p.Runtime.EditableLaunch = &EditableLaunch{FixedArgs: []string{"serve"}, Controls: []LaunchControl{{Value: "{server.host}:{server.port}", Env: []string{"OLLAMA_HOST"}}, {Value: "{cors.origins}", Env: []string{"OLLAMA_ORIGINS"}}}}+ if command {+ p.Runtime.Mode = "command"+ p.Runtime.CLI = fakeEngineBin+ p.Runtime.Start = [][]string{{"{cli}", "server", "start", "--port", "{port}", "--bind", "{host}"}}+ p.Runtime.EditableLaunch = &EditableLaunch{FixedArgs: []string{"server", "start"}, Controls: []LaunchControl{{Value: "{server.port}", Flags: []string{"--port", "-p"}}, {Value: "{server.host}", Flags: []string{"--bind"}, Env: []string{"LMS_SERVER_HOST"}}, {Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"--cors"}}}}+ }+ m.Platforms[key] = p+ e := newTestExecutor(t, m)+ e.overrideDir = t.TempDir()+ if _, err := e.Detect("fake"); err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = e.Stop("fake") })+ return e+}++func settingsRequest(t *testing.T, e *Executor) settings.Request {+ t.Helper()+ s, err := e.LaunchSettings("fake")+ if err != nil {+ t.Fatal(err)+ }+ return settings.Request{Engine: "fake", Settings: settings.Config{ServerPort: s.ServerPort, ProxyPort: 54301, LaunchText: s.LaunchText}}+}++// eachEngineMode runs test against both Runtime.Mode lifecycles: "process",+// where this service spawns the engine and its managed controls bind to+// environment variables, and "command", where a control CLI brings the engine+// up and the same controls bind to flags. The launch settings path must behave+// identically either way, so every mode-independent test here runs twice.+func eachEngineMode(t *testing.T, test func(*testing.T, *Executor)) {+ t.Helper()+ t.Run("process mode", func(t *testing.T) { test(t, settingsExecutor(t, false)) })+ t.Run("command mode", func(t *testing.T) { test(t, settingsExecutor(t, true)) })+}++func previewSettings(t *testing.T, e *Executor, request settings.Request) settings.Preview {+ t.Helper()+ preview, err := e.PreviewLaunch(request)+ if err != nil {+ t.Fatalf("PreviewLaunch: %v", err)+ }+ return preview+}++func settingsState(t *testing.T, e *Executor) *engineState {+ t.Helper()+ state, err := e.state("fake")+ if err != nil {+ t.Fatal(err)+ }+ return state+}++func assertNoSettingsOverride(t *testing.T, e *Executor) {+ t.Helper()+ entries, err := os.ReadDir(e.overrideDir)+ if err != nil {+ t.Fatal(err)+ }+ if len(entries) != 0 {+ t.Fatal("rejected operation wrote configuration")+ }+}++func TestSettingsPreviewPreservesLiteralArguments(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ request := settingsRequest(t, e)+ request.Settings.LaunchText += ` --parallel 3 "two words" "" "{port}" "$HOME"`+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 || preview.Conflict != nil {+ t.Fatalf("valid preview: %+v", preview)+ }+ want := []string{"--parallel", "3", "two words", "", "{port}", "$HOME"}+ if !reflect.DeepEqual(preview.Args, want) {+ t.Fatalf("literal args: %#v, want %#v", preview.Args, want)+ }+ assertNoSettingsOverride(t, e)+ })+}++func TestSettingsPreviewPortConflict(t *testing.T) {+ test := func(name, resolution string) {+ t.Run(name, func(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ request := settingsRequest(t, e)+ launchPort := request.Settings.ServerPort+ request.Settings.ServerPort+++ request.Resolution = resolution+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 {+ t.Fatalf("unexpected errors: %v", preview.Errors)+ }+ if resolution == "" {+ if preview.Conflict == nil || preview.Conflict.ServerPort != request.Settings.ServerPort || preview.Conflict.LaunchPort != launchPort {+ t.Fatalf("missing port conflict: %+v", preview)+ }+ return+ }+ want := request.Settings.ServerPort+ if resolution == "launch" {+ want = launchPort+ }+ if preview.Conflict != nil || preview.Settings.ServerPort != want {+ t.Fatalf("resolution %s: %+v, want port %d", resolution, preview, want)+ }+ })+ })+ }+ test("requires explicit resolution", "")+ test("uses server field", "server")+ test("uses launch port", "launch")+}++func TestSettingsPreviewChecksOnlyDeclaredControls(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ for _, suffix := range []string{" | other", " && other"} {+ p := settingsRequest(t, e)+ p.Settings.LaunchText += suffix+ if result := previewSettings(t, e, p); result.Errors["launchText"] == "" {+ t.Fatalf("accepted shell syntax: %q", suffix)+ }+ }+ policy := settingsState(t, e).plat.Runtime.EditableLaunch+ if policy.Controls[0].Value == "{server.port}" {+ for _, suffix := range []string{" --bind 0.0.0.0", " --port 0", " -- --bind 0.0.0.0"} {+ p := settingsRequest(t, e)+ p.Settings.LaunchText += suffix+ if result := previewSettings(t, e, p); result.Errors["launchText"] == "" {+ t.Fatalf("accepted invalid managed control: %q", suffix)+ }+ }+ } else {+ p := settingsRequest(t, e)+ p.Settings.LaunchText = "OLLAMA_HOST=0.0.0.0:12345"+ if result := previewSettings(t, e, p); result.Errors["launchText"] == "" {+ t.Fatal("accepted invalid managed host")+ }+ }+ assertNoSettingsOverride(t, e)+ })+}++func TestSettingsDoesNotGuessNetworkOptionSemantics(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ p := settingsRequest(t, e)+ want := []string{"--bind-address", "0.0.0.0", "--set", "host=0.0.0.0", "--set=port=22", "--set=--bind=0.0.0.0", "--hostname=anything", "--listen=anything"}+ text, err := formatLaunchText(want)+ if err != nil {+ t.Fatal(err)+ }+ p.Settings.LaunchText += " " + text+ result := previewSettings(t, e, p)+ if len(result.Errors) != 0 || !reflect.DeepEqual(result.Args, want) {+ t.Fatalf("opaque options changed or rejected: %+v", result)+ }+ })+}++func TestSettingsPreviewAcceptsUnrelatedOptions(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ request := settingsRequest(t, e)+ want := []string{"--transport", "grpc", "-v", "--max-tokens", "not-a-number",+ "--future-engine-option", "unknown-value", "-batch", "-ctx-size", "4096",+ "--config", "custom.json", "--config-file=custom.json", "--api-key", "test-value",+ "--token=test-value", "--password=test-value", "--secret=test-value",+ "--set=transport=grpc", "--label=host", "--set=api-key=test-value", "--set=token=test-value"}+ text, err := formatLaunchText(want)+ if err != nil {+ t.Fatal(err)+ }+ request.Settings.LaunchText += " " + text+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 || preview.Conflict != nil {+ t.Fatalf("safe options rejected: %+v", preview)+ }+ if !reflect.DeepEqual(preview.Args, want) {+ t.Fatalf("args = %v, want %v", preview.Args, want)+ }+ })+}++func TestSettingsArgumentsDoNotIncludeExecutableOrSubcommand(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ p := settingsRequest(t, e)+ if strings.Contains(p.Settings.LaunchText, fakeEngineBin) || strings.Contains(p.Settings.LaunchText, "server start") || strings.Contains(p.Settings.LaunchText, "serve") {+ t.Fatalf("manifest command leaked into editor: %q", p.Settings.LaunchText)+ }+ p.Settings.LaunchText = "different serve"+ result := previewSettings(t, e, p)+ if len(result.Errors) != 0 {+ t.Fatalf("positional arguments rejected: %+v", result)+ }+ st := settingsState(t, e)+ rt := st.plat.Runtime+ rt.LaunchArgs = &result.Args+ rt.LaunchEnv = &result.Env+ launch, err := launchForState(st, p.Settings.ServerPort)+ if err != nil {+ t.Fatal(err)+ }+ actual, err := applyLiteralLaunch(rt, launch, map[string]string{"host": "127.0.0.1", "port": fmt.Sprint(p.Settings.ServerPort)})+ if err != nil || actual.Bin != fakeEngineBin || !slices.Equal(actual.Args[:len(rt.EditableLaunch.FixedArgs)], rt.EditableLaunch.FixedArgs) {+ t.Fatalf("arguments changed the executable/subcommand: %+v %v", actual, err)+ }+ })+}++func TestSettingsMigratesFullCommandWithoutChangingArguments(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ p := settingsRequest(t, e)+ launch, err := launchForState(settingsState(t, e), p.Settings.ServerPort)+ if err != nil {+ t.Fatal(err)+ }+ p.Settings.LaunchText, err = launch.text()+ if err != nil {+ t.Fatal(err)+ }+ p.Settings.LaunchText += ` --future-option "two words"`+ p.Format = "pair-launch-v1"+ result := previewSettings(t, e, p)+ if len(result.Errors) != 0 || !reflect.DeepEqual(result.Args, []string{"--future-option", "two words"}) || strings.Contains(result.Settings.LaunchText, fakeEngineBin) {+ t.Fatalf("migration changed arguments: %+v", result)+ }+ })+}++func TestSettingsEmptyArgumentsRestoreManagedDefaults(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ p := settingsRequest(t, e)+ p.Settings.LaunchText = ""+ result := previewSettings(t, e, p)+ if len(result.Errors) != 0 || len(result.Args) != 0 || len(result.Env) != 0 || result.Settings.ServerPort != p.Settings.ServerPort {+ t.Fatalf("empty arguments did not restore defaults: %+v", result)+ }+ })+}++func readSettingsOverride(t *testing.T, e *Executor) Runtime {+ t.Helper()+ data, err := os.ReadFile(filepath.Join(e.overrideDir, "fake.json"))+ if err != nil {+ t.Fatal(err)+ }+ var override struct {+ Platforms map[string]struct {+ Runtime Runtime `json:"runtime"`+ } `json:"platforms"`+ }+ if err := json.Unmarshal(data, &override); err != nil {+ t.Fatalf("decode override: %v", err)+ }+ platform, ok := override.Platforms[runtime.GOOS+"/"+runtime.GOARCH]+ if !ok {+ t.Fatal("host platform missing from override")+ }+ return platform.Runtime+}++// lifecycle is what applying settings should do to the engine process.+type lifecycle int++const (+ staysStopped lifecycle = iota+ preservesProcess+ restartsProcess+)++func TestSettingsConfigureLifecycle(t *testing.T) {+ test := func(name string, want lifecycle, edit func(*testing.T, *settings.Request)) {+ t.Run(name, func(t *testing.T) {+ e := settingsExecutor(t, false)+ st := settingsState(t, e)+ startLog := filepath.Join(t.TempDir(), "starts.jsonl")+ st.plat.Runtime.Env["FAKE_START_LOG"] = startLog+ if want != staysStopped {+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ }+ pid := func() int {+ st.mu.Lock()+ defer st.mu.Unlock()+ if st.proc == nil {+ return 0+ }+ return st.proc.cmd.Process.Pid+ }+ before := pid()+ request := settingsRequest(t, e)+ edit(t, &request)+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 || preview.Conflict != nil {+ t.Fatalf("preview: %+v", preview)+ }+ rebinds := 0+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: preview.Settings}, func() error { rebinds++; return nil })+ if err != nil {+ t.Fatal(err)+ }+ got := staysStopped+ if result.Running {+ got = preservesProcess+ }+ if pid() != before {+ got = restartsProcess+ }+ if got != want || rebinds != 1 {+ t.Fatalf("result=%+v pid=%d previous=%d rebinds=%d", result, pid(), before, rebinds)+ }+ if result.ServerPort != preview.Settings.ServerPort {+ t.Fatalf("port=%d, want %d", result.ServerPort, preview.Settings.ServerPort)+ }+ override := readSettingsOverride(t, e)+ if override.LaunchArgs == nil || !reflect.DeepEqual(*override.LaunchArgs, preview.Args) {+ t.Fatalf("persisted arguments = %v, want %v", override.LaunchArgs, preview.Args)+ }+ if want != staysStopped {+ data, err := os.ReadFile(startLog)+ if err != nil {+ t.Fatal(err)+ }+ launches := 1+ if want == restartsProcess {+ launches+++ }+ if count := bytes.Count(data, []byte("\n")); count != launches {+ t.Fatalf("launch count=%d, want %d", count, launches)+ }+ } else if _, err := os.Stat(startLog); !os.IsNotExist(err) {+ t.Fatalf("stopped engine launched: %v", err)+ }+ })+ }+ test("no-op preserves process", preservesProcess, func(*testing.T, *settings.Request) {})+ test("proxy port preserves process", preservesProcess, func(t *testing.T, request *settings.Request) {+ request.Settings.ProxyPort+++ })+ test("literal arguments restart process", restartsProcess, func(t *testing.T, request *settings.Request) {+ request.Settings.LaunchText += ` --parallel 4 "{port}"`+ })+ test("server port restarts process", restartsProcess, func(t *testing.T, request *settings.Request) {+ port, err := freePort()+ if err != nil {+ t.Fatal(err)+ }+ request.Settings.ServerPort = port+ request.Resolution = "server"+ })+ test("stopped engine stays stopped", staysStopped, func(t *testing.T, request *settings.Request) {+ request.Settings.LaunchText += " --another-option"+ })+}++// A no-op Apply still persists an empty launch_env; log capture must survive.++func TestSettingsNoOpApplyKeepsEngineLogCapture(t *testing.T) {+ e := settingsExecutor(t, false)+ st := settingsState(t, e)+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ if len(st.logs.snapshot()) == 0 {+ t.Fatal("no engine output captured before Apply")+ }+ request := settingsRequest(t, e)+ preview, err := e.PreviewLaunch(request)+ if err != nil || len(preview.Errors) > 0 {+ t.Fatalf("preview: %+v %v", preview, err)+ }+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: preview.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ st.mu.Lock()+ persisted := st.plat.Runtime.LaunchEnv+ st.mu.Unlock()+ if persisted == nil || len(*persisted) != 0 {+ t.Fatalf("expected a no-op Apply to leave an empty launch_env, got %v", persisted)+ }+ if err := e.Stop("fake"); err != nil {+ t.Fatal(err)+ }+ before := len(st.logs.snapshot())+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ if len(st.logs.snapshot()) == before {+ t.Fatal("engine log capture stopped after a no-op Apply persisted an empty launch_env")+ }+}++func TestSettingsEarlyLaunchFailureRetainsDesiredOptions(t *testing.T) {+ e := settingsExecutor(t, false)+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ p := settingsRequest(t, e)+ p.Settings.LaunchText += " --fail-launch private-value"+ started := time.Now()+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: p.Settings}, func() error { return nil })+ if err == nil || result.Running || !strings.Contains(err.Error(), "exited before readiness") {+ t.Fatalf("early failure misreported: %+v %v", result, err)+ }+ if time.Since(started) > 5*time.Second {+ t.Fatal("early exit waited through readiness timeout")+ }+ if !strings.Contains(result.LaunchText, "--fail-launch") {+ t.Fatal("failed desired arguments lost")+ }+ if !strings.Contains(err.Error(), "invalid launch") || strings.Contains(err.Error(), "private-value") {+ t.Fatal("vendor echo escaped into error")+ }+ if errors := e.Errors(); hasErr(errors, startFailedID("fake")) || hasErr(errors, exitedID("fake")) {+ t.Fatalf("settings failure was also reported through the global dialog: %+v", errors)+ }+}++func TestEarlyExitHasOneStartError(t *testing.T) {+ e := settingsExecutor(t, false)+ p := settingsRequest(t, e)+ p.Settings.LaunchText += " --fail-launch"+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: p.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ if err := e.Start(context.Background(), "fake"); err == nil {+ t.Fatal("expected failed start")+ }+ if errors := e.Errors(); len(errors) != 1 || !hasErr(errors, startFailedID("fake")) || hasErr(errors, exitedID("fake")) {+ t.Fatalf("expected one start failure, got %+v", errors)+ }+}++func TestSettingsCORSOriginsValidationAndNormalization(t *testing.T) {+ test := func(name, origins, wantError string) {+ t.Run(name, func(t *testing.T) {+ e := settingsExecutor(t, false)+ request := settingsRequest(t, e)+ request.Settings.LaunchText = `OLLAMA_ORIGINS="` + origins + `" ` + request.Settings.LaunchText+ result := previewSettings(t, e, request)+ if wantError != "" {+ if !strings.Contains(result.Errors["launchText"], wantError) {+ t.Fatalf("expected %q: %+v", wantError, result)+ }+ } else {+ if len(result.Errors) != 0 {+ t.Fatalf("valid origins rejected: %+v", result)+ }+ env, err := literalEnvironment(result.Env)+ if err != nil {+ t.Fatal(err)+ }+ if value, ok := env["OLLAMA_ORIGINS"]; !ok || value != origins {+ t.Fatalf("origins = %q (present %v), want %q", value, ok, origins)+ }+ }+ assertNoSettingsOverride(t, e)+ })+ }+ test("rejects origin without scheme", "localhost", `"http://localhost"`)+ test("rejects mixed valid and invalid origins", "http://localhost,invalid", `"http://localhost"`)+ test("rejects bare wildcard", "*", "every origin")+ test("rejects wildcard host", "http://*", "every origin")+ test("rejects wildcard scheme and host", "*://*", "every origin")+ test("rejects wildcard in origin list", "http://localhost,*", "every origin")+ test("accepts localhost URL", "http://localhost", "")+ test("accepts explicit origin list", "https://example.test,http://localhost", "")+ test("accepts wildcard subdomain", "https://*.example.test", "")+ test("accepts empty origins", "", "")+}++func TestSettingsCORSIsOptionalAndIndependentOfEngine(t *testing.T) {+ test := func(name, corsEnv, corsFlag, prefix, suffix string, wantError bool) {+ t.Run(name, func(t *testing.T) {+ e := settingsExecutor(t, false)+ rt := &settingsState(t, e).plat.Runtime+ rt.Env = map[string]string{"FUTURE_BIND": "{host}:{port}"}+ rt.EditableLaunch = &EditableLaunch{FixedArgs: []string{"serve"}, Controls: []LaunchControl{{Value: "{server.host}:{server.port}", Env: []string{"FUTURE_BIND"}}}}+ if corsEnv != "" {+ rt.EditableLaunch.Controls = append(rt.EditableLaunch.Controls, LaunchControl{Value: "{cors.origins}", Env: []string{corsEnv}})+ }+ if corsFlag != "" {+ rt.EditableLaunch.Controls = append(rt.EditableLaunch.Controls, LaunchControl{Value: "{cors.origins}", Flags: []string{corsFlag}})+ }++ request := settingsRequest(t, e)+ request.Settings.LaunchText = prefix + request.Settings.LaunchText + suffix+ preview := previewSettings(t, e, request)+ if (len(preview.Errors) != 0) != wantError {+ t.Fatalf("preview errors = %v, want error %v", preview.Errors, wantError)+ }+ if !wantError {+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ }+ })+ }+ test("no CORS option required", "", "", "", " --future-option arbitrary", false)+ test("undeclared CORS configuration stays opaque", "", "", "FUTURE_ORIGINS=* ", " --cors", false)+ test("declared environment accepts origins", "FUTURE_ORIGINS", "", "FUTURE_ORIGINS=https://example.test ", "", false)+ test("declared environment rejects wildcard", "FUTURE_ORIGINS", "", "FUTURE_ORIGINS=* ", "", true)+ test("declared flag accepts origins", "", "--browser-origins", "", " --browser-origins https://example.test", false)+ test("declared flag accepts equals form", "", "--browser-origins", "", " --browser-origins=https://example.test", false)+ test("declared flag rejects wildcard", "", "--browser-origins", "", " --browser-origins=*", true)+ test("declared flag rejects missing value", "", "--browser-origins", "", " --browser-origins", true)+}++func TestSettingsPassesUnknownEnvironmentNamesAndValues(t *testing.T) {+ eachEngineMode(t, func(t *testing.T, e *Executor) {+ request := settingsRequest(t, e)+ want := []string{"FUTURE_ENGINE_SETTING=unknown-value", "OLLAMA_CONTEXT_LENGTH=not-a-number",+ "OLLAMA_HOSTNAME=example.test", "PATH=/custom", "LD_LIBRARY_PATH=/custom/lib"}+ text, err := formatLaunchText(want)+ if err != nil {+ t.Fatal(err)+ }+ request.Settings.LaunchText = text + " " + request.Settings.LaunchText+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 || preview.Conflict != nil {+ t.Fatalf("opaque environment rejected: %+v", preview)+ }+ if !reflect.DeepEqual(preview.Env, want) {+ t.Fatalf("environment = %v, want %v", preview.Env, want)+ }+ assertNoSettingsOverride(t, e)+ })+}++func manifestSettingsRequest(t *testing.T, platform string) (*Executor, settings.Request, []string) {+ t.Helper()+ reg := loadWithOverrides(t, t.TempDir())+ manifest, ok := reg.Get("ollama")+ if !ok {+ t.Fatal("Ollama manifest missing")+ }+ config, ok := manifest.Platforms[platform]+ if !ok {+ t.Fatalf("platform %q missing", platform)+ }+ e := settingsExecutor(t, false)+ settingsState(t, e).plat.Runtime = config.Runtime+ request := settingsRequest(t, e)+ tokens, err := parseLaunchText(request.Settings.LaunchText)+ if err != nil {+ t.Fatal(err)+ }+ if len(tokens) == 0 || !strings.HasPrefix(tokens[0], "LD_LIBRARY_PATH=") {+ t.Fatalf("missing manifest library path: %v", tokens)+ }+ return e, request, tokens+}++func TestSettingsManifestEnvironmentCanBeOverridden(t *testing.T) {+ test := func(name, platform, replacement string) {+ t.Run(name, func(t *testing.T) {+ e, request, tokens := manifestSettingsRequest(t, platform)+ tokens[0] = "LD_LIBRARY_PATH=" + replacement+ var err error+ request.Settings.LaunchText, err = formatLaunchText(tokens)+ if err != nil {+ t.Fatal(err)+ }+ if preview := previewSettings(t, e, request); len(preview.Errors) != 0 {+ t.Fatalf("rejected replacement library path %q: %+v", replacement, preview)+ }+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ override := readSettingsOverride(t, e)+ env, err := literalEnvironment(*override.LaunchEnv)+ if err != nil || env["LD_LIBRARY_PATH"] != replacement {+ t.Fatalf("saved environment = %v, error %v", env, err)+ }+ })+ }+ test("amd64 custom directory", "linux/amd64", "/custom/libraries")+ test("amd64 empty directory", "linux/amd64", "")+ test("amd64 literal template", "linux/amd64", "{install_dir}/other")+ test("arm64 custom directory", "linux/arm64", "/custom/libraries")+ test("arm64 empty directory", "linux/arm64", "")+ test("arm64 literal template", "linux/arm64", "{install_dir}/other")+}++func TestSettingsSafeEditPreservesManifestEnvironment(t *testing.T) {+ test := func(name, platform string, omitFixed bool) {+ t.Run(name, func(t *testing.T) {+ e, request, tokens := manifestSettingsRequest(t, platform)+ if omitFixed {+ var err error+ request.Settings.LaunchText, err = formatLaunchText(tokens[1:])+ if err != nil {+ t.Fatal(err)+ }+ }+ request.Settings.LaunchText = "OLLAMA_NUM_PARALLEL=3 " + request.Settings.LaunchText+ preview := previewSettings(t, e, request)+ if len(preview.Errors) != 0 {+ t.Fatalf("safe edit rejected: %+v", preview)+ }+ actual, err := parseLaunchText(preview.Settings.LaunchText)+ if err != nil {+ t.Fatal(err)+ }+ if len(actual) == 0 || actual[0] != tokens[0] {+ t.Fatalf("safe edit lost fixed library path: %v", actual)+ }+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ state := settingsState(t, e)+ state.installDir = "/updated-install"+ launch, err := launchForState(state, request.Settings.ServerPort)+ if err != nil || launch.Env["LD_LIBRARY_PATH"] != "/updated-install/lib/ollama" {+ t.Fatalf("default environment stopped following the manifest: %v, %v", launch.Env, err)+ }+ })+ }+ test("amd64 retains fixed assignment", "linux/amd64", false)+ test("amd64 restores omitted assignment", "linux/amd64", true)+ test("arm64 retains fixed assignment", "linux/arm64", false)+ test("arm64 restores omitted assignment", "linux/arm64", true)+}++func TestSettingsBudgetCoversBundledReadiness(t *testing.T) {+ reg := loadWithOverrides(t, t.TempDir())+ for _, name := range reg.Names() {+ manifest, ok := reg.Get(name)+ if !ok {+ t.Fatalf("manifest %q missing", name)+ }+ for platform, config := range manifest.Platforms {+ rt := config.Runtime+ if rt.EditableLaunch == nil || rt.Ready == nil {+ continue+ }+ required := time.Duration(rt.Ready.TimeoutS) * time.Second+ if rt.Stop != nil {+ required += time.Duration(rt.Stop.GraceS) * time.Second+ }+ if settings.ConfigureBudget <= required {+ t.Errorf("%s/%s: configure budget %s cuts off stop/readiness allowance %s", name, platform, settings.ConfigureBudget, required)+ }+ }+ }+ if settings.OperationBudget <= settings.ConfigureBudget || settings.CallBudget <= settings.OperationBudget || settings.RelayBudget <= settings.CallBudget {+ t.Fatal("settings callers must leave headroom above the operation they await")+ }+}++func TestSavedLaunchOverridesManifestEnvironmentLiterally(t *testing.T) {+ rt := Runtime{+ EditableLaunch: &EditableLaunch{FixedArgs: []string{"serve"}},+ Env: map[string]string{"LD_LIBRARY_PATH": "{install_dir}/lib"},+ }+ args := []string{}+ rt.LaunchArgs = &args+ for _, value := range []string{"/custom", "", "{install_dir}/other"} {+ env := []string{"LD_LIBRARY_PATH=" + value}+ rt.LaunchEnv = &env+ launch, err := resolveProcessLaunch(rt, "engine", map[string]string{"install_dir": "/default", "host": "127.0.0.1", "port": "12345"})+ if err != nil || launch.Env["LD_LIBRARY_PATH"] != value {+ t.Errorf("saved launch environment = %v, error %v; want literal %q", launch.Env, err, value)+ }+ }+}++func TestSettingsSwapsLiveServerAndProxyPorts(t *testing.T) {+ e := settingsExecutor(t, false)+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ proxy, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = proxy.Close() })+ p := settingsRequest(t, e)+ oldServer := p.Settings.ServerPort+ p.Settings.ServerPort = proxy.Addr().(*net.TCPAddr).Port+ p.Settings.ProxyPort = oldServer+ p.Resolution = "server"+ preview, err := e.PreviewLaunch(p)+ if err != nil || len(preview.Errors) != 0 || preview.Conflict != nil {+ t.Fatalf("swap preview: %+v %v", preview, err)+ }+ rebinds := 0+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: preview.Settings}, func() error {+ rebinds+++ // The old engine must release its port before the proxy moves, and+ // the new engine must wait until the old proxy listener is closed.+ next, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", oldServer))+ if err != nil {+ return err+ }+ _ = proxy.Close()+ proxy = next+ return nil+ })+ if err != nil || !result.Running || result.EffectivePort != p.Settings.ServerPort || rebinds != 1 {+ t.Fatalf("live swap: %+v rebinds=%d err=%v", result, rebinds, err)+ }+}++func TestSettingsCommandLaunchPreservesLiteralsAndCleansFailedStart(t *testing.T) {+ e := settingsExecutor(t, true)+ st := settingsState(t, e)+ capture := filepath.Join(t.TempDir(), "argv.json")+ stopped := filepath.Join(t.TempDir(), "stopped")+ rt := &st.plat.Runtime+ rt.Start = [][]string{{fakeEngineBin, "captureargs", capture, "--port", "{port}", "--bind", "{host}"}}+ rt.EditableLaunch.FixedArgs = []string{"captureargs", capture}+ rt.Ready = nil+ rt.Health = nil+ rt.Stop = &StopSpec{Cmd: []string{fakeEngineBin, "touch", stopped}}+ p := settingsRequest(t, e)+ p.Settings.LaunchText += ` "{port}" "$HOME" "two words" ""`+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: p.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ data, err := os.ReadFile(capture)+ var args []string+ if err != nil || json.Unmarshal(data, &args) != nil || len(args) < 4 || !reflect.DeepEqual(args[len(args)-4:], []string{"{port}", "$HOME", "two words", ""}) {+ t.Fatalf("command mode expanded literal options: %s %v", data, err)+ }+ if err := e.Stop("fake"); err != nil {+ t.Fatal(err)+ }+ if err := os.Remove(stopped); err != nil {+ t.Fatal(err)+ }+ p = settingsRequest(t, e)+ p.Settings.LaunchText += " --fail-launch private-value"+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: p.Settings}, func() error { return nil }); err != nil {+ t.Fatal(err)+ }+ err = e.Start(context.Background(), "fake")+ if err == nil || !strings.Contains(err.Error(), "invalid launch") || strings.Contains(err.Error(), "private-value") {+ t.Fatalf("failed command output was not classified safely: %v", err)+ }+ if _, err := os.Stat(stopped); err != nil {+ t.Fatal("failed first command did not run official cleanup")+ }+}++func TestSettingsEnvironmentReachesEngineAndCanBeEditedAndRemoved(t *testing.T) {+ for _, command := range []bool{false, true} {+ t.Run(fmt.Sprint(command), func(t *testing.T) {+ e := settingsExecutor(t, command)+ st := settingsState(t, e)+ if command {+ capture := filepath.Join(t.TempDir(), "args.json")+ rt := &st.plat.Runtime+ rt.Start = [][]string{{fakeEngineBin, "captureargs", capture, "--port", "{port}", "--bind", "{host}"}}+ rt.EditableLaunch.FixedArgs = []string{"captureargs", capture}+ rt.Ready, rt.Health = nil, nil+ rt.Stop = &StopSpec{Cmd: []string{fakeEngineBin, "touch", filepath.Join(t.TempDir(), "stopped")}}+ }+ captureEnv := filepath.Join(t.TempDir(), "env.json")+ prefix, err := formatLaunchText([]string{"PAIR_TEST_ENV_FILE=" + captureEnv, "OLLAMA_ORIGINS=http://localhost", `PAIR_TEST_LITERAL=$HOME {port} C:\new\tools`, "PAIR_TEST_EMPTY="})+ if err != nil {+ t.Fatal(err)+ }+ p := settingsRequest(t, e)+ p.Settings.LaunchText = prefix + " " + p.Settings.LaunchText+ configure := func() settings.LaunchState {+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: p.Settings}, func() error { return nil })+ if err != nil {+ t.Fatal(err)+ }+ return result+ }+ if configure().Running {+ t.Fatal("environment edit started stopped engine")+ }+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ readEnv := func() map[string]string {+ data, err := os.ReadFile(captureEnv)+ if err != nil {+ t.Fatal(err)+ }+ var env map[string]string+ if err := json.Unmarshal(data, &env); err != nil {+ t.Fatal(err)+ }+ return env+ }+ if env := readEnv(); env["OLLAMA_ORIGINS"] != "http://localhost" || env["PAIR_TEST_LITERAL"] != `$HOME {port} C:\new\tools` || env["PAIR_TEST_EMPTY"] != "" {+ t.Fatalf("environment not passed literally: %#v", env)+ }+ p = settingsRequest(t, e)+ p.Settings.LaunchText = strings.Replace(p.Settings.LaunchText, `OLLAMA_ORIGINS="http://localhost"`, `OLLAMA_ORIGINS="http://example.test"`, 1)+ if !configure().Running || readEnv()["OLLAMA_ORIGINS"] != "http://example.test" {+ t.Fatal("environment-only edit did not restart with new value")+ }+ p = settingsRequest(t, e)+ p.Settings.LaunchText = strings.Replace(p.Settings.LaunchText, `OLLAMA_ORIGINS="http://example.test" `, "", 1)+ configure()+ if readEnv()["OLLAMA_ORIGINS"] != "" {+ t.Fatal("removed environment variable survived")+ }+ override := readSettingsOverride(t, e)+ if override.LaunchEnv == nil {+ t.Fatal("launch environment missing from override")+ }+ env, err := literalEnvironment(*override.LaunchEnv)+ if err != nil {+ t.Fatal(err)+ }+ if _, exists := env["OLLAMA_ORIGINS"]; exists {+ t.Fatal("removed environment variable remains in override")+ }+ if env["PAIR_TEST_ENV_FILE"] != captureEnv || env["PAIR_TEST_LITERAL"] != `$HOME {port} C:\new\tools` {+ t.Fatalf("unrelated environment values lost: %v", env)+ }+ })+ }+}++func TestSettingsEnvironmentValidation(t *testing.T) {+ e := settingsExecutor(t, false)+ for _, prefix := range []string{"9BAD=value", "BAD-NAME=value", "PAIR_TEST=x PAIR_TEST=y"} {+ p := settingsRequest(t, e)+ p.Settings.LaunchText = prefix + " " + p.Settings.LaunchText+ result, err := e.PreviewLaunch(p)+ if err != nil || len(result.Errors) == 0 {+ t.Fatalf("invalid assignment accepted: %+v %v", result, err)+ }+ }+}++// A stop that fails has to leave the saved configuration alone. Persisting+// first would put the new launch on disk while the live process kept the old+// one, and the next start would adopt settings the user was told had failed.+func TestSettingsFailedStopLeavesSavedConfigurationIntact(t *testing.T) {+ e := settingsExecutor(t, true)+ st := settingsState(t, e)+ capture := filepath.Join(t.TempDir(), "argv.json")+ rt := &st.plat.Runtime+ rt.Start = [][]string{{fakeEngineBin, "captureargs", capture, "--port", "{port}", "--bind", "{host}"}}+ rt.EditableLaunch.FixedArgs = []string{"captureargs", capture}+ rt.Ready, rt.Health = nil, nil+ rt.Stop = &StopSpec{Cmd: []string{fakeEngineBin, "failmark", filepath.Join(t.TempDir(), "stop-attempts")}}+ if err := e.Start(context.Background(), "fake"); err != nil {+ t.Fatal(err)+ }+ override := filepath.Join(e.overrideDir, "fake.json")+ before, err := os.ReadFile(override)+ if err != nil && !os.IsNotExist(err) {+ t.Fatal(err)+ }+ request := settingsRequest(t, e)+ request.Settings.LaunchText += " --parallel 7"+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error {+ t.Error("rebound an engine that could not be stopped")+ return nil+ })+ if err == nil {+ t.Fatalf("failed stop reported success: %+v", result)+ }+ after, readErr := os.ReadFile(override)+ if readErr != nil && !os.IsNotExist(readErr) {+ t.Fatal(readErr)+ }+ if !bytes.Equal(before, after) {+ t.Fatalf("stop failure still rewrote saved configuration: %q -> %q", before, after)+ }+ live := e.launchStateLocked("fake", st)+ if strings.Contains(live.LaunchText, "--parallel 7") {+ t.Fatalf("in-memory launch adopted the rejected change: %q", live.LaunchText)+ }+}++func TestSettingsRejectBeforeMutationAndRetainAcceptedFailure(t *testing.T) {+ e := settingsExecutor(t, false)+ request := settingsRequest(t, e)+ st := settingsState(t, e)+ st.mu.Lock()+ st.running = true+ st.adopted = true+ st.mu.Unlock()+ request.Settings.LaunchText += " --new"+ if _, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { t.Fatal("rebound adopted engine"); return nil }); err == nil {+ t.Fatal("adopted process accepted")+ }+ assertNoSettingsOverride(t, e)+ st.mu.Lock()+ st.running = false+ st.adopted = false+ st.mu.Unlock()+ result, err := e.ConfigureLaunch(context.Background(), settings.Configure{Engine: "fake", Settings: request.Settings}, func() error { return fmt.Errorf("bind failed") })+ if err == nil || result.Running || !strings.Contains(result.LaunchText, "--new") {+ t.Fatalf("accepted desired config not retained: %+v %v", result, err)+ }+}++func TestSettingsSupportsEngineWithoutStartupSubcommand(t *testing.T) {+ e := settingsExecutor(t, false)+ st := settingsState(t, e)+ st.plat.Runtime.Args = nil+ st.plat.Runtime.EditableLaunch.FixedArgs = nil+ if err := st.plat.validate(runtime.GOOS + "/" + runtime.GOARCH); err != nil {+ t.Fatal(err)+ }+ p := settingsRequest(t, e)+ p.Settings.LaunchText += " --future-option=opaque"+ preview := previewSettings(t, e, p)+ if len(preview.Errors) != 0 || !reflect.DeepEqual(preview.Args, []string{"--future-option=opaque"}) {+ t.Fatalf("engine without subcommand rejected: %+v", preview)+ }+}diff --git a/services/nvpair-engine-manager/settingsrelay.go b/services/nvpair-engine-manager/settingsrelay.gonew file mode 100644index 0000000..b0efdf7--- /dev/null+++ b/services/nvpair-engine-manager/settingsrelay.go@@ -0,0 +1,137 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "fmt"+ "sync"++ settings "nvpair-shared/enginesettings"+)++type settingsReply struct {+ ID string `json:"id"`+ Result json.RawMessage `json:"result"`+ Error string `json:"error,omitempty"`+}+type settingsRelay struct {+ mu sync.Mutex+ pending map[string]chan settingsReply+ send func(string, any) error+}++func (r *settingsRelay) call(ctx context.Context, method string, request settings.Request, caller string) (json.RawMessage, error) {+ ctx, cancel := context.WithTimeout(ctx, settings.RelayBudget)+ defer cancel()+ id := newOpID()+ ch := make(chan settingsReply, 1)+ r.mu.Lock()+ if len(r.pending) >= 64 {+ r.mu.Unlock()+ return nil, fmt.Errorf("too many settings requests")+ }+ if r.pending == nil {+ r.pending = make(map[string]chan settingsReply)+ }+ r.pending[id] = ch+ r.mu.Unlock()+ defer func() { r.mu.Lock(); delete(r.pending, id); r.mu.Unlock() }()+ if err := r.send("engine:settings-request", settings.Relay{ID: id, Method: method, Request: request, Caller: caller}); err != nil {+ return nil, err+ }+ select {+ case reply := <-ch:+ if reply.Error != "" {+ return nil, fmt.Errorf("%s", reply.Error)+ }+ return reply.Result, nil+ case <-ctx.Done():+ _ = r.send("engine:settings-cancel", map[string]string{"id": id})+ return nil, ctx.Err()+ }+}++func (r *settingsRelay) reply(raw json.RawMessage) {+ var reply settingsReply+ if json.Unmarshal(raw, &reply) != nil {+ return+ }+ r.mu.Lock()+ ch := r.pending[reply.ID]+ r.mu.Unlock()+ if ch != nil {+ select {+ case ch <- reply:+ default:+ }+ }+}++func (m *Manager) handleSettingsMessage(ctx context.Context, msg *Message) bool {+ if msg.Method == "engine:settings-reply" && msg.IsNotification() {+ m.settingsRelay.reply(msg.Params)+ return true+ }+ if msg.Method == "engine:settings-projection" && msg.IsNotification() {+ var snapshots []settings.Snapshot+ if json.Unmarshal(msg.Params, &snapshots) == nil {+ m.exec.settingsHub.Publish(snapshots)+ }+ return true+ }+ if !msg.IsRequest() {+ return false+ }+ switch msg.Method {+ case "engine:configured-ports":+ go func() {+ type port struct {+ Engine string `json:"engine"`+ Port int `json:"port"`+ }+ ports := []port{}+ for _, name := range m.exec.reg.Names() {+ if launch, err := m.exec.LaunchSettings(name); err == nil {+ ports = append(ports, port{name, launch.ServerPort})+ }+ }+ m.respondOrErr(msg, map[string]any{"engines": ports}, nil)+ }()+ return true+ case "engine:get-launch", "engine:preview-launch", "engine:configure-launch":+ go func() {+ var p settings.Request+ if !m.parse(msg, &p) {+ return+ }+ switch msg.Method {+ case "engine:get-launch":+ result, err := m.exec.LaunchSettings(p.Engine)+ m.respondOrErr(msg, result, err)+ case "engine:preview-launch":+ result, err := m.exec.PreviewLaunch(p)+ m.respondOrErr(msg, result, err)+ case "engine:configure-launch":+ configureCtx, cancel := context.WithTimeout(ctx, settings.ConfigureBudget)+ defer cancel()+ var configure settings.Configure+ if !m.parse(msg, &configure) {+ return+ }+ result, err := m.exec.ConfigureLaunch(configureCtx, configure, func() error {+ _, err := m.settingsRelay.call(configureCtx, "rebind", settings.Request{Engine: configure.Engine, RequestID: configure.OperationID, Settings: configure.Settings}, "")+ return err+ })+ m.respondOrErr(msg, result, err)+ }+ }()+ return true+ case "engine:remote-get-settings", "engine:remote-preview-settings", "engine:remote-apply-settings":+ go m.remoteSettings(ctx, msg)+ return true+ }+ return false+}diff --git a/services/nvpair-engine-manager/settingsremote.go b/services/nvpair-engine-manager/settingsremote.gonew file mode 100644index 0000000..0768962--- /dev/null+++ b/services/nvpair-engine-manager/settingsremote.go@@ -0,0 +1,245 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bufio"+ "context"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "strings"+ "time"++ settings "nvpair-shared/enginesettings"+)++const settingsPath = "/v1/engine-settings/"++func (s *controlServer) settingsRoutes(mux *http.ServeMux) {+ for _, method := range []string{"get", "preview", "apply"} {+ mux.HandleFunc(settingsPath+method, s.requirePinCaller(func(w http.ResponseWriter, r *http.Request, caller string) {+ if r.Method != http.MethodPost {+ http.Error(w, "method not allowed", 405)+ return+ }+ if s.exec.settingsParent == nil {+ http.Error(w, "settings coordinator unavailable", 503)+ return+ }+ var p settings.Request+ decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64*1024))+ decoder.DisallowUnknownFields()+ if decoder.Decode(&p) != nil || decoder.Decode(&struct{}{}) != io.EOF {+ http.Error(w, "invalid settings request", 400)+ return+ }+ // A peer can only address this target node, never forward another hop.+ p.NodeID = ""+ if method != "get" {+ if err := s.exec.RejectRemoteCORSChange(p); err != nil {+ http.Error(w, err.Error(), 403)+ return+ }+ }+ ctx, cancel := context.WithCancel(r.Context())+ defer cancel()+ go func() {+ ticker := time.NewTicker(time.Second)+ defer ticker.Stop()+ for {+ select {+ case <-ctx.Done():+ return+ case <-ticker.C:+ s.mesh.Refresh()+ if _, ok := s.mesh.VerifyClientPin(r); !ok {+ cancel()+ return+ }+ }+ }+ }()+ result, err := s.exec.settingsParent(ctx, method, p, caller)+ if err != nil {+ http.Error(w, err.Error(), 409)+ return+ }+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write(result)+ }))+ }+ mux.HandleFunc(settingsPath+"events", s.requirePin(s.streamSettings))+}++func (s *controlServer) streamSettings(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodGet {+ http.Error(w, "method not allowed", 405)+ return+ }+ if s.exec.settingsParent == nil {+ http.Error(w, "settings coordinator unavailable", 503)+ return+ }+ ch, closeSub, ok := s.exec.settingsHub.Subscribe()+ if !ok {+ http.Error(w, "too many settings subscriptions", 503)+ return+ }+ defer closeSub()+ w.Header().Set("Content-Type", "application/x-ndjson")+ controller := http.NewResponseController(w)+ send := func(value any) bool {+ _ = controller.SetWriteDeadline(time.Now().Add(5 * time.Second))+ if json.NewEncoder(w).Encode(value) != nil {+ return false+ }+ return controller.Flush() == nil+ }+ ticker := time.NewTicker(time.Second)+ defer ticker.Stop()+ for {+ select {+ case <-r.Context().Done():+ return+ case snapshot := <-ch:+ s.mesh.Refresh()+ if _, ok := s.mesh.VerifyClientPin(r); !ok {+ return+ }+ if !send(snapshot) {+ return+ }+ case <-ticker.C:+ s.mesh.Refresh()+ if _, ok := s.mesh.VerifyClientPin(r); !ok {+ return+ }+ if !send(nil) {+ return+ }+ }+ }+}++func (m *Manager) remoteSettings(ctx context.Context, msg *Message) {+ var p settings.Request+ if !m.parse(msg, &p) {+ return+ }+ peer, ok := m.peers.lookup(p.NodeID)+ if !ok || m.mesh == nil {+ m.respondOrErr(msg, nil, fmt.Errorf("settings unavailable: device is offline or does not support settings"))+ return+ }+ client, err := m.remoteClient(ctx, peer)+ if err != nil {+ m.respondOrErr(msg, nil, err)+ return+ }+ method := strings.TrimSuffix(strings.TrimPrefix(msg.Method, "engine:remote-"), "-settings")+ p.NodeID = ""+ result, err := client.postJSON(ctx, settingsPath+method, p.Engine, p)+ m.respondOrErr(msg, result, err)+}++// Settings are pushed directly by each authority. Discovery polling here only+// manages connection lifetimes; configuration itself is never polled from peers.+func (m *Manager) watchPeerSettings(ctx context.Context) {+ active := map[string]context.CancelFunc{}+ defer func() {+ for _, cancel := range active {+ cancel()+ }+ }()+ ticker := time.NewTicker(2 * time.Second)+ defer ticker.Stop()+ for {+ select {+ case <-ctx.Done():+ return+ case <-ticker.C:+ if m.mesh == nil {+ continue+ }+ m.mesh.Refresh()+ m.peers.mu.RLock()+ peers := make(map[string]ecPeer, len(m.peers.peers))+ for k, v := range m.peers.peers {+ peers[k] = v+ }+ m.peers.mu.RUnlock()+ for node, cancel := range active {+ p, exists := peers[node]+ if !exists || !m.mesh.HasPin(p.clusterUUID) {+ cancel()+ delete(active, node)+ }+ }+ for node, peer := range peers {+ if active[node] != nil || len(active) >= 64 || !m.mesh.HasPin(peer.clusterUUID) {+ continue+ }+ streamCtx, cancel := context.WithCancel(ctx)+ active[node] = cancel+ go func(node string) {+ for streamCtx.Err() == nil {+ current, exists := m.peers.lookup(node)+ if !exists {+ return+ }+ m.consumeSettingsStream(streamCtx, current)+ m.exec.notify("engine:settings-disconnected", map[string]string{"nodeId": node})+ select {+ case <-streamCtx.Done():+ return+ case <-time.After(3 * time.Second):+ }+ }+ }(node)+ }+ }+ }+}++func (m *Manager) consumeSettingsStream(parent context.Context, peer ecPeer) {+ ctx, cancel := context.WithCancel(parent)+ defer cancel()+ client, err := m.remoteClient(ctx, peer)+ if err != nil {+ return+ }+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, client.base+settingsPath+"events", nil)+ if err != nil {+ return+ }+ response, err := client.http.Do(req)+ if err != nil {+ client.forgetAddress()+ return+ }+ defer response.Body.Close()+ if response.StatusCode != http.StatusOK {+ return+ }+ watchdog := time.AfterFunc(15*time.Second, cancel)+ defer watchdog.Stop()+ scanner := bufio.NewScanner(response.Body)+ scanner.Buffer(make([]byte, 4096), 256*1024)+ for scanner.Scan() {+ watchdog.Reset(15 * time.Second)+ var snapshots []settings.Snapshot+ if json.Unmarshal(scanner.Bytes(), &snapshots) != nil {+ return+ }+ for _, snapshot := range snapshots {+ if snapshot.Engine != "ollama" && snapshot.Engine != "lmstudio" {+ continue+ }+ snapshot.NodeID = peer.nodeID+ m.exec.notify("engine:settings-changed", snapshot)+ }+ }+}diff --git a/services/nvpair-engine-manager/settingsremote_test.go b/services/nvpair-engine-manager/settingsremote_test.gonew file mode 100644index 0000000..0cdca74--- /dev/null+++ b/services/nvpair-engine-manager/settingsremote_test.go@@ -0,0 +1,309 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bufio"+ "bytes"+ "context"+ "crypto/ed25519"+ "crypto/rand"+ "crypto/x509"+ "crypto/x509/pkix"+ "encoding/json"+ "encoding/pem"+ "io"+ "math/big"+ "net/http"+ "net/http/httptest"+ "net/url"+ "os"+ "path/filepath"+ "strconv"+ "strings"+ "sync"+ "testing"+ "time"++ "nvpair-shared/clustertrust"+ settings "nvpair-shared/enginesettings"+)++func settingsMesh(t *testing.T, id string) (string, []byte) {+ t.Helper()+ dir := t.TempDir()+ pub, key, err := ed25519.GenerateKey(rand.Reader)+ if err != nil {+ t.Fatal(err)+ }+ uri, _ := url.Parse("urn:nvpair:node:" + id)+ cert := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: id}, URIs: []*url.URL{uri}, NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour), KeyUsage: x509.KeyUsageDigitalSignature, ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth, x509.ExtKeyUsageClientAuth}}+ der, err := x509.CreateCertificate(rand.Reader, cert, cert, pub, key)+ if err != nil {+ t.Fatal(err)+ }+ certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})+ keyDER, _ := x509.MarshalPKCS8PrivateKey(key)+ for name, data := range map[string][]byte{"node.crt": certPEM, "node.key": pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER})} {+ if err := os.WriteFile(filepath.Join(dir, name), data, 0600); err != nil {+ t.Fatal(err)+ }+ }+ return dir, certPEM+}+func settingsPin(t *testing.T, dir, id string, cert []byte) {+ t.Helper()+ path := filepath.Join(dir, "trusted")+ if err := os.MkdirAll(path, 0700); err != nil {+ t.Fatal(err)+ }+ data, _ := json.Marshal(map[string]string{"nodeUuid": id, "certPem": string(cert)})+ if err := os.WriteFile(filepath.Join(path, id+".json"), data, 0600); err != nil {+ t.Fatal(err)+ }+}++func TestSettingsPairedMutationPushObserversAndRevocation(t *testing.T) {+ a, certA := settingsMesh(t, "a")+ b, certB := settingsMesh(t, "b")+ c, certC := settingsMesh(t, "c")+ stranger, _ := settingsMesh(t, "stranger")+ settingsPin(t, a, "b", certB)+ settingsPin(t, a, "c", certC)+ for _, dir := range []string{b, c, stranger} {+ settingsPin(t, dir, "a", certA)+ }+ mesh := clustertrust.Open(a)+ exec := settingsExecutor(t, false)+ snapshot := settings.Snapshot{NodeID: "a-host", Engine: "ollama", Revision: 1, Epoch: "epoch-a", Sequence: 1, Phase: "idle", Settings: settings.Config{ServerPort: 12000, ProxyPort: 12001, LaunchText: "managed serve"}}+ exec.settingsHub.Publish([]settings.Snapshot{snapshot})+ var mu sync.Mutex+ callerSeen := ""+ exec.settingsParent = func(ctx context.Context, method string, p settings.Request, caller string) (json.RawMessage, error) {+ mu.Lock()+ defer mu.Unlock()+ callerSeen = caller+ if p.NodeID != "" {+ t.Error("forwarded another target through settings HTTP")+ }+ if method == "apply" {+ snapshot.Revision+++ snapshot.Sequence+++ snapshot.Settings = p.Settings+ exec.settingsHub.Publish([]settings.Snapshot{snapshot})+ }+ data, _ := json.Marshal(snapshot)+ return data, nil+ }+ server := httptest.NewUnstartedServer((&controlServer{exec: exec, mesh: mesh}).mux())+ server.TLS = mesh.ServerTLSConfig()+ server.StartTLS()+ defer server.Close()+ client := func(dir string) *http.Client {+ m := clustertrust.Open(dir)+ config, ok := m.ClientTLSConfig("a")+ if !ok {+ t.Fatal("pin unavailable")+ }+ tr := &http.Transport{TLSClientConfig: config}+ t.Cleanup(tr.CloseIdleConnections)+ return &http.Client{Transport: tr}+ }+ clientB, clientC := client(b), client(c)+ ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second)+ defer cancel()+ open := func(cl *http.Client) (*http.Response, *bufio.Scanner) {+ req, _ := http.NewRequestWithContext(ctx, "GET", server.URL+settingsPath+"events", nil)+ res, err := cl.Do(req)+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = res.Body.Close() })+ return res, bufio.NewScanner(res.Body)+ }+ _, scanB := open(clientB)+ resC, scanC := open(clientC)+ read := func(scan *bufio.Scanner, want uint64) {+ t.Helper()+ for scan.Scan() {+ var rows []settings.Snapshot+ if json.Unmarshal(scan.Bytes(), &rows) != nil {+ t.Fatal("invalid stream")+ }+ if len(rows) > 0 {+ if rows[0].Revision != want {+ t.Fatalf("revision=%d want=%d", rows[0].Revision, want)+ }+ return+ }+ }+ t.Fatalf("stream ended: %v", scan.Err())+ }+ read(scanB, 1)+ read(scanC, 1)+ config := settings.Config{ServerPort: 12002, ProxyPort: 12003, LaunchText: "managed serve --parallel 2"}+ body, _ := json.Marshal(settings.Request{NodeID: "forwarding-forbidden", Engine: "ollama", Settings: config})+ response, err := clientB.Post(server.URL+settingsPath+"apply", "application/json", bytes.NewReader(body))+ if err != nil {+ t.Fatal(err)+ }+ _ = response.Body.Close()+ if response.StatusCode != 200 {+ t.Fatalf("paired mutation rejected: %d", response.StatusCode)+ }+ read(scanB, 2)+ read(scanC, 2)+ mu.Lock()+ seen := callerSeen+ mu.Unlock()+ if seen != "b" {+ t.Fatalf("caller not authenticated: %q", seen)+ }+ response, err = client(stranger).Post(server.URL+settingsPath+"apply", "application/json", bytes.NewReader(body))+ if err != nil {+ t.Fatal(err)+ }+ _ = response.Body.Close()+ if response.StatusCode != 403 {+ t.Fatal("unpinned mutation accepted")+ }+ if err := os.Remove(filepath.Join(a, "trusted", "c.json")); err != nil {+ t.Fatal(err)+ }+ mesh.Refresh()+ ended := make(chan error, 1)+ go func() { _, err := io.Copy(io.Discard, resC.Body); ended <- err }()+ select {+ case <-ended:+ case <-time.After(3 * time.Second):+ t.Fatal("revoked peer stream did not close")+ }+ // A reconnected remaining peer atomically receives the latest full state.+ _, again := open(clientB)+ read(again, 2)+}++// Ordinary environment options pass through for pinned peers. Only changes+// to the engine's CORS environment require an edit on the owning device.+func TestSettingsRemoteOnlyCORSIsLocalOnly(t *testing.T) {+ a, certA := settingsMesh(t, "a")+ b, certB := settingsMesh(t, "b")+ settingsPin(t, a, "b", certB)+ settingsPin(t, b, "a", certA)+ mesh := clustertrust.Open(a)+ exec := settingsExecutor(t, false)+ exec.settingsParent = func(context.Context, string, settings.Request, string) (json.RawMessage, error) {+ return json.RawMessage(`{}`), nil+ }+ server := httptest.NewUnstartedServer((&controlServer{exec: exec, mesh: mesh}).mux())+ server.TLS = mesh.ServerTLSConfig()+ server.StartTLS()+ defer server.Close()+ config, ok := clustertrust.Open(b).ClientTLSConfig("a")+ if !ok {+ t.Fatal("pin unavailable")+ }+ transport := &http.Transport{TLSClientConfig: config}+ t.Cleanup(transport.CloseIdleConnections)+ peer := &http.Client{Transport: transport}+ post := func(request settings.Request) int {+ body, _ := json.Marshal(request)+ response, err := peer.Post(server.URL+settingsPath+"apply", "application/json", bytes.NewReader(body))+ if err != nil {+ t.Fatal(err)+ }+ _ = response.Body.Close()+ return response.StatusCode+ }+ arguments := settingsRequest(t, exec)+ arguments.Settings.LaunchText += " --parallel 3"+ if code := post(arguments); code != 200 {+ t.Fatalf("peer argument change refused: %d", code)+ }+ ports := settingsRequest(t, exec)+ next := ports.Settings.ServerPort + 1+ ports.Settings.LaunchText = strings.Replace(ports.Settings.LaunchText,+ strconv.Itoa(ports.Settings.ServerPort), strconv.Itoa(next), 1)+ ports.Settings.ServerPort = next+ if code := post(ports); code != 200 {+ t.Fatalf("peer port change refused: %d", code)+ }+ environment := settingsRequest(t, exec)+ environment.Settings.LaunchText = `FUTURE_ENGINE_SETTING="unknown-value" ` + environment.Settings.LaunchText+ if code := post(environment); code != 200 {+ t.Fatalf("peer opaque environment change refused: %d", code)+ }+ environment = settingsRequest(t, exec)+ environment.Settings.LaunchText = `OLLAMA_ORIGINS="http://localhost" ` + environment.Settings.LaunchText+ if code := post(environment); code != 403 {+ t.Fatalf("peer CORS environment change accepted: %d", code)+ }+ // Exercise switch-based policy on the same authenticated route.+ state := settingsState(t, exec)+ state.plat.Runtime.EditableLaunch.Controls[1] = LaunchControl{Value: "{cors.enabled}", Implicit: implicitLaunchValue("true"), Flags: []string{"--cors", "-c"}}+ for _, text := range []string{"--cors", "-c", "--cors=false", "-- --cors", "-vc"} {+ request := settingsRequest(t, exec)+ request.Settings.LaunchText += " " + text+ if code := post(request); code != 403 {+ t.Fatalf("peer CORS switch %q accepted: %d", text, code)+ }+ }+}++func TestSettingsRelayCorrelationCancellationAndCleanup(t *testing.T) {+ sent := make(chan settings.Relay, 2)+ canceled := make(chan string, 1)+ relay := &settingsRelay{send: func(method string, value any) error {+ data, _ := json.Marshal(value)+ if method == "engine:settings-request" {+ var p settings.Relay+ _ = json.Unmarshal(data, &p)+ sent <- p+ } else {+ var p struct {+ ID string `json:"id"`+ }+ _ = json.Unmarshal(data, &p)+ canceled <- p.ID+ }+ return nil+ }}+ results := make(chan string, 2)+ for _, name := range []string{"one", "two"} {+ go func(name string) {+ result, err := relay.call(context.Background(), "preview", settings.Request{Engine: name}, "")+ if err != nil {+ results <- "error"+ } else {+ results <- string(result)+ }+ }(name)+ }+ first, second := <-sent, <-sent+ for _, request := range []settings.Relay{second, first} {+ data, _ := json.Marshal(settingsReply{ID: request.ID, Result: json.RawMessage(`"` + request.Request.Engine + `"`)})+ relay.reply(data)+ }+ got := map[string]bool{<-results: true, <-results: true}+ if !got[`"one"`] || !got[`"two"`] {+ t.Fatal("responses were not correlated")+ }+ ctx, cancel := context.WithCancel(context.Background())+ done := make(chan error, 1)+ go func() { _, err := relay.call(ctx, "apply", settings.Request{}, ""); done <- err }()+ request := <-sent+ cancel()+ if err := <-done; err == nil {+ t.Fatal("cancellation ignored")+ }+ if <-canceled != request.ID {+ t.Fatal("wrong canceled correlation")+ }+ relay.mu.Lock()+ pending := len(relay.pending)+ relay.mu.Unlock()+ if pending != 0 {+ t.Fatal("relay leaked requests")+ }+}diff --git a/services/nvpair-engine-manager/spec.md b/services/nvpair-engine-manager/spec.mdindex 3150aaa..ba2e632 100644--- a/services/nvpair-engine-manager/spec.md+++ b/services/nvpair-engine-manager/spec.md@@ -10,8 +10,18 @@ A declarative, config-driven control plane for **local inference engines** (Olla## 2. Scope**In scope**+- Broker-coordinated argument/server/proxy settings, literal argument+ persistence, ownership validation and pinned peer settings synchronization.+ The normative operation and failure contract is+ [ENGINE_SETTINGS.md](../nvpair-ui-broker/ENGINE_SETTINGS.md); launch grammar is+ [LAUNCH_TEXT.md](LAUNCH_TEXT.md).- Detect installation; **user-mode** install (HTTPS download + checksum-verify-when-pinned + run) per OS/arch.- Lifecycle: start (with readiness probe), stop, restart, status, periodic health.+- Persistent server-port changes preserve arguments, environment and unrelated+ manifest overrides. Resetting to the bundled port removes only shared and+ host-platform port overrides, deleting the file only when it has no other+ settings. Host-platform precedence must not override a successfully saved port+ on reload; malformed existing overrides fail the save and remain intact.- Config-declared **actions** covering the full model lifecycle — Ollama: `list_models`, `loaded_models`, `pull_model`, `run_model`, `unload_model`, `delete_model`; LM Studio: `list_models`/`list_downloaded`, `loaded_models`, `pull_model`, `load_model`, `chat`, `unload_model`, `delete_model` (`remove_path` with `lms-disk-path` resolution) — mapped to each engine's local control API. `loaded_models` reports the models currently resident in memory (Ollama `GET /api/ps`, LM Studio `GET /api/v1/models` filtered by nonempty `loaded_instances`), name-extracted via the same declarative `result` spec (with an optional `match` row filter).- Per-engine stdout/stderr log capture and structured operational error records, surfaced via the errors pipeline.- A normalized node-level model list (`engine:models`): union of every running engine's `list_models`, name-extracted via each action's declarative `result` spec, plus the per-engine set of models loaded in memory (`loadedByEngine`, from each engine's `loaded_models` action). A successful explicit empty inventory remains an engine key with `[]`; a missing/malformed/failed inventory omits that engine key instead of being mislabeled as authoritative empty. A watcher polls the loaded set and pushes `engine:models-changed` when it changes (explicit load/unload, JIT auto-load, TTL/idle eviction).diff --git a/services/nvpair-engine-manager/startup_output.go b/services/nvpair-engine-manager/startup_output.gonew file mode 100644index 0000000..e2e4449--- /dev/null+++ b/services/nvpair-engine-manager/startup_output.go@@ -0,0 +1,139 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "fmt"+ "regexp"+ "sort"+ "strings"+ "sync"+ "unicode"+)++const maxStartupOutput = 8 * 1024++// startupOutput retains a bounded diagnostic tail without interpreting vendor+// messages or option names. It is discarded when startup succeeds.+type startupOutput struct {+ mu sync.Mutex+ tail string+ pending string+ private *regexp.Regexp+ lookback int+ closed bool+}++func (o *startupOutput) Write(p []byte) (int, error) {+ n := len(p)+ o.mu.Lock()+ defer o.mu.Unlock()+ for !o.closed && len(p) > 0 {+ size := min(len(p), maxStartupOutput)+ o.pending += string(p[:size])+ p = p[size:]+ o.flush(false)+ }+ return n, nil+}++// flush redacts before bounding the tail. Keep enough undecided input to match+// the longest private value across Write calls, independent of output volume.+// The caller holds mu.+func (o *startupOutput) flush(final bool) {+ end := len(o.pending)+ if !final {+ end -= o.lookback+ }+ if end <= 0 {+ return+ }+ start := 0+ if o.private != nil {+ for _, match := range o.private.FindAllStringIndex(o.pending, -1) {+ if match[0] >= end {+ break+ }+ o.appendTail(o.pending[start:match[0]])+ o.appendTail("[redacted]")+ start = match[1]+ end = max(end, start)+ }+ }+ o.appendTail(o.pending[start:end])+ o.pending = o.pending[end:]+}++func (o *startupOutput) appendTail(text string) {+ if len(text) > maxStartupOutput {+ text = text[len(text)-maxStartupOutput:]+ }+ o.tail += text+ if len(o.tail) > maxStartupOutput {+ o.tail = o.tail[len(o.tail)-maxStartupOutput:]+ }+}++func (o *startupOutput) close() {+ o.mu.Lock()+ defer o.mu.Unlock()+ o.closed = true+ o.tail = ""+ o.pending = ""+}++func newStartupOutput(args []string, env map[string]string) *startupOutput {+ // Redact supplied values generically, while preserving flag names such as+ // --unknown-option so the engine's explanation remains useful.+ values := make([]string, 0, len(args)+len(env))+ for _, arg := range args {+ if strings.HasPrefix(arg, "-") {+ if _, value, ok := strings.Cut(arg, "="); ok {+ values = append(values, value)+ }+ } else {+ values = append(values, arg)+ }+ }+ for _, value := range env {+ values = append(values, value)+ }+ sort.Slice(values, func(i, j int) bool { return len(values[i]) > len(values[j]) })+ o := &startupOutput{}+ patterns := make([]string, 0, len(values))+ for _, value := range values {+ if value != "" {+ patterns = append(patterns, regexp.QuoteMeta(value))+ o.lookback = max(o.lookback, len(value)-1)+ }+ }+ if len(patterns) > 0 {+ o.private = regexp.MustCompile(strings.Join(patterns, "|"))+ }+ return o+}++func (o *startupOutput) failure(err error) error {+ o.mu.Lock()+ o.flush(true)+ text := o.tail+ o.mu.Unlock()+ text = strings.TrimSpace(strings.Map(func(r rune) rune {+ if unicode.IsControl(r) && r != '\n' && r != '\t' {+ return -1+ }+ return r+ }, strings.ToValidUTF8(text, "")))+ if text == "" {+ return err+ }+ return fmt.Errorf("%w: %s", err, text)+}++func launchDiagnosticArgs(rt Runtime) []string {+ if rt.LaunchArgs != nil {+ return *rt.LaunchArgs+ }+ return nil+}diff --git a/services/nvpair-engine-manager/startup_output_test.go b/services/nvpair-engine-manager/startup_output_test.gonew file mode 100644index 0000000..8b6040f--- /dev/null+++ b/services/nvpair-engine-manager/startup_output_test.go@@ -0,0 +1,92 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "errors"+ "strings"+ "testing"+)++func TestStartupOutputPreservesExplanationAndRedactsValues(t *testing.T) {+ o := newStartupOutput([]string{"--future-option", "private-value"}, map[string]string{"FUTURE_ENV": "private-env"})+ if _, err := o.Write([]byte("unknown option --future-option; input=private-value env=private-env\n")); err != nil {+ t.Fatal(err)+ }+ cause := errors.New("exit status 1")+ err := o.failure(cause)+ if !errors.Is(err, cause) || !strings.Contains(err.Error(), "unknown option --future-option") || strings.Contains(err.Error(), "private-value") || strings.Contains(err.Error(), "private-env") {+ t.Fatalf("lost diagnostic or leaked supplied value: %v", err)+ }+}++func TestStartupOutputBoundsLargeWritesAndStopsCapturing(t *testing.T) {+ o := newStartupOutput([]string{"x", "x", "x"}, nil)+ data := []byte(strings.Repeat("x", maxStartupOutput*4) + "last diagnostic")+ if n, err := o.Write(data); n != len(data) || err != nil {+ t.Fatalf("writer did not consume all output: %d %v", n, err)+ }+ cause := errors.New("failed")+ err := o.failure(cause)+ if len(err.Error()) > maxStartupOutput+len(cause.Error())+2 || !strings.HasSuffix(err.Error(), "last diagnostic") {+ t.Fatalf("diagnostic tail exceeded bound or lost final message: %d bytes", len(err.Error()))+ }+ o.close()+ if _, err := o.Write([]byte("later engine log")); err != nil {+ t.Fatal(err)+ }+ if o.failure(cause) != cause {+ t.Fatal("startup capture retained output after successful startup")+ }+}++func TestStartupOutputRedactsAcrossCaptureBoundaries(t *testing.T) {+ test := func(name, value, before, after string, chunkSize int) {+ t.Run(name, func(t *testing.T) {+ // Exercise both argument and environment collection without relying on+ // an engine-specific credential name.+ o := newStartupOutput([]string{"--future-value=" + value}, map[string]string{"CUSTOM": value})+ output := before + value + after+ for offset := 0; offset < len(output); offset += chunkSize {+ chunk := output[offset:min(offset+chunkSize, len(output))]+ if n, err := o.Write([]byte(chunk)); n != len(chunk) || err != nil {+ t.Fatalf("Write() = %d, %v", n, err)+ }+ if len(o.tail) > maxStartupOutput || len(o.pending) > o.lookback {+ t.Fatal("capture exceeded its diagnostic and boundary-context bounds")+ }+ }+ // Compare the entire result with redaction before truncation: checking+ // only for the full value would miss the original partial-value leak.+ want := strings.ReplaceAll(output, value, "[redacted]")+ if len(want) > maxStartupOutput {+ want = want[len(want)-maxStartupOutput:]+ }+ cause := errors.New("failed")+ got := o.failure(cause)+ if !errors.Is(got, cause) || got.Error() != "failed: "+want {+ t.Fatal("failure diagnostic differs from redact-before-truncate result")+ }+ })+ }++ test("value longer than capture", strings.Repeat("private", 1500), "input=", "; useful diagnostic", maxStartupOutput*4)+ test("tail begins inside value", "private-value", "input=", strings.Repeat("z", maxStartupOutput-5), maxStartupOutput*4)+ test("value split between writes", "private-value", "input=", "; useful diagnostic", 1)+ test("long value split between writes", strings.Repeat("private", 1500), "input=", "; useful diagnostic", 3071)+ test("literal regexp punctuation", "[private].*($value)", "input=", "; useful diagnostic", 3)+ test("expanding replacements", "x", strings.Repeat("x", maxStartupOutput*2), "; useful diagnostic", 517)+}++func TestStartupOutputPrefersLongestPrivateValueAcrossWrites(t *testing.T) {+ o := newStartupOutput([]string{"private", "private-longer-value"}, nil)+ for _, part := range []string{"input=private", "-longer-value; useful diagnostic"} {+ if _, err := o.Write([]byte(part)); err != nil {+ t.Fatal(err)+ }+ }+ if o.failure(errors.New("failed")).Error() != "failed: input=[redacted]; useful diagnostic" {+ t.Fatal("a shorter private value exposed the suffix of a longer value")+ }+}diff --git a/services/nvpair-engine-manager/testdata/fakeengine/main.go b/services/nvpair-engine-manager/testdata/fakeengine/main.goindex 76626c2..9f12ba8 100644--- a/services/nvpair-engine-manager/testdata/fakeengine/main.go+++ b/services/nvpair-engine-manager/testdata/fakeengine/main.go@@ -71,10 +71,43 @@ func bstr(m map[string]any, k string) string {}func main() {+ if path := os.Getenv("PAIR_TEST_ENV_FILE"); path != "" {+ values := map[string]string{}+ for _, key := range []string{"OLLAMA_ORIGINS", "PAIR_TEST_LITERAL", "PAIR_TEST_EMPTY", "OLLAMA_HOST"} {+ values[key] = os.Getenv(key)+ }+ data, _ := json.Marshal(values)+ if os.WriteFile(path, data, 0600) != nil {+ os.Exit(2)+ }+ }+ for _, arg := range os.Args[1:] {+ if arg == "--fail-launch" {+ fmt.Fprintln(os.Stderr, "invalid launch", os.Args[1:])+ os.Exit(2)+ }+ }+ if path := os.Getenv("FAKE_START_LOG"); path != "" {+ file, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)+ if err != nil {+ os.Exit(2)+ }+ _ = json.NewEncoder(file).Encode(os.Args[1:])+ _ = file.Close()+ }// Subcommands used by command-mode + cmd-action tests. They run and// exit (no server), standing in for a daemon's control CLI.if len(os.Args) > 1 {switch os.Args[1] {+ case "captureargs": // record exact argv for launch-text round-trip tests+ if len(os.Args) < 3 {+ os.Exit(2)+ }+ data, err := json.Marshal(os.Args[3:])+ if err != nil || os.WriteFile(os.Args[2], data, 0o600) != nil {+ os.Exit(1)+ }+ returncase "touch": // write a marker file so a test can assert the command ranif len(os.Args) > 2 {_ = os.WriteFile(os.Args[2], []byte("ok"), 0o644)diff --git a/services/nvpair-engine-manager/testdata/fuzz/FuzzLaunchBindings/2abf8bf03eb1c51c b/services/nvpair-engine-manager/testdata/fuzz/FuzzLaunchBindings/2abf8bf03eb1c51cnew file mode 100644index 0000000..8103c7c--- /dev/null+++ b/services/nvpair-engine-manager/testdata/fuzz/FuzzLaunchBindings/2abf8bf03eb1c51c@@ -0,0 +1,3 @@+go test fuzz v1+string("{server.port}\xc2")+string("0")diff --git a/services/nvpair-engine-manager/testdata/launch-bindings.json b/services/nvpair-engine-manager/testdata/launch-bindings.jsonnew file mode 100644index 0000000..f0bab2d--- /dev/null+++ b/services/nvpair-engine-manager/testdata/launch-bindings.json@@ -0,0 +1,200 @@+[+ {+ "name": "separate-flags",+ "input": "-q23456 --listen-address=127.0.0.1 --browser",+ "policy": [+ "cors.enabled=true"+ ],+ "invalid": [+ "-q0",+ "--listen-address=0.0.0.0",+ "--browser=false"+ ],+ "definition": {+ "fixed_args": [+ "server",+ "start"+ ],+ "controls": [+ {+ "flags": [+ "--api-port",+ "-q"+ ],+ "value": "{server.port}"+ },+ {+ "flags": [+ "--listen-address"+ ],+ "value": "{server.host}"+ },+ {+ "flags": [+ "--browser"+ ],+ "value": "{cors.enabled}",+ "implicit": "true"+ }+ ]+ }+ },+ {+ "name": "environment-only",+ "input": "ALT_PORT=23456 API_HOST=127.0.0.1 WEB_ACCESS=1",+ "policy": [+ "cors.enabled=true"+ ],+ "invalid": [+ "API_PORT=23456 ALT_PORT=23457",+ "API_HOST=0.0.0.0",+ "WEB_ACCESS=maybe"+ ],+ "definition": {+ "fixed_args": [+ "server",+ "start"+ ],+ "controls": [+ {+ "env": [+ "API_PORT",+ "ALT_PORT"+ ],+ "value": "{server.port}"+ },+ {+ "env": [+ "API_HOST"+ ],+ "value": "{server.host}"+ },+ {+ "env": [+ "WEB_ACCESS"+ ],+ "value": "{cors.enabled}"+ }+ ]+ }+ },+ {+ "name": "url-address",+ "input": "-etcp://127.0.0.1:23456 -ohttps://example.test",+ "policy": [+ "cors.origins=https://example.test"+ ],+ "invalid": [+ "--endpoint=tcp://0.0.0.0:23456",+ "--endpoint=127.0.0.1:23456",+ "--endpoint=tcp://127.0.0.1:0",+ "--origins='\"*\"'"+ ],+ "definition": {+ "fixed_args": [+ "server",+ "start"+ ],+ "controls": [+ {+ "flags": [+ "--endpoint",+ "-e"+ ],+ "env": [+ "ENDPOINT"+ ],+ "value": "tcp://{server.host}:{server.port}"+ },+ {+ "flags": [+ "--origins",+ "-o"+ ],+ "value": "{cors.origins}"+ }+ ]+ }+ },+ {+ "name": "ipv6-address",+ "host": "::1",+ "input": "WEB_ACCESS=true --endpoint=http://[::1]:23456 --web-access",+ "policy": [+ "cors.enabled=true"+ ],+ "invalid": [+ "--endpoint=http://[::]:23456",+ "--endpoint=http://[::1]:65536",+ "WEB_ACCESS=false --web-access"+ ],+ "definition": {+ "fixed_args": [+ "server",+ "start"+ ],+ "controls": [+ {+ "flags": [+ "--endpoint"+ ],+ "value": "http://[{server.host}]:{server.port}"+ },+ {+ "flags": [+ "--web-access"+ ],+ "env": [+ "WEB_ACCESS"+ ],+ "value": "{cors.enabled}",+ "implicit": "true"+ }+ ]+ }+ },+ {+ "name": "reordered-address-and-negative-switch",+ "input": "ENDPOINT=\"port=23456;host=127.0.0.1\" -n",+ "policy": [+ "cors.enabled=false"+ ],+ "invalid": [+ "--no-browser --browser",+ "ENDPOINT=\"port=0;host=127.0.0.1\"",+ "ENDPOINT=\"port=23456;host=0.0.0.0\""+ ],+ "definition": {+ "fixed_args": [+ "server",+ "start"+ ],+ "controls": [+ {+ "env": [+ "ENDPOINT"+ ],+ "flags": [+ "--endpoint"+ ],+ "value": "port={server.port};host={server.host}"+ },+ {+ "flags": [+ "--no-browser",+ "-n"+ ],+ "value": "{cors.enabled}",+ "implicit": "false"+ },+ {+ "flags": [+ "--browser"+ ],+ "value": "{cors.enabled}",+ "implicit": "true"+ }+ ]+ }+ }+]diff --git a/services/nvpair-proxy/README.md b/services/nvpair-proxy/README.mdindex 6bcdc50..c36fb0c 100644--- a/services/nvpair-proxy/README.md+++ b/services/nvpair-proxy/README.md@@ -146,38 +146,15 @@ LM Studio additionally refuses to restore port 1235 even if it is stored: thatis where engine-manager runs a managed LM Studio, so a proxy restoring it wouldsit on the engine's own port. The stored value predates the current default.-**Browser clients (CORS).** The proxy is usable from a web front end. When an-engine is available, the proxy forwards an `OPTIONS` preflight so an-engine-declared exact origin and credentials policy reaches the browser-unchanged. If no engine is available, the engine returns no CORS policy, or a-non-loopback caller must be refused before routing, the proxy answers with its-own permissive `204` fallback. It also labels every response it generates —-including rejections such as the `502` when no node is available and the `403`-refusing a non-loopback plaintext caller — with `Access-Control-Allow-Origin: *`.-That matters as much as the success path: a response without those headers-reaches the browser as a generic "CORS error" with the real status and reason-stripped out, so the caller cannot tell what went wrong. A locally answered-preflight grants no access, since the request that follows still faces the same-gate. The policy comes from `nvpair-shared/cors`, so every engine answers-identically.--A response *forwarded from an engine* is different: if the engine set its own-`Access-Control-Allow-Origin` (Ollama with `OLLAMA_ORIGINS`), that header is-passed through untouched rather than replaced with the wildcard, so a-deliberately narrow engine policy is never silently widened and a credentialed-response is not broken. An engine that sends no CORS header has expressed no-policy to keep, so the proxy supplies its own — and drops any-`Access-Control-Allow-Credentials` that arrived without an origin, because a-browser rejects that header alongside a wildcard origin and would discard the-response the fallback exists to make readable.--One limit is outside the proxy's control: current Chromium-based browsers gate a-request from a public origin to a local or loopback address behind the user's-[Local Network Access](https://chromestatus.com/feature/5152728072060928)-permission, which replaced the old server-side opt-in header. No header the-proxy sends can grant that. A hosted page needs the permission plus a-`fetch(url, { targetAddressSpace: 'loopback' })` annotation; a page served from-the local machine is unaffected.+**Browser clients (CORS).** PAIR does not enable CORS or add default browser permissions. Configure origins through the engine; its built-in defaults and user configuration remain authoritative. Ordinary forwarded responses preserve the upstream status, body, and CORS headers, including missing headers. A denial is never replaced with a successful OPTIONS response or retried to find permission elsewhere. Proxy-generated errors carry their actual status without CORS permission headers, so browser JavaScript may see a generic CORS failure while curl and diagnostics show the real error.++A browser preflight (OPTIONS with Origin and Access-Control-Request-Method) queries every currently routable target, with concurrency eight, a ten-second query deadline, and no redirects. A single target's response is relayed. Multiple responding targets must all permit the requested origin, method, and headers; PAIR grants only their shared permissions. Credentials require unanimous explicit support. Synthesized preflights allow browsers to cache the result for 60 seconds; PAIR itself does not cache decisions. A policy denial returns 403. Unavailable targets are skipped; if none can answer, the proxy returns 502. Ordinary OPTIONS requests retain normal routing. Preflights do not create inference jobs or reserve scheduler capacity. Paired ingress forwards only to its local engine.++Combined model lists forward the caller's origin and end-to-end headers, excluding Authorization and Cookie so credentials are not shared across engines. Multi-target preflights apply the same credential filtering. With an Origin header, every responding engine must return a valid list and permit sharing: one denial returns 403 and one invalid list returns 502, without partial inventory. An invalid-list error retains the combined CORS permissions when every responding engine allows the origin. Unavailable engines are skipped, with 502 returned when none can answer. Successful lists combine origin/credential permissions and Vary requirements. Requests without Origin retain partial aggregation when some inventories are unavailable. Engines without CORS support remain unavailable to cross-origin browser clients through PAIR.++Both engine facades use nvpair-shared/cors. Neither facade reads engine environment variables or parses launch commands to determine CORS policy.++One limit is outside the proxy's control: current Chromium-based browsers gate a request from a public origin to a local or loopback address behind the user's [Local Network Access](https://chromestatus.com/feature/5152728072060928) permission, which replaced the old server-side opt-in header. No header the proxy sends can grant that. A hosted page needs the permission plus a `fetch(url, { targetAddressSpace: 'loopback' })` annotation; a page served from the local machine is unaffected.### Node selectiondiff --git a/services/nvpair-proxy/cors_generic_test.go b/services/nvpair-proxy/cors_generic_test.gonew file mode 100644index 0000000..7b39f03--- /dev/null+++ b/services/nvpair-proxy/cors_generic_test.go@@ -0,0 +1,37 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "net/http"+ "net/http/httptest"+ "testing"+)++// CORS follows HTTP responses even for a profile absent from the engine table.+// No launch-option knowledge is supplied to the proxy.+func TestCORSPolicyIsIndependentOfEngineIdentity(t *testing.T) {+ tc := lmstudioCase(t)+ tc.profile.Name = "future-engine"+ test := func(name, allowed string) {+ t.Run(name, func(t *testing.T) {+ upstream := corsEngine(t, tc, allowed, http.StatusOK)+ defer upstream.Close()+ proxy := proxyForCORSTargets(t, tc, upstream)+ for _, method := range []string{http.MethodOptions, http.MethodGet} {+ rec := httptest.NewRecorder()+ proxy.handlePlain(rec, corsRequest(method, "/future-api", "https://app.test"))+ wantStatus := http.StatusOK+ if method == http.MethodOptions {+ wantStatus = http.StatusNoContent+ }+ if rec.Code != wantStatus || rec.Header().Get("Access-Control-Allow-Origin") != allowed {+ t.Fatalf("%s: status=%d, headers=%v", method, rec.Code, rec.Header())+ }+ }+ })+ }+ test("engine grants browser access", "https://app.test")+ test("engine grants no CORS permission", "")+}diff --git a/services/nvpair-proxy/cors_inventory_test.go b/services/nvpair-proxy/cors_inventory_test.gonew file mode 100644index 0000000..a428957--- /dev/null+++ b/services/nvpair-proxy/cors_inventory_test.go@@ -0,0 +1,82 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "io"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+)++func TestCORSInvalidInventoryPreservesApprovedPolicy(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ test := func(name string, denied, malformedFirst bool) {+ t.Run(name, func(t *testing.T) {+ broken := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Access-Control-Allow-Origin", "http://app.test")+ w.Header().Set("Vary", "Origin")+ if _, err := io.WriteString(w, "{malformed"); err != nil {+ t.Error(err)+ }+ }))+ defer broken.Close()+ status, origin := http.StatusOK, "http://app.test"+ if denied {+ status, origin = http.StatusForbidden, ""+ }+ other := corsEngine(t, tc, origin, status)+ defer other.Close()+ targets := []*httptest.Server{other, broken}+ if malformedFirst {+ targets = []*httptest.Server{broken, other}+ }+ p := proxyForCORSTargets(t, tc, targets...)+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest(http.MethodGet, tc.modelListPath, "http://app.test"))+ wantStatus, wantOrigin := http.StatusBadGateway, "http://app.test"+ if denied {+ wantStatus, wantOrigin = http.StatusForbidden, ""+ }+ if rec.Code != wantStatus || rec.Header().Get("Access-Control-Allow-Origin") != wantOrigin {+ t.Fatalf("status=%d headers=%v, want %d origin %q", rec.Code, rec.Header(), wantStatus, wantOrigin)+ }+ if strings.Contains(rec.Body.String(), "private-model") {+ t.Fatal("returned partial model inventory")+ }+ if !denied && !strings.Contains(rec.Body.String(), "model inventory unavailable") {+ t.Fatalf("missing readable error: %s", rec.Body.String())+ }+ })+ }+ test("approved invalid inventory first", false, true)+ test("approved invalid inventory last", false, false)+ test("denial after invalid inventory", true, true)+ test("denial before invalid inventory", true, false)+ })+}++func TestModelListStripsCredentialsWithoutOrigin(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Authorization") != "" || r.Header.Get("Cookie") != "" {+ t.Error("caller credentials forwarded to model-list candidate")+ }+ if _, err := io.WriteString(w, corsModels(tc)); err != nil {+ t.Error(err)+ }+ }))+ defer upstream.Close()+ p := proxyForCORSTargets(t, tc, upstream, upstream)+ request := corsRequest(http.MethodGet, tc.modelListPath, "")+ request.Header.Set("Authorization", "Bearer private")+ request.Header.Set("Cookie", "session=private")+ rec := httptest.NewRecorder()+ p.handlePlain(rec, request)+ if rec.Code != http.StatusOK {+ t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())+ }+ })+}diff --git a/services/nvpair-proxy/cors_test.go b/services/nvpair-proxy/cors_test.gonew file mode 100644index 0000000..dbd889f--- /dev/null+++ b/services/nvpair-proxy/cors_test.go@@ -0,0 +1,595 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0+package main++import (+ "context"+ "encoding/json"+ "io"+ "net"+ "net/http"+ "net/http/httptest"+ "nvpair-shared/clustertrust"+ "nvpair-shared/clustertrusttest"+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "sync/atomic"+ "testing"+ "time"+)++func corsModels(tc engineCase) string {+ if tc.profile.Name == "ollama" {+ return `{"models":[{"name":"private-model"}]}`+ }+ return `{"object":"list","data":[{"id":"private-model"}]}`+}++func corsRequest(method, path, origin string) *http.Request {+ r := httptest.NewRequest(method, path, nil)+ r.RemoteAddr = "127.0.0.1:40000"+ if origin != "" {+ r.Header.Set("Origin", origin)+ }+ if method == "OPTIONS" {+ r.Header.Set("Access-Control-Request-Method", "POST")+ r.Header.Set("Access-Control-Request-Headers", "Content-Type")+ }+ return r+}+func corsEngine(t *testing.T, tc engineCase, allowed string, status int) *httptest.Server {+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if allowed != "" && (r.Header.Get("Origin") == allowed || allowed == "*") {+ w.Header().Set("Access-Control-Allow-Origin", allowed)+ w.Header().Set("Access-Control-Allow-Methods", "GET, POST")+ w.Header().Set("Access-Control-Allow-Headers", "Content-Type")+ w.Header().Set("Access-Control-Allow-Credentials", "true")+ w.Header().Add("Vary", "Origin")+ }+ w.Header().Set("Content-Type", "application/json")+ if status != 200 {+ w.WriteHeader(status)+ if _, err := io.WriteString(w, "engine refused"); err != nil {+ t.Error(err)+ }+ return+ }+ if r.Method == "OPTIONS" {+ w.WriteHeader(204)+ return+ }+ if _, err := io.WriteString(w, corsModels(tc)); err != nil {+ t.Error(err)+ }+ }))+}+func proxyForCORSTargets(t *testing.T, tc engineCase, servers ...*httptest.Server) *facade {+ d := NewDiscovery()+ for i, s := range servers {+ d.AddManual(nodeFor(t, string(rune('a'+i)), s.URL))+ }+ return testProxy(tc.profile, d, tc.profile.StandalonePort).soleFacade()+}+func TestCORSOriginDenialIsNotRewritten(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ for _, status := range []int{200, 401, 403} {+ t.Run(http.StatusText(status), func(t *testing.T) {+ engine := corsEngine(t, tc, "", status)+ defer engine.Close()+ p := proxyForCORSTargets(t, tc, engine)+ for _, method := range []string{"OPTIONS", "GET"} {+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest(method, "/policy", "http://example.com"))+ want := status+ if method == "OPTIONS" && status == 200 {+ want = 204+ }+ if rec.Code != want || rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatalf("%s: %d %v", method, rec.Code, rec.Header())+ }+ if status != 200 && rec.Body.String() != "engine refused" {+ t.Fatal("upstream error body changed")+ }+ }+ })+ }+ })+}++// A preflight is shared only where every engine that answered agrees. The+// request it precedes would route around an engine that is down, so that+// engine's silence must not deny the browser the ones that are up.+func TestCORSClusterRequiresEveryRespondingTarget(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ for _, policy := range []struct {+ name, origin string+ status, want int+ }{+ {"agree", "http://app.test", 200, 204}, {"different origin", "http://other.test", 200, 403},+ {"missing policy", "", 200, 403}, {"denied", "", 403, 403}, {"unavailable", "", 503, 204},+ } {+ t.Run(policy.name, func(t *testing.T) {+ a := corsEngine(t, tc, "http://app.test", 200)+ defer a.Close()+ b := corsEngine(t, tc, policy.origin, policy.status)+ defer b.Close()+ p := proxyForCORSTargets(t, tc, a, b)+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest("OPTIONS", tc.inferencePath, "http://app.test"))+ if rec.Code != policy.want {+ t.Fatalf("status=%d want=%d", rec.Code, policy.want)+ }+ if policy.want != 204 && rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatal("granted denied origin")+ }+ if policy.want == 204 && (rec.Header().Get("Access-Control-Max-Age") == "" || rec.Header().Get("Access-Control-Allow-Credentials") != "true") {+ t.Fatal("invalid agreement")+ }+ })+ }+ })+}++// The model list is shared only where every engine that answered agrees. An+// engine that could not answer has no permission to intersect: its models are+// absent from the merged list either way, so treating its silence as a denial+// would let one offline node cut a browser off from every online one.+func TestCORSModelListRequiresEveryRespondingTarget(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ for _, policy := range []struct {+ name, origin string+ status, want int+ }{+ {"agree", "http://app.test", 200, 200}, {"different origin", "http://other.test", 200, 403},+ {"missing policy", "", 200, 403}, {"denied", "", 403, 403}, {"unavailable", "", 503, 200},+ } {+ t.Run(policy.name, func(t *testing.T) {+ a := corsEngine(t, tc, "http://app.test", 200)+ defer a.Close()+ b := corsEngine(t, tc, policy.origin, policy.status)+ defer b.Close()+ p := proxyForCORSTargets(t, tc, a, b)+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest("GET", tc.modelListPath, "http://app.test"))+ if rec.Code != policy.want {+ t.Fatalf("status=%d want=%d body=%s", rec.Code, policy.want, rec.Body)+ }+ if policy.want != 200 {+ if strings.Contains(rec.Body.String(), "private-model") || rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatal("partial inventory exposed")+ }+ } else if rec.Header().Get("Access-Control-Allow-Origin") != "http://app.test" || rec.Header().Get("Access-Control-Allow-Credentials") != "true" {+ t.Fatal("shared permissions missing")+ }+ })+ }+ })+}++// An engine that is down must not be able to deny the browser, but one that+// answers and refuses the origin still must.+func TestCORSModelListSeparatesSilenceFromDenial(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ allowing := corsEngine(t, tc, "http://app.test", 200)+ defer allowing.Close()+ offline := corsEngine(t, tc, "", 503)+ defer offline.Close()++ rec := httptest.NewRecorder()+ proxyForCORSTargets(t, tc, allowing, offline).+ handlePlain(rec, corsRequest("GET", tc.modelListPath, "http://app.test"))+ if rec.Code != 200 || rec.Header().Get("Access-Control-Allow-Origin") != "http://app.test" {+ t.Fatalf("an offline engine denied the browser: status=%d body=%s", rec.Code, rec.Body)+ }+ if !strings.Contains(rec.Body.String(), "private-model") {+ t.Fatal("the reachable engine's inventory was dropped")+ }++ refusing := corsEngine(t, tc, "http://other.test", 200)+ defer refusing.Close()+ rec = httptest.NewRecorder()+ proxyForCORSTargets(t, tc, allowing, refusing).+ handlePlain(rec, corsRequest("GET", tc.modelListPath, "http://app.test"))+ if rec.Code != 403 || strings.Contains(rec.Body.String(), "private-model") {+ t.Fatalf("a live refusal was overridden: status=%d body=%s", rec.Code, rec.Body)+ }+ })+}+func TestCORSNoRetryOnPermissionDenial(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ for _, status := range []int{401, 403} {+ a := corsEngine(t, tc, "", status)+ var calls atomic.Int32+ b := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { calls.Add(1); w.WriteHeader(200) }))+ p := proxyForCORSTargets(t, tc, a, b)+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest("GET", "/policy", "http://app.test"))+ if rec.Code != status || calls.Load() != 0 {+ t.Fatal("retried a permission denial")+ }+ a.Close()+ b.Close()+ }+ })+}+func TestCORSOrdinaryOptionsAndPolicyChanges(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ var origin atomic.Value+ origin.Store("http://app.test")+ var calls atomic.Int32+ a := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Access-Control-Allow-Origin", origin.Load().(string))+ w.Header().Set("Access-Control-Allow-Methods", "POST")+ w.Header().Set("Access-Control-Allow-Headers", "Content-Type")+ w.WriteHeader(200)+ }))+ defer a.Close()+ b := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ w.Header().Set("Access-Control-Allow-Origin", "http://app.test")+ w.Header().Set("Access-Control-Allow-Methods", "POST")+ w.Header().Set("Access-Control-Allow-Headers", "Content-Type")+ w.WriteHeader(200)+ }))+ defer b.Close()+ p := proxyForCORSTargets(t, tc, a, b)+ req := httptest.NewRequest("OPTIONS", "/policy", nil)+ rec := httptest.NewRecorder()+ p.handleHTTP(rec, req)+ if rec.Code != 200 || calls.Load() != 0 {+ t.Fatal("ordinary OPTIONS was synthesized or fanned out")+ }+ rec = httptest.NewRecorder()+ p.handleHTTP(rec, corsRequest("OPTIONS", "/policy", "http://app.test"))+ if rec.Code != 204 {+ t.Fatal("initial agreement failed")+ }+ origin.Store("http://other.test")+ rec = httptest.NewRecorder()+ p.handleHTTP(rec, corsRequest("OPTIONS", "/policy", "http://app.test"))+ if rec.Code != 403 {+ t.Fatal("cached obsolete permission")+ }+ })+}+func TestCORSModelListStripsCredentialsAndDoesNotRedirect(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ var leaked atomic.Int32+ sink := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { leaked.Add(1) }))+ defer sink.Close()+ for _, redirect := range []bool{false, true} {+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Origin") != "http://app.test" || r.Header.Get("X-Test") != "end-to-end" {+ t.Error("CORS inputs lost")+ }+ if r.Header.Get("Authorization") != "" || r.Header.Get("Cookie") != "" {+ t.Error("caller credentials forwarded to model-list candidate")+ }+ if r.Header.Get("X-Hop") != "" {+ t.Error("hop header forwarded")+ }+ w.Header().Set("Access-Control-Allow-Origin", "http://app.test")+ w.Header().Set("Vary", "X-Test")+ if redirect {+ http.Redirect(w, r, sink.URL, 307)+ return+ }+ if _, err := io.WriteString(w, corsModels(tc)); err != nil {+ t.Error(err)+ }+ }))+ p := proxyForCORSTargets(t, tc, upstream, upstream)+ req := corsRequest("GET", tc.modelListPath, "http://app.test")+ req.Header.Set("Authorization", "Bearer test")+ req.Header.Set("Cookie", "session=test")+ req.Header.Set("X-Test", "end-to-end")+ req.Header.Set("Connection", "X-Hop")+ req.Header.Set("X-Hop", "local")+ rec := httptest.NewRecorder()+ p.handlePlain(rec, req)+ want := 200+ if redirect {+ want = 502+ }+ if rec.Code != want {+ t.Fatalf("status %d", rec.Code)+ }+ if !redirect && !strings.Contains(strings.Join(rec.Header().Values("Vary"), ","), "X-Test") {+ t.Fatal("Vary lost")+ }+ upstream.Close()+ }+ if leaked.Load() != 0 {+ t.Fatal("followed aggregate redirect")+ }+ })+}+func TestCORSPairedIngressPreservesPolicyAndIsTerminal(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ aDir, bDir := t.TempDir(), t.TempDir()+ clustertrusttest.Join(t, aDir, "cluster", "a")+ clustertrusttest.Join(t, bDir, "cluster", "b")+ pin := func(dst, src, id string) {+ pem, err := os.ReadFile(filepath.Join(src, "node.crt"))+ if err != nil {+ t.Fatal(err)+ }+ body, _ := json.Marshal(map[string]string{"nodeUuid": id, "certPem": string(pem)})+ if err = os.MkdirAll(filepath.Join(dst, "trusted"), 0700); err != nil {+ t.Fatal(err)+ }+ if err = os.WriteFile(filepath.Join(dst, "trusted", id+".json"), body, 0600); err != nil {+ t.Fatal(err)+ }+ }+ pin(aDir, bDir, "b")+ pin(bDir, aDir, "a")+ local := corsEngine(t, tc, "http://app.test", 200)+ defer local.Close()+ var unexpected atomic.Int32+ other := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { unexpected.Add(1) }))+ defer other.Close()+ peer := proxyForCORSTargets(t, tc, other)+ peer.host.mesh = clustertrust.Open(bDir)+ backend := nodeFor(t, "local", local.URL)+ if err := peer.setLocalBackend(localBackend{Host: backend.Addresses[0], Port: backend.Port, Healthy: true}); err != nil {+ t.Fatal(err)+ }+ ingress := httptest.NewUnstartedServer(http.HandlerFunc(peer.handleClusterIngress))+ ingress.TLS = peer.host.mesh.ServerTLSConfig()+ ingress.StartTLS()+ defer ingress.Close()+ caller := testProxy(tc.profile, NewDiscovery(), tc.profile.StandalonePort).soleFacade()+ caller.host.mesh = clustertrust.Open(aDir)+ n := nodeFor(t, "peer", ingress.URL)+ n.ClusterUUID = "b"+ caller.discovery.SetSubscribed([]Node{n})+ for _, origin := range []string{"http://app.test", "http://denied.test"} {+ for _, method := range []string{"OPTIONS", "GET"} {+ rec := httptest.NewRecorder()+ caller.handlePlain(rec, corsRequest(method, "/policy", origin))+ expected := ""+ if origin == "http://app.test" {+ expected = origin+ }+ if rec.Header().Get("Access-Control-Allow-Origin") != expected {+ t.Fatalf("paired policy lost: %d %v", rec.Code, rec.Header())+ }+ if rec.Code != 200 && rec.Code != 204 {+ t.Fatalf("paired status %d: %s", rec.Code, rec.Body)+ }+ }+ }+ if unexpected.Load() != 0 {+ t.Fatal("paired ingress routed onward")+ }+ })+}++// Opt-in fixture for real browser validation; regular suites do not keep a server running.+func TestCORSBrowserFixture(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ file := os.Getenv("PAIR_CORS_BROWSER_FIXTURE")+ if file == "" {+ t.Skip("browser fixture is opt-in")+ }+ page := func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html")+ if _, err := io.WriteString(w, "<!doctype html><title>CORS test</title>"); err != nil {+ t.Error(err)+ }+ }+ allowed := httptest.NewServer(http.HandlerFunc(page))+ defer allowed.Close()+ denied := httptest.NewServer(http.HandlerFunc(page))+ defer denied.Close()+ engine := corsEngine(t, tc, allowed.URL, 200)+ defer engine.Close()+ second := corsEngine(t, tc, allowed.URL, 200)+ defer second.Close()+ p := proxyForCORSTargets(t, tc, engine, second)+ proxy := httptest.NewServer(http.HandlerFunc(p.handlePlain))+ defer proxy.Close()+ none := proxyForCORSTargets(t, tc)+ unavailable := httptest.NewServer(http.HandlerFunc(none.handlePlain))+ defer unavailable.Close()+ data, _ := json.Marshal(map[string]string{"allowed": allowed.URL, "denied": denied.URL, "proxy": proxy.URL, "engine": engine.URL, "unavailable": unavailable.URL, "models": tc.modelListPath})+ if err := os.WriteFile(file, data, 0600); err != nil {+ t.Fatal(err)+ }+ deadline := time.After(60 * time.Second)+ tick := time.NewTicker(100 * time.Millisecond)+ defer tick.Stop()+ for {+ select {+ case <-deadline:+ t.Fatal("browser fixture timed out")+ case <-tick.C:+ if _, err := os.Stat(file + ".done"); err == nil {+ if err := os.Remove(file + ".done"); err != nil {+ t.Fatal(err)+ }+ return+ }+ }+ }+ })+}++// TestCORSExternalEngineParity optionally compares a running engine with this+// proxy implementation using read-only OPTIONS and GET requests.+func TestCORSExternalEngineParity(t *testing.T) {+ tc := ollamaCase(t)+ base := os.Getenv("PAIR_CORS_PARITY_URL")+ if executable := os.Getenv("PAIR_CORS_OLLAMA_EXECUTABLE"); base == "" && executable != "" {+ ln, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatal(err)+ }+ address := ln.Addr().String()+ if err := ln.Close(); err != nil {+ t.Fatal(err)+ }+ base = "http://" + address+ ctx, cancel := context.WithCancel(context.Background())+ command := exec.CommandContext(ctx, executable, "serve")+ command.Env = append(os.Environ(), "OLLAMA_HOST="+address, "OLLAMA_ORIGINS=http://wrong.com", "OLLAMA_MODELS="+t.TempDir())+ if err := command.Start(); err != nil {+ cancel()+ t.Fatal(err)+ }+ t.Cleanup(func() { cancel(); _ = command.Wait() })+ ready := false+ client := &http.Client{Timeout: time.Second}+ for deadline := time.Now().Add(30 * time.Second); time.Now().Before(deadline); {+ resp, err := client.Get(base + "/api/version")+ if err == nil {+ if err := resp.Body.Close(); err != nil {+ t.Fatal(err)+ }+ if resp.StatusCode == 200 {+ ready = true+ break+ }+ }+ time.Sleep(100 * time.Millisecond)+ }+ if !ready {+ t.Fatal("isolated Ollama did not become ready")+ }+ }+ if base == "" {+ t.Skip("external engine parity is opt-in")+ }+ d := NewDiscovery()+ d.AddManual(nodeFor(t, "engine", base))+ p := testProxy(tc.profile, d, tc.profile.StandalonePort).soleFacade()+ proxy := httptest.NewServer(http.HandlerFunc(p.handlePlain))+ defer proxy.Close()+ client := &http.Client{Timeout: 3 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}+ for _, origin := range []string{"http://wrong.com", "http://example.com"} {+ for _, method := range []string{"OPTIONS", "GET"} {+ fetch := func(target string) (*http.Response, string) {+ req, err := http.NewRequest(method, target+"/", nil)+ if err != nil {+ t.Fatal(err)+ }+ req.Header.Set("Origin", origin)+ if method == "OPTIONS" {+ req.Header.Set("Access-Control-Request-Method", "GET")+ }+ resp, err := client.Do(req)+ if err != nil {+ t.Fatal(err)+ }+ defer func() {+ if err := resp.Body.Close(); err != nil {+ t.Error(err)+ }+ }()+ body, err := io.ReadAll(resp.Body)+ if err != nil {+ t.Fatal(err)+ }+ return resp, string(body)+ }+ direct, directBody := fetch(base)+ forwarded, body := fetch(proxy.URL)+ if direct.StatusCode != forwarded.StatusCode || directBody != body {+ t.Fatalf("%s %s: direct=%d proxy=%d body mismatch=%v", method, origin, direct.StatusCode, forwarded.StatusCode, directBody != body)+ }+ for _, name := range []string{"Access-Control-Allow-Origin", "Access-Control-Allow-Headers", "Access-Control-Allow-Methods", "Access-Control-Allow-Credentials", "Access-Control-Max-Age", "Access-Control-Expose-Headers", "Vary"} {+ if strings.Join(direct.Header.Values(name), ",") != strings.Join(forwarded.Header.Values(name), ",") {+ t.Fatalf("header %s changed", name)+ }+ }+ t.Logf("%s origin=%s direct=%d proxy=%d allow-origin=%q", method, origin, direct.StatusCode, forwarded.StatusCode, forwarded.Header.Get("Access-Control-Allow-Origin"))+ }+ }+}++func TestCORSInvalidModelListIsNotPartiallyExposed(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ good := corsEngine(t, tc, "http://app.test", 200)+ defer good.Close()+ for _, invalid := range []string{"not json", "{}", "null"} {+ bad := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Access-Control-Allow-Origin", "http://app.test")+ if _, err := io.WriteString(w, invalid); err != nil {+ t.Error(err)+ }+ }))+ p := proxyForCORSTargets(t, tc, good, bad)+ rec := httptest.NewRecorder()+ p.handlePlain(rec, corsRequest("GET", tc.modelListPath, "http://app.test"))+ if rec.Code != http.StatusBadGateway || rec.Header().Get("Access-Control-Allow-Origin") != "http://app.test" || strings.Contains(rec.Body.String(), "private-model") {+ t.Fatalf("invalid inventory exposed: %d %s", rec.Code, rec.Body)+ }+ bad.Close()+ }+ })+}+func TestCORSStreamingResponseIsPreserved(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ release := make(chan struct{})+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Origin") != "http://app.test" {+ t.Error("lost stream origin")+ }+ w.Header().Set("Access-Control-Allow-Origin", "http://app.test")+ w.Header().Set("Access-Control-Expose-Headers", "X-Engine")+ w.Header().Set("X-Engine", "metadata")+ if _, err := io.WriteString(w, "first"); err != nil {+ t.Error(err)+ }+ w.(http.Flusher).Flush()+ select {+ case <-release:+ if _, err := io.WriteString(w, "last"); err != nil {+ t.Error(err)+ }+ case <-r.Context().Done():+ }+ }))+ defer upstream.Close()+ p := proxyForCORSTargets(t, tc, upstream)+ proxy := httptest.NewServer(http.HandlerFunc(p.handlePlain))+ defer proxy.Close()+ defer func() {+ select {+ case <-release:+ default:+ close(release)+ }+ }()+ req, err := http.NewRequest("GET", proxy.URL+"/stream", nil)+ if err != nil {+ t.Fatal(err)+ }+ req.Header.Set("Origin", "http://app.test")+ client := &http.Client{Timeout: 3 * time.Second}+ resp, err := client.Do(req)+ if err != nil {+ t.Fatal(err)+ }+ defer func() {+ if err := resp.Body.Close(); err != nil {+ t.Error(err)+ }+ }()+ first := make([]byte, 5)+ if _, err = io.ReadFull(resp.Body, first); err != nil {+ t.Fatal(err)+ }+ if string(first) != "first" || resp.Header.Get("Access-Control-Allow-Origin") != "http://app.test" || resp.Header.Get("Access-Control-Expose-Headers") != "X-Engine" {+ t.Fatal("stream changed")+ }+ close(release)+ rest, err := io.ReadAll(resp.Body)+ if err != nil || string(rest) != "last" {+ t.Fatal("stream incomplete", err)+ }+ })+}diff --git a/services/nvpair-proxy/e2e_test.go b/services/nvpair-proxy/e2e_test.goindex 27579a9..3251e13 100644--- a/services/nvpair-proxy/e2e_test.go+++ b/services/nvpair-proxy/e2e_test.go@@ -69,6 +69,7 @@ type e2eFrame struct {}func e2eReadFrames(r io.Reader, out chan<- e2eFrame) {+ defer close(out)sc := bufio.NewScanner(r)sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)for sc.Scan() {@@ -92,28 +93,50 @@ func e2eSend(t *testing.T, w io.Writer, id int, method string, params any) {}}-func e2eWaitResult(t *testing.T, frames <-chan e2eFrame, id string, timeout time.Duration) {+// e2eInbox retains interleaved replies and notifications for later waits.+// All waits for a child process share one inbox and run on the test goroutine.+type e2eInbox struct {+ frames <-chan e2eFrame+ pending []e2eFrame+}++func (in *e2eInbox) wait(t *testing.T, match func(e2eFrame) bool, description string, timeout time.Duration) e2eFrame {t.Helper()- deadline := time.After(timeout)+ for i, f := range in.pending {+ if match(f) {+ in.pending = append(in.pending[:i], in.pending[i+1:]...)+ return f+ }+ }+ timer := time.NewTimer(timeout)+ defer timer.Stop()for {select {- case f := <-frames:- if string(f.ID) != id {- continue+ case f, ok := <-in.frames:+ if !ok {+ t.Fatalf("stream closed waiting for %s", description)}- if len(f.Error) > 0 && string(f.Error) != "null" {- t.Fatalf("rpc id %s returned error: %s", id, f.Error)+ if match(f) {+ return f}- return- case <-deadline:- t.Fatalf("timed out waiting for response id %s", id)+ in.pending = append(in.pending, f)+ case <-timer.C:+ t.Fatalf("timed out waiting for %s", description)}}}+func e2eWaitResult(t *testing.T, frames *e2eInbox, id string, timeout time.Duration) {+ t.Helper()+ f := frames.wait(t, func(f e2eFrame) bool { return string(f.ID) == id }, "response id "+id, timeout)+ if len(f.Error) > 0 && string(f.Error) != "null" {+ t.Fatalf("rpc id %s returned error: %s", id, f.Error)+ }+}+// e2eEnableWithRetry enables a facade, trying a fresh port whenever the child// reports a lost bind race, and returns the port it actually bound.-func e2eEnableWithRetry(t *testing.T, stdin io.Writer, frames <-chan e2eFrame, engine string, port int) int {+func e2eEnableWithRetry(t *testing.T, stdin io.Writer, frames *e2eInbox, engine string, port int) int {t.Helper()for attempt := 0; attempt < 8; attempt++ {id := 100 + attempt@@ -139,57 +162,79 @@ func e2eEnableWithRetry(t *testing.T, stdin io.Writer, frames <-chan e2eFrame, e// e2eEnabledPort reads the port a facade/enable bound, reporting bindRace when// the child refused because the port was taken. Only a bind race is retryable;// any other rejection is a real failure.-func e2eEnabledPort(t *testing.T, frames <-chan e2eFrame, id string, timeout time.Duration) (port int, bindRace bool) {+func e2eEnabledPort(t *testing.T, frames *e2eInbox, id string, timeout time.Duration) (port int, bindRace bool) {t.Helper()- deadline := time.After(timeout)- for {- select {- case f := <-frames:- if string(f.ID) != id {- continue- }- if len(f.Error) > 0 && string(f.Error) != "null" {- var rpcErr struct {- Code int `json:"code"`- }- if json.Unmarshal(f.Error, &rpcErr) == nil && rpcErr.Code == codeFacadeBindFailed {- return 0, true- }- t.Fatalf("facade/enable returned error: %s", f.Error)- }- var res struct {- Port int `json:"port"`- }- if err := json.Unmarshal(f.Result, &res); err != nil {- t.Fatalf("parse facade/enable result: %v", err)- }- return res.Port, false- case <-deadline:- t.Fatalf("timed out waiting for facade/enable response id %s", id)+ f := frames.wait(t, func(f e2eFrame) bool { return string(f.ID) == id }, "facade/enable response id "+id, timeout)+ if len(f.Error) > 0 && string(f.Error) != "null" {+ var rpcErr struct {+ Code int `json:"code"`+ }+ if json.Unmarshal(f.Error, &rpcErr) == nil && rpcErr.Code == codeFacadeBindFailed {+ return 0, true}+ t.Fatalf("facade/enable returned error: %s", f.Error)+ }+ var res struct {+ Port int `json:"port"`+ }+ if err := json.Unmarshal(f.Result, &res); err != nil {+ t.Fatalf("parse facade/enable result: %v", err)}+ return res.Port, false}-func e2eWaitReadyPort(t *testing.T, frames <-chan e2eFrame, timeout time.Duration) int {+func e2eWaitReadyPort(t *testing.T, frames *e2eInbox, timeout time.Duration) int {t.Helper()- deadline := time.After(timeout)- for {- select {- case f := <-frames:- if f.Method != "ready" {- continue+ f := frames.wait(t, func(f e2eFrame) bool { return f.Method == "ready" }, "ready notification", timeout)+ var p struct {+ Port int `json:"port"`+ }+ if err := json.Unmarshal(f.Params, &p); err != nil {+ t.Fatalf("parse ready params: %v", err)+ }+ return p.Port+}++func TestE2EInboxPreservesInterleavedFrames(t *testing.T) {+ for _, readyFirst := range []bool{true, false} {+ t.Run(fmt.Sprintf("ready-first-%t", readyFirst), func(t *testing.T) {+ source := make(chan e2eFrame, 4)+ source <- e2eFrame{ID: json.RawMessage("2"), Result: json.RawMessage(`{}`)}+ ready := e2eFrame{Method: "ready", Params: json.RawMessage(`{"port":12345}`)}+ enabled := e2eFrame{ID: json.RawMessage("100"), Result: json.RawMessage(`{"port":12345}`)}+ if readyFirst {+ source <- ready+ source <- enabled+ } else {+ source <- enabled+ source <- ready}- var p struct {- Port int `json:"port"`+ source <- e2eFrame{ID: json.RawMessage("1"), Result: json.RawMessage(`{}`)}+ close(source)+ frames := &e2eInbox{frames: source}+ if readyFirst {+ port, retry := e2eEnabledPort(t, frames, "100", time.Second)+ if retry || port != 12345 {+ t.Fatalf("enabled port=%d retry=%v", port, retry)+ }+ if port := e2eWaitReadyPort(t, frames, time.Second); port != 12345 {+ t.Fatalf("ready port=%d", port)+ }+ } else {+ if port := e2eWaitReadyPort(t, frames, time.Second); port != 12345 {+ t.Fatalf("ready port=%d", port)+ }+ port, retry := e2eEnabledPort(t, frames, "100", time.Second)+ if retry || port != 12345 {+ t.Fatalf("enabled port=%d retry=%v", port, retry)+ }}- if err := json.Unmarshal(f.Params, &p); err != nil {- t.Fatalf("parse ready params: %v", err)+ e2eWaitResult(t, frames, "1", time.Second)+ e2eWaitResult(t, frames, "2", time.Second)+ if len(frames.pending) != 0 {+ t.Fatalf("unconsumed frames: %+v", frames.pending)}- return p.Port- case <-deadline:- t.Fatalf("timed out waiting for ready notification")- return 0- }+ })}}@@ -270,8 +315,9 @@ func TestE2EFailoverOverRealBinary(t *testing.T) {_ = cmd.Wait()}()- frames := make(chan e2eFrame, 256)- go e2eReadFrames(stdout, frames)+ source := make(chan e2eFrame, 256)+ go e2eReadFrames(stdout, source)+ frames := &e2eInbox{frames: source}// Retried on a bind race: e2eFreePort can only probe-then-close, and a// process spawn sits between the probe and the child's bind, so the@@ -312,8 +358,8 @@ func TestE2EFailoverOverRealBinary(t *testing.T) {if resp.StatusCode != http.StatusOK {t.Fatalf("status = %d, want 200 (should fail over from the 503 node)", resp.StatusCode)}- if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)+ if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header", got)}if gotBody != body {t.Errorf("healthy upstream got body %q, want the original request body %q", gotBody, body)diff --git a/services/nvpair-proxy/facade.go b/services/nvpair-proxy/facade.goindex 1b70c91..b53cfa3 100644--- a/services/nvpair-proxy/facade.go+++ b/services/nvpair-proxy/facade.go@@ -50,6 +50,9 @@ type facade struct {// never mutated, so every read is safe without a lock.profile engineProfile+ // portMu serializes durable rebinds without blocking routing during storage I/O.+ portMu sync.Mutex+// httpMu guards port, the servers, the split listener, and the listeners// across a live set-port rebind. The HTTP handlers never read port (they// route by upstream node), so the only contention is set-port vs set-port@@ -750,19 +753,18 @@ func (f *facade) stopServing(ctx context.Context) {// naturally. A fresh `ready` notification announces the new port so the// orchestrator/UI learn where the proxy is now listening.// Only the listener swap runs under httpMu. Persisting the choice and-// announcing it happen after the unlock, because every request takes this+// announcing it happen outside that lock, because every request takes this// mutex through resolveCandidates: holding it across slow storage or a// backpressured stdout would stall all inference through this facade, and delay// teardown with it.func (f *facade) setPort(newPort int) error {+ f.portMu.Lock()+ defer f.portMu.Unlock()swapped, err := f.swapListener(newPort)if err != nil || !swapped {return err}- if err := savePersistedPort(f.profile, newPort); err != nil {- slog.Warn("failed to persist proxy port", "port", newPort, "err", err)- }if err := f.notify("ready", ReadyParams{Version: Version, Port: newPort}); err != nil {slog.Warn("failed to emit ready after rebind", "err", err)}@@ -771,18 +773,23 @@ func (f *facade) setPort(newPort int) error {// swapListener binds newPort and moves both personalities onto it, reporting// false when the facade was already there. The new listener is bound before the-// old split closes, so a bind failure leaves the current one serving.+// old split closes and persisted before the swap, so either failure leaves the+// current listener serving. The caller holds portMu throughout the operation.func (f *facade) swapListener(newPort int) (bool, error) {- f.httpMu.Lock()- defer f.httpMu.Unlock()-- if newPort == f.port {- return false, nil+ port, _ := f.selfAddresses()+ if newPort == port {+ return false, savePersistedPort(f.profile, newPort)}newLn, err := net.Listen("tcp", fmt.Sprintf(":%d", newPort))if err != nil {return false, fmt.Errorf("failed to bind port %d: %w", newPort, err)}+ if err := savePersistedPort(f.profile, newPort); err != nil {+ _ = newLn.Close()+ return false, fmt.Errorf("persist proxy port: %w", err)+ }+ f.httpMu.Lock()+ defer f.httpMu.Unlock()oldSplit := f.splitf.port = newPortdiff --git a/services/nvpair-proxy/failover_test.go b/services/nvpair-proxy/failover_test.goindex 47c0693..e84429b 100644--- a/services/nvpair-proxy/failover_test.go+++ b/services/nvpair-proxy/failover_test.go@@ -87,32 +87,15 @@ func nodeForModel(t *testing.T, id, serverURL, model string) Node {return node}-// TestHandlePlain_OptionsPreflight: a CORS preflight is answered locally with-// 204 + permissive headers and never forwarded.-func TestHandlePlain_OptionsPreflight(t *testing.T) {+// Preflight cannot authorize a browser when no engine is reachable.+func TestHandlePlain_PreflightWithoutEngineFails(t *testing.T) {forEachEngine(t, func(t *testing.T, tc engineCase) {p := testProxy(tc.profile, NewDiscovery(), tc.profile.FacadePort)+ req := corsRequest(http.MethodOptions, tc.inferencePath, "http://app.test")rec := httptest.NewRecorder()- req := httptest.NewRequest(http.MethodOptions, tc.inferencePath, nil)- req.RemoteAddr = "127.0.0.1:40000"- req.Header.Set("Access-Control-Request-Headers", "X-Custom-Token")p.soleFacade().handlePlain(rec, req)-- if rec.Code != http.StatusNoContent {- t.Fatalf("status = %d, want 204", rec.Code)- }- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)- }- if rec.Header().Get("Access-Control-Allow-Methods") == "" {- t.Errorf("missing Access-Control-Allow-Methods")- }- if got := rec.Header().Get("Access-Control-Expose-Headers"); got != "*" {- t.Errorf("Access-Control-Expose-Headers = %q, want *", got)- }- // The browser's requested headers are echoed so an arbitrary header clears preflight.- if got := rec.Header().Get("Access-Control-Allow-Headers"); got != "X-Custom-Token" {- t.Errorf("Access-Control-Allow-Headers = %q, want echoed X-Custom-Token", got)+ if rec.Code != http.StatusBadGateway || rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatalf("status=%d headers=%v", rec.Code, rec.Header())}})}@@ -194,12 +177,8 @@ func TestHandleHTTP_EngineCORSPolicyPreserved(t *testing.T) {})}-// TestHandleHTTP_EngineCredentialsWithoutOriginDropped: an engine (or an-// intermediary in front of it) that sends Allow-Credentials but no origin has-// declared no policy to keep, so the proxy supplies its own. The wildcard it-// writes is invalid next to Allow-Credentials: true, and a browser rejects that-// pair, so the inherited header must not survive the forward.-func TestHandleHTTP_EngineCredentialsWithoutOriginDropped(t *testing.T) {+// Preserve incomplete upstream policy without adding permissions.+func TestHandleHTTP_EngineCredentialsWithoutOriginPreserved(t *testing.T) {forEachEngine(t, func(t *testing.T, tc engineCase) {engine := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {w.Header().Set("Access-Control-Allow-Credentials", "true")@@ -215,17 +194,17 @@ func TestHandleHTTP_EngineCredentialsWithoutOriginDropped(t *testing.T) {rec := httptest.NewRecorder()p.soleFacade().handleHTTP(rec, tc.inferenceRequest())- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want the proxy's wildcard", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header", got)}- if got := rec.Header().Get("Access-Control-Allow-Credentials"); got != "" {- t.Errorf("Access-Control-Allow-Credentials = %q, want cleared alongside the wildcard origin", got)+ if got := rec.Header().Get("Access-Control-Allow-Credentials"); got != "true" {+ t.Errorf("Access-Control-Allow-Credentials = %q, want upstream value preserved", got)}})}// TestHandleHTTP_HappyPathSingleNode: the common case — one healthy node-// answers directly, body forwarded, CORS present on the success response.+// answers directly, preserving the body and absence of CORS permissions.func TestHandleHTTP_HappyPathSingleNode(t *testing.T) {forEachEngine(t, func(t *testing.T, tc engineCase) {var gotBody string@@ -250,8 +229,8 @@ func TestHandleHTTP_HappyPathSingleNode(t *testing.T) {if gotBody != tc.inferenceBody() {t.Errorf("node got body %q, want the original request body", gotBody)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want * on success", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header on success", got)}})}@@ -290,9 +269,8 @@ func TestHandleHTTP_NoRetryOn400(t *testing.T) {})}-// TestHandleHTTP_RejectionHasCORS: even the no-node rejection carries CORS so a-// browser sees the real 502 instead of an opaque CORS error.-func TestHandleHTTP_RejectionHasCORS(t *testing.T) {+// Proxy-generated errors grant no cross-origin access.+func TestHandleHTTP_RejectionHasNoCORS(t *testing.T) {forEachEngine(t, func(t *testing.T, tc engineCase) {p := testProxy(tc.profile, NewDiscovery(), tc.profile.FacadePort)rec := httptest.NewRecorder()@@ -301,8 +279,8 @@ func TestHandleHTTP_RejectionHasCORS(t *testing.T) {if rec.Code != http.StatusBadGateway {t.Fatalf("status = %d, want 502", rec.Code)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want * on rejection", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header on rejection", got)}})}@@ -341,14 +319,14 @@ func TestHandleHTTP_FailoverOn503(t *testing.T) {if gotBody != tc.inferenceBody() {t.Errorf("failover node got body %q, want the original request body", gotBody)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want * on proxied success", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header on proxied success", got)}})}// TestHandleHTTP_AllNodesDownReturnsError: when every candidate fails at the-// transport, the client gets one clean 502 (not a hang), still with CORS.+// transport, the client gets a 502 without added CORS permissions.func TestHandleHTTP_AllNodesDownReturnsError(t *testing.T) {forEachEngine(t, func(t *testing.T, tc engineCase) {// Two servers we immediately close so dials fail.@@ -370,8 +348,8 @@ func TestHandleHTTP_AllNodesDownReturnsError(t *testing.T) {if rec.Code != http.StatusBadGateway {t.Fatalf("status = %d, want 502 when all nodes are down", rec.Code)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want * on exhausted error", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header on exhausted error", got)}})}@@ -500,8 +478,8 @@ func TestHandleHTTP_AggregatesNativeModelList(t *testing.T) {if got.Models[1].Digest != "first" {t.Errorf("duplicate metadata = %q, want deterministic first candidate", got.Models[1].Digest)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header", got)}// Addressed to the engine, like every facade-scoped notification: the// broker's process-scoped router claims only workload and node-activitydiff --git a/services/nvpair-proxy/ingress.go b/services/nvpair-proxy/ingress.goindex 828c98e..ba8336f 100644--- a/services/nvpair-proxy/ingress.go+++ b/services/nvpair-proxy/ingress.go@@ -12,8 +12,6 @@ import ("net/http/httputil""net/url""strconv"-- "nvpair-shared/cors")const engineIdentityProbeHeader = "X-NVPAIR-Engine-Identity-Probe"@@ -80,13 +78,6 @@ func (f *facade) localBackendTarget() (*url.URL, bool) {// interfaces for the TLS personality, but plaintext is loopback-only).func (f *facade) handlePlain(w http.ResponseWriter, r *http.Request) {if !isLoopbackRemote(r.RemoteAddr) {- // Answer a non-loopback preflight ahead of the gate. It grants no access- // on its own; the request that follows still receives the real 403. A- // loopback preflight continues into handleHTTP so an available engine's- // exact origin and credentials policy can be preserved.- if cors.WritePreflight(w, r) {- return- }slog.Warn("rejected non-loopback plaintext request; cluster peers must use mTLS","remote", r.RemoteAddr, "method", r.Method, "path", r.URL.Path)writeIngressError(w, http.StatusForbidden, "loopback-only",@@ -167,12 +158,8 @@ func isLoopbackRemote(remoteAddr string) bool {return ip != nil && ip.IsLoopback()}-// writeIngressError writes a small structured JSON error. It never echoes the-// request body or any generated output. CORS headers are included because these-// are the proxy's own rejections: without them a browser client cannot read the-// status or reason, and every one of them looks like a generic CORS failure.+// writeIngressError returns the actual failure without granting browser permissions.func writeIngressError(w http.ResponseWriter, status int, code, msg string) {- cors.Apply(w.Header())w.Header().Set("Content-Type", "application/json")w.Header().Set("X-Content-Type-Options", "nosniff")w.WriteHeader(status)diff --git a/services/nvpair-proxy/ingress_test.go b/services/nvpair-proxy/ingress_test.goindex 7d5cc8a..5ccc24a 100644--- a/services/nvpair-proxy/ingress_test.go+++ b/services/nvpair-proxy/ingress_test.go@@ -52,29 +52,24 @@ func TestHandlePlainRejectsNonLoopback(t *testing.T) {if rec.Code != http.StatusForbidden {t.Fatalf("non-loopback plaintext status = %d, want %d", rec.Code, http.StatusForbidden)}- // The refusal carries CORS so a browser client reads this 403 and its reason- // instead of an opaque "CORS error" that hides why the call failed.- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want * on the refusal", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header on the refusal", got)}}-// TestHandlePlainAnswersPreflightBeforeLoopbackGate: the preflight is answered-// even for a caller the gate will refuse. It authorizes nothing — the request-// that follows is still rejected — but without it the browser never sends that-// request and reports the refusal as a generic CORS failure.-func TestHandlePlainAnswersPreflightBeforeLoopbackGate(t *testing.T) {+// Preflight is subject to the same ingress gate as ordinary requests.+func TestHandlePlainRejectsPreflightAtLoopbackGate(t *testing.T) {p := testProxy(anyProfile(t), NewDiscovery(), 11435)req := httptest.NewRequest(http.MethodOptions, "/api/generate", nil)req.RemoteAddr = "192.0.2.50:40000"rec := httptest.NewRecorder()p.soleFacade().handlePlain(rec, req)- if rec.Code != http.StatusNoContent {- t.Fatalf("preflight status = %d, want %d", rec.Code, http.StatusNoContent)+ if rec.Code != http.StatusForbidden {+ t.Fatalf("preflight status = %d, want %d", rec.Code, http.StatusForbidden)}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)+ if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {+ t.Errorf("Access-Control-Allow-Origin = %q, want no CORS header", got)}}diff --git a/services/nvpair-proxy/portstore_test.go b/services/nvpair-proxy/portstore_test.goindex e63c260..6484c3b 100644--- a/services/nvpair-proxy/portstore_test.go+++ b/services/nvpair-proxy/portstore_test.go@@ -151,3 +151,41 @@ func TestSetPortRebinds(t *testing.T) {}})}++// Persistence failure must leave the old listener serving and the new port free.+func TestSetPortPersistenceFailurePreservesListener(t *testing.T) {+ forEachEngine(t, func(t *testing.T, tc engineCase) {+ redirectConfigDir(t)+ portA := freeTCPPort(t)+ proxy := newTestProxy(tc.profile, NewCodec(&bytes.Buffer{}), NewDiscovery(), portA)+ ln, err := net.Listen("tcp", fmt.Sprintf(":%d", portA))+ if err != nil {+ t.Fatal(err)+ }+ ctx, cancel := context.WithCancel(context.Background())+ defer cancel()+ proxy.soleFacade().serveHTTP(ctx, ln)+ defer proxy.shutdown(context.Background())+ path, err := proxyPortPath(tc.profile)+ if err != nil {+ t.Fatal(err)+ }+ if err := os.MkdirAll(path, 0700); err != nil {+ t.Fatal(err)+ }+ portB := freeTCPPort(t)+ if err := proxy.soleFacade().setPort(portB); err == nil {+ t.Fatal("persistence failure reported success")+ }+ conn, err := net.DialTimeout("tcp", fmt.Sprintf("127.0.0.1:%d", portA), time.Second)+ if err != nil {+ t.Fatal("old listener lost", err)+ }+ _ = conn.Close()+ next, err := net.Listen("tcp", fmt.Sprintf(":%d", portB))+ if err != nil {+ t.Fatal("failed candidate listener leaked", err)+ }+ _ = next.Close()+ })+}diff --git a/services/nvpair-proxy/proxy.go b/services/nvpair-proxy/proxy.goindex ff89dbe..929c3d6 100644--- a/services/nvpair-proxy/proxy.go+++ b/services/nvpair-proxy/proxy.go@@ -915,9 +915,15 @@ type modelListItem struct {}type modelListResult struct {- items []modelListItem- ok bool- err error+ headers http.Header+ denied bool+ // unavailable marks a candidate that never answered — unreachable or a+ // server error — as opposed to one that answered unusably. Only the former+ // is excluded from the CORS intersection.+ unavailable bool+ items []modelListItem+ ok bool+ err error}// serveModelList queries every candidate concurrently and returns the engine's@@ -931,7 +937,6 @@ func (f *facade) serveModelList(w http.ResponseWriter, r *http.Request, role roup := f.hostopenAI := role == roleModelListOpenAIGETwriteJSON := func(status int, body []byte) {- cors.Apply(w.Header())w.Header().Set("Content-Type", "application/json")w.Header().Set("X-Content-Type-Options", "nosniff")w.WriteHeader(status)@@ -949,13 +954,19 @@ func (f *facade) serveModelList(w http.ResponseWriter, r *http.Request, role rouresults[i].err = errcontinue}- upstream.Header.Set("Accept", "application/json")+ upstream.Header = cors.FanoutHeaders(r.Header)+ upstream.Header.Del("Content-Length")+ if upstream.Header.Get("Accept") == "" {+ upstream.Header.Set("Accept", "application/json")+ }// A cluster-peer candidate is queried over mTLS to its promoted proxy;// self/manual candidates use the shared plain client.- client := modelListClient+ clientCopy := *modelListClient+ clientCopy.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }+ client := &clientCopyif cand.peerUUID != "" {- client = &http.Client{Timeout: modelListClient.Timeout, Transport: p.candidateTransport(cand)}+ client.Transport = p.candidateTransport(cand)}wg.Add(1)@@ -964,10 +975,20 @@ func (f *facade) serveModelList(w http.ResponseWriter, r *http.Request, role rouresp, err := client.Do(req)if err != nil {f.targets.Forget(cand.id)- results[i].err = err+ results[i] = modelListResult{unavailable: true, err: err}return}defer resp.Body.Close()+ responseHeaders := cors.EndToEndHeaders(resp.Header)+ results[i].headers = responseHeaders+ if r.Header.Get("Origin") != "" && (resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden || (resp.StatusCode == http.StatusOK && !cors.AllowsOrigin(responseHeaders, r.Header.Get("Origin")))) {+ results[i].denied = true+ return+ }+ if resp.StatusCode >= 500 {+ results[i] = modelListResult{unavailable: true, err: fmt.Errorf("upstream returned %s", resp.Status)}+ return+ }if resp.StatusCode != http.StatusOK {results[i].err = fmt.Errorf("upstream returned %s", resp.Status)return@@ -1023,11 +1044,57 @@ func (f *facade) serveModelList(w http.ResponseWriter, r *http.Request, role rou}items = append(items, modelListItem{key: key, digest: identity.Digest, raw: raw})}- results[i] = modelListResult{items: items, ok: true}+ results[i] = modelListResult{items: items, ok: true, headers: responseHeaders}}(i, cand, upstream, client)}wg.Wait()+ var combinedHeaders http.Header+ if r.Header.Get("Origin") != "" {+ headers := make([]http.Header, 0, len(results))+ invalidInventory := false+ for _, result := range results {+ // An engine that answered and refused the origin is a real denial;+ // its peers must not vote it away.+ if result.denied {+ writeJSON(http.StatusForbidden, []byte(`{"error":"an engine denied access to the model list"}`))+ return http.StatusForbidden, fmt.Errorf("engine denied model list")+ }+ // An engine that never answered expressed no opinion. Its models+ // are dropped from the merged list below, so intersecting its+ // absent headers would let one unreachable node deny the browser+ // access to every reachable one.+ if result.unavailable {+ continue+ }+ // An engine that answered unusably is reachable and broken. Do not+ // quietly hand a browser a list that silently omits it.+ if !result.ok {+ invalidInventory = true+ }+ headers = append(headers, result.headers)+ }+ if len(headers) == 0 {+ writeJSON(http.StatusBadGateway, []byte(`{"error":"model inventory unavailable"}`))+ return http.StatusBadGateway, fmt.Errorf("model inventory unavailable")+ }+ var allowed bool+ combinedHeaders, allowed = cors.Combine(r, headers)+ if invalidInventory {+ if allowed {+ for key, values := range combinedHeaders {+ w.Header()[key] = values+ }+ }+ writeJSON(http.StatusBadGateway, []byte(`{"error":"model inventory unavailable"}`))+ return http.StatusBadGateway, fmt.Errorf("model inventory unavailable")+ }+ if !allowed {+ writeJSON(http.StatusForbidden, []byte(`{"error":"engines do not all permit access to the model list"}`))+ return http.StatusForbidden, fmt.Errorf("engines denied model list")+ }+ }+success := falsemodels := make([]json.RawMessage, 0)seen := make(map[string]modelListItem)@@ -1072,6 +1139,9 @@ func (f *facade) serveModelList(w http.ResponseWriter, r *http.Request, role rouwriteJSON(http.StatusInternalServerError, []byte(`{"error":"failed to encode model inventory"}`))return http.StatusInternalServerError, err}+ for key, values := range combinedHeaders {+ w.Header()[key] = values+ }writeJSON(http.StatusOK, body)return http.StatusOK, nil}@@ -1098,6 +1168,16 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {routingModel = model}candidates := f.resolveCandidates(routingModel)+ if cors.IsPreflight(r) {+ targets := make([]cors.Target, 0, len(candidates))+ for _, cand := range candidates {+ targets = append(targets, cors.Target{URL: cand.url, Transport: p.candidateTransport(cand)})+ }+ sc := &statusCapture{ResponseWriter: w, status: http.StatusOK}+ cors.ServePreflight(sc, r, targets)+ f.notify("proxy/request", RequestEvent{ID: reqID, Method: r.Method, Path: r.URL.Path, Target: "cluster", Status: sc.status, Duration: time.Since(start).Milliseconds()})+ return+ }// held is this request's claim on a node's capacity while it is in flight.// resMu guards it because failover re-points it from the ReverseProxy's// callbacks while the disconnect watcher may be releasing it.@@ -1146,12 +1226,6 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {return}if len(candidates) == 0 {- // With no engine to consult, retain the local permissive preflight used- // for engines that do not publish a CORS policy.- if cors.WritePreflight(w, r) {- return- }- cors.Apply(w.Header())rejectionBody := `{"error":"no active node selected or available"}`rejectionError := "no active node"if isInf && model != "" {@@ -1686,10 +1760,6 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {if peeked != nil {resp.Body = peeked}- // Prefer an engine-declared preflight policy so an exact origin plus- // Allow-Credentials can pass a credentialed browser fetch. Engines- // that publish no policy retain the proxy's permissive 204 fallback.- cors.CompletePreflightFallback(resp)// Committing to this candidate — body stream is about to begin.ttfbMs = time.Since(start).Milliseconds()servedNodeID = cand.id@@ -1703,16 +1773,7 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {// came from the node. Same goroutine as the body copy, so no// synchronization is needed.sc.upstreamAlive = func() { p.reportActivity(cand.id) }- // The engine may enforce its own origin policy (Ollama's- // OLLAMA_ORIGINS). Honor it: overwriting a declared- // Access-Control-Allow-Origin would silently widen the user's- // policy, and a wildcard is invalid alongside- // Allow-Credentials, so it would break a credentialed response- // outright. An engine that omits the header has expressed- // nothing to preserve, so the proxy supplies its own.- if resp.Header.Get("Access-Control-Allow-Origin") == "" {- cors.Apply(resp.Header)- }+ // Preserve the upstream response, including absent CORS permissions.if !started {started = true_ = f.notify("proxy/request-started", RequestStartedEvent{@@ -1780,10 +1841,6 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {respondedWithError = trueservedNodeID = cand.idservedTarget = cand.url.Host- if cors.WritePreflight(ew, r) {- proxyErr = ""- return- }proxyErr = err.Error()slog.Warn("proxy upstream error, retries exhausted","id", reqID, "node_id", cand.id, "target", cand.url.Host,@@ -1801,7 +1858,6 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {if stderrors.Is(err, errFirstBodyTimeout) {status = http.StatusGatewayTimeout}- cors.Apply(ew.Header())ew.Header().Set("Content-Type", "application/json")ew.Header().Set("X-Content-Type-Options", "nosniff")ew.WriteHeader(status)@@ -1857,7 +1913,6 @@ func (f *facade) handleHTTP(w http.ResponseWriter, r *http.Request) {if mErr != nil {body = []byte(`{"error":"retry budget exhausted"}`)}- cors.Apply(w.Header())w.Header().Set("Content-Type", "application/json")w.Header().Set("X-Content-Type-Options", "nosniff")// Advisory only: the caller knows its own patience better than we do.diff --git a/services/nvpair-proxy/spec.md b/services/nvpair-proxy/spec.mdindex 92bce19..18c5999 100644--- a/services/nvpair-proxy/spec.md+++ b/services/nvpair-proxy/spec.md@@ -486,6 +486,19 @@ adopted engine keeps its own environment regardless. An engine that did offer areal cancellation API would change this calculus, and the claim should berevisited per engine rather than assumed to hold forever.+### 5.8 Browser policy++Each facade preserves its engine's CORS policy, including missing headers and+permission denials. Ingress gates apply before preflight forwarding. Proxy errors+grant no CORS permissions. Multi-target preflights intersect permissions from all+responding engines without forwarding caller credentials; unavailable engines+are skipped, and no responders yields 502. Preflights take no reservations.++Model inventories with an Origin require agreement from every responding engine:+a denial yields 403, an invalid inventory yields 502 without a partial list. An+invalid-inventory error retains CORS headers only when all responding engines+approve. See README.md for the complete forwarding and intersection rules.+## 6. ReservationsA reservation is one in-flight dispatch this process has made since the lastdiff --git a/services/nvpair-ui-broker/ENGINE_SETTINGS.md b/services/nvpair-ui-broker/ENGINE_SETTINGS.mdnew file mode 100644index 0000000..a6e2351--- /dev/null+++ b/services/nvpair-ui-broker/ENGINE_SETTINGS.md@@ -0,0 +1,120 @@+<!--+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+SPDX-License-Identifier: Apache-2.0+-->++# Engine settings protocol++The broker owns combined settings operations for Ollama and LM Studio. Each+node owns its own configuration. `nodeId` selects a discovered, currently pinned+peer; omission or the local host ID selects this node. Bulk propagation is not+part of this API.++| Method | Request | Result |+| --- | --- | --- |+| `engine:get-settings` | `{engine, nodeId?}` | Full snapshot |+| `engine:preview-settings` | `{engine, nodeId?, expectedRevision, settings, resolution?}` | Normalized settings, errors, conflict, restart/rebind summary |+| `engine:apply-settings` | Preview request plus `requestId` | `{revision, phase}` acknowledgement |++`engine` is `ollama` or `lmstudio`. `settings` contains all three fields:+`serverPort`, `proxyPort`, `launchText`. The last field contains arguments and+leading environment assignments, without the executable or startup subcommand.+The argument grammar is+[`pair-arguments-v1`](../nvpair-engine-manager/LAUNCH_TEXT.md). Preview does not+change component configuration or runtime. A snapshot read may persist the+initial revision baseline or reconcile an external component change.++Each full snapshot includes desired `settings`, `revision`, `appliedRevision`,+`phase` (`idle`, `applying`, `succeeded`, `failed`), `requestId`, `error`,+`effectiveServerPort`, `effectiveProxyPort`, `running`, `adopted`, `editable`,+`reason`, `format`, `epoch`, and `sequence`. A configured runtime server port+does not imply a listening server: consult `running`. The operation receipt is+not a state update. Consume `engine:settings-changed` or fetch the full snapshot+after a response loss. A renderer must retain dirty drafts and reject stale+baseline revisions, even when only arguments changed.++Declared CORS origin lists, switches and explicit booleans can only change on+the engine's owning node. The broker derives an internal `preserveCORS` preview+guard from the authenticated caller, overriding any client-supplied value. It+rechecks canonical CORS policy under the apply lock before accepting a revision;+the early remote ingress check alone is insufficient when operations overlap.++## Ownership, ordering and failures++The node configuration mutex precedes engine operation locks. Worker dispatch+is asynchronous; neither stdio reader waits for an operation. The broker holds+the node lock across validation, journal acceptance and application. The worker+holds its engine lock across override persistence, stopping with the old launch+context, installing the new context, the narrow proxy rebind callback and one+start/readiness wait. The callback validates an active operation token and+acquires no node configuration lock. Legacy public port setters enter this same+operation and retain their response shape. Legacy lifecycle port overrides and+automatic port reconciliation share the node lock and revision reconciliation.++Validate both ports together against the unchanged counterpart, registered+PAIR services, aliases, other configured engines/proxies and occupied listeners.+Only this engine's current running port and its proxy listener can be reused+for a swap. Revalidation happens at Apply; OS bind remains the final arbiter of+a competing process. Adopted process engines are read-only; command-mode+engines require their official stop path.++A normalized no-op changes no runtime. Proxy-only edits do not restart the+engine. A stopped engine remains stopped. Running launch/server changes stop+and start once without rewriting explicit enabled intent. Advertisements and+proxy upstream eligibility are disabled during application and restored only+after readiness. Polling advertisers share the node lock.++Validation, stale revisions and journal-write failures cause no runtime+mutation. Once accepted, desired settings remain saved if the engine or proxy+fails. The failed snapshot exposes actual runtime facts and the prior applied+revision; correction/retry is another explicit Apply. Component writes and OS+listeners are recoverable steps, not an ACID transaction. The failed snapshot+preserves the worker's error message. Settings-driven start failures use this+result instead of also raising global lifecycle errors. Normal start failures+still raise a lifecycle error; the exit watcher begins after readiness to avoid+reporting the same startup failure twice.++`engine-settings-operations.json` in the app data directory holds previous and+desired settings, revision, resume intent and operation receipts. Component+engine overrides and proxy-port files remain their owners' configuration.+Acceptance is written and synced before component changes. Interrupted applying+records replay before enabled-engine restoration. Explicit settings override+automatic facade defaults on later startup. Unreadable journal data is preserved+and suppresses automatic component rewrites. On first upgrade, a valid existing+proxy-port choice is preserved as explicit when it differs from the engine port+(except LM Studio's obsolete 1235 default). Old stores lack choice provenance,+so a historical automatic move is conservatively preserved too. Unreadable data+blocks automatic recovery. The journal retains up to 256 terminal receipts+per engine; evicted retries must still pass the original expected revision.++## Paired transport++The existing engine-control listener exposes pinned-mTLS POST endpoints+`/v1/engine-settings/get`, `/preview`, `/apply` and GET `/events`. Requests are+limited to 64 KiB and cannot forward another hop. The authenticated caller ID is+carried through correlated `engine:settings-request` / `engine:settings-reply`+notifications to the local broker. Cancellation and pin removal cancel queued+work; the broker rechecks the caller after acquiring the node lock. Once+durably accepted, the target completes under its own eleven-minute deadline even+if the initiating peer disconnects.++`engine:settings-projection` seeds the worker's subscription hub with full local+snapshots. A subscription registers and receives its baseline under one lock.+Slow readers coalesce full snapshots, avoiding missing-field patches. There are+at most 64 subscribers and 64 outbound peer streams. Each stream checks trust+on every frame/heartbeat, bounds writes to five seconds and emits one-second+heartbeats. Clients reconnect after disconnection and discard older sequences+within an epoch; a fresh authority epoch replaces the baseline. Settings never+enter mDNS/public discovery metadata. Older/offline/unpaired peers are read-only+with an explicit unavailable state in the editor.++## Validation++Tests cover literal argv, parser fuzz/table cases, managed-field validation,+real process no-op/proxy-only/launch changes, ownership rejection, persistence+failure, journal recovery, revision conflicts/deduplication, queued cancellation,+three-node pinned TLS subscriptions, revocation/reconnect, bounded slow readers,+proxy persistence failure preserving its listener, renderer ordering and log+redaction. The rendered editor is also exercised with isolated browser fixtures.+Native vendor and Linux/macOS runtime verification remain release-platform+checks; Windows fixture results do not certify vendor-option compatibility.diff --git a/services/nvpair-ui-broker/README.md b/services/nvpair-ui-broker/README.mdindex 6eeee29..df5ac9d 100644--- a/services/nvpair-ui-broker/README.md+++ b/services/nvpair-ui-broker/README.md@@ -5,6 +5,9 @@ SPDX-License-Identifier: Apache-2.0# nvpair-ui-broker+The [engine settings protocol](ENGINE_SETTINGS.md) documents local/paired+launch and port editing, revision checks, serialized application and recovery.+A Go service that exposes the NVIDIA Personal AI Router API to **UI processes**and other clients (CLIs, dashboards, mobile companions, scripts, tests, etc.).The shipped graphical UI is bundled alongside the backend services and launches@@ -383,13 +386,15 @@ Two relay-specific error cases:#### `ollama-proxy:set-port`-**Intercepted, not relayed verbatim** — this is where the broker coordinates the engine ↔ proxy port conflict, because it's the only component that sees both. On `ollama-proxy:set-port {port}` the broker asks `nvpair-engine-manager` (`engine:get-installed`) which ports its **running** engines hold. If the requested port is free, it relays `set-port {port}` to the proxy unchanged. If a running engine already holds it, **the engine wins**: the broker bumps the proxy to the next free port, relays `set-port {effectivePort}`, and surfaces a sticky `warning` into the errors pipeline (id `ollama-proxy:port-bumped`, `action:"none"`) explaining the move; a later non-colliding `ollama-proxy:set-port` clears that warning. The conflict path **never changes an engine's port** — only the proxy is moved. The response is the proxy's own `set-port` result (`{version, port}` with the actually-bound port).+**Intercepted, not relayed verbatim.** A port-only caller — `nvpair-tui` is the one in tree — gets to move a single port without rendering the whole launch settings form, but the change still runs through the same authoritative settings operation the desktop editor uses, so a port set from the terminal cannot diverge from one set from the UI. The broker reads the engine's current settings, substitutes the requested proxy port, and applies the result.++A **requested port that is already in use is refused** with error `-32000 "port %d is already in use"`. The broker does not pick a different port on the caller's behalf: silently binding somewhere else left clients pointed at a port nothing was listening on. Retry with a free port. A request that collides with an inherited `OLLAMA_HOST` alias is refused with its own message naming that alias. The response echoes the requested port (`{"port": <requested>}`) once it is bound.```json{"jsonrpc":"2.0","id":9,"method":"ollama-proxy:set-port","params":{"port":11500}}```-The same check runs whenever the proxy announces a (re)bound port (its restored port on startup), so a proxy that comes back up on a port a running engine has since taken is steered to a free one automatically. Error `-32000 "ollama-proxy not available"` when no proxy is supervised.+Automatic conflict resolution still exists, but only for a port the user did not just choose: when the proxy announces a (re)bound port on startup and a running engine has since taken it, the broker steers the proxy to a free port and surfaces a sticky `warning` into the errors pipeline (id `ollama-proxy:port-bumped`, `action:"none"`) explaining the move. That path **never changes an engine's port** — only the proxy is moved. Error `-32000 "ollama-proxy not available"` when no proxy is supervised.#### `lmstudio-proxy:get-status` / `lmstudio-proxy:subscribe` / `lmstudio-proxy:unsubscribe` / `lmstudio-proxy:<method>` (generic relay)@@ -477,7 +482,9 @@ Opt into / out of the `engine:<event>` stream (off by default). Acks `{ subscrib#### `engine:<method>` (generic relay)-Any other `engine:*` request is forwarded to `nvpair-engine-manager` verbatim and its response relayed straight back. This covers the whole engine control plane: `engine:get-installed`, `engine:describe`, `engine:status`, `engine:install`, `engine:uninstall`, `engine:start`, `engine:stop`, `engine:restart`, `engine:set-port`, `engine:action`, `engine:logs`, `engine:errors`, `engine:models`. (`engine:set-port` persists the engine's server port as a manifest override that survives a restart — see the `nvpair-engine-manager` README.) Lifecycle ops run for minutes (reporting progress via the `engine:install-progress` / `engine:state-changed` push events), so the relay imposes **no broker-side timeout** — fire the request and watch the event stream for the outcome. Error `-32000 "engine-manager not available"` when no engine-manager is supervised.+Any other `engine:*` request is forwarded to `nvpair-engine-manager` verbatim and its response relayed straight back. This covers the whole engine control plane: `engine:get-installed`, `engine:describe`, `engine:status`, `engine:install`, `engine:uninstall`, `engine:start`, `engine:stop`, `engine:restart`, `engine:action`, `engine:logs`, `engine:errors`, `engine:models`. Lifecycle ops run for minutes (reporting progress via the `engine:install-progress` / `engine:state-changed` push events), so the relay imposes **no broker-side timeout** — fire the request and watch the event stream for the outcome. Error `-32000 "engine-manager not available"` when no engine-manager is supervised.++`engine:set-port` is **not** in that generic set. Like `proxy:set-port` it is intercepted and run through the authoritative settings operation, so moving an engine's server port from a port-only caller validates and restarts exactly as the full editor does, and persists as a manifest override that survives a restart. Its response is the engine's `engine:status` result.#### `settings/<method>` (generic relay)diff --git a/services/nvpair-ui-broker/advertiser.go b/services/nvpair-ui-broker/advertiser.goindex 0a908ce..05d85fd 100644--- a/services/nvpair-ui-broker/advertiser.go+++ b/services/nvpair-ui-broker/advertiser.go@@ -86,6 +86,8 @@ func (b *Broker) runAutoAdvertise(ctx context.Context) {// /v1/models endpoint (registered separately), which peers fetch during// enrichment.func (b *Broker) reconcileAdvertise(client *http.Client) {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()// During the managed bind -> backend-move transition, engine:status would// probe :11434 and could mistake the proxy (or a remote response forwarded// through it) for an externally started Ollama. Do not query liveness until@@ -152,6 +154,8 @@ func (b *Broker) runAutoAdvertiseLMStudio(ctx context.Context) {// promoted proxy port (never the engine) and hands the engine's loopback port to// the LM Studio proxy via node/set-local-backend.func (b *Broker) reconcileAdvertiseLMStudio(client *http.Client) {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()enginePort, probe := b.localEnginePort("lmstudio", defaultLMStudioPort)proxyPort := b.lmstudioProxyListenPort()if proxyPort != 0 && enginePort == proxyPort {diff --git a/services/nvpair-ui-broker/broker.go b/services/nvpair-ui-broker/broker.goindex 3dcb6f7..c5da7fd 100644--- a/services/nvpair-ui-broker/broker.go+++ b/services/nvpair-ui-broker/broker.go@@ -147,22 +147,36 @@ type ProxyStatusResult struct {// client connection in listen mode so future per-session caches (auth// tokens, watched-resource cursors, etc.) don't bleed across clients.type Broker struct {- codec *Codec- cancel context.CancelFunc- startedAt time.Time- nodeID string- scannerPath string- nodeInfoPath string- proxyPath string- proxyEngines []string- workloadMgrPath string- errorsPath string- engineMgrPath string- manualNodesPath string- settingsPath string- clusterMgrPath string- schedulerPath string- clusterDir string+ // settingsApplyMu serializes engine settings applies end to end, including+ // the engine stop and restart. engineConfigMu guards only the journal and+ // is released while an engine restarts, so this is what keeps two applies —+ // which may compete for the same port — from interleaving. Always take it+ // before engineConfigMu, never the reverse.+ settingsApplyMu sync.Mutex+ engineConfigMu sync.Mutex+ engineSettingsLoaded bool+ engineSettingsError error+ engineSettingsEpoch string+ engineSettings map[string]*engineSettingsRecord+ settingsRelayMu sync.Mutex+ settingsCancels map[string]context.CancelFunc+ activeSettings map[string]activeSettingsOperation+ codec *Codec+ cancel context.CancelFunc+ startedAt time.Time+ nodeID string+ scannerPath string+ nodeInfoPath string+ proxyPath string+ proxyEngines []string+ workloadMgrPath string+ errorsPath string+ engineMgrPath string+ manualNodesPath string+ settingsPath string+ clusterMgrPath string+ schedulerPath string+ clusterDir string// Managed-port state is prepared before proxy startup and read by the proxy// supervisor/reader goroutines. Ollama commits its pending backend move after// its proxy reserves :11434; LM Studio moves through engine-manager first,@@ -505,6 +519,9 @@ func (b *Broker) restoreEnabledEngines(w *rpcWorker) {if w == nil {return}+ // An unreadable journal must not discard the component stores' enabled+ // intent. Recovery logs the failure; restore still uses the saved runtime.+ b.recoverEngineSettings()if err := w.Notify(restoreEnabledEnginesMethod, nil); err != nil {slog.Warn("failed to request enabled-engine restoration", "err", err)}@@ -1447,11 +1464,36 @@ func (b *Broker) pushClusterIdentityToNodeInfo() {// pipeline; the rest of each worker's notification stream is logged and// dropped until its control-plane relay is wired in.func (b *Broker) forwardEngineNotification(method string, params json.RawMessage) {+ if method == "engine:settings-request" {+ b.handleSettingsRelay(params)+ return+ }+ if method == "engine:settings-cancel" {+ var p struct {+ ID string `json:"id"`+ }+ if json.Unmarshal(params, &p) == nil {+ b.settingsRelayMu.Lock()+ cancel := b.settingsCancels[p.ID]+ b.settingsRelayMu.Unlock()+ if cancel != nil {+ cancel()+ }+ }+ return+ }if b.dispatchErrorsNotif("engine-manager", method, params) {return}if method == "engine:ready" {b.reconcileLMStudioProxyAfterEngineManagerReady()+ go func() {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if b.engineSettingsLoaded && b.engineSettingsError == nil && len(b.engineSettings) > 0 {+ b.publishSettingsLocked()+ }+ }()}if method == noderec.MethodSubscribe {// engine-manager subscribes upward for its ec peer set (nodes exposing@@ -2030,6 +2072,7 @@ func (b *Broker) Serve(ctx context.Context) error {// Bound how long a lost terminal event can keep a remote workload displaying// as in-flight. Independent of persistence above: it guards the live set.go b.runStaleWorkloadSweep(ctx)+ go b.refreshEngineSettings(ctx)// The scanner is the broker's core worker. Its supervisor's first// spawn is synchronous so a hard startup failure stays fatal — the@@ -2079,6 +2122,7 @@ func (b *Broker) Serve(ctx context.Context) error {if b.engineMgrSup != nil {defer b.engineMgrSup.Stop()}+ b.migrateLegacyEngineSettings()b.prepareEnabledFacades()// node-info is an auxiliary worker: spawning it lets the broker's own@@ -2371,7 +2415,7 @@ func (b *Broker) forwardProxyNotificationForGeneration(generation uint64, methodCode string `json:"code"`Port int `json:"port"`}- if json.Unmarshal(params, &ep) == nil && ep.Code == "bind-failed" {+ if json.Unmarshal(params, &ep) == nil && ep.Code == "bind-failed" && !b.ollamaState().explicitSettings.Load() {switch {case b.ollamaState().managedFacade.Load() && ep.Port == managedOllamaFacadePort:b.blockManagedOllamaFacade("another process acquired the compatibility port during startup")@@ -3099,6 +3143,8 @@ func (b *Broker) handleMessage(msg *Message) {}switch msg.Method {+ case "engine:get-settings", "engine:preview-settings", "engine:apply-settings":+ go b.handleEngineSettings(msg)case "ping":if err := b.codec.Respond(msg.ID, PingResult{Pong: true,@@ -3187,14 +3233,12 @@ func (b *Broker) handleMessage(msg *Message) {log.Printf("failed to respond to proxy:unsubscribe: %v", err)}+ case "engine:set-port":+ go b.handleSettingsPortRPC(msg, "")case "ollama-proxy:set-port":- // Intercepted rather than relayed verbatim: the broker resolves a- // port conflict against the running engines (engines win, the proxy- // is bumped) before handing the proxy the port to bind.- b.handleProxySetPort(msg)-+ go b.handleSettingsPortRPC(msg, "ollama")case "lmstudio-proxy:set-port":- b.handleLMStudioProxySetPort(msg)+ go b.handleSettingsPortRPC(msg, "lmstudio")case "lmstudio-proxy:get-status":// Answered locally from the lmstudio-proxy handle's captured state,@@ -3275,6 +3319,16 @@ func (b *Broker) handleMessage(msg *Message) {log.Printf("failed to reject private engine method %s: %v", msg.Method, err)}+ // Reached only because the default branch relays every other engine:*+ // method straight to the engine manager. Configuring a launch that way+ // would skip the journal entry, the port reservation, and the proxy+ // rebind that engine:apply-settings owns, leaving the broker's recorded+ // settings describing an engine it no longer matches.+ case "engine:configure-launch":+ if err := b.codec.RespondError(msg.ID, -32601, "use engine:apply-settings for launch configuration"); err != nil {+ log.Printf("failed to reject direct %s: %v", msg.Method, err)+ }+case "engine:subscribe":b.engineMu.Lock()b.engineSubscribed = true@@ -3349,6 +3403,10 @@ func (b *Broker) handleMessage(msg *Message) {// response asynchronously rather than fabricating a timeout — meanwhile// other client requests keep being served on the read-loop goroutine.func (b *Broker) relayToEngine(msg *Message) {+ go b.relayToEngineNow(msg)+}++func (b *Broker) relayToEngineNow(msg *Message) {if needsOllamaPortGate(msg.Method, msg.Params) && b.ollamaFacadeIsPendingBackend() {go func() {select {@@ -3379,6 +3437,11 @@ func (b *Broker) relayToEngine(msg *Message) {}requestedEngine, requestedPort, isEnginePortAssignment := enginePortAssignmentRequest(msg.Method, msg.Params)+ if isEnginePortAssignment || msg.Method == "engine:stop" || msg.Method == "engine:start" || msg.Method == "engine:restart" {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ defer b.reconcileLegacySettingsLocked()+ }isOllamaPortAssignment := isEnginePortAssignment && requestedEngine == "ollama"if isEnginePortAssignment && b.rejectOllamaHostAliasPort(msg, requestedPort, requestedEngine) {return@@ -3408,36 +3471,30 @@ func (b *Broker) relayToEngine(msg *Message) {// read loop allocates a fresh Message per request so these are stable.id := msg.IDmethod := msg.Method- relayErr := em.RelayRequest(method, msg.Params, func(result json.RawMessage, rpcErr *RPCError, err error) {- switch {- case err != nil:- if e := b.codec.RespondError(id, -32000, fmt.Sprintf("engine call failed: %v", err)); e != nil {- log.Printf("failed to relay engine error for %s: %v", method, e)- }- case rpcErr != nil:- if e := b.codec.RespondError(id, rpcErr.Code, rpcErr.Message); e != nil {- log.Printf("failed to relay engine error for %s: %v", method, e)- }- default:- if isOllamaPortAssignment {- var status struct {- Port int `json:"port"`- }- if json.Unmarshal(result, &status) == nil && status.Port > 0 {- b.ollamaState().backendPort.Store(int32(status.Port))- }- }- if isLMStudioSetPort {- b.lmstudioState().backendPort.Store(int32(requestedLMStudioPort))+ result, rpcErr, err := em.CallNoTimeout(context.Background(), method, msg.Params)+ switch {+ case err != nil:+ if e := b.codec.RespondError(id, -32000, fmt.Sprintf("engine call failed: %v", err)); e != nil {+ log.Printf("failed to relay engine error for %s: %v", method, e)+ }+ case rpcErr != nil:+ if e := b.codec.RespondError(id, rpcErr.Code, rpcErr.Message); e != nil {+ log.Printf("failed to relay engine error for %s: %v", method, e)+ }+ default:+ if isOllamaPortAssignment {+ var status struct {+ Port int `json:"port"`}- if e := b.codec.Respond(id, result); e != nil {- log.Printf("failed to relay engine result for %s: %v", method, e)+ if json.Unmarshal(result, &status) == nil && status.Port > 0 {+ b.ollamaState().backendPort.Store(int32(status.Port))}}- })- if relayErr != nil {- if err := b.codec.RespondError(msg.ID, -32000, fmt.Sprintf("engine call failed: %v", relayErr)); err != nil {- log.Printf("failed to respond to %s: %v", msg.Method, err)+ if isLMStudioSetPort {+ b.lmstudioState().backendPort.Store(int32(requestedLMStudioPort))+ }+ if e := b.codec.Respond(id, result); e != nil {+ log.Printf("failed to relay engine result for %s: %v", method, e)}}}diff --git a/services/nvpair-ui-broker/engineproxy.go b/services/nvpair-ui-broker/engineproxy.goindex 17045bd..1254d08 100644--- a/services/nvpair-ui-broker/engineproxy.go+++ b/services/nvpair-ui-broker/engineproxy.go@@ -107,6 +107,10 @@ type engineProxyRuntime struct {// managedFacade reports that the broker is holding this engine's facade// port for its proxy.managedFacade atomic.Bool+ // explicitSettings keeps automatic bind recovery from overriding a saved+ // user choice. The reader must inspect this without taking engineConfigMu,+ // which a settings operation may hold while waiting for the same reader.+ explicitSettings atomic.Bool// backendPort is engine-manager's configured port for the engine itself,// as last observed. Zero means not yet known, which several paths treat@@ -248,7 +252,8 @@ func (b *Broker) enableProxyFacade(parent context.Context, p *proxyProcess, spec}// enableProxyFacadeWithFallback enables a facade, retrying once on a fallback-// port if the first attempt lost a bind race.+// port if the first attempt lost a bind race. An explicit settings choice is+// never moved automatically; its failure is surfaced to the caller.//// Retrying in-process is the point of moving bring-up off argv. A bind failure// used to end the child so the supervisor could respawn it on a corrected port,@@ -266,6 +271,9 @@ func (b *Broker) enableProxyFacadeWithFallback(if err == nil || !stderrors.Is(err, errFacadeBindFailed) {return err}+ if profile, ok := engineProxyProfileFor(spec.Engine); ok && b.engineProxy(profile).explicitSettings.Load() {+ return err+ }// Teardown began between the attempt and the retry: stop here rather than// spending another proxyCallTimeout of the shared budget on a port the// process is about to stop serving anyway.@@ -398,13 +406,6 @@ func (p engineProxyProfile) addressed(method string) string {return engines.AddressMethod(p.Name, method)}-// portBumpedID is the sticky warning surfaced when the broker moves this-// engine's proxy off a port a running engine holds. Sticky (no timestamp-// suffix) so repeated bumps upsert one entry.-func (p engineProxyProfile) portBumpedID() string {- return p.ComponentName() + ":port-bumped"-}-// ownershipBlockedID matches the per-engine constants; see// TestBrokerConstantsMatchTheEngineTable.func (p engineProxyProfile) ownershipBlockedID() string {@@ -430,12 +431,6 @@ func (b *Broker) reportProxyUnavailable(p engineProxyProfile, reason string) {})}-// managedFacade reports whether the broker currently holds this engine's-// facade port for its proxy.-func (b *Broker) managedFacade(p engineProxyProfile) bool {- return b.engineProxy(p).managedFacade.Load()-}-// engineProxyHandle returns the live proxy process for an engine, or nil.func (b *Broker) engineProxyHandle(p engineProxyProfile) *proxyProcess {b.workersMu.Lock()diff --git a/services/nvpair-ui-broker/enginesettings.go b/services/nvpair-ui-broker/enginesettings.gonew file mode 100644index 0000000..9f65e88--- /dev/null+++ b/services/nvpair-ui-broker/enginesettings.go@@ -0,0 +1,742 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "crypto/rand"+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "fmt"+ "os"+ "path/filepath"+ "reflect"+ "strings"+ "time"++ "nvpair-shared/appdir"+ "nvpair-shared/clustertrust"+ settings "nvpair-shared/enginesettings"+ "nvpair-shared/noderec"+)++type settingsReceipt struct {+ Hash string `json:"hash"`+ Revision uint64 `json:"revision"`+ Phase string `json:"phase"`+}+type engineSettingsRecord struct {+ Snapshot settings.Snapshot `json:"snapshot"`+ Previous settings.Config `json:"previous"`+ Resume bool `json:"resume"`+ Explicit bool `json:"explicit"`+ Receipts map[string]settingsReceipt `json:"receipts"`+}+type activeSettingsOperation struct {+ Engine string+ Port int+}++func settingsID() string { var id [16]byte; _, _ = rand.Read(id[:]); return hex.EncodeToString(id[:]) }+func settingsJSON(value any) json.RawMessage { data, _ := json.Marshal(value); return data }++func (b *Broker) engineSettingsPath() (string, error) {+ if base := b.clusterManagerConfigDir(); base != "" {+ return filepath.Join(base, "engine-settings-operations.json"), nil+ }+ return appdir.Path("engine-settings-operations.json")+}++// The journal records accepted desired configuration and operation outcomes.+// Component stores still supply the normal settings baseline. Interrupted or+// failed operations retain the journal's desired values until reconciled.+func (b *Broker) loadEngineSettingsLocked() error {+ if b.engineSettingsLoaded {+ return b.engineSettingsError+ }+ b.engineSettingsLoaded = true+ b.engineSettingsEpoch = settingsID()+ b.engineSettings = make(map[string]*engineSettingsRecord)+ path, err := b.engineSettingsPath()+ if err != nil {+ b.engineSettingsError = err+ return err+ }+ data, err := os.ReadFile(path)+ if os.IsNotExist(err) {+ return nil+ }+ if err == nil {+ err = json.Unmarshal(data, &b.engineSettings)+ }+ if err != nil || b.engineSettings == nil {+ b.engineSettingsError = fmt.Errorf("settings operation journal could not be read; existing settings were preserved")+ return b.engineSettingsError+ }+ for _, record := range b.engineSettings {+ if record == nil {+ b.engineSettingsError = fmt.Errorf("invalid settings journal")+ return b.engineSettingsError+ }+ record.Snapshot.Epoch = b.engineSettingsEpoch+ record.Snapshot.Sequence = 0+ if record.Receipts == nil {+ record.Receipts = make(map[string]settingsReceipt)+ }+ }+ return nil+}++func (b *Broker) saveEngineSettingsLocked() error {+ // Bound recovery metadata. An evicted retry still has its original stale+ // expected revision, so it cannot overwrite a later configuration.+ for _, record := range b.engineSettings {+ for len(record.Receipts) > 256 {+ oldest := ""+ var revision uint64 = ^uint64(0)+ for id, receipt := range record.Receipts {+ if id != record.Snapshot.RequestID && receipt.Phase != "applying" && receipt.Revision <= revision {+ oldest = id+ revision = receipt.Revision+ }+ }+ if oldest == "" {+ break+ }+ delete(record.Receipts, oldest)+ }+ }+ path, err := b.engineSettingsPath()+ if err != nil {+ return err+ }+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {+ return err+ }+ data, err := json.Marshal(b.engineSettings)+ if err != nil {+ return err+ }+ file, err := os.CreateTemp(filepath.Dir(path), ".engine-settings-*")+ if err != nil {+ return err+ }+ tmp := file.Name()+ defer os.Remove(tmp)+ if err = file.Chmod(0o600); err == nil {+ _, err = file.Write(data)+ }+ if err == nil {+ err = file.Sync()+ }+ closeErr := file.Close()+ if err == nil {+ err = closeErr+ }+ if err != nil {+ return err+ }+ return os.Rename(tmp, path)+}++func (b *Broker) settingsWorkerCall(ctx context.Context, method string, params any, target any) error {+ w := b.getEngineMgr()+ if w == nil {+ return fmt.Errorf("engine manager unavailable")+ }+ result, rpcErr, err := w.CallNoTimeout(ctx, method, settingsJSON(params))+ if err != nil {+ return err+ }+ if rpcErr != nil {+ return fmt.Errorf("%s", rpcErr.Message)+ }+ if target != nil {+ return json.Unmarshal(result, target)+ }+ return nil+}++func (b *Broker) settingsProxy(engine string) *proxyProcess {+ if engine == "ollama" {+ return b.getProxy()+ }+ if engine == "lmstudio" {+ return b.getLMStudioProxy()+ }+ return nil+}++func (b *Broker) settingsSnapshotLocked(ctx context.Context, engine string) (settings.Snapshot, error) {+ if engine != "ollama" && engine != "lmstudio" {+ return settings.Snapshot{}, fmt.Errorf("this engine does not support settings")+ }+ if err := b.loadEngineSettingsLocked(); err != nil {+ return settings.Snapshot{}, err+ }+ var launch settings.LaunchState+ if err := b.settingsWorkerCall(ctx, "engine:get-launch", map[string]string{"engine": engine}, &launch); err != nil {+ return settings.Snapshot{}, err+ }+ proxyPort := 0+ ready := false+ if proxy := b.settingsProxy(engine); proxy != nil {+ ready, proxyPort = proxy.Status(engine)+ }+ record := b.engineSettings[engine]+ if err := b.migrateSettingsArgumentsLocked(ctx, engine, record); err != nil {+ return settings.Snapshot{}, err+ }+ configuredProxy := proxyPort+ if !ready && record != nil {+ configuredProxy = record.Snapshot.Settings.ProxyPort+ }+ current := settings.Config{ServerPort: launch.ServerPort, ProxyPort: configuredProxy, LaunchText: launch.LaunchText}+ if record == nil {+ record = &engineSettingsRecord{Snapshot: settings.Snapshot{NodeID: b.nodeID, Engine: engine, Revision: 1, AppliedRevision: 1, Epoch: b.engineSettingsEpoch, Phase: "idle", Settings: current}, Receipts: make(map[string]settingsReceipt)}+ b.engineSettings[engine] = record+ if err := b.saveEngineSettingsLocked(); err != nil {+ delete(b.engineSettings, engine)+ return settings.Snapshot{}, err+ }+ } else if record.Snapshot.Phase != "applying" && record.Snapshot.Phase != "failed" && record.Snapshot.Settings != current {+ record.Snapshot.Settings = current+ record.Snapshot.Revision+++ record.Snapshot.AppliedRevision = record.Snapshot.Revision+ if err := b.saveEngineSettingsLocked(); err != nil {+ return settings.Snapshot{}, err+ }+ }+ snapshot := record.Snapshot+ snapshot.EffectiveServerPort = launch.EffectivePort+ snapshot.EffectiveProxyPort = proxyPort+ snapshot.Running = launch.Running+ snapshot.Adopted = launch.Adopted+ snapshot.Format = launch.Format+ snapshot.Editable = launch.Editable && ready+ snapshot.Reason = launch.Reason+ if !ready {+ snapshot.Reason = "The proxy service is unavailable."+ }+ if snapshot.Phase == "applying" {+ snapshot.Editable = false+ snapshot.Reason = "Settings are being applied."+ }+ if !reflect.DeepEqual(snapshot, record.Snapshot) {+ snapshot.Sequence+++ record.Snapshot = snapshot+ }+ return snapshot, nil+}++func (b *Broker) publishSettingsLocked() {+ all := make([]settings.Snapshot, 0, len(b.engineSettings))+ for _, engine := range []string{"ollama", "lmstudio"} {+ if record := b.engineSettings[engine]; record != nil {+ record.Snapshot.Sequence+++ all = append(all, record.Snapshot)+ if b.codec != nil {+ _ = b.codec.Notify("engine:settings-changed", record.Snapshot)+ }+ }+ }+ if worker := b.getEngineMgr(); worker != nil {+ _ = worker.Notify("engine:settings-projection", all)+ }+}++func (b *Broker) validateSettingsPortsLocked(ctx context.Context, engine string, config settings.Config, current settings.Snapshot) error {+ if config.ServerPort < 1 || config.ServerPort > 65535 || config.ProxyPort < 1 || config.ProxyPort > 65535 {+ return fmt.Errorf("ports must be between 1 and 65535")+ }+ if config.ServerPort == config.ProxyPort {+ return fmt.Errorf("Server port and proxy port collide: both are %d. Choose different ports.", config.ServerPort)+ }+ reserved := map[int]bool{engineManagerHTTPPort: true, engineControlPort: true, nodeInfoHTTPPort: true, errorsHTTPPort: true, workloadHTTPPort: true, clusterManagerHTTPPort: true}+ if alias := b.currentOllamaHostAlias().Port; alias > 0 {+ reserved[alias] = true+ }+ // Include every registered PAIR listener, including services added later.+ if b.regCache != nil {+ for _, service := range b.regCache.Snapshot() {+ if service.Port > 0 && service.Service != noderec.ServiceOllama && service.Service != noderec.ServiceLMStudio {+ reserved[service.Port] = true+ }+ }+ }+ if reserved[config.ServerPort] || reserved[config.ProxyPort] {+ return fmt.Errorf("a selected port is reserved by a PAIR service or proxy alias")+ }+ var installed struct {+ Engines []struct {+ Engine string `json:"engine"`+ Port int `json:"port"`+ } `json:"engines"`+ }+ if err := b.settingsWorkerCall(ctx, "engine:configured-ports", nil, &installed); err != nil {+ return err+ }+ for _, other := range installed.Engines {+ if other.Engine != engine && (other.Port == config.ServerPort || other.Port == config.ProxyPort) {+ return fmt.Errorf("a selected port is reserved by another configured engine")+ }+ }+ for _, other := range []string{"ollama", "lmstudio"} {+ if other == engine {+ continue+ }+ if record := b.engineSettings[other]; record != nil {+ port := record.Snapshot.Settings.ProxyPort+ if port == config.ServerPort || port == config.ProxyPort {+ return fmt.Errorf("a selected port is reserved by another configured proxy")+ }+ }+ if proxy := b.settingsProxy(other); proxy != nil {+ _, port := proxy.Status(other)+ if port == config.ServerPort || port == config.ProxyPort {+ return fmt.Errorf("a selected port is already used by another proxy")+ }+ }+ }+ for _, port := range []int{config.ServerPort, config.ProxyPort} {+ if port == current.EffectiveProxyPort || (current.Running && port == current.EffectiveServerPort) {+ continue+ }+ if !tcpPortAvailable(port) {+ return fmt.Errorf("port %d is already in use", port)+ }+ }+ return nil+}++func (b *Broker) previewSettingsLocked(ctx context.Context, p settings.Request) (settings.Preview, error) {+ current, err := b.settingsSnapshotLocked(ctx, p.Engine)+ if err != nil {+ return settings.Preview{}, err+ }+ if current.Revision != p.ExpectedRevision {+ return settings.Preview{}, fmt.Errorf("settings changed on this device; reload before applying")+ }+ var preview settings.Preview+ if err := b.settingsWorkerCall(ctx, "engine:preview-launch", p, &preview); err != nil {+ return preview, err+ }+ preview.Revision = current.Revision+ preview.Rebind = preview.Settings.ProxyPort != current.EffectiveProxyPort+ if preview.Errors == nil {+ preview.Errors = make(map[string]string)+ }+ if !current.Editable {+ preview.Errors["settings"] = current.Reason+ }+ if len(preview.Errors) == 0 && preview.Conflict == nil {+ if err := b.validateSettingsPortsLocked(ctx, p.Engine, preview.Settings, current); err != nil {+ preview.Errors["ports"] = err.Error()+ }+ }+ return preview, nil+}++// runSettingsOperationLocked applies an already-accepted record. The caller+// holds engineConfigMu; it is released around the engine-manager call, which+// stops and restarts the engine and can run for minutes, and re-acquired to+// record the outcome. Holding the journal lock across that call froze every+// other reader — the other engine's editor, the refresh poller — for the whole+// restart. settingsApplyMu, which the caller also holds, is what keeps a+// second apply out of this window.+func (b *Broker) runSettingsOperationLocked(ctx context.Context, engine string, record *engineSettingsRecord) error {+ if err := b.migrateSettingsArgumentsLocked(ctx, engine, record); err != nil {+ return err+ }+ service := noderec.ServiceOllama+ if engine == "lmstudio" {+ service = noderec.ServiceLMStudio+ }+ if b.regCache != nil {+ b.unregisterService(service)+ }+ b.setProxyLocalBackend(b.settingsProxy(engine), engine, record.Snapshot.EffectiveServerPort, false)+ id := settingsID()+ b.settingsRelayMu.Lock()+ if b.activeSettings == nil {+ b.activeSettings = make(map[string]activeSettingsOperation)+ }+ b.activeSettings[id] = activeSettingsOperation{Engine: engine, Port: record.Snapshot.Settings.ProxyPort}+ b.settingsRelayMu.Unlock()+ defer func() { b.settingsRelayMu.Lock(); delete(b.activeSettings, id); b.settingsRelayMu.Unlock() }()+ configure := settings.Configure{Engine: engine, Settings: record.Snapshot.Settings, OperationID: id, Resume: record.Resume}++ launch, err := func() (settings.LaunchState, error) {+ b.engineConfigMu.Unlock()+ defer b.engineConfigMu.Lock()+ var launch settings.LaunchState+ err := b.settingsWorkerCall(ctx, "engine:configure-launch", configure, &launch)+ if err != nil {+ // A failed RPC carries no result, so read the observed facts back+ // here too and keep the whole worker round trip off the lock.+ launch = settings.LaunchState{}+ _ = b.settingsWorkerCall(ctx, "engine:get-launch", map[string]string{"engine": engine}, &launch)+ }+ return launch, err+ }()++ if err != nil {+ record.Snapshot.Phase = "failed"+ record.Snapshot.Error = err.Error()+ } else {+ record.Snapshot.Phase = "succeeded"+ record.Snapshot.Error = ""+ record.Snapshot.AppliedRevision = record.Snapshot.Revision+ }+ // Refresh observed facts without replacing the accepted desired revision;+ // never publish the pre-operation running state.+ if launch.Engine != "" {+ record.Snapshot.Running = launch.Running+ record.Snapshot.Adopted = launch.Adopted+ record.Snapshot.EffectiveServerPort = launch.EffectivePort+ record.Snapshot.Editable = launch.Editable+ record.Snapshot.Reason = launch.Reason+ if engine == "ollama" {+ b.ollamaState().backendPort.Store(int32(launch.EffectivePort))+ } else {+ b.lmstudioState().backendPort.Store(int32(launch.EffectivePort))+ }+ }+ proxyReady := false+ if proxy := b.settingsProxy(engine); proxy != nil {+ proxyReady, record.Snapshot.EffectiveProxyPort = proxy.Status(engine)+ }+ // An unsuccessful apply can leave the previous engine running. Restore+ // discovery from observed runtime state, independent of the apply result.+ if proxyReady && launch.Running && launch.EffectivePort > 0 && record.Snapshot.EffectiveProxyPort > 0 && launch.EffectivePort != record.Snapshot.EffectiveProxyPort {+ b.setProxyLocalBackend(b.settingsProxy(engine), engine, launch.EffectivePort, true)+ if b.regCache != nil {+ b.registerService(noderec.RegisterParams{Service: service, Port: record.Snapshot.EffectiveProxyPort})+ }+ }+ if err == nil {+ record.Resume = false+ }+ if receipt, exists := record.Receipts[record.Snapshot.RequestID]; exists {+ receipt.Phase = record.Snapshot.Phase+ record.Receipts[record.Snapshot.RequestID] = receipt+ }+ if saveErr := b.saveEngineSettingsLocked(); saveErr != nil {+ record.Snapshot.Phase = "failed"+ record.Snapshot.Error = "The operation result could not be saved. Reload to reconcile the device."+ if receipt, exists := record.Receipts[record.Snapshot.RequestID]; exists {+ receipt.Phase = "failed"+ record.Receipts[record.Snapshot.RequestID] = receipt+ }+ err = saveErr+ }+ b.publishSettingsLocked()+ return err+}++// authorizeSettingsCallerLocked rejects a peer this node no longer pins. A+// local caller passes an empty caller and is always allowed.+func (b *Broker) authorizeSettingsCallerLocked(caller string) error {+ if caller == "" {+ return nil+ }+ if !clustertrust.Open(b.clusterDir).HasPin(caller) {+ return fmt.Errorf("the requesting device is no longer paired")+ }+ return nil+}++// getEngineSettings reads the authoritative snapshot for one engine and+// republishes it, so a reader and every subscriber see the same revision.+func (b *Broker) getEngineSettings(ctx context.Context, p settings.Request, caller string) (settings.Snapshot, error) {+ ctx, cancel := context.WithTimeout(ctx, settings.CallBudget)+ defer cancel()+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if err := ctx.Err(); err != nil {+ return settings.Snapshot{}, err+ }+ if err := b.authorizeSettingsCallerLocked(caller); err != nil {+ return settings.Snapshot{}, err+ }+ snapshot, err := b.settingsSnapshotLocked(ctx, p.Engine)+ if err != nil {+ return settings.Snapshot{}, err+ }+ b.publishSettingsLocked()+ return snapshot, nil+}++// previewEngineSettings validates a proposed change and reports what applying+// it would do, without touching the journal or the engine.+func (b *Broker) previewEngineSettings(ctx context.Context, p settings.Request, caller string) (settings.Preview, error) {+ ctx, cancel := context.WithTimeout(ctx, settings.CallBudget)+ defer cancel()+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if err := ctx.Err(); err != nil {+ return settings.Preview{}, err+ }+ if err := b.authorizeSettingsCallerLocked(caller); err != nil {+ return settings.Preview{}, err+ }+ p.PreserveCORS = caller != ""+ return b.previewSettingsLocked(ctx, p)+}++// applyEngineSettings accepts a change into the journal and then converges the+// engine onto it. RequestID makes it idempotent: replaying one returns the+// original receipt, and reusing it for different settings is refused.+func (b *Broker) applyEngineSettings(ctx context.Context, p settings.Request, caller string) (settingsReceipt, error) {+ ctx, cancel := context.WithTimeout(ctx, settings.CallBudget)+ defer cancel()+ // Serialize whole applies. Taken before engineConfigMu; see its comment.+ b.settingsApplyMu.Lock()+ defer b.settingsApplyMu.Unlock()+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if err := ctx.Err(); err != nil {+ return settingsReceipt{}, err+ }+ if err := b.authorizeSettingsCallerLocked(caller); err != nil {+ return settingsReceipt{}, err+ }+ if p.RequestID == "" || len(p.RequestID) > 128 {+ return settingsReceipt{}, fmt.Errorf("a request identifier is required")+ }+ if err := b.loadEngineSettingsLocked(); err != nil {+ return settingsReceipt{}, err+ }+ fingerprint := sha256.Sum256(settingsJSON(struct {+ Caller string+ Request settings.Request+ }{caller, p}))+ hash := hex.EncodeToString(fingerprint[:])+ if record := b.engineSettings[p.Engine]; record != nil {+ if receipt, exists := record.Receipts[p.RequestID]; exists {+ if receipt.Hash != hash {+ return settingsReceipt{}, fmt.Errorf("request identifier was already used for different settings")+ }+ return receipt, nil+ }+ }+ // Recheck CORS after acquiring the target's apply lock. An HTTP ingress+ // check alone can become stale while another accepted apply is running.+ p.PreserveCORS = caller != ""+ preview, err := b.previewSettingsLocked(ctx, p)+ if err != nil {+ return settingsReceipt{}, err+ }+ if len(preview.Errors) > 0 || preview.Conflict != nil {+ return settingsReceipt{}, fmt.Errorf("resolve settings errors and port conflicts before applying")+ }+ record := b.engineSettings[p.Engine]+ previous := *record+ previous.Receipts = make(map[string]settingsReceipt, len(record.Receipts))+ for k, v := range record.Receipts {+ previous.Receipts[k] = v+ }+ if preview.Settings == record.Snapshot.Settings && record.Snapshot.Phase != "failed" {+ record.Snapshot.RequestID = p.RequestID+ record.Snapshot.Phase = "succeeded"+ record.Receipts[p.RequestID] = settingsReceipt{Hash: hash, Revision: record.Snapshot.Revision, Phase: "succeeded"}+ if err := b.saveEngineSettingsLocked(); err != nil {+ *record = previous+ return settingsReceipt{}, err+ }+ b.publishSettingsLocked()+ return record.Receipts[p.RequestID], nil+ }+ record.Previous = record.Snapshot.Settings+ record.Resume = record.Resume || preview.Restart+ record.Explicit = true+ record.Snapshot.Settings = preview.Settings+ record.Snapshot.Revision+++ record.Snapshot.RequestID = p.RequestID+ record.Snapshot.Phase = "applying"+ record.Snapshot.Error = ""+ record.Receipts[p.RequestID] = settingsReceipt{Hash: hash, Revision: record.Snapshot.Revision, Phase: "applying"}+ if err := b.saveEngineSettingsLocked(); err != nil {+ *record = previous+ return settingsReceipt{}, fmt.Errorf("settings could not be saved; no runtime changes were made")+ }+ b.publishSettingsLocked()+ // Once accepted, completion is target-owned. Losing the requesting UI or+ // peer cannot abandon half a port swap. The operation has its own deadline.+ operationCtx, operationCancel := context.WithTimeout(context.Background(), settings.OperationBudget)+ defer operationCancel()+ _ = b.runSettingsOperationLocked(operationCtx, p.Engine, record)+ return record.Receipts[p.RequestID], nil+}++// dispatchEngineSettings routes an RPC method name to its typed entry point.+// It exists only for the two edges that receive the method as a string — the+// client RPC surface and the peer relay — so no in-process caller has to+// recover a concrete result from an interface.+func (b *Broker) dispatchEngineSettings(ctx context.Context, method string, p settings.Request, caller string) (any, error) {+ switch method {+ case "get":+ return b.getEngineSettings(ctx, p, caller)+ case "preview":+ return b.previewEngineSettings(ctx, p, caller)+ case "apply":+ return b.applyEngineSettings(ctx, p, caller)+ default:+ return nil, fmt.Errorf("unsupported settings method")+ }+}++func (b *Broker) handleEngineSettings(msg *Message) {+ var p settings.Request+ if json.Unmarshal(msg.Params, &p) != nil {+ _ = b.codec.RespondError(msg.ID, -32602, "invalid settings request")+ return+ }+ if p.NodeID != "" && p.NodeID != b.nodeID {+ remote := "engine:remote-" + strings.TrimPrefix(msg.Method, "engine:")+ worker := b.getEngineMgr()+ if worker == nil {+ _ = b.codec.RespondError(msg.ID, -32000, "engine manager unavailable")+ return+ }+ err := worker.RelayRequest(remote, msg.Params, func(result json.RawMessage, rpcErr *RPCError, err error) {+ if err != nil {+ _ = b.codec.RespondError(msg.ID, -32000, err.Error())+ } else if rpcErr != nil {+ _ = b.codec.RespondError(msg.ID, rpcErr.Code, rpcErr.Message)+ } else {+ _ = b.codec.Respond(msg.ID, result)+ }+ })+ if err != nil {+ _ = b.codec.RespondError(msg.ID, -32000, err.Error())+ }+ return+ }+ method := strings.TrimSuffix(strings.TrimPrefix(msg.Method, "engine:"), "-settings")+ result, err := b.dispatchEngineSettings(context.Background(), method, p, "")+ if err != nil {+ _ = b.codec.RespondError(msg.ID, -32000, err.Error())+ } else {+ _ = b.codec.Respond(msg.ID, result)+ }+}++func (b *Broker) handleSettingsRelay(raw json.RawMessage) {+ var relay settings.Relay+ if json.Unmarshal(raw, &relay) != nil {+ return+ }+ worker := b.getEngineMgr()+ if worker == nil {+ return+ }+ ctx, cancel := context.WithTimeout(context.Background(), settings.RelayBudget)+ b.settingsRelayMu.Lock()+ if b.settingsCancels == nil {+ b.settingsCancels = make(map[string]context.CancelFunc)+ }+ if len(b.settingsCancels) >= 128 {+ b.settingsRelayMu.Unlock()+ cancel()+ _ = worker.Notify("engine:settings-reply", map[string]string{"id": relay.ID, "error": "too many settings requests"})+ return+ }+ b.settingsCancels[relay.ID] = cancel+ b.settingsRelayMu.Unlock()+ go func() {+ defer cancel()+ defer func() { b.settingsRelayMu.Lock(); delete(b.settingsCancels, relay.ID); b.settingsRelayMu.Unlock() }()+ var result any+ var err error+ if relay.Method == "rebind" {+ b.settingsRelayMu.Lock()+ operation, ok := b.activeSettings[relay.Request.RequestID]+ b.settingsRelayMu.Unlock()+ if !ok || operation.Engine != relay.Request.Engine || operation.Port != relay.Request.Settings.ProxyPort {+ err = fmt.Errorf("unknown settings operation")+ } else {+ err = b.rebindSettingsProxy(operation.Engine, operation.Port)+ }+ } else {+ result, err = b.dispatchEngineSettings(ctx, relay.Method, relay.Request, relay.Caller)+ }+ reply := struct {+ ID string `json:"id"`+ Result any `json:"result"`+ Error string `json:"error,omitempty"`+ }{ID: relay.ID, Result: result}+ if err != nil {+ reply.Error = err.Error()+ }+ _ = worker.Notify("engine:settings-reply", reply)+ }()+}++func (b *Broker) rebindSettingsProxy(engine string, port int) error {+ p := b.settingsProxy(engine)+ if p == nil {+ return fmt.Errorf("proxy unavailable")+ }+ // Disable automatic facade takeover before the ready event can race the+ // explicit rebind. The accepted journal restores these choices after restart.+ profile, _ := engineProxyProfileFor(engine)+ b.engineProxy(profile).explicitSettings.Store(true)+ if engine == "ollama" {+ b.ollamaState().managedFacade.Store(false)+ } else {+ b.lmstudioState().managedFacade.Store(false)+ }+ _, rpcErr, err := p.Call(context.Background(), engine+":set-port", settingsJSON(map[string]int{"port": port}))+ if err != nil {+ return err+ }+ if rpcErr != nil {+ return fmt.Errorf("%s", rpcErr.Message)+ }+ if engine == "ollama" {+ b.ollamaState().managedFacade.Store(false)+ b.ollamaState().startupPort.Store(int32(port))+ } else {+ b.lmstudioState().managedFacade.Store(false)+ b.lmstudioState().startupPort.Store(int32(port))+ }+ return nil+}++func (b *Broker) refreshEngineSettings(ctx context.Context) {+ ticker := time.NewTicker(2 * time.Second)+ defer ticker.Stop()+ for {+ select {+ case <-ctx.Done():+ return+ case <-ticker.C:+ if !b.managedPortOwnershipReady() {+ continue+ }+ func() {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ readCtx, cancel := context.WithTimeout(ctx, 5*time.Second)+ defer cancel()+ changed := false+ for _, engine := range []string{"ollama", "lmstudio"} {+ var before settings.Snapshot+ if r := b.engineSettings[engine]; r != nil {+ before = r.Snapshot+ }+ after, err := b.settingsSnapshotLocked(readCtx, engine)+ if err == nil && before != after {+ changed = true+ }+ }+ if changed {+ b.publishSettingsLocked()+ }+ }()+ }+ }+}diff --git a/services/nvpair-ui-broker/enginesettings_recovery.go b/services/nvpair-ui-broker/enginesettings_recovery.gonew file mode 100644index 0000000..ec444c3--- /dev/null+++ b/services/nvpair-ui-broker/enginesettings_recovery.go@@ -0,0 +1,193 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "fmt"+ "log/slog"+ "os"+ "path/filepath"+ "time"++ settings "nvpair-shared/enginesettings"+)++// Convert pending/failed full-command settings before replay, preserving the+// accepted arguments and proxy port. Component launch_args/launch_env need no+// migration because they have always stored only literal user overrides.+func (b *Broker) migrateSettingsArgumentsLocked(ctx context.Context, engine string, record *engineSettingsRecord) error {+ if record == nil || record.Snapshot.Format != "pair-launch-v1" {+ return nil+ }+ var preview settings.Preview+ if err := b.settingsWorkerCall(ctx, "engine:preview-launch", settings.Request{+ Engine: engine, Settings: record.Snapshot.Settings, Format: "pair-launch-v1",+ }, &preview); err != nil {+ return err+ }+ if len(preview.Errors) != 0 || preview.Conflict != nil {+ return fmt.Errorf("saved full-command settings could not be converted; existing settings were preserved")+ }+ previous := record.Snapshot+ record.Snapshot.Settings = preview.Settings+ record.Snapshot.Format = "pair-arguments-v1"+ record.Snapshot.Revision+++ if previous.AppliedRevision == previous.Revision {+ record.Snapshot.AppliedRevision = record.Snapshot.Revision+ }+ if err := b.saveEngineSettingsLocked(); err != nil {+ record.Snapshot = previous+ return err+ }+ return nil+}++func (b *Broker) explicitEngineSettings(engine string) (settings.Config, bool) {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ return b.explicitEngineSettingsLocked(engine)+}++func (b *Broker) explicitEngineSettingsLocked(engine string) (settings.Config, bool) {+ if err := b.loadEngineSettingsLocked(); err != nil {+ return settings.Config{}, false+ }+ if record := b.engineSettings[engine]; record != nil && record.Explicit {+ return record.Snapshot.Settings, true+ }+ return settings.Config{}, false+}++func (b *Broker) prepareExplicitEngineSettings(engine string) bool {+ b.engineConfigMu.Lock()+ loadErr := b.loadEngineSettingsLocked()+ b.engineConfigMu.Unlock()+ if loadErr != nil {+ return true+ } // preserve component stores; recovery reports the journal error+ config, ok := b.explicitEngineSettings(engine)+ if !ok {+ return false+ }+ profile, _ := engineProxyProfileFor(engine)+ b.engineProxy(profile).explicitSettings.Store(true)+ if engine == "ollama" {+ b.ollamaState().managedFacade.Store(false)+ b.managedOllamaBackend.Store(0)+ b.ollamaState().backendPort.Store(int32(config.ServerPort))+ b.ollamaState().startupPort.Store(int32(config.ProxyPort))+ b.syncCurrentEngineOllamaHostAliasReservation()+ } else {+ b.lmstudioState().managedFacade.Store(false)+ b.lmstudioState().backendPort.Store(int32(config.ServerPort))+ b.lmstudioState().startupPort.Store(int32(config.ProxyPort))+ }+ return true+}++// Legacy proxy stores did not distinguish user choices from automatic moves.+// Preserve a valid non-colliding saved choice as explicit on first upgrade.+// LM Studio's old 1235 default is excluded, matching its existing migration.+func (b *Broker) migrateLegacyEngineSettings() {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if b.loadEngineSettingsLocked() != nil || b.getEngineMgr() == nil {+ return+ }+ journal, err := b.engineSettingsPath()+ if err != nil {+ return+ }+ for _, engine := range []string{"ollama", "lmstudio"} {+ name := "proxy-port.json"+ if engine == "lmstudio" {+ name = "lmstudio-proxy-port.json"+ }+ if b.engineSettings[engine] != nil {+ continue+ }+ data, err := os.ReadFile(filepath.Join(filepath.Dir(journal), name))+ if err != nil {+ continue+ }+ var saved struct {+ Port int `json:"port"`+ }+ if json.Unmarshal(data, &saved) != nil || saved.Port < 1 || saved.Port > 65535 || (engine == "lmstudio" && saved.Port == 1235) {+ continue+ }+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)+ _ = b.settingsWorkerCall(ctx, "engine:status", map[string]string{"engine": engine}, nil)+ var launch settings.LaunchState+ err = b.settingsWorkerCall(ctx, "engine:get-launch", map[string]string{"engine": engine}, &launch)+ if err != nil || !launch.Editable || launch.ServerPort == saved.Port {+ cancel()+ continue+ }+ config := settings.Config{ServerPort: launch.ServerPort, ProxyPort: saved.Port, LaunchText: launch.LaunchText}+ current := settings.Snapshot{Running: launch.Running, EffectiveServerPort: launch.EffectivePort}+ if proxy := b.settingsProxy(engine); proxy != nil {+ _, current.EffectiveProxyPort = proxy.Status(engine)+ }+ err = b.validateSettingsPortsLocked(ctx, engine, config, current)+ cancel()+ if err != nil {+ continue+ }+ b.engineSettings[engine] = &engineSettingsRecord{Explicit: true, Receipts: map[string]settingsReceipt{}, Snapshot: settings.Snapshot{NodeID: b.nodeID, Engine: engine, Revision: 1, AppliedRevision: 1, Epoch: b.engineSettingsEpoch, Phase: "idle", Settings: settings.Config{ServerPort: launch.ServerPort, ProxyPort: saved.Port, LaunchText: launch.LaunchText}}}+ if err := b.saveEngineSettingsLocked(); err != nil {+ delete(b.engineSettings, engine)+ b.engineSettingsError = err+ return+ }+ }+}++// Replay accepted operations before automatic engine startup. Component stores+// can be at any phase after a crash; configure revalidates and converges them+// under the same engine lock used by a live Apply, then records its outcome.+func (b *Broker) recoverEngineSettings() bool {+ // Same order a live Apply uses: the operation lock, then the journal lock+ // that runSettingsOperationLocked releases around the engine restart.+ b.settingsApplyMu.Lock()+ defer b.settingsApplyMu.Unlock()+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if err := b.loadEngineSettingsLocked(); err != nil {+ slog.Error("engine settings recovery blocked", "err", err)+ return false+ }+ for engine, record := range b.engineSettings {+ if record.Snapshot.Phase != "applying" {+ continue+ }+ ctx, cancel := context.WithTimeout(context.Background(), settings.OperationBudget)+ _ = b.runSettingsOperationLocked(ctx, engine, record)+ cancel()+ }+ return true+}++// Legacy lifecycle/port RPCs share the node lock. Reconcile their component+// changes into the same revision stream before allowing another Apply.+func (b *Broker) reconcileLegacySettingsLocked() {+ if !b.engineSettingsLoaded || b.engineSettingsError != nil {+ return+ }+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)+ defer cancel()+ changed := false+ for engine, record := range b.engineSettings {+ before := record.Snapshot+ after, err := b.settingsSnapshotLocked(ctx, engine)+ if err == nil && before != after {+ changed = true+ }+ }+ if changed {+ b.publishSettingsLocked()+ }+}diff --git a/services/nvpair-ui-broker/enginesettings_review_test.go b/services/nvpair-ui-broker/enginesettings_review_test.gonew file mode 100644index 0000000..50cb11b--- /dev/null+++ b/services/nvpair-ui-broker/enginesettings_review_test.go@@ -0,0 +1,225 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bytes"+ "context"+ "encoding/json"+ "net"+ "os"+ "path/filepath"+ "testing"+ "time"++ settings "nvpair-shared/enginesettings"+)++func TestSettingsRebindAddressesOnlyRequestedFacade(t *testing.T) {+ for _, profile := range engineProxyProfiles {+ t.Run(profile.Name, func(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.b.getProxy()+ _, ollamaBefore := p.Status("ollama")+ _, lmstudioBefore := p.Status("lmstudio")+ ln, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatal(err)+ }+ port := ln.Addr().(*net.TCPAddr).Port+ _ = ln.Close()+ if err := h.b.rebindSettingsProxy(profile.Name, port); err != nil {+ t.Fatal(err)+ }+ wantOllama, wantLMStudio := ollamaBefore, lmstudioBefore+ if profile.Name == "ollama" {+ wantOllama = port+ } else {+ wantLMStudio = port+ }+ for engine, want := range map[string]int{"ollama": wantOllama, "lmstudio": wantLMStudio} {+ ready, got := p.Status(engine)+ if !ready || got != want {+ t.Fatalf("%s ready=%v port=%d, want %d", engine, ready, got, want)+ }+ }+ })+ }+}++func TestExplicitSettingsBindFailurePreservesChosenPort(t *testing.T) {+ for _, profile := range engineProxyProfiles {+ t.Run(profile.Name, func(t *testing.T) {+ const requested = 25000+ b := &Broker{codec: NewCodec(&bytes.Buffer{}), engineSettingsLoaded: true,+ engineSettings: map[string]*engineSettingsRecord{profile.Name: {+ Explicit: true, Snapshot: settings.Snapshot{Settings: settings.Config{ServerPort: 24999, ProxyPort: requested}},+ }},+ }+ if !b.prepareExplicitEngineSettings(profile.Name) {+ t.Fatal("explicit settings were not restored")+ }+ failure := settingsJSON(map[string]any{"code": "bind-failed", "port": requested})+ if profile.Name == "ollama" {+ b.forwardProxyNotification("error", failure)+ } else {+ b.forwardLMStudioProxyNotification("error", failure)+ }+ if got := b.engineProxy(profile).startupPort.Load(); got != requested {+ t.Fatalf("bind notification changed chosen port to %d", got)+ }+ client, server := net.Pipe()+ t.Cleanup(func() { _ = client.Close(); _ = server.Close() })+ p := &proxyProcess{peer: NewPeer(NewCodec(client))}+ go p.peer.Serve(nil, nil)+ attempts := make(chan enableFacadeRequest, 2)+ serveFacadeEnable(t, server, map[int]bool{requested: true}, attempts)+ err := b.enableProxyFacadeWithFallback(context.Background(), p, enableFacadeRequest{Engine: profile.Name, Port: requested}, func(int) int {+ t.Error("explicit port must not fall back")+ return requested + 1+ })+ if err == nil {+ t.Fatal("bind failure was hidden")+ }+ if len(attempts) != 1 {+ t.Fatalf("attempts=%d, want only the chosen port", len(attempts))+ }+ })+ }+}++func TestSettingsReservesStoppedProxySavedPort(t *testing.T) {+ test := func(name string, serverPort bool) {+ t.Run(name, func(t *testing.T) {+ h := newSettingsHarness(t)+ request := h.request(t)+ _, reserved := h.b.getLMStudioProxy().Status("lmstudio")+ h.b.setLMStudioProxy(nil)+ h.b.engineSettings["lmstudio"] = &engineSettingsRecord{+ Explicit: true,+ Snapshot: settings.Snapshot{Settings: settings.Config{ProxyPort: reserved}},+ }+ if serverPort {+ request.Settings.ServerPort = reserved+ } else {+ request.Settings.ProxyPort = reserved+ }+ preview, err := h.b.previewEngineSettings(context.Background(), request, "")+ if err != nil {+ t.Fatal(err)+ }+ if len(preview.Errors) == 0 {+ t.Fatalf("accepted stopped proxy's saved port: %+v", preview)+ }+ })+ }+ test("server port cannot reuse saved proxy port", true)+ test("proxy port cannot reuse saved proxy port", false)+}++func TestSettingsMigrationRejectsReservedPorts(t *testing.T) {+ test := func(name string, reserve func(*settingsHarness, settings.Request) int) {+ t.Run(name, func(t *testing.T) {+ h := newSettingsHarness(t)+ request := h.request(t)+ delete(h.b.engineSettings, "ollama")+ port := reserve(h, request)+ path, err := h.b.engineSettingsPath()+ if err != nil {+ t.Fatal(err)+ }+ data, err := json.Marshal(map[string]int{"port": port})+ if err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(filepath.Dir(path), "proxy-port.json"), data, 0600); err != nil {+ t.Fatal(err)+ }+ h.b.migrateLegacyEngineSettings()+ if _, explicit := h.b.explicitEngineSettings("ollama"); explicit {+ t.Fatal("reserved legacy port became an explicit setting")+ }+ })+ }+ test("PAIR control port", func(h *settingsHarness, request settings.Request) int {+ return engineControlPort+ })+ test("inherited Ollama host alias", func(h *settingsHarness, request settings.Request) int {+ h.b.ollamaHostAliasMu.Lock()+ h.b.ollamaHostAlias.Port = request.Settings.ProxyPort+ h.b.ollamaHostAliasMu.Unlock()+ return request.Settings.ProxyPort+ })+ test("stopped proxy saved port", func(h *settingsHarness, request settings.Request) int {+ _, port := h.b.getLMStudioProxy().Status("lmstudio")+ h.b.setLMStudioProxy(nil)+ h.b.engineSettings["lmstudio"] = &engineSettingsRecord{+ Explicit: true,+ Snapshot: settings.Snapshot{Settings: settings.Config{ProxyPort: port}},+ }+ return port+ })+}++func TestEnabledEngineRestorationSurvivesInvalidSettingsJournal(t *testing.T) {+ b := &Broker{clusterDir: filepath.Join(t.TempDir(), "cluster")}+ path, err := b.engineSettingsPath()+ if err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(path, []byte("{invalid"), 0600); err != nil {+ t.Fatal(err)+ }+ worker, codec := newTestRPCWorkerPipe(t)+ restored := make(chan string, 1)+ go func() {+ msg, err := codec.Read()+ if err != nil {+ t.Error(err)+ return+ }+ restored <- msg.Method+ }()+ b.restoreEnabledEngines(worker)+ select {+ case method := <-restored:+ if method != restoreEnabledEnginesMethod {+ t.Fatalf("method=%q", method)+ }+ case <-time.After(time.Second):+ t.Fatal("invalid journal suppressed enabled-engine restoration")+ }+ if b.engineSettingsError == nil {+ t.Fatal("invalid journal was not reported")+ }+}++func TestSettingsFullCommandJournalMigratesBeforeRecovery(t *testing.T) {+ h := newSettingsHarness(t)+ request := h.request(t)+ h.b.engineConfigMu.Lock()+ record := h.b.engineSettings["ollama"]+ record.Snapshot.Format = "pair-launch-v1"+ record.Snapshot.Settings.LaunchText = "managed serve --fixture-option --future-option"+ record.Snapshot.Phase = "applying"+ record.Resume = true+ oldProxyPort := record.Snapshot.Settings.ProxyPort+ if err := h.b.saveEngineSettingsLocked(); err != nil {+ t.Fatal(err)+ }+ h.b.engineConfigMu.Unlock()+ if !h.b.recoverEngineSettings() {+ t.Fatal("recovery failed")+ }+ snapshot, err := h.b.getEngineSettings(context.Background(), settings.Request{Engine: "ollama"}, "")+ if err != nil {+ t.Fatal(err)+ }+ if snapshot.Format != "pair-arguments-v1" || snapshot.Phase != "succeeded" || snapshot.Settings.LaunchText != "--fixture-option --future-option" || snapshot.Settings.ProxyPort != oldProxyPort || snapshot.Settings.ServerPort != request.Settings.ServerPort {+ t.Fatalf("migration lost accepted configuration: %+v", snapshot)+ }+ if h.applies.Load() != 1 {+ t.Fatal("pending operation was not applied exactly once")+ }+}diff --git a/services/nvpair-ui-broker/enginesettings_security_test.go b/services/nvpair-ui-broker/enginesettings_security_test.gonew file mode 100644index 0000000..ed2eec6--- /dev/null+++ b/services/nvpair-ui-broker/enginesettings_security_test.go@@ -0,0 +1,65 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "crypto/ed25519"+ "crypto/rand"+ "crypto/x509"+ "encoding/pem"+ "math/big"+ "net/url"+ "os"+ "path/filepath"+ "testing"+ "time"+)++func TestSettingsDerivesCORSGuardFromAuthenticatedCaller(t *testing.T) {+ h := newSettingsHarness(t)+ pub, key, err := ed25519.GenerateKey(rand.Reader)+ if err != nil {+ t.Fatal(err)+ }+ uri, _ := url.Parse("urn:nvpair:node:paired-caller")+ cert := &x509.Certificate{SerialNumber: big.NewInt(1), URIs: []*url.URL{uri}, NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour)}+ der, err := x509.CreateCertificate(rand.Reader, cert, cert, pub, key)+ if err != nil {+ t.Fatal(err)+ }+ keyDER, err := x509.MarshalPKCS8PrivateKey(key)+ if err != nil {+ t.Fatal(err)+ }+ if err := os.MkdirAll(h.b.clusterDir, 0700); err != nil {+ t.Fatal(err)+ }+ for name, data := range map[string][]byte{+ "node.crt": pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}),+ "node.key": pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER}),+ "admission.json": []byte(`{"clusterId":"test","epoch":1}`),+ } {+ if err := os.WriteFile(filepath.Join(h.b.clusterDir, name), data, 0600); err != nil {+ t.Fatal(err)+ }+ }+ for _, caller := range []string{"", "paired-caller"} {+ request := h.request(t)+ // Deliberately supply the opposite of what the authenticated caller needs.+ request.PreserveCORS = caller == ""+ if _, err := h.b.previewEngineSettings(context.Background(), request, caller); err != nil {+ t.Fatal(err)+ }+ if h.previewPreserveCORS.Load() != (caller != "") {+ t.Fatal("preview trusted client-supplied guard")+ }+ if _, err := h.b.applyEngineSettings(context.Background(), request, caller); err != nil {+ t.Fatal(err)+ }+ if h.previewPreserveCORS.Load() != (caller != "") {+ t.Fatal("apply trusted client-supplied guard")+ }+ }+}diff --git a/services/nvpair-ui-broker/enginesettings_test.go b/services/nvpair-ui-broker/enginesettings_test.gonew file mode 100644index 0000000..e8d487b--- /dev/null+++ b/services/nvpair-ui-broker/enginesettings_test.go@@ -0,0 +1,439 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "bytes"+ "context"+ "encoding/json"+ "net"+ "os"+ "path/filepath"+ "strings"+ "sync"+ "sync/atomic"+ "testing"+ "time"++ settings "nvpair-shared/enginesettings"+ "nvpair-shared/noderec"+ "nvpair-ui-broker/relay"+)++type settingsHarness struct {+ b *Broker+ applies atomic.Int32+ fail atomic.Bool+ failBeforeStop atomic.Bool+ loseProxyOnStop atomic.Bool+ failResultSave atomic.Bool+ otherEnginePort atomic.Int32+ previewPreserveCORS atomic.Bool+ entered, release chan struct{}+ // launchMu guards the fixture's launch state, which a suspended+ // engine:configure-launch mutates while the reader loop keeps serving.+ launchMu sync.Mutex+}++func newSettingsHarness(t *testing.T) *settingsHarness {+ t.Helper()+ ports := make([]int, 3)+ listeners := []net.Listener{}+ for i := range ports {+ ln, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ t.Fatal(err)+ }+ listeners = append(listeners, ln)+ ports[i] = ln.Addr().(*net.TCPAddr).Port+ }+ for _, ln := range listeners {+ _ = ln.Close()+ }+ h := &settingsHarness{b: &Broker{codec: NewCodec(&bytes.Buffer{}), nodeID: "target", clusterDir: filepath.Join(t.TempDir(), "cluster")}}+ worker, codec := newTestRPCWorkerPipe(t)+ h.b.setEngineMgr(worker)+ proxyWorker, proxyCodec := newTestRPCWorkerPipe(t)+ proxy := &proxyProcess{peer: proxyWorker.peer, facadeState: map[string]proxyFacadeState{+ "ollama": {ready: true, port: ports[1]},+ "lmstudio": {ready: true, port: ports[2]},+ }}+ h.b.setProxy(proxy)+ h.b.setLMStudioProxy(proxy)+ go func() {+ for {+ msg, err := proxyCodec.Read()+ if err != nil {+ return+ }+ if !msg.IsRequest() {+ continue+ }+ if msg.Method != "ollama:set-port" && msg.Method != "lmstudio:set-port" {+ _ = proxyCodec.Respond(msg.ID, map[string]bool{"ok": true})+ continue+ }+ var p struct {+ Port int `json:"port"`+ }+ _ = json.Unmarshal(msg.Params, &p)+ proxy.readyMu.Lock()+ engine := "ollama"+ if msg.Method == "lmstudio:set-port" {+ engine = "lmstudio"+ }+ proxy.facadeState[engine] = proxyFacadeState{ready: true, port: p.Port}+ proxy.readyMu.Unlock()+ _ = proxyCodec.Respond(msg.ID, map[string]int{"port": p.Port})+ }+ }()+ launch := settings.LaunchState{Engine: "ollama", ServerPort: ports[0], EffectivePort: ports[0], LaunchText: "--fixture-option", Running: true, Editable: true, Format: "pair-arguments-v1"}+ go func() {+ for {+ msg, err := codec.Read()+ if err != nil {+ return+ }+ if !msg.IsRequest() {+ continue+ }+ switch msg.Method {+ case "engine:get-launch":+ h.launchMu.Lock()+ current := launch+ h.launchMu.Unlock()+ _ = codec.Respond(msg.ID, current)+ case "engine:configured-ports":+ _ = codec.Respond(msg.ID, map[string]any{"engines": []any{map[string]any{"engine": "lmstudio", "port": h.otherEnginePort.Load()}}})+ case "engine:preview-launch":+ var p settings.Request+ _ = json.Unmarshal(msg.Params, &p)+ h.previewPreserveCORS.Store(p.PreserveCORS)+ if p.Format == "pair-launch-v1" {+ p.Settings.LaunchText = strings.TrimPrefix(p.Settings.LaunchText, "managed serve ")+ }+ h.launchMu.Lock()+ restart := launch.Running && (p.Settings.ServerPort != launch.ServerPort || p.Settings.LaunchText != launch.LaunchText)+ h.launchMu.Unlock()+ _ = codec.Respond(msg.ID, settings.Preview{Settings: p.Settings, Restart: restart})+ case "engine:configure-launch":+ // Serve this off the reader loop: a suspended apply must not+ // stop the fixture from answering an unrelated read, which is+ // exactly what the broker's lock split makes possible.+ go func(msg *Message) {+ h.applies.Add(1)+ if h.entered != nil {+ h.entered <- struct{}{}+ <-h.release+ }+ if h.failBeforeStop.Load() {+ if h.loseProxyOnStop.Load() {+ proxy.readyMu.Lock()+ state := proxy.facadeState["ollama"]+ state.ready = false+ proxy.facadeState["ollama"] = state+ proxy.readyMu.Unlock()+ }+ _ = codec.RespondError(msg.ID, -32000, "stop failure")+ return+ }+ var p settings.Configure+ _ = json.Unmarshal(msg.Params, &p)+ h.launchMu.Lock()+ launch.ServerPort = p.Settings.ServerPort+ launch.LaunchText = p.Settings.LaunchText+ launch.Running = false+ h.launchMu.Unlock()+ if err := h.b.rebindSettingsProxy(p.Engine, p.Settings.ProxyPort); err != nil {+ _ = codec.RespondError(msg.ID, -32000, err.Error())+ return+ }+ if h.fail.Load() {+ _ = codec.RespondError(msg.ID, -32000, "startup failure")+ return+ }+ h.launchMu.Lock()+ launch.EffectivePort = p.Settings.ServerPort+ launch.Running = p.Resume+ current := launch+ h.launchMu.Unlock()+ if h.failResultSave.Load() {+ journal, _ := h.b.engineSettingsPath()+ if err := os.Remove(journal); err != nil {+ t.Error(err)+ }+ if err := os.Mkdir(journal, 0700); err != nil {+ t.Error(err)+ }+ }+ _ = codec.Respond(msg.ID, current)+ }(msg)+ default:+ _ = codec.RespondError(msg.ID, -32601, "unsupported fixture method")+ }+ }+ }()+ return h+}++func (h *settingsHarness) request(t *testing.T) settings.Request {+ t.Helper()+ s, err := h.b.getEngineSettings(context.Background(), settings.Request{Engine: "ollama"}, "")+ if err != nil {+ t.Fatal(err)+ }+ return settings.Request{Engine: "ollama", ExpectedRevision: s.Revision, RequestID: settingsID(), Settings: s.Settings}+}++func TestSettingsCoordinatorRevisionDedupNoopAndFailure(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ receipt, err := h.b.applyEngineSettings(context.Background(), p, "")+ if err != nil {+ t.Fatal(err)+ }+ if h.applies.Load() != 0 || receipt.Phase != "succeeded" {+ t.Fatal("no-op mutated runtime")+ }+ p = h.request(t)+ p.Settings.LaunchText += " --parallel 2"+ receipt, err = h.b.applyEngineSettings(context.Background(), p, "")+ if err != nil {+ t.Fatal(err)+ }+ if receipt.Revision != p.ExpectedRevision+1 || receipt.Phase != "succeeded" || h.applies.Load() != 1 {+ t.Fatalf("receipt=%+v applies=%d", receipt, h.applies.Load())+ }+ if _, err = h.b.applyEngineSettings(context.Background(), p, ""); err != nil || h.applies.Load() != 1 {+ t.Fatal("duplicate restarted")+ }+ reused := p+ reused.Settings.LaunchText += " --different"+ if _, err = h.b.applyEngineSettings(context.Background(), reused, ""); err == nil {+ t.Fatal("reused identifier accepted")+ }+ p.RequestID = settingsID()+ if _, err = h.b.applyEngineSettings(context.Background(), p, ""); err == nil {+ t.Fatal("stale revision accepted")+ }+ p = h.request(t)+ p.Settings.LaunchText += " --invalid"+ h.fail.Store(true)+ receipt, err = h.b.applyEngineSettings(context.Background(), p, "")+ if err != nil || receipt.Phase != "failed" {+ t.Fatalf("failure receipt %+v %v", receipt, err)+ }+ s := h.b.engineSettings["ollama"].Snapshot+ if s.Settings != p.Settings || s.Running || s.AppliedRevision >= s.Revision || s.Error == "" {+ t.Fatalf("untruthful failed snapshot: %+v", s)+ }+ h.fail.Store(false)+ p = h.request(t)+ if _, err = h.b.applyEngineSettings(context.Background(), p, ""); err != nil {+ t.Fatal(err)+ }+ if s := h.b.engineSettings["ollama"].Snapshot; !s.Running || s.Phase != "succeeded" {+ t.Fatalf("retry lost resume intent: %+v", s)+ }+}++func TestSettingsFailedApplyRestoresOnlyRunningReadyService(t *testing.T) {+ for _, tc := range []struct {+ name string+ stopFails bool+ proxyReady bool+ advertised bool+ }{+ {"stop failed with engine still running", true, true, true},+ {"engine stopped before startup failed", false, true, false},+ {"proxy unavailable", true, false, false},+ } {+ t.Run(tc.name, func(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ oldPort := p.Settings.ProxyPort+ h.b.regCache = relay.NewRegistrationCache()+ h.b.registerService(noderec.RegisterParams{Service: noderec.ServiceOllama, Port: oldPort})+ h.failBeforeStop.Store(tc.stopFails)+ h.fail.Store(true)+ h.loseProxyOnStop.Store(!tc.proxyReady)+ p.Settings.LaunchText += " --new-option"+ receipt, err := h.b.applyEngineSettings(context.Background(), p, "")+ if err != nil || receipt.Phase != "failed" {+ t.Fatalf("expected failed receipt, got %+v, %v", receipt, err)+ }+ registered := h.b.regCache.Snapshot()+ if tc.advertised {+ if len(registered) != 1 || registered[0].Service != noderec.ServiceOllama || registered[0].Port != oldPort {+ t.Fatalf("running engine lost registration: %+v", registered)+ }+ } else if len(registered) != 0 {+ t.Fatalf("unavailable service advertised: %+v", registered)+ }+ })+ }+}++func TestSettingsCoordinatorSerializesAndCancelsQueuedRequests(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ p.Settings.LaunchText += " --first"+ h.entered = make(chan struct{}, 1)+ h.release = make(chan struct{})+ done := make(chan error, 1)+ go func() { _, err := h.b.applyEngineSettings(context.Background(), p, ""); done <- err }()+ <-h.entered+ ctx, cancel := context.WithCancel(context.Background())+ cancel()+ other := p+ other.RequestID = settingsID()+ canceled := make(chan error, 1)+ go func() { _, err := h.b.applyEngineSettings(ctx, other, ""); canceled <- err }()+ close(h.release)+ if err := <-done; err != nil {+ t.Fatal(err)+ }+ if err := <-canceled; err == nil {+ t.Fatal("canceled queued mutation accepted")+ }+ if h.applies.Load() != 1 {+ t.Fatal("concurrent request mutated runtime")+ }+}++// An apply stops and restarts an engine, which can run for minutes. Holding the+// journal lock across that froze the other engine's editor and the refresh+// poller for the whole restart.+func TestSettingsApplyDoesNotBlockUnrelatedReads(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ p.Settings.LaunchText += " --busy"+ h.entered = make(chan struct{}, 1)+ h.release = make(chan struct{})+ done := make(chan error, 1)+ go func() { _, err := h.b.applyEngineSettings(context.Background(), p, ""); done <- err }()+ <-h.entered++ read := make(chan error, 1)+ go func() {+ _, err := h.b.getEngineSettings(context.Background(), settings.Request{Engine: "lmstudio"}, "")+ read <- err+ }()+ select {+ case err := <-read:+ if err != nil {+ t.Fatalf("read during an in-flight apply failed: %v", err)+ }+ case <-time.After(10 * time.Second):+ t.Fatal("engine settings read blocked behind an in-flight apply")+ }++ close(h.release)+ if err := <-done; err != nil {+ t.Fatal(err)+ }+}++func TestSettingsResultPersistenceFailureReturnsFailedReceipt(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ p.Settings.LaunchText += " --new"+ h.failResultSave.Store(true)+ receipt, err := h.b.applyEngineSettings(context.Background(), p, "")+ if err != nil || receipt.Phase != "failed" || h.b.engineSettings["ollama"].Snapshot.Phase != "failed" {+ t.Fatalf("result persistence failure claimed success: %+v %v", receipt, err)+ }+}++func TestSettingsJournalFailureAndInterruptedRecovery(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ p.Settings.LaunchText += " --new"+ path, _ := h.b.engineSettingsPath()+ if err := os.Remove(path); err != nil {+ t.Fatal(err)+ }+ if err := os.Mkdir(path, 0700); err != nil {+ t.Fatal(err)+ }+ if _, err := h.b.applyEngineSettings(context.Background(), p, ""); err == nil || h.applies.Load() != 0 {+ t.Fatal("runtime changed despite failed journal write")+ }+ if err := os.Remove(path); err != nil {+ t.Fatal(err)+ }+ r := h.b.engineSettings["ollama"]+ r.Snapshot.Settings = p.Settings+ r.Snapshot.Revision+++ r.Snapshot.Phase = "applying"+ r.Resume = true+ r.Explicit = true+ if err := h.b.saveEngineSettingsLocked(); err != nil {+ t.Fatal(err)+ }+ // Simulate a fresh coordinator after its journal was written but component+ // writes/rebind/start had not completed. The same replay handles later cuts.+ h.b.engineSettingsLoaded = false+ if !h.b.recoverEngineSettings() {+ t.Fatal("recovery refused")+ }+ if h.applies.Load() != 1 || h.b.engineSettings["ollama"].Snapshot.Phase != "succeeded" {+ t.Fatal("accepted operation not recovered")+ }+ if !h.b.recoverEngineSettings() || h.applies.Load() != 1 {+ t.Fatal("completed operation replayed")+ }+ if _, ok := h.b.explicitEngineSettings("ollama"); !ok {+ t.Fatal("explicit startup preference lost")+ }+}++func TestSettingsPortValidationIncludesStoppedEnginesAndAliases(t *testing.T) {+ h := newSettingsHarness(t)+ p := h.request(t)+ p.Settings.ProxyPort = p.Settings.ServerPort+ preview, err := h.b.previewEngineSettings(context.Background(), p, "")+ if err != nil {+ t.Fatal(err)+ }+ if len(preview.Errors) == 0 {+ t.Fatal("equal ports accepted")+ }+ p = h.request(t)+ p.Settings.ServerPort = engineControlPort+ preview, err = h.b.previewEngineSettings(context.Background(), p, "")+ if err != nil || len(preview.Errors) == 0 {+ t.Fatalf("reserved control port accepted: %v %v", preview, err)+ }+ p = h.request(t)+ h.otherEnginePort.Store(int32(p.Settings.ServerPort))+ preview, err = h.b.previewEngineSettings(context.Background(), p, "")+ if err != nil || len(preview.Errors) == 0 {+ t.Fatalf("stopped engine reservation ignored: %v %v", preview, err)+ }+ h.otherEnginePort.Store(0)+ h.b.ollamaHostAliasMu.Lock()+ h.b.ollamaHostAlias.Port = p.Settings.ProxyPort+ h.b.ollamaHostAliasMu.Unlock()+ preview, err = h.b.previewEngineSettings(context.Background(), p, "")+ if err != nil || len(preview.Errors) == 0 {+ t.Fatalf("proxy alias reservation ignored: %v %v", preview, err)+ }+}++func TestSettingsMigratesLegacyProxyChoiceBeforeManagedDefaults(t *testing.T) {+ h := newSettingsHarness(t)+ path, _ := h.b.engineSettingsPath()+ if err := os.WriteFile(filepath.Join(filepath.Dir(path), "proxy-port.json"), []byte(`{"port":26080}`), 0600); err != nil {+ t.Fatal(err)+ }+ h.b.migrateLegacyEngineSettings()+ config, ok := h.b.explicitEngineSettings("ollama")+ if !ok || config.ProxyPort != 26080 {+ t.Fatalf("legacy choice lost: %+v %v", config, ok)+ }+ if !h.b.prepareExplicitEngineSettings("ollama") || h.b.ollamaState().startupPort.Load() != 26080 || h.b.ollamaState().managedFacade.Load() {+ t.Fatal("automatic startup overrode saved proxy choice")+ }+}diff --git a/services/nvpair-ui-broker/lmstudioport.go b/services/nvpair-ui-broker/lmstudioport.goindex 783e21f..a736662 100644--- a/services/nvpair-ui-broker/lmstudioport.go+++ b/services/nvpair-ui-broker/lmstudioport.go@@ -196,6 +196,9 @@ func (b *Broker) prepareManagedLMStudioFacade() {}func (b *Broker) prepareManagedLMStudioFacadeWithPortCheck(portAvailable func(int) bool) {+ if b.prepareExplicitEngineSettings("lmstudio") {+ return+ }// Ollama's facade is prepared first, so an inherited OLLAMA_HOST alias is// already reserved here and must stay out of LM Studio's backend search.portAvailable = b.availableOffOllamaHostAlias(portAvailable)@@ -349,6 +352,21 @@ func (b *Broker) reconcileLMStudioProxyPortOnReady(boundPort int) {}func (b *Broker) reconcileLMStudioProxyPortOnReadyForGeneration(generation uint64, boundPort int) {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if b.loadEngineSettingsLocked() != nil {+ if b.lmstudioProxyGeneration.Load() == generation {+ b.markLMStudioPortReady()+ }+ return+ }+ if b.lmstudioProxyGeneration.Load() != generation {+ return+ }+ if _, explicit := b.explicitEngineSettingsLocked("lmstudio"); explicit {+ b.markLMStudioPortReady()+ return+ }if b.lmstudioProxyGeneration.Load() != generation {return}diff --git a/services/nvpair-ui-broker/lmstudioproxy.go b/services/nvpair-ui-broker/lmstudioproxy.goindex 2af00f7..28f1afc 100644--- a/services/nvpair-ui-broker/lmstudioproxy.go+++ b/services/nvpair-ui-broker/lmstudioproxy.go@@ -89,7 +89,7 @@ func (b *Broker) forwardLMStudioProxyNotificationForGeneration(generation uint64Code string `json:"code"`Port int `json:"port"`}- if json.Unmarshal(params, &ep) == nil && ep.Code == "bind-failed" {+ if json.Unmarshal(params, &ep) == nil && ep.Code == "bind-failed" && !b.lmstudioState().explicitSettings.Load() {if b.lmstudioState().managedFacade.Load() && ep.Port == managedLMStudioFacadePort {_, _ = b.blockManagedLMStudioFacade("another process acquired the compatibility port during startup", nil)} else {diff --git a/services/nvpair-ui-broker/proxyport.go b/services/nvpair-ui-broker/proxyport.goindex c23f970..7ecfb7b 100644--- a/services/nvpair-ui-broker/proxyport.go+++ b/services/nvpair-ui-broker/proxyport.go@@ -250,6 +250,9 @@ func (b *Broker) prepareManagedOllamaFacade() {}func (b *Broker) prepareManagedOllamaFacadeWithPortCheck(portAvailable func(int) bool) {+ if b.prepareExplicitEngineSettings("ollama") {+ return+ }b.setOllamaHostAlias(ollamaHostAlias{})// Resolve the worker inside the deferred method: engine-manager can respawn// while the blocking settings/status calls below are preparing the alias.@@ -389,13 +392,6 @@ func (b *Broker) rejectOllamaHostAliasPort(msg *Message, port int, owner string)return true}-// handleLMStudioProxySetPort used to relay the request verbatim, so a user-// could park the LM Studio proxy on a port a running engine already held and-// get no warning. It now takes the same path Ollama's does.-func (b *Broker) handleLMStudioProxySetPort(msg *Message) {- b.handleEngineProxySetPort(lmstudioProxyProfile, msg)-}-// needsOllamaPortGate reports the client requests that can probe and adopt the// configured Ollama port. While :11434 is changing from backend to facade,// those probes must wait or they can mistake the proxy for a local engine.@@ -412,111 +408,6 @@ func needsOllamaPortGate(method string, params json.RawMessage) bool {return json.Unmarshal(params, &request) == nil && request.Engine == "ollama"}-// handleProxySetPort intercepts proxy:set-port (rather than relaying it-// verbatim like the rest of the proxy: namespace) so it can resolve a port-// conflict against the running engines before handing the proxy the port to-// bind. It responds with the proxy's own set-port result (which echoes the-// actually-bound port).-func (b *Broker) handleProxySetPort(msg *Message) {- b.handleEngineProxySetPort(ollamaProxyProfile, msg)-}--// handleEngineProxySetPort is the engine-agnostic form. Both proxies get the-// same treatment: validate the port, resolve it against the running engines,-// then hand the proxy the port to bind and echo back what it actually bound.-func (b *Broker) handleEngineProxySetPort(profile engineProxyProfile, msg *Message) {- respondErr := func(code int, format string, args ...any) {- if err := b.codec.RespondError(msg.ID, code, fmt.Sprintf(format, args...)); err != nil {- log.Printf("failed to respond to %s: %v", msg.Method, err)- }- }-- // Validate the request before reporting on the proxy: a port that is- // reserved for the inherited OLLAMA_HOST alias is refused with an- // actionable message whether or not the proxy happens to be up, which is- // more use than "not available".- var params struct {- Port int `json:"port"`- }- if err := json.Unmarshal(msg.Params, ¶ms); err != nil {- respondErr(-32602, "invalid params: expected {\"port\": <int>}")- return- }- if params.Port < 1 || params.Port > 65535 {- respondErr(-32602, "port must be between 1 and 65535")- return- }- if b.rejectOllamaHostAliasPort(msg, params.Port, "the "+profile.DisplayName+" proxy") {- return- }-- p := b.engineProxyHandle(profile)- if p == nil {- respondErr(-32000, "%s not available", profile.ComponentName())- return- }-- effective := b.resolveEngineProxyPort(profile, params.Port)-- body, err := json.Marshal(map[string]int{"port": effective})- if err != nil {- respondErr(-32000, "encode set-port: %v", err)- return- }- result, rpcErr, err := p.Call(context.Background(), profile.addressed("set-port"), body)- switch {- case err != nil:- respondErr(-32000, "proxy set-port failed: %v", err)- case rpcErr != nil:- if err := b.codec.RespondError(msg.ID, rpcErr.Code, rpcErr.Message); err != nil {- log.Printf("failed to relay proxy set-port error: %v", err)- }- default:- if err := b.codec.Respond(msg.ID, result); err != nil {- log.Printf("failed to relay proxy set-port result: %v", err)- }- }-}--// resolveProxyPort returns the port the proxy should actually bind for a-// requested port: the request itself when free, or the next free port when a-// running engine already holds it (engines take precedence). A bump surfaces-// a sticky warning into the errors pipeline; a clean request clears any stale-// one so the notice doesn't outlive the conflict.-func (b *Broker) resolveProxyPort(requested int) int {- return b.resolveEngineProxyPort(ollamaProxyProfile, requested)-}--// resolveEngineProxyPort is the engine-agnostic form. A managed facade is not-// negotiable, so the request is answered with the facade port; otherwise a port-// a running engine already holds is bumped past, because engines take-// precedence over their proxy.-func (b *Broker) resolveEngineProxyPort(p engineProxyProfile, requested int) int {- bumpedID := p.portBumpedID()- if b.managedFacade(p) {- b.forwardErrorsClear(bumpedID)- return p.FacadePort- }- taken := b.runningEnginePorts()- if aliasPort := b.currentOllamaHostAlias().Port; aliasPort > 0 {- taken[aliasPort] = true- }- effective := nextFreeProxyPort(requested, taken)- if effective != requested {- b.forwardErrorsReport(errors.ServiceError{- ID: bumpedID,- Message: fmt.Sprintf("Port %d is in use by a running engine; the %s proxy was moved to %d.", requested, p.DisplayName, effective),- Timestamp: nowMillis(),- NodeID: b.nodeID,- Severity: "warning",- Action: "none",- })- } else {- b.forwardErrorsClear(bumpedID)- }- return effective-}-// reconcileProxyPortOnReady runs after the proxy announces a bound port// (notably its restored port on startup). If a running engine now holds that// port, it steers the proxy to a free one — engines take precedence — and@@ -524,6 +415,16 @@ func (b *Broker) resolveEngineProxyPort(p engineProxyProfile, requested int) int// goroutine that calls forwardProxyNotification), so the p.Call round-trip// can't deadlock the very reader that would deliver its response.func (b *Broker) reconcileProxyPortOnReady(boundPort int) {+ b.engineConfigMu.Lock()+ defer b.engineConfigMu.Unlock()+ if b.loadEngineSettingsLocked() != nil {+ b.markOllamaPortReady()+ return+ }+ if _, explicit := b.explicitEngineSettingsLocked("ollama"); explicit {+ b.markOllamaPortReady()+ return+ }if b.ollamaState().managedFacade.Load() {p := b.getProxy()if p == nil {diff --git a/services/nvpair-ui-broker/proxyportbump_test.go b/services/nvpair-ui-broker/proxyportbump_test.goindex e22ae3b..872dab7 100644--- a/services/nvpair-ui-broker/proxyportbump_test.go+++ b/services/nvpair-ui-broker/proxyportbump_test.go@@ -3,15 +3,7 @@package main-// Baseline coverage for the Ollama proxy-port paths that had none.-//-// resolveProxyPort, handleProxySetPort and the unmanaged branch of-// reconcileProxyPortOnReady were reachable only through code no test drove:-// the two existing reconcile tests store managedOllamaFacade=true first, so-// they return before the unmanaged branch, and nothing referenced the set-port-// handler at all. Those are precisely the paths the proxy unification-// generalizes onto LM Studio, so they need assertions that fail if the-// generalization changes them.+// Coverage for automatic facade preparation, bind recovery, and ownership gates.import ("context"@@ -25,7 +17,6 @@ import ("time""nvpair-shared/engines"- "nvpair-shared/errors")// brokerWithRunningEngines answers one engine:get-installed with the given@@ -102,63 +93,6 @@ func awaitErrorsNotification(t *testing.T, seen <-chan *Message, method string)}}-// A running engine owns its port, so a proxy asked for that port is moved to-// the next free one and the move is surfaced as a sticky warning.-func TestResolveProxyPortBumpsPastRunningEngine(t *testing.T) {- b := brokerWithRunningEngines(t, 11434)- seen := observeErrors(t, b)-- if got := b.resolveProxyPort(11434); got != 11435 {- t.Fatalf("resolveProxyPort(11434) = %d, want 11435", got)- }-- msg := awaitErrorsNotification(t, seen, methodErrorsReport)- if !strings.Contains(string(msg.Params), proxyPortBumpedID) {- t.Fatalf("warning did not carry %s: %s", proxyPortBumpedID, msg.Params)- }- var reported struct {- Severity string `json:"severity"`- Action string `json:"action"`- }- if err := json.Unmarshal(msg.Params, &reported); err != nil {- t.Fatal(err)- }- if reported.Severity != "warning" || reported.Action != "none" {- t.Fatalf("severity/action = %q/%q, want warning/none", reported.Severity, reported.Action)- }-}--// A request that collides with nothing clears any warning a previous bump-// left, so the notice cannot outlive the conflict that produced it.-func TestResolveProxyPortClearsStaleBumpWarning(t *testing.T) {- b := brokerWithRunningEngines(t)- seen := observeErrors(t, b)-- if got := b.resolveProxyPort(11500); got != 11500 {- t.Fatalf("resolveProxyPort(11500) = %d, want it unchanged", got)- }-- msg := awaitErrorsNotification(t, seen, methodErrorsClear)- var cleared errors.ClearParams- if err := json.Unmarshal(msg.Params, &cleared); err != nil {- t.Fatal(err)- }- if cleared.ID != proxyPortBumpedID {- t.Fatalf("cleared id = %q, want %q", cleared.ID, proxyPortBumpedID)- }-}--// Managed mode overrides the request entirely: the proxy owns the facade port,-// so no bump warning applies.-func TestResolveProxyPortForcesFacadeWhenManaged(t *testing.T) {- b := brokerWithRunningEngines(t)- b.ollamaState().managedFacade.Store(true)-- if got := b.resolveProxyPort(9999); got != managedOllamaFacadePort {- t.Fatalf("resolveProxyPort under managed mode = %d, want %d", got, managedOllamaFacadePort)- }-}-// The unmanaged reconcile branch: a proxy that came up on a port a running// engine holds is corrected onto the next free port, and the correction is// announced. Both existing reconcile tests set managedOllamaFacade first and@@ -431,53 +365,6 @@ func TestFacadeEnableRejectionIsNotRetried(t *testing.T) {}}-// LM Studio's set-port used to relay verbatim, so a user could park its proxy-// on a port a running engine already held and hear nothing about it. Both-// engines now resolve the request the same way, and the warning names the-// engine so two proxies bumping cannot produce one indistinguishable notice.-func TestBothProxiesResolveSetPortAgainstRunningEngines(t *testing.T) {- for _, tc := range []struct {- engine string- requested int- want int- }{- {engine: "ollama", requested: 11434, want: 11435},- {engine: "lmstudio", requested: 1234, want: 1235},- } {- t.Run(tc.engine, func(t *testing.T) {- profile, ok := engineProxyProfileFor(tc.engine)- if !ok {- t.Fatalf("no profile for %s", tc.engine)- }- b := brokerWithRunningEngines(t, tc.requested)- seen := observeErrors(t, b)-- if got := b.resolveEngineProxyPort(profile, tc.requested); got != tc.want {- t.Fatalf("resolveEngineProxyPort(%d) = %d, want %d", tc.requested, got, tc.want)- }-- msg := awaitErrorsNotification(t, seen, methodErrorsReport)- if !strings.Contains(string(msg.Params), profile.portBumpedID()) {- t.Fatalf("warning did not carry %s: %s", profile.portBumpedID(), msg.Params)- }- if !strings.Contains(string(msg.Params), profile.DisplayName) {- t.Fatalf("warning does not name the engine: %s", msg.Params)- }- })- }-}--// A managed facade is not negotiable: the request is answered with the facade-// port and any stale bump warning is cleared, for either engine.-func TestManagedFacadeOverridesRequestedProxyPort(t *testing.T) {- b := brokerWithRunningEngines(t)- b.lmstudioState().managedFacade.Store(true)-- if got := b.resolveEngineProxyPort(lmstudioProxyProfile, 4321); got != managedLMStudioFacadePort {- t.Fatalf("resolveEngineProxyPort = %d, want the managed facade %d", got, managedLMStudioFacadePort)- }-}-// The proxy's explicit fallback port must never be one the engine is going to// want. When the configured backend is unknown, a free port is not evidence the// engine will not claim it, and the stock backend port is exactly where adiff --git a/services/nvpair-ui-broker/settingsport.go b/services/nvpair-ui-broker/settingsport.gonew file mode 100644index 0000000..c1d1110--- /dev/null+++ b/services/nvpair-ui-broker/settingsport.go@@ -0,0 +1,72 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "context"+ "encoding/json"+ "fmt"++ settings "nvpair-shared/enginesettings"+)++// handleSettingsPortRPC serves the port-only RPCs — engine:set-port,+// proxy:set-port, and lmstudio-proxy:set-port — which nvpair-tui calls to move+// a single port without rendering the full launch settings form. They keep+// their own narrow request and response shapes, but run through the same+// authoritative settings operation as the desktop editor, so a port change+// made from the terminal cannot diverge from one made from the UI. In+// particular a proxy change now fails on a busy port instead of silently+// binding a different one.+//+// proxyEngine selects which port the request addresses: "" is the engine's own+// server port, and a non-empty value names the proxy in front of that engine.+func (b *Broker) handleSettingsPortRPC(msg *Message, proxyEngine string) {+ var p struct {+ Engine string `json:"engine"`+ Port int `json:"port"`+ }+ if json.Unmarshal(msg.Params, &p) != nil || p.Port < 1 || p.Port > 65535 {+ _ = b.codec.RespondError(msg.ID, -32602, "port must be between 1 and 65535")+ return+ }+ if proxyEngine != "" {+ p.Engine = proxyEngine+ }+ if b.rejectOllamaHostAliasPort(msg, p.Port, p.Engine) {+ return+ }+ target := settings.Request{Engine: p.Engine}+ snapshot, err := b.getEngineSettings(context.Background(), target, "")+ if err == nil {+ target.Settings = snapshot.Settings+ target.ExpectedRevision = snapshot.Revision+ target.RequestID = settingsID()+ target.Resolution = "server"+ if proxyEngine != "" {+ target.Settings.ProxyPort = p.Port+ } else {+ target.Settings.ServerPort = p.Port+ }+ var receipt settingsReceipt+ receipt, err = b.applyEngineSettings(context.Background(), target, "")+ if err == nil && receipt.Phase == "failed" {+ err = fmt.Errorf("settings were saved but could not be applied; inspect engine settings for the current state")+ }+ }+ if err != nil {+ _ = b.codec.RespondError(msg.ID, -32000, err.Error())+ return+ }+ if proxyEngine != "" {+ _ = b.codec.Respond(msg.ID, map[string]int{"port": p.Port})+ return+ }+ var status json.RawMessage+ if err = b.settingsWorkerCall(context.Background(), "engine:status", map[string]string{"engine": p.Engine}, &status); err != nil {+ _ = b.codec.RespondError(msg.ID, -32000, err.Error())+ return+ }+ _ = b.codec.Respond(msg.ID, status)+}diff --git a/services/nvpair-ui-broker/testmain_test.go b/services/nvpair-ui-broker/testmain_test.gonew file mode 100644index 0000000..cf2167e--- /dev/null+++ b/services/nvpair-ui-broker/testmain_test.go@@ -0,0 +1,30 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package main++import (+ "fmt"+ "os"+ "testing"+)++// Bare broker fixtures also consult the settings journal during startup. Keep+// all default app-data lookups away from the developer's live configuration.+func TestMain(m *testing.M) {+ dir, err := os.MkdirTemp("", "nvpair-broker-test-")+ if err != nil {+ fmt.Fprintln(os.Stderr, err)+ os.Exit(1)+ }+ for _, key := range []string{"LOCALAPPDATA", "APPDATA", "XDG_CONFIG_HOME", "HOME", "USERPROFILE"} {+ if err := os.Setenv(key, dir); err != nil {+ fmt.Fprintln(os.Stderr, err)+ _ = os.RemoveAll(dir)+ os.Exit(1)+ }+ }+ code := m.Run()+ _ = os.RemoveAll(dir)+ os.Exit(code)+}diff --git a/services/shared/cors/cors.go b/services/shared/cors/cors.goindex 67f1516..2e387ed 100644--- a/services/shared/cors/cors.go+++ b/services/shared/cors/cors.go@@ -1,91 +1,166 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-// Package cors is the single source of truth for the CORS policy NVPAIR's-// inference proxies present to browser clients. Both proxies front a-// local-network inference engine for the same kinds of caller (a local web UI,-// an Electron renderer whose origin differs from the proxy's), so they must-// answer a preflight and label a response identically; keeping one-// implementation is what stops the two from drifting apart.-//-// The policy applies to responses a proxy authors itself. A response forwarded-// from an engine that declared its own Access-Control-Allow-Origin keeps that-// engine's policy — including on a preflight, where preserving an exact origin-// and Access-Control-Allow-Credentials is required for credentialed browser-// requests. An engine without a CORS policy gets the proxy's permissive fallback.+// Package cors combines upstream HTTP permissions without defining engine policy.+// Forwarded responses must not be supplemented with default CORS permissions.package cors-import "net/http"+import (+ "net/http"+ "strconv"+ "strings"+)-// Apply writes the permissive CORS policy so browser-based clients can read-// proxy responses — and, crucially, error bodies. Without an-// Access-Control-Allow-Origin a browser surfaces every failure as an opaque-// "CORS error", hiding the real status the proxy returned. The proxies front a-// local-network inference engine, not a credentialed API, so a wildcard origin-// is appropriate and they never reflect credentials.-func Apply(h http.Header) {- h.Set("Access-Control-Allow-Origin", "*")- h.Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")- h.Set("Access-Control-Allow-Headers", "Content-Type, Authorization")- // A browser rejects a wildcard origin paired with Allow-Credentials: true,- // so setting the former while inheriting the latter would leave the- // response unreadable — the failure this policy exists to prevent. Callers- // reach here only when no engine policy is being preserved, so an- // Allow-Credentials from an upstream that sent no origin of its own- // describes a policy this response no longer carries. Drop it.- h.Del("Access-Control-Allow-Credentials")- // Uncredentialed wildcard responses may expose every header, so a browser- // client can read engine metadata outside the CORS-safelisted set.- h.Set("Access-Control-Expose-Headers", "*")- h.Set("Access-Control-Max-Age", "86400")+// preflightMaxAgeSeconds is how long a browser may reuse a combined preflight+// result. The combination is an intersection over a changing set of engines,+// so it is deliberately short.+const preflightMaxAgeSeconds = 60++func IsPreflight(r *http.Request) bool {+ return r.Method == http.MethodOptions && r.Header.Get("Origin") != "" && r.Header.Get("Access-Control-Request-Method") != ""}-func applyPreflight(h http.Header, r *http.Request) {- Apply(h)- // Echo the browser's requested headers so an arbitrary client header- // (e.g. a custom auth header) clears preflight instead of being- // rejected by our static default.- if reqHdrs := r.Header.Get("Access-Control-Request-Headers"); reqHdrs != "" {- h.Set("Access-Control-Allow-Headers", reqHdrs)+// AllowsOrigin checks uncredentialed sharing. Credentialed sharing is separately+// intersected by Combine because a request's credentials mode is not observable.+func AllowsOrigin(h http.Header, origin string) bool {+ values := h.Values("Access-Control-Allow-Origin")+ return origin != "" && len(values) == 1 && (values[0] == origin || values[0] == "*")+}+func credentials(h http.Header, origin string) bool {+ values := h.Values("Access-Control-Allow-Credentials")+ return h.Get("Access-Control-Allow-Origin") == origin && len(values) == 1 && values[0] == "true"+}+func tokens(values []string) ([]string, bool) {+ var out []string+ for _, value := range values {+ for _, token := range strings.Split(value, ",") {+ token = strings.TrimSpace(token)+ if token == "" {+ continue+ }+ if !validToken(token) {+ return nil, false+ }+ out = append(out, token)+ }}+ return out, true}--// WritePreflight answers a browser's OPTIONS preflight locally with 204 plus-// the permissive fallback policy, and reports whether it handled the request.-// The proxies use this when no engine can be consulted (or before rejecting a-// non-loopback plaintext caller). When an engine is available, its preflight is-// forwarded instead so an exact origin and credentials policy can survive.-func WritePreflight(w http.ResponseWriter, r *http.Request) bool {- if r.Method != http.MethodOptions {+func permits(list []string, token string, fold, wildcard bool) bool {+ for _, allowed := range list {+ if allowed == token || (fold && strings.EqualFold(allowed, token)) || (wildcard && allowed == "*") {+ return true+ }+ }+ return false+}+func permitsPreflight(h http.Header, method string, headers []string, credentialed bool) bool {+ methods, ok := tokens(h.Values("Access-Control-Allow-Methods"))+ if !ok {return false}- applyPreflight(w.Header(), r)- w.WriteHeader(http.StatusNoContent)+ allowedHeaders, ok := tokens(h.Values("Access-Control-Allow-Headers"))+ if !ok {+ return false+ }+ if method != "GET" && method != "HEAD" && method != "POST" && !permits(methods, method, false, !credentialed) {+ return false+ }+ for _, header := range headers {+ if !permits(allowedHeaders, header, true, !credentialed && !strings.EqualFold(header, "Authorization")) {+ return false+ }+ }return true}-// CompletePreflightFallback replaces an upstream OPTIONS response that has no-// CORS policy with the proxy's local 204 fallback. Engines that do declare an-// Access-Control-Allow-Origin are left completely untouched; in particular,-// an exact origin plus Access-Control-Allow-Credentials must reach the browser-// unchanged for a credentialed preflight to pass.-func CompletePreflightFallback(resp *http.Response) bool {- if resp == nil || resp.Request == nil || resp.Request.Method != http.MethodOptions ||- resp.Header.Get("Access-Control-Allow-Origin") != "" {+// Combine grants only permissions supported by every response. Callers separately+// validate statuses and bodies. Single forwarded responses are relayed unchanged.+func Combine(r *http.Request, responses []http.Header) (http.Header, bool) {+ origin := r.Header.Get("Origin")+ if origin == "" || len(responses) == 0 {+ return nil, false+ }+ preflight := IsPreflight(r)+ method := r.Header.Get("Access-Control-Request-Method")+ requested, ok := tokens(r.Header.Values("Access-Control-Request-Headers"))+ if preflight && (!ok || !validToken(method)) {+ return nil, false+ }+ out := make(http.Header)+ credentialed := true+ for _, h := range responses {+ if !AllowsOrigin(h, origin) || (preflight && !permitsPreflight(h, method, requested, false)) {+ return nil, false+ }+ credentialed = credentialed && credentials(h, origin) && (!preflight || permitsPreflight(h, method, requested, true))+ for _, vary := range h.Values("Vary") {+ out.Add("Vary", vary)+ }+ }+ out.Add("Vary", "Origin")+ out.Set("Access-Control-Allow-Origin", origin)+ if credentialed {+ out.Set("Access-Control-Allow-Credentials", "true")+ }+ if preflight {+ out.Add("Vary", "Access-Control-Request-Method, Access-Control-Request-Headers")+ out.Set("Access-Control-Allow-Methods", method)+ if len(requested) > 0 {+ out.Set("Access-Control-Allow-Headers", strings.Join(requested, ", "))+ }+ // Bound rather than forbid preflight caching. Zero made a browser+ // preflight every request, and each preflight fans out to every+ // candidate engine. A short window keeps that cost off the hot path+ // while limiting how long a stale intersection can be reused; the+ // actual response's headers are still computed live, so a permission+ // withdrawn mid-window still blocks the request.+ out.Set("Access-Control-Max-Age", strconv.Itoa(preflightMaxAgeSeconds))+ }+ return out, true+}++// EndToEndHeaders retains headers for forwarded requests and responses,+// excluding connection-specific fields as a reverse proxy does.+func EndToEndHeaders(h http.Header) http.Header {+ out := h.Clone()+ for _, value := range out.Values("Connection") {+ for _, name := range strings.Split(value, ",") {+ out.Del(strings.TrimSpace(name))+ }+ }+ for _, name := range []string{"Connection", "Proxy-Connection", "Keep-Alive", "Proxy-Authenticate", "Proxy-Authorization", "Te", "Trailer", "Transfer-Encoding", "Upgrade"} {+ out.Del(name)+ }+ return out+}++// FanoutHeaders preserves CORS inputs without sharing caller credentials across+// engines. Credentials for a proxy endpoint do not authorize every peer.+func FanoutHeaders(h http.Header) http.Header {+ out := EndToEndHeaders(h)+ out.Del("Authorization")+ out.Del("Cookie")+ return out+}++// tokenSpecials is the non-alphanumeric half of RFC 9110's `tchar` set. The+// backtick is an ordinary character in an interpreted string literal.+const tokenSpecials = "!#$%&'*+-.^_`|~"++// validToken implements the HTTP token grammar for field names and methods.+func validToken(value string) bool {+ if value == "" {return false}- if resp.Body != nil {- _ = resp.Body.Close()+ for i := 0; i < len(value); i++ {+ c := value[i]+ if c >= '0' && c <= '9' || c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' {+ continue+ }+ if !strings.ContainsRune(tokenSpecials, rune(c)) {+ return false+ }}- applyPreflight(resp.Header, resp.Request)- resp.StatusCode = http.StatusNoContent- resp.Status = "204 No Content"- resp.Body = http.NoBody- resp.ContentLength = 0- resp.TransferEncoding = nil- resp.Header.Del("Content-Length")- resp.Header.Del("Content-Type")- resp.Header.Del("Content-Encoding")- resp.Header.Del("Transfer-Encoding")return true}diff --git a/services/shared/cors/cors_test.go b/services/shared/cors/cors_test.goindex c561aba..c7bfd2d 100644--- a/services/shared/cors/cors_test.go+++ b/services/shared/cors/cors_test.go@@ -1,158 +1,268 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-package corsimport (+ "context""io""net/http""net/http/httptest"+ "net/url"+ "strconv""strings"+ "sync/atomic""testing"+ "time")-func TestApplySetsPolicy(t *testing.T) {- h := http.Header{}- Apply(h)- for header, want := range map[string]string{- "Access-Control-Allow-Origin": "*",- "Access-Control-Expose-Headers": "*",+func preflight() *http.Request {+ r := httptest.NewRequest("OPTIONS", "/api/chat?test=1", nil)+ r.Header.Set("Origin", "http://app.test")+ r.Header.Set("Access-Control-Request-Method", "PUT")+ r.Header.Set("Access-Control-Request-Headers", "Content-Type, Authorization")+ return r+}+func policy() http.Header {+ h := make(http.Header)+ h.Set("Access-Control-Allow-Origin", "http://app.test")+ h.Set("Access-Control-Allow-Methods", "GET, PUT")+ h.Set("Access-Control-Allow-Headers", "content-type, authorization")+ h.Set("Access-Control-Allow-Credentials", "true")+ h.Add("Vary", "Accept-Encoding")+ return h+}+func TestCombine(t *testing.T) {+ for _, tc := range []struct {+ name string+ change func(http.Header)+ allowed, creds bool+ }{+ {"exact", func(h http.Header) {}, true, true},+ {"missing origin", func(h http.Header) { h.Del("Access-Control-Allow-Origin") }, false, false},+ {"wrong origin", func(h http.Header) { h.Set("Access-Control-Allow-Origin", "http://wrong.test") }, false, false},+ {"duplicate origin", func(h http.Header) { h.Add("Access-Control-Allow-Origin", "http://app.test") }, false, false},+ {"wildcard origin", func(h http.Header) { h.Set("Access-Control-Allow-Origin", "*") }, true, false},+ {"no credentials", func(h http.Header) { h.Del("Access-Control-Allow-Credentials") }, true, false},+ {"missing method", func(h http.Header) { h.Del("Access-Control-Allow-Methods") }, false, false},+ {"case sensitive method", func(h http.Header) { h.Set("Access-Control-Allow-Methods", "put") }, false, false},+ {"missing header", func(h http.Header) { h.Set("Access-Control-Allow-Headers", "Content-Type") }, false, false},+ {"wildcard does not grant authorization", func(h http.Header) { h.Set("Access-Control-Allow-Headers", "*") }, false, false},+ {"wildcard plus authorization", func(h http.Header) { h.Set("Access-Control-Allow-Headers", "*, Authorization") }, true, false},+ {"wildcard method", func(h http.Header) { h.Set("Access-Control-Allow-Methods", "*") }, true, false},+ {"invalid list", func(h http.Header) { h.Set("Access-Control-Allow-Headers", "Content-Type, bad header") }, false, false},} {- if got := h.Get(header); got != want {- t.Errorf("%s = %q, want %q", header, got, want)- }- }- if h.Get("Access-Control-Allow-Methods") == "" {- t.Error("missing Access-Control-Allow-Methods")- }- // A wildcard origin is only valid for uncredentialed responses, so the- // policy must never claim to allow credentials.- if got := h.Get("Access-Control-Allow-Credentials"); got != "" {- t.Errorf("Access-Control-Allow-Credentials = %q, want unset alongside a wildcard origin", got)+ t.Run(tc.name, func(t *testing.T) {+ second := policy()+ tc.change(second)+ h, ok := Combine(preflight(), []http.Header{policy(), second})+ if ok != tc.allowed {+ t.Fatalf("allowed=%v want %v", ok, tc.allowed)+ }+ if !ok {+ return+ }+ if (h.Get("Access-Control-Allow-Credentials") == "true") != tc.creds {+ t.Fatal("credentials widened")+ }+ if h.Get("Access-Control-Allow-Origin") != "http://app.test" || h.Get("Access-Control-Allow-Methods") != "PUT" {+ t.Fatalf("bad combined headers: %v", h)+ }+ // Bounded, not disabled: zero made every browser request pay for a+ // preflight fan-out to every candidate engine.+ maxAge, err := strconv.Atoi(h.Get("Access-Control-Max-Age"))+ if err != nil || maxAge <= 0 || maxAge > 600 {+ t.Fatalf("preflight max-age is not a short positive window: %q", h.Get("Access-Control-Max-Age"))+ }+ if !strings.Contains(strings.Join(h.Values("Vary"), ","), "Accept-Encoding") {+ t.Fatal("lost Vary")+ }+ })}}-// TestApplyClearsInheritedCredentials: Apply runs on forwarded responses too,-// where the header map is whatever the upstream sent. An upstream that emits-// Allow-Credentials without an origin of its own would otherwise leave the-// invalid wildcard + credentials pair, which a browser fails closed.-func TestApplyClearsInheritedCredentials(t *testing.T) {- h := http.Header{"Access-Control-Allow-Credentials": []string{"true"}}- Apply(h)-- if got := h.Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)+func TestCombineSafelistedAndOrdinaryRequests(t *testing.T) {+ r := preflight()+ r.Header.Set("Access-Control-Request-Method", "GET")+ r.Header.Del("Access-Control-Request-Headers")+ h := policy()+ h.Del("Access-Control-Allow-Methods")+ h.Del("Access-Control-Allow-Headers")+ if _, ok := Combine(r, []http.Header{h}); !ok {+ t.Fatal("safelisted method needs no explicit grant")}- if got := h.Get("Access-Control-Allow-Credentials"); got != "" {- t.Errorf("Access-Control-Allow-Credentials = %q, want cleared alongside the wildcard origin", got)+ r.Method = "GET"+ if _, ok := Combine(r, []http.Header{h}); !ok {+ t.Fatal("ordinary response")}-}--func TestWritePreflightEchoesRequestedHeaders(t *testing.T) {- rec := httptest.NewRecorder()- req := httptest.NewRequest(http.MethodOptions, "/v1/chat/completions", nil)- req.Header.Set("Access-Control-Request-Headers", "X-Custom-Token")-- if !WritePreflight(rec, req) {- t.Fatal("WritePreflight(OPTIONS) = false, want the preflight handled")+ if _, ok := Combine(r, nil); ok {+ t.Fatal("empty set allowed")}- if rec.Code != http.StatusNoContent {- t.Errorf("status = %d, want %d", rec.Code, http.StatusNoContent)+ r.Header.Del("Origin")+ if _, ok := Combine(r, []http.Header{h}); ok {+ t.Fatal("invented origin")}- if got := rec.Header().Get("Access-Control-Allow-Headers"); got != "X-Custom-Token" {- t.Errorf("Access-Control-Allow-Headers = %q, want echoed X-Custom-Token", got)+ if IsPreflight(r) {+ t.Fatal("GET is not preflight")}}--// TestWritePreflightIgnoresOtherMethods: a real request must fall through to the-// caller's own handling untouched, with no response written.-func TestWritePreflightIgnoresOtherMethods(t *testing.T) {- rec := httptest.NewRecorder()- if WritePreflight(rec, httptest.NewRequest(http.MethodPost, "/api/chat", nil)) {- t.Fatal("WritePreflight(POST) = true, want the request left to the caller")+func TestEndToEndHeaders(t *testing.T) {+ h := http.Header{+ "Origin": {"http://app.test"},+ "Authorization": {"Bearer test"},+ "Cookie": {"test=1"},+ "Connection": {"X-Hop, keep-alive"},+ "X-Hop": {"private"},+ "Keep-Alive": {"yes"},}- if got := rec.Header().Get("Access-Control-Allow-Origin"); got != "" {- t.Errorf("Access-Control-Allow-Origin = %q, want no headers written", got)+ got := EndToEndHeaders(h)+ if got.Get("X-Hop") != "" || got.Get("Keep-Alive") != "" || got.Get("Connection") != "" {+ t.Fatal("forwarded hop headers")}-}--func TestCompletePreflightFallbackPreservesEnginePolicy(t *testing.T) {- req := httptest.NewRequest(http.MethodOptions, "/api/chat", nil)- resp := &http.Response{- StatusCode: http.StatusNoContent,- Status: "204 No Content",- Header: http.Header{- "Access-Control-Allow-Origin": []string{"https://app.example"},- "Access-Control-Allow-Credentials": []string{"true"},- },- Body: http.NoBody,- Request: req,+ if got.Get("Origin") != h.Get("Origin") || got.Get("Authorization") != h.Get("Authorization") || got.Get("Cookie") != h.Get("Cookie") {+ t.Fatal("lost end-to-end headers")}-- if CompletePreflightFallback(resp) {- t.Fatal("CompletePreflightFallback = true, want the engine policy preserved")+ if h.Get("X-Hop") == "" {+ t.Fatal("mutated caller")}- if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "https://app.example" {- t.Errorf("Access-Control-Allow-Origin = %q, want the engine's exact origin", got)+}+func target(s *httptest.Server) Target {+ u, _ := url.Parse(s.URL)+ return Target{URL: u, Transport: s.Client().Transport}+}+func TestFanoutStripsCredentials(t *testing.T) {+ request := preflight()+ request.Header.Set("Authorization", "Bearer private")+ request.Header.Set("Cookie", "session=private")+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Authorization") != "" || r.Header.Get("Cookie") != "" {+ t.Error("fan-out shared caller credentials")+ }+ if r.Header.Get("Origin") != "http://app.test" || r.Header.Get("Access-Control-Request-Headers") != "Content-Type, Authorization" {+ t.Error("fan-out lost CORS inputs")+ }+ for key, values := range policy() {+ w.Header()[key] = values+ }+ w.WriteHeader(http.StatusNoContent)+ }))+ defer server.Close()+ rec := httptest.NewRecorder()+ ServePreflight(rec, request, []Target{target(server), target(server)})+ if rec.Code != http.StatusNoContent {+ t.Fatalf("status=%d", rec.Code)}- if got := resp.Header.Get("Access-Control-Allow-Credentials"); got != "true" {- t.Errorf("Access-Control-Allow-Credentials = %q, want the engine's true", got)+ if request.Header.Get("Authorization") != "Bearer private" || request.Header.Get("Cookie") != "session=private" {+ t.Fatal("mutated original request")}}--func TestCompletePreflightFallbackReplacesMissingEnginePolicy(t *testing.T) {- req := httptest.NewRequest(http.MethodOptions, "/api/chat", nil)- req.Header.Set("Access-Control-Request-Headers", "X-Custom-Token")- resp := &http.Response{- StatusCode: http.StatusNotFound,- Status: "404 Not Found",- Header: http.Header{"Content-Type": []string{"text/plain"}},- Body: io.NopCloser(strings.NewReader("not found")),- ContentLength: 9,- Request: req,+func TestPreflightResponses(t *testing.T) {+ test := func(name string, status int, withPolicy bool, combinedStatus int) {+ t.Run(name, func(t *testing.T) {+ var calls atomic.Int32+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ if r.Header.Get("Origin") != "http://app.test" || r.URL.RawQuery != "test=1" || r.Header.Get("Access-Control-Request-Method") != "PUT" {+ t.Error("request changed")+ }+ if withPolicy {+ for k, v := range policy() {+ w.Header()[k] = v+ }+ }+ w.Header().Set("Location", "/redirect-target")+ w.WriteHeader(status)+ if status != http.StatusNoContent {+ if _, err := io.WriteString(w, "engine response"); err != nil {+ t.Error(err)+ }+ }+ }))+ defer server.Close()+ rec := httptest.NewRecorder()+ ServePreflight(rec, preflight(), []Target{target(server)})+ if rec.Code != status {+ t.Fatalf("single status %d", rec.Code)+ }+ if (rec.Header().Get("Access-Control-Allow-Origin") != "") != withPolicy {+ t.Fatal("single policy changed")+ }+ if status != http.StatusNoContent && rec.Body.String() != "engine response" {+ t.Fatal("single body changed")+ }+ if calls.Load() != 1 {+ t.Fatal("followed redirect")+ }+ rec = httptest.NewRecorder()+ ServePreflight(rec, preflight(), []Target{target(server), target(server)})+ want := combinedStatus+ if rec.Code != want {+ t.Fatalf("combined status=%d want=%d", rec.Code, want)+ }+ if want != http.StatusNoContent && rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatal("permission on failure")+ }+ })}+ test("allow", http.StatusNoContent, true, http.StatusNoContent)+ test("denial", http.StatusForbidden, false, http.StatusForbidden)+ test("no policy", http.StatusOK, false, http.StatusForbidden)+ test("redirect", http.StatusTemporaryRedirect, true, http.StatusForbidden)+ test("failure", http.StatusServiceUnavailable, false, http.StatusBadGateway)+}- if !CompletePreflightFallback(resp) {- t.Fatal("CompletePreflightFallback = false, want the local fallback applied")- }- if resp.StatusCode != http.StatusNoContent {- t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusNoContent)- }- if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)- }- if got := resp.Header.Get("Access-Control-Allow-Headers"); got != "X-Custom-Token" {- t.Errorf("Access-Control-Allow-Headers = %q, want echoed X-Custom-Token", got)- }- if resp.Body != http.NoBody || resp.ContentLength != 0 {- t.Errorf("fallback body = %#v with length %d, want http.NoBody with length 0", resp.Body, resp.ContentLength)- }- if got := resp.Header.Get("Content-Type"); got != "" {- t.Errorf("Content-Type = %q, want removed from the empty 204", got)+func TestPreflightWithoutTargets(t *testing.T) {+ rec := httptest.NewRecorder()+ ServePreflight(rec, preflight(), nil)+ if rec.Code != http.StatusBadGateway || rec.Header().Get("Access-Control-Allow-Origin") != "" {+ t.Fatal("no engines granted preflight")}}-// TestCompletePreflightFallbackDropsCredentialsWithoutOrigin: an upstream-// preflight carrying Allow-Credentials but no origin has no policy to preserve,-// so the fallback applies — and must not leave the credentials header behind to-// invalidate the wildcard origin it just wrote.-func TestCompletePreflightFallbackDropsCredentialsWithoutOrigin(t *testing.T) {- req := httptest.NewRequest(http.MethodOptions, "/api/chat", nil)- resp := &http.Response{- StatusCode: http.StatusNoContent,- Status: "204 No Content",- Header: http.Header{"Access-Control-Allow-Credentials": []string{"true"}},- Body: http.NoBody,- Request: req,- }+type roundTripFunc func(*http.Request) (*http.Response, error)- if !CompletePreflightFallback(resp) {- t.Fatal("CompletePreflightFallback = false, want the local fallback applied")+func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }+func TestBoundedFanoutAndCancellation(t *testing.T) {+ var active, max atomic.Int32+ started := make(chan struct{}, 20)+ transport := roundTripFunc(func(r *http.Request) (*http.Response, error) {+ n := active.Add(1)+ defer active.Add(-1)+ for old := max.Load(); n > old; old = max.Load() {+ if max.CompareAndSwap(old, n) {+ break+ }+ }+ started <- struct{}{}+ <-r.Context().Done()+ return nil, r.Context().Err()+ })+ u, _ := url.Parse("http://engine.test")+ targets := make([]Target, 20)+ for i := range targets {+ targets[i] = Target{URL: u, Transport: transport}+ }+ ctx, cancel := context.WithCancel(context.Background())+ defer cancel()+ rec := httptest.NewRecorder()+ done := make(chan struct{})+ go func() { ServePreflight(rec, preflight().WithContext(ctx), targets); close(done) }()+ for i := 0; i < 8; i++ {+ select {+ case <-started:+ case <-time.After(time.Second):+ t.Fatal("fanout did not start")+ }+ }+ if max.Load() != 8 {+ t.Fatalf("active maximum %d", max.Load())}- if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "*" {- t.Errorf("Access-Control-Allow-Origin = %q, want *", got)+ cancel()+ select {+ case <-done:+ case <-time.After(time.Second):+ t.Fatal("cancellation blocked")}- if got := resp.Header.Get("Access-Control-Allow-Credentials"); got != "" {- t.Errorf("Access-Control-Allow-Credentials = %q, want cleared alongside the wildcard origin", got)+ if max.Load() > 8 || rec.Code != http.StatusBadGateway {+ t.Fatalf("max=%d status=%d", max.Load(), rec.Code)}}diff --git a/services/shared/cors/preflight.go b/services/shared/cors/preflight.gonew file mode 100644index 0000000..cecea8b--- /dev/null+++ b/services/shared/cors/preflight.go@@ -0,0 +1,114 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package cors++import (+ "context"+ "net/http"+ "net/http/httputil"+ "net/url"+ "sync"+ "time"+)++type Target struct {+ URL *url.URL+ Transport http.RoundTripper+}++// ServePreflight queries a snapshot of routable targets without discovery,+// scheduling, redirects, or cached permissions.+func ServePreflight(w http.ResponseWriter, r *http.Request, targets []Target) {+ ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)+ defer cancel()+ r = r.WithContext(ctx)+ if len(targets) == 0 {+ http.Error(w, "no available engine for preflight", http.StatusBadGateway)+ return+ }+ if len(targets) == 1 {+ target := targets[0]+ proxy := &httputil.ReverseProxy{+ Director: func(req *http.Request) {+ req.URL.Scheme, req.URL.Host, req.Host = target.URL.Scheme, target.URL.Host, target.URL.Host+ },+ Transport: target.Transport,+ ErrorHandler: func(w http.ResponseWriter, _ *http.Request, _ error) {+ http.Error(w, "engine unavailable for preflight", http.StatusBadGateway)+ },+ }+ proxy.ServeHTTP(w, r)+ return+ }+ responses := make([]http.Header, len(targets))+ unavailable := make([]bool, len(targets))+ denied := make([]bool, len(targets))+ querySlots := make(chan struct{}, 8)+ var wg sync.WaitGroup+ for i, target := range targets {+ wg.Add(1)+ go func(i int, target Target) {+ defer wg.Done()+ select {+ case querySlots <- struct{}{}:+ defer func() { <-querySlots }()+ case <-ctx.Done():+ unavailable[i] = true+ return+ }+ req := r.Clone(ctx)+ req.URL.Scheme, req.URL.Host, req.Host = target.URL.Scheme, target.URL.Host, target.URL.Host+ req.RequestURI = ""+ req.Header = FanoutHeaders(r.Header)+ req.Body, req.GetBody, req.ContentLength, req.TransferEncoding = nil, nil, 0, nil+ req.Header.Del("Content-Length")+ transport := target.Transport+ if transport == nil {+ transport = http.DefaultTransport+ }+ resp, err := transport.RoundTrip(req)+ if err != nil {+ unavailable[i] = true+ return+ }+ defer resp.Body.Close()+ responses[i] = EndToEndHeaders(resp.Header)+ // A server error is an engine that could not answer, not one that+ // refused. Keeping these disjoint is what lets the filter below+ // drop silence without dropping a refusal.+ unavailable[i] = resp.StatusCode >= 500+ denied[i] = !unavailable[i] && (resp.StatusCode < 200 || resp.StatusCode >= 300)+ }(i, target)+ }+ wg.Wait()+ for _, rejected := range denied {+ if rejected {+ http.Error(w, "engine denied preflight", http.StatusForbidden)+ return+ }+ }+ // An engine that could not answer expressed no opinion, and the request+ // being preflighted would route around it anyway. Intersecting its absent+ // headers would let one offline node deny the browser every online one.+ // Only a total blackout is an error.+ answered := make([]http.Header, 0, len(responses))+ for i, h := range responses {+ if !unavailable[i] {+ answered = append(answered, h)+ }+ }+ if len(answered) == 0 {+ http.Error(w, "engine unavailable for preflight", http.StatusBadGateway)+ return+ }+ headers, ok := Combine(r, answered)+ if !ok {+ http.Error(w, "engines do not all permit this preflight", http.StatusForbidden)+ return+ }+ for key, values := range headers {+ w.Header()[key] = values+ }+ w.WriteHeader(http.StatusNoContent)+}diff --git a/services/shared/enginesettings/hub.go b/services/shared/enginesettings/hub.gonew file mode 100644index 0000000..69e03e6--- /dev/null+++ b/services/shared/enginesettings/hub.go@@ -0,0 +1,42 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package enginesettings++import "sync"++// Hub sends full snapshots, so coalescing a slow reader cannot lose a patch.+// Subscribe installs the reader and its baseline under the same lock.+type Hub struct {+ mu sync.Mutex+ latest []Snapshot+ readers map[chan []Snapshot]bool+}++func (h *Hub) Publish(value []Snapshot) {+ h.mu.Lock()+ defer h.mu.Unlock()+ h.latest = append([]Snapshot{}, value...)+ for ch := range h.readers {+ select {+ case <-ch:+ default:+ }+ ch <- append([]Snapshot{}, value...)+ }+}++func (h *Hub) Subscribe() (<-chan []Snapshot, func(), bool) {+ h.mu.Lock()+ defer h.mu.Unlock()+ if len(h.readers) >= 64 {+ return nil, func() {}, false+ }+ if h.readers == nil {+ h.readers = make(map[chan []Snapshot]bool)+ }+ ch := make(chan []Snapshot, 1)+ h.readers[ch] = true+ ch <- append([]Snapshot{}, h.latest...)+ return ch, func() { h.mu.Lock(); delete(h.readers, ch); h.mu.Unlock() }, true+}diff --git a/services/shared/enginesettings/hub_test.go b/services/shared/enginesettings/hub_test.gonew file mode 100644index 0000000..2fbfa8b--- /dev/null+++ b/services/shared/enginesettings/hub_test.go@@ -0,0 +1,41 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package enginesettings++import "testing"++func TestFullBaselineCoalescingAndLimits(t *testing.T) {+ h := &Hub{}+ h.Publish([]Snapshot{{Revision: 1}})+ ch, closeSub, ok := h.Subscribe()+ if !ok || (<-ch)[0].Revision != 1 {+ t.Fatal("baseline missing")+ }+ for i := uint64(2); i < 1000; i++ {+ h.Publish([]Snapshot{{Revision: i}})+ }+ if (<-ch)[0].Revision != 999 {+ t.Fatal("slow subscriber missed latest full state")+ }+ closeSub()+ var closeAll []func()+ for i := 0; i < 64; i++ {+ _, close, ok := h.Subscribe()+ if !ok {+ t.Fatal("early subscriber cap")+ }+ closeAll = append(closeAll, close)+ }+ if _, _, ok := h.Subscribe(); ok {+ t.Fatal("unbounded subscribers")+ }+ for _, close := range closeAll {+ close()+ }+ if _, close, ok := h.Subscribe(); !ok {+ t.Fatal("cleanup leaked capacity")+ } else {+ close()+ }+}diff --git a/services/shared/enginesettings/settings.go b/services/shared/enginesettings/settings.gonew file mode 100644index 0000000..7de762c--- /dev/null+++ b/services/shared/enginesettings/settings.go@@ -0,0 +1,93 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++// Package enginesettings is the node-owned engine settings wire contract.+package enginesettings++type Config struct {+ ServerPort int `json:"serverPort"`+ ProxyPort int `json:"proxyPort"`+ // Arguments and leading environment assignments; excludes the executable+ // and manifest-owned startup subcommand. Snapshot.Format identifies syntax.+ LaunchText string `json:"launchText"`+}++type Request struct {+ NodeID string `json:"nodeId,omitempty"`+ Engine string `json:"engine"`+ ExpectedRevision uint64 `json:"expectedRevision"`+ RequestID string `json:"requestId,omitempty"`+ Settings Config `json:"settings"`+ Resolution string `json:"resolution,omitempty"`+ // Format is supplied only when migrating a saved full-command journal.+ Format string `json:"format,omitempty"`+ // Internal preview guard, overwritten by the broker from the authenticated+ // caller. Client input cannot disable the target's local-only CORS policy.+ PreserveCORS bool `json:"preserveCORS,omitempty"`+}++type Snapshot struct {+ NodeID string `json:"nodeId"`+ Engine string `json:"engine"`+ Revision uint64 `json:"revision"`+ AppliedRevision uint64 `json:"appliedRevision"`+ Sequence uint64 `json:"sequence"`+ Epoch string `json:"epoch"`+ Settings Config `json:"settings"`+ EffectiveServerPort int `json:"effectiveServerPort"`+ EffectiveProxyPort int `json:"effectiveProxyPort"`+ Running bool `json:"running"`+ Adopted bool `json:"adopted"`+ Editable bool `json:"editable"`+ Reason string `json:"reason,omitempty"`+ Format string `json:"format"`+ Phase string `json:"phase"`+ Error string `json:"error,omitempty"`+ RequestID string `json:"requestId,omitempty"`+}++type Conflict struct {+ ServerPort int `json:"serverPort"`+ LaunchPort int `json:"launchPort"`+}++type Preview struct {+ Settings Config `json:"settings"`+ Revision uint64 `json:"revision"`+ Conflict *Conflict `json:"conflict,omitempty"`+ Errors map[string]string `json:"errors,omitempty"`+ Restart bool `json:"restart"`+ Rebind bool `json:"rebind"`+ // Named to match Runtime's persisted override keys: these carry the same+ // user-supplied launch content, and a log sink redacts them by key. Plain+ // "args"/"env" would collide with every worker-spawn diagnostic.+ Args []string `json:"launch_args"`+ Env []string `json:"launch_env"`+}++type LaunchState struct {+ Engine string `json:"engine"`+ ServerPort int `json:"serverPort"`+ EffectivePort int `json:"effectivePort"`+ LaunchText string `json:"launchText"`+ Running bool `json:"running"`+ Adopted bool `json:"adopted"`+ Editable bool `json:"editable"`+ Reason string `json:"reason,omitempty"`+ Format string `json:"format"`+}++type Configure struct {+ Engine string `json:"engine"`+ Settings Config `json:"settings"`+ OperationID string `json:"operationId"`+ Resume bool `json:"resume,omitempty"`+}++// Relay is a correlated worker-to-parent request. It never blocks a reader.+type Relay struct {+ ID string `json:"id"`+ Method string `json:"method"`+ Caller string `json:"caller,omitempty"`+ Request Request `json:"request"`+}diff --git a/services/shared/enginesettings/timeouts.go b/services/shared/enginesettings/timeouts.gonew file mode 100644index 0000000..448da79--- /dev/null+++ b/services/shared/enginesettings/timeouts.go@@ -0,0 +1,17 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++package enginesettings++import "time"++// Settings calls wait for stop, rebind, and readiness. The bundled Ollama+// probe permits ten minutes; configure adds time for stop and rebind, and+// each caller leaves headroom for the layer it waits on. Desktop's outer+// envelope is fourteen minutes (modular-runtime.ts).+const (+ ConfigureBudget = 10*time.Minute + 30*time.Second+ OperationBudget = ConfigureBudget + 30*time.Second+ CallBudget = OperationBudget + time.Minute+ RelayBudget = CallBudget + time.Minute+)diff --git a/services/tests/broker_supervision_test.go b/services/tests/broker_supervision_test.goindex 7eb37e6..87a9fce 100644--- a/services/tests/broker_supervision_test.go+++ b/services/tests/broker_supervision_test.go@@ -409,7 +409,9 @@ func TestBrokerSpawnsAllModules(t *testing.T) {_ = stdint.Cleanup(cleanup)- waitForMethod(t, msgs, "app:ready", 10*time.Second)+ // Native engine detection and managed-port preparation run before ready.+ // Allow those bounded probes to finish on a host with installed engines.+ waitForMethod(t, msgs, "app:ready", 30*time.Second)// Each supervised worker logs "<name> started" on spawn (before any// bind), so these lines appear regardless of later port conflicts.diff --git a/services/tests/cluster_data_plane_test.go b/services/tests/cluster_data_plane_test.goindex 901e690..962c876 100644--- a/services/tests/cluster_data_plane_test.go+++ b/services/tests/cluster_data_plane_test.go@@ -226,9 +226,10 @@ func TestModelInventoryRefusesLANPlaintext(t *testing.T) {t.Skip("engine-manager em port 14322 already in use; skipping")}- // startBrokerProc pins an empty cluster dir, so this node is a non-member.- _, msgs, cleanup := startBrokerProc(t,- "--scanner-path", scannerBin,+ // Isolate both cluster identity and engine desired state. A developer's+ // saved enabled engine can otherwise start here and block inventory reads+ // behind restoration, even though this test only exercises ingress policy.+ _, msgs, _, cleanup := startBrokerWith(t,"--engine-manager-path", engineMgrBin,)t.Cleanup(cleanup)diff --git a/services/versions.json b/services/versions.jsonindex cdc9bd6..a439186 100644--- a/services/versions.json+++ b/services/versions.json@@ -1,17 +1,17 @@{"$comment": "Single source of truth for all version numbers. See VERSIONING.md for bump rules.",- "product": "1.1.0",- "installer": "1.1.0",+ "product": "1.2.0",+ "installer": "1.2.0","components": {- "nvpair-proxy": "1.1.0",+ "nvpair-proxy": "1.2.0","nvpair-node-info": "0.13.3","nvpair-node-scanner": "0.20.3","nvpair-manual-nodes": "0.11.1","nvpair-workload-manager": "0.14.0","nvpair-errors": "0.7.4","nvpair-node-settings": "1.0.4",- "nvpair-ui-broker": "1.1.0",- "nvpair-engine-manager": "0.17.4",+ "nvpair-ui-broker": "1.2.0",+ "nvpair-engine-manager": "0.18.0","nvpair-cluster-manager": "1.1.4","nvpair-job-scheduler": "0.4.2","nvpair-tui": "0.7.3"