amicus 4.1.2 → 4.2.1

package/src/utils/env-raw-store.js

@@ -0,0 +1,120 @@
+/**
+ * Arbitrary-env-var writes to the amicus .env (local-provider bearers, v4.2 §4.6).
+ * Split out of api-key-store.js to keep that file under the 300-line gate (B2/D3).
+ * The upsertEnvLine/deleteEnvLine merge helpers here are the SINGLE copy of the
+ * .env line-merge logic: saveApiKey/removeApiKey in api-key-store.js call them too
+ * (deduped, not copy-pasted). getEnvPath is required LAZILY inside each writer so
+ * api-key-store.js can re-export from here without a load-time require cycle.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Env-var names are UPPER_SNAKE, leading letter (mirrors POSIX + saveApiKey inputs). */
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Upsert `envVar=value` into the .env at envPath: preserve comments/other lines,
+ * dedup by REPLACING an existing `<envVar>=` line rather than appending a second,
+ * strip trailing blank lines before an append, write 0600 with a trailing newline.
+ * @param {string} envPath
+ * @param {string} envVar
+ * @param {string} value
+ */
+function upsertEnvLine(envPath, envVar, value) {
+  // Strip CR/LF: a newline in the value corrupts the line-based .env (splits it,
+  // or bakes a trailing CR into the persisted/served token). Bearer/API-key schemes
+  // never contain newlines, so stripping cannot damage a legitimate token.
+  const clean = String(value).replace(/[\r\n]/g, '');
+  fs.mkdirSync(path.dirname(envPath), { recursive: true });
+
+  let lines = [];
+  try {
+    if (fs.existsSync(envPath)) {
+      lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+    }
+  } catch (_err) {
+    // Start fresh
+  }
+
+  let found = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith(envVar + '=')) {
+      lines[i] = `${envVar}=${clean}`;
+      found = true;
+      break;
+    }
+  }
+  if (!found) {
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+      lines.pop();
+    }
+    lines.push(`${envVar}=${clean}`);
+  }
+
+  fs.writeFileSync(envPath, lines.join('\n') + '\n', { mode: 0o600 });
+  // writeFileSync's mode only applies on CREATE; re-assert 0600 so an existing
+  // secrets file whose perms drifted is re-tightened. Best-effort (no-op on Windows).
+  try { fs.chmodSync(envPath, 0o600); } catch (_err) { /* perms best-effort */ }
+  return clean;
+}
+
+/**
+ * Remove any `envVar=` line from the .env at envPath (best-effort): preserves the
+ * other lines, strips trailing blanks, writes 0600 with a trailing newline (or an
+ * empty file when nothing remains). No-op when the file is absent.
+ * @param {string} envPath
+ * @param {string} envVar
+ */
+function deleteEnvLine(envPath, envVar) {
+  try {
+    if (fs.existsSync(envPath)) {
+      const lines = fs.readFileSync(envPath, 'utf-8').split('\n')
+        .filter((line) => !line.trim().startsWith(envVar + '='));
+      while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+        lines.pop();
+      }
+      fs.writeFileSync(envPath, lines.length > 0 ? lines.join('\n') + '\n' : '', { mode: 0o600 });
+      try { fs.chmodSync(envPath, 0o600); } catch (_err) { /* perms best-effort */ }
+    }
+  } catch (_err) {
+    // Best-effort
+  }
+}
+
+/**
+ * Write an arbitrary env-var line to the amicus .env (local-provider bearers).
+ * Keyed on the env-var NAME directly (no PROVIDER_ENV_MAP), so it can persist
+ * `LAB_API_KEY`, `VLLM_LAB_API_KEY`, ... Validates the name and returns
+ * `{success:false, error}` WITHOUT throwing so callers can bail before saving a
+ * config entry that references a rejected name. Mirrors the value into process.env.
+ * @param {string} envVar e.g. 'LAB_API_KEY'
+ * @param {string} value bearer token
+ * @returns {{success: boolean, error?: string}}
+ */
+function saveRawEnv(envVar, value) {
+  if (typeof envVar !== 'string' || !ENV_VAR_RE.test(envVar)) {
+    return { success: false, error: `Invalid env var name: ${envVar}` };
+  }
+  const { getEnvPath } = require('./api-key-store'); // lazy: avoids a load-time cycle
+  const clean = upsertEnvLine(getEnvPath(), envVar, value);
+  process.env[envVar] = clean; // mirror the sanitized on-disk value
+  return { success: true };
+}
+
+/**
+ * Remove an arbitrary env-var line from the amicus .env (local-provider bearers).
+ * No auth.json reconciliation — that store is keyed on the 5 static vendors, and a
+ * local provider never has an entry there.
+ * @param {string} envVar e.g. 'LAB_API_KEY'
+ * @returns {{success: boolean}}
+ */
+function removeRawEnv(envVar) {
+  const { getEnvPath } = require('./api-key-store'); // lazy: avoids a load-time cycle
+  deleteEnvLine(getEnvPath(), envVar);
+  delete process.env[envVar];
+  return { success: true };
+}
+
+module.exports = { saveRawEnv, removeRawEnv, upsertEnvLine, deleteEnvLine };

package/src/utils/gateway-router.js

@@ -16,6 +16,59 @@ function executableFor(gateway, vendor, model) {
   return gateway === 'openrouter' ? `openrouter/${vendor}/${model}` : `${vendor}/${model}`;
 }
 
+/** Per-flavor remediation hint for an unreachable local endpoint / missing model. */
+function localHint(entry, kind) {
+  const f = entry && entry.flavor;
+  if (kind === 'unreachable') {
+    if (f === 'ollama') { return 'Is Ollama running? `ollama serve`'; }
+    if (f === 'lmstudio') { return 'Start the LM Studio server (Developer → Start Server).'; }
+    return `Check the server at ${entry && entry.baseURL}.`;
+  }
+  // model_not_found
+  return f === 'ollama' ? `Model not pulled — \`ollama pull ${(entry && entry.model) || '<model>'}\`.`
+    : `Load the model in ${f === 'lmstudio' ? 'LM Studio' : 'the server'} first.`;
+}
+
+/**
+ * Local-provider branch (v4.2 §4.2). The vendor is a configured local provider
+ * (key in req.localProviders). Returns a RouteResult; never consults the cached
+ * catalog (route-time truth is the injected live probe).
+ */
+function resolveLocal(d, req) {
+  const entry = req.localProviders[d.vendor];
+  const executableId = executableFor('direct', d.vendor, d.model); // `<id>/<model>`, no openrouter/ prefix
+  // 1. OpenRouter is never a local route.
+  if (d.isExplicitOpenRouter || req.gatewayMode === 'openrouter') {
+    return routeError({ requested: d.raw, reason: 'no_openrouter_route', preferredGateway: 'direct', suggestions: [] });
+  }
+  // 2. Declared-but-missing bearer.
+  if (entry.apiKeyEnv && !entry.keyPresent) {
+    return routeError({ requested: d.raw, reason: 'no_local_key', preferredGateway: 'direct', suggestions: [] });
+  }
+  const live = req.localLive || { status: 'skipped', models: [] };
+  // 3. Unreachable (never reached under --no-validate-model — status is 'skipped' then).
+  if (live.status === 'unreachable') {
+    const e = routeError({ requested: d.raw, reason: 'local_endpoint_unreachable', preferredGateway: 'direct', suggestions: [] });
+    e.hint = localHint(entry, 'unreachable');
+    return e;
+  }
+  // 4. Reachable but the model is absent from the live roster.
+  if (live.status === 'ok' && !live.models.includes(executableId)) {
+    if (req.allowSelection) {
+      const suggestions = live.models.slice(0, 6).map((id) => ({ model: id, gateway: 'local', note: 'available locally' }));
+      return selectionRequired({ requested: d.raw, suggestions });
+    }
+    const e = routeError({ requested: d.raw, reason: 'model_not_found', preferredGateway: 'direct', suggestions: [] });
+    e.hint = localHint({ ...entry, model: d.model }, 'model_not_found');
+    return e;
+  }
+  // 5. Resolve. status 'skipped' → unverified notice (tri-state 'unknown').
+  const notice = live.status === 'skipped'
+    ? 'Local endpoint unverified (--no-validate-model); attempting anyway.' : undefined;
+  return resolved({ model: executableId, gateway: 'local', executableId,
+    provenance: { source: req.source, requested: d.raw, gatewayMode: req.gatewayMode }, notice });
+}
+
 /**
  * Catalog gate: returns { ok:true, notice? } to proceed, or { ok:false, result }
  * carrying a selection_required/error to return to the caller.
@@ -78,16 +131,26 @@ function resolveRoute(req) {
   const model = d.model;
 
   // 2. Explicit conflict: force-OR literal vs --gateway direct
-  if (d.isExplicitOpenRouter && rq.gatewayMode === 'direct') {
+  if (d.isExplicitOpenRouter && rq.gatewayMode === 'direct' && !(rq.localProviders && Object.prototype.hasOwnProperty.call(rq.localProviders, vendor))) {
     return routeError({ requested: d.raw, reason: 'gateway_conflict', preferredGateway: 'direct', suggestions: [] });
   }
   // 3. Explicit OR literal
-  if (d.isExplicitOpenRouter) {
+  if (d.isExplicitOpenRouter && !(rq.localProviders && Object.prototype.hasOwnProperty.call(rq.localProviders, vendor))) {
     if (!rq.keys.openrouter) {
       return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
     }
     return finish('openrouter', vendor, model, rq);
   }
+  // 3.5 Local / OpenAI-compatible provider (v4.2 §4.2). Placed before the
+  // gateway-only-vendor check so a local id shadows an OR vendor namespace for
+  // bare descriptors (resolved Q6). Steps 2 and 3 above are BYPASSED for a local
+  // vendor (see the two guards above), so an explicit openrouter/<id>/... literal
+  // — with any gatewayMode — falls through to here and resolveLocal returns
+  // no_openrouter_route. Grammar still outranks shadowing; it just reports the
+  // local-specific reason instead of no_openrouter_key / gateway_conflict.
+  if (rq.localProviders && Object.prototype.hasOwnProperty.call(rq.localProviders, vendor)) {
+    return resolveLocal(d, rq);
+  }
   // 4. Gateway-only vendor (no direct integration)
   if (!isDirectProvider(vendor)) {
     if (rq.gatewayMode === 'direct') {

package/src/utils/lifecycle.js

@@ -12,7 +12,8 @@
 // when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
 // `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
 // interactive Electron flow that must never be force-exited).
-const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor', 'spend' /* local-only: no OpenCode server, no stray handles */]);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor', 'spend', 'provider', /* provider: runs a 2s socket probe (M11) — arm the watchdog so a stray handle can't hang the shell */
+  'init' /* init (Task 15): runs the full doctor-check suite (network probes, OpenCode binary scan) via summarizeDoctor's runDoctorChecks() call — same lingering-handle risk 'doctor' already guards against */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {

package/src/utils/local-probe.js

@@ -0,0 +1,109 @@
+// src/utils/local-probe.js
+'use strict';
+
+/**
+ * @module local-probe
+ * Scheme-aware (http/https) bounded GET for local / OpenAI-compatible servers
+ * (v4.2 §3 http-fix, §4.2 route-time probe, §4.4 catalog rows). Fixes the
+ * model-fetcher https-only silent-[] bug for local http endpoints. No redirects
+ * followed; bearer attached only to the configured origin; Authorization never
+ * logged. Never throws — every failure resolves to unreachable / [].
+ */
+
+const http = require('http');
+const https = require('https');
+
+/** GET JSON with a hard timeout; no redirect follow. Resolves {status, body} or {status:0}. */
+function getJson(url, { timeoutMs, bearer }) {
+  return new Promise((resolve) => {
+    try {
+      const parsed = new URL(url);
+      // Scheme allowlist: http:/https: only. Handing a non-http(s) URL straight to
+      // http.get/https.get is not safe to rely on — Node validates the URL's own embedded
+      // protocol against the module and throws ERR_INVALID_PROTOCOL synchronously for a
+      // mismatch (e.g. file:, ftp:, javascript:), which would otherwise reject this promise
+      // instead of resolving it. Reject the scheme ourselves, before any module dispatch.
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') { resolve({ status: 0 }); return; }
+      const mod = parsed.protocol === 'https:' ? https : http;
+      const headers = bearer ? { Authorization: `Bearer ${bearer}` } : {};
+      let body = '';
+      const req = mod.get(url, { headers }, (res) => {
+        const status = res.statusCode || 0;
+        // Non-200 (incl. 3xx redirects — NOT followed) → drain + report status, no body parse.
+        if (status !== 200) { res.on('data', () => {}); res.on('end', () => resolve({ status })); return; }
+        res.on('data', (c) => { body += c; });
+        res.on('end', () => { try { resolve({ status, body: JSON.parse(body) }); } catch { resolve({ status: 0 }); } });
+      });
+      const timer = setTimeout(() => { req.destroy(); resolve({ status: 0 }); }, timeoutMs);
+      req.on('error', () => { clearTimeout(timer); resolve({ status: 0 }); });
+      req.on('close', () => clearTimeout(timer));
+    } catch {
+      // Belt and braces: this module's contract is "never throws". Any other synchronous
+      // throw we haven't explicitly enumerated (malformed input, etc.) must still resolve.
+      resolve({ status: 0 });
+    }
+  });
+}
+
+/** Trim a trailing `/v1` (or `/`) off the baseURL to get the server origin for /api/tags. */
+function originOf(baseURL) {
+  try { const u = new URL(baseURL); return `${u.protocol}//${u.host}`; } catch { return baseURL; }
+}
+
+/** OpenAI /v1/models body → ['<id>/<model>', ...]. */
+function idsFromV1(id, body) {
+  const data = (body && Array.isArray(body.data)) ? body.data : [];
+  return data.map((m) => m && m.id).filter(Boolean).map((name) => `${id}/${name}`);
+}
+
+/** Ollama /api/tags body → ['<id>/<model>', ...]. */
+function idsFromTags(id, body) {
+  const models = (body && Array.isArray(body.models)) ? body.models : [];
+  return models.map((m) => m && m.name).filter(Boolean).map((name) => `${id}/${name}`);
+}
+
+/**
+ * Route-time reachability probe (spec §4.2). Never throws.
+ * @param {{id:string, baseURL:string, flavor?:string}} entry
+ * @param {{timeoutMs?:number, bearer?:string}} [opts]
+ * @returns {Promise<{status:'ok'|'unreachable', models:string[]}>}
+ */
+async function probeLocalProvider(entry, opts = {}) {
+  // Finding 1 (CRITICAL): entry.baseURL.replace(...) below ran before getJson was ever
+  // called and outside any try/catch — a missing/null/non-string baseURL (or a missing
+  // entry altogether) threw synchronously inside this async function, which rejected the
+  // returned promise instead of resolving the documented unreachable/[] shape. This is the
+  // same defect shape as the scheme bug already fixed in getJson, one field over: that fix
+  // guards the URL's *scheme*; this guards entry.baseURL's *shape*, before it ever reaches
+  // getJson. listLocalModels (below) inherits the fix by calling through this function.
+  if (!entry || typeof entry.baseURL !== 'string' || !entry.baseURL) { return { status: 'unreachable', models: [] }; }
+  const timeoutMs = opts.timeoutMs || 2000;
+  const bearer = opts.bearer;
+  const primary = await getJson(`${entry.baseURL.replace(/\/$/, '')}/models`, { timeoutMs, bearer });
+  if (primary.status === 200) { return { status: 'ok', models: idsFromV1(entry.id, primary.body) }; }
+  // Ollama-flavor fallback: older servers answer /api/tags, not /v1/models.
+  if (entry.flavor === 'ollama' && primary.status === 404) {
+    const tags = await getJson(`${originOf(entry.baseURL)}/api/tags`, { timeoutMs, bearer });
+    if (tags.status === 200) { return { status: 'ok', models: idsFromTags(entry.id, tags.body) }; }
+  }
+  return { status: 'unreachable', models: [] };
+}
+
+/**
+ * Catalog rows (spec §4.4). Never throws; [] on any failure.
+ * @param {{id:string, baseURL:string, flavor?:string, pricing?:object}} entry
+ * @param {{timeoutMs?:number, bearer?:string}} [opts]
+ * @returns {Promise<Array<object>>}
+ */
+async function listLocalModels(entry, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 5000;
+  const probe = await probeLocalProvider(entry, { timeoutMs, bearer: opts.bearer });
+  if (probe.status !== 'ok') { return []; }
+  const pricing = entry.pricing || { prompt: 0, completion: 0 };
+  return probe.models.map((id) => ({
+    id, name: id.slice(entry.id.length + 1), contextLength: null, pricing,
+    authoritative: true, local: true,
+  }));
+}
+
+module.exports = { probeLocalProvider, listLocalModels };

package/src/utils/local-providers.js

@@ -0,0 +1,141 @@
+// src/utils/local-providers.js
+'use strict';
+
+/**
+ * @module local-providers
+ * The merge layer beside the static provider-registry (v4.2 §4.1). Reads
+ * user-defined OpenAI-compatible providers from config.providers, validates
+ * and normalizes them. Forgiving: an invalid entry is skipped with a one-line
+ * stderr warning, never fatal (config.js posture). Leaf-ish: only lazy-requires
+ * ./config; NEVER requires provider-registry (no cycle, no static-table edits).
+ */
+
+// Mirrors PROVIDERS ids in provider-registry.js; duplicated (not imported) per the leaf-module rule — update both together.
+const RESERVED_IDS = Object.freeze(['openrouter', 'google', 'openai', 'anthropic', 'deepseek']);
+const VALID_FLAVORS = Object.freeze(['ollama', 'lmstudio', 'vllm', 'generic']);
+const ID_RE = /^[a-z][a-z0-9_-]{1,31}$/;
+
+/**
+ * Preset id → partial entry (baseURL + flavor). ALL THREE carry a baseURL (D15):
+ * vLLM's own default `vllm serve` port is 8000, so `--preset vllm` works alone;
+ * `--url` overrides any preset for a non-default port or a remote host.
+ * 127.0.0.1 never `localhost` (IPv6-first `::1` gotcha, spec §4.1/§4.10).
+ */
+const PRESETS = Object.freeze({
+  ollama: { baseURL: 'http://127.0.0.1:11434/v1', flavor: 'ollama' },
+  lmstudio: { baseURL: 'http://127.0.0.1:1234/v1', flavor: 'lmstudio' },
+  vllm: { baseURL: 'http://127.0.0.1:8000/v1', flavor: 'vllm' },
+});
+
+/** `vllm-lab` → `VLLM_LAB_API_KEY`. @param {string} id @returns {string} */
+function deriveKeyEnv(id) {
+  return `${String(id).toUpperCase().replace(/[^A-Z0-9]/g, '_')}_API_KEY`;
+}
+
+/** Absolute http:/https: only. @param {string} u @returns {boolean} */
+function isAllowedUrl(u) {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch { return false; }
+}
+
+/**
+ * Validate + normalize a provider entry (id-agnostic — id is checked at the map level).
+ * @param {object} entry @returns {{ok:true, normalized:object}|{ok:false, error:string}}
+ */
+function validateProviderEntry(entry) {
+  if (!entry || typeof entry !== 'object') { return { ok: false, error: 'entry must be an object' }; }
+  if (entry.type !== 'openai-compatible') { return { ok: false, error: `unsupported type '${entry.type}'` }; }
+  if (typeof entry.baseURL !== 'string' || !isAllowedUrl(entry.baseURL)) {
+    return { ok: false, error: `baseURL must be an absolute http:/https: URL (got '${entry.baseURL}')` };
+  }
+  const flavor = entry.flavor === undefined ? 'generic' : entry.flavor;
+  if (!VALID_FLAVORS.includes(flavor)) { return { ok: false, error: `invalid flavor '${entry.flavor}'` }; }
+  let pricing = { prompt: 0, completion: 0 };
+  if (entry.pricing !== undefined) {
+    const p = entry.pricing;
+    const prompt = Number(p && p.prompt);
+    const completion = Number(p && p.completion);
+    if (!Number.isFinite(prompt) || !Number.isFinite(completion) || prompt < 0 || completion < 0) {
+      return { ok: false, error: 'pricing.prompt/completion must be non-negative numbers' };
+    }
+    pricing = { prompt, completion };
+  }
+  const normalized = {
+    type: 'openai-compatible',
+    baseURL: entry.baseURL,
+    flavor,
+    name: typeof entry.name === 'string' && entry.name ? entry.name : undefined,
+    apiKeyEnv: typeof entry.apiKeyEnv === 'string' && entry.apiKeyEnv ? entry.apiKeyEnv : undefined,
+    pricing,
+  };
+  return { ok: true, normalized };
+}
+
+/**
+ * Validated, normalized local-provider map from config.providers.
+ * Invalid/reserved/malformed-id entries are skipped with a stderr warning.
+ * @returns {Object<string, object>} id → normalized entry (id stamped on; name defaulted to id)
+ */
+function getLocalProviders() {
+  let config;
+  try { config = require('./config').loadConfig(); } catch { config = null; }
+  const raw = (config && config.providers && typeof config.providers === 'object') ? config.providers : {};
+  const out = {};
+  for (const [id, entry] of Object.entries(raw)) {
+    if (!ID_RE.test(id) || RESERVED_IDS.includes(id)) {
+      process.stderr.write(`Notice: skipping invalid provider id '${id}' in config.providers.\n`);
+      continue;
+    }
+    const v = validateProviderEntry(entry);
+    if (!v.ok) {
+      process.stderr.write(`Notice: skipping provider '${id}' — ${v.error}.\n`);
+      continue;
+    }
+    out[id] = { ...v.normalized, id, name: v.normalized.name || id };
+  }
+  return out;
+}
+
+/** @param {string} id @returns {boolean} */
+function isLocalProvider(id) {
+  return !!id && Object.prototype.hasOwnProperty.call(getLocalProviders(), id);
+}
+
+/**
+ * v4.2: assemble the router's local inputs for one descriptor.
+ * Lives here (not in route-launch.js) so route-launch stays under the 300-line gate.
+ * `providers` is a PARAMETER, not a bare same-module `getLocalProviders()` call, so
+ * callers/tests control the map (cf. B3: bare identifiers are unmockable via the exports object).
+ * @returns {Promise<{localProviders?: Object, localLive?: Object}>} — `{}` for a non-local vendor.
+ */
+async function resolveLocalRouteInputs(descriptor, { validateModel, providers } = {}) {
+  const all = providers || getLocalProviders();
+  const vendor = descriptor && descriptor.vendor;
+  const entry = vendor && all && Object.prototype.hasOwnProperty.call(all, vendor) ? all[vendor] : undefined;
+  if (!entry) { return {}; }
+  let bearer;
+  if (entry.apiKeyEnv) {
+    // Sole source: env-loader.js's loadCredentials() already projects every
+    // configured apiKeyEnv from the .env into process.env at CLI bootstrap.
+    // (B1, whole-branch review: do NOT add a readApiKeyValues()[vendor]
+    // fallback here. That map is keyed only by the 5 static PROVIDER_ENV_MAP
+    // vendor ids, so for a real local id the lookup is always an own-property
+    // miss -- and for a local id colliding with an Object.prototype member
+    // (e.g. 'constructor') it walks the prototype chain to a truthy inherited
+    // value, fabricating a bearer and defeating gateway-router.js's
+    // no_local_key check. Never use a bare `map[vendor]`-shaped lookup here.)
+    bearer = process.env[entry.apiKeyEnv] || undefined;
+  }
+  const localProviders = { [vendor]: { ...entry, keyPresent: !!bearer } };
+  const localLive = validateModel === false
+    ? { status: 'skipped', models: [] }
+    : await require('./local-probe').probeLocalProvider(entry, { timeoutMs: 2000, bearer });
+  return { localProviders, localLive };
+}
+
+module.exports = {
+  getLocalProviders, isLocalProvider, deriveKeyEnv, validateProviderEntry, resolveLocalRouteInputs,
+  PRESETS, RESERVED_IDS, VALID_FLAVORS, ID_RE,
+};

package/src/utils/model-catalog.js

@@ -95,8 +95,12 @@ async function refreshCatalog() {
   // The anthropic rows are a hardcoded zero-network floor: a result containing
   // ONLY them means every network provider failed. Treat that as a failed
   // refresh — never clobber a previously-good cache with the floor (the
-  // "stale cache stands" contract).
-  const networkRows = (models || []).filter(m => m && typeof m.id === 'string' && !m.id.startsWith('anthropic/'));
+  // "stale cache stands" contract). v4.2 §4.4: local rows (local:true) are
+  // ALSO excluded here — a localhost-only refresh (offline except loopback)
+  // must not be counted as a successful network refresh, or it would clobber
+  // a previously-good OpenRouter cache with a local-only catalog.
+  const networkRows = (models || []).filter(m =>
+    m && typeof m.id === 'string' && !m.id.startsWith('anthropic/') && m.local !== true);
   if (networkRows.length === 0) {
     const reason = (models || []).length > 0
       ? 'floor-only: all providers returned no network rows'

package/src/utils/model-fetcher.js

@@ -192,7 +192,17 @@ function providersToFetch(keys) {
 async function fetchAllModels(keys) {
   const providers = providersToFetch(keys);
   const results = await Promise.all(providers.map(p => fetchModelsFromProvider(p, keys[p] || '')));
-  return results.flat();
+  const rows = results.flat();
+  // v4.2 §4.4: append local-provider rows via the scheme-aware probe (5s, [] on failure).
+  try {
+    const { getLocalProviders } = require('./local-providers');
+    const { listLocalModels } = require('./local-probe');
+    const localEntries = Object.values(getLocalProviders());
+    const localResults = await Promise.all(localEntries.map((e) =>
+      listLocalModels(e, { timeoutMs: 5000, bearer: e.apiKeyEnv ? process.env[e.apiKeyEnv] : undefined })));
+    for (const r of localResults) { rows.push(...r); }
+  } catch (_err) { /* local rows are best-effort — never break the cloud catalog */ }
+  return rows;
 }
 
 /**

package/src/utils/pricing.js

@@ -39,14 +39,27 @@ function sumPerMessageUsage(map) {
 function lookupPricing(modelId) {
   if (!modelId) { return null; }
   let cache;
-  try { cache = require('./model-catalog').readCache(); } catch { return null; }
-  if (!cache || !Array.isArray(cache.models)) { return null; }
-  const row = cache.models.find(m => m && m.id === modelId);
-  if (!row || !row.pricing) { return null; }
-  const prompt = Number(row.pricing.prompt);
-  const completion = Number(row.pricing.completion);
-  if (!Number.isFinite(prompt) || !Number.isFinite(completion) || prompt < 0 || completion < 0) { return null; }
-  return { prompt, completion };
+  try { cache = require('./model-catalog').readCache(); } catch { cache = null; }
+  const rows = (cache && Array.isArray(cache.models)) ? cache.models : [];
+  const row = rows.find(m => m && m.id === modelId);
+  if (row && row.pricing) {
+    const prompt = Number(row.pricing.prompt);
+    const completion = Number(row.pricing.completion);
+    if (Number.isFinite(prompt) && Number.isFinite(completion) && prompt >= 0 && completion >= 0) {
+      return { prompt, completion };
+    }
+  }
+  // v4.2 §4.5: local vendor with no catalog row → the provider's configured pricing (default zeros).
+  try {
+    const vendor = modelId.split('/')[0];
+    const { isLocalProvider, getLocalProviders } = require('./local-providers');
+    if (isLocalProvider(vendor)) {
+      const entry = getLocalProviders()[vendor];
+      const p = (entry && entry.pricing) || { prompt: 0, completion: 0 };
+      return { prompt: Number(p.prompt) || 0, completion: Number(p.completion) || 0 };
+    }
+  } catch { /* fall through */ }
+  return null;
 }
 
 /** @returns {{amount:number|null, currency:'USD', source:'reported'|'estimated'|'unknown'}} */
@@ -56,7 +69,8 @@ function resolveLegCost({ reportedCost, tokens, pricing }) {
   }
   if (pricing && tokens) {
     const est = (tokens.input || 0) * pricing.prompt + (tokens.output || 0) * pricing.completion;
-    if (est > 0) { return { amount: est, currency: 'USD', source: 'estimated' }; }
+    // v4.2 §4.5: a genuine $0 estimate is a REAL priced tier (not unknown/null).
+    if (est >= 0) { return { amount: est, currency: 'USD', source: 'estimated' }; }
   }
   return { amount: null, currency: 'USD', source: 'unknown' };
 }

package/src/utils/provider-default-picker.js

@@ -18,6 +18,7 @@ const { resolveTier } = require('./model-tiers');
 const { getCostTier, loadConfig, saveConfig } = require('./config');
 const { pairAcrossGateways } = require('./gateway-route-catalog');
 const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+const { isLocalProvider } = require('./local-providers');
 
 /**
  * @param {{pricing?: {prompt?: string|number|null}|null}|null|undefined} orRow
@@ -97,6 +98,9 @@ function buildRows(catalog, vendor) {
   const catalogInfo = { models: catalog };
   const directPrefix = `${vendor}/`;
   const orPrefix = `openrouter/${vendor}/`;
+  // Hoisted: `vendor` is fixed for the whole call, so this is decided once
+  // rather than re-reading config.providers on every row.
+  const isLocal = isLocalProvider(vendor);
 
   const rows = [];
   const seenIds = new Set();
@@ -112,11 +116,22 @@ function buildRows(catalog, vendor) {
     const orRow = paired.openrouter ? byId.get(paired.openrouter) : null;
     const sourceRow = isDirect ? row : ((paired.direct && byId.get(paired.direct)) || orRow || row);
 
+    // A local vendor (v4.2 §4.5) has no OpenRouter twin BY CONSTRUCTION --
+    // OpenRouter cannot proxy a localhost model -- so `orRow` is always null
+    // here and `pricePerMInputFrom(orRow)` would always be null too, no
+    // matter that the local catalog row carries its own real
+    // `pricing: {prompt:0, completion:0}`. Price local rows from their OWN
+    // pricing (`sourceRow`, which for a local/direct row IS the catalog row
+    // itself) instead. Gated on `isLocal`, NOT on "no OpenRouter twin", so a
+    // direct (non-local) row with no twin still renders `pricePerMInput:
+    // null` (tests/provider-default-picker.test.js:59, pinned).
+    const localPrice = isLocal ? pricePerMInputFrom(sourceRow) : null;
+
     rows.push({
       id: chosenId,
       name: sourceRow.name,
       contextLength: (sourceRow.contextLength === undefined ? null : sourceRow.contextLength),
-      pricePerMInput: pricePerMInputFrom(orRow),
+      pricePerMInput: localPrice !== null ? localPrice : pricePerMInputFrom(orRow),
       isPreselected: false,
     });
   }
@@ -231,4 +246,4 @@ function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true } =
   return { alias: vendor, setAsDefault };
 }
 
-module.exports = { buildProviderDefaultChoices, applyProviderDefault };
+module.exports = { buildProviderDefaultChoices, applyProviderDefault, pricePerMInputFrom };

package/src/utils/provider-default-prompt.js

@@ -17,6 +17,7 @@
 
 const { buildProviderDefaultChoices, applyProviderDefault } = require('./provider-default-picker');
 const { isDirectProvider } = require('./provider-registry');
+const { isLocalProvider } = require('./local-providers');
 
 /** Format a $/M-input price for display; `null`/`undefined` -> 'n/a'. @param {number|null|undefined} pricePerMInput */
 function formatPrice(pricePerMInput) {
@@ -68,8 +69,10 @@ async function promptForChoice(ask, print, choices) {
  * match every OR-namespaced catalog row, "recommended" would be arbitrary,
  * and writing `aliases.openrouter = "<some vendor>/<model>"` would be
  * nonsensical. Per-provider defaults only make sense for DIRECT model
- * vendors (`provider-registry.isDirectProvider`) -- no choices are built, no
- * alias is written, and `config.default` is never seeded for a gateway.
+ * vendors (`provider-registry.isDirectProvider`) and local/OpenAI-compatible
+ * vendors (`local-providers.isLocalProvider`, v4.2 §4.5) -- for any other
+ * (gateway) provider, no choices are built, no alias is written, and
+ * `config.default` is never seeded.
  * @param {string} provider vendor name, e.g. 'anthropic'
  * @param {{interactive?: boolean, ask?: (prompt: string) => Promise<string>,
  *   catalog?: Array<object>, print?: (line: string) => void}} [options]
@@ -80,11 +83,11 @@ async function runProviderDefaultFlow(provider, options = {}) {
   const catalog = Array.isArray(options.catalog) ? options.catalog : [];
   const print = typeof options.print === 'function' ? options.print : () => {};
 
-  if (!isDirectProvider(provider)) {
+  if (!isDirectProvider(provider) && !isLocalProvider(provider)) {
     return {
       chosenId: null,
       setAsDefault: false,
-      summaryLine: 'Per-provider defaults apply to direct provider keys (openai/anthropic/google/deepseek) -- ' +
+      summaryLine: 'Per-provider defaults apply to direct provider keys and local providers -- ' +
         'models routed via OpenRouter use your overall default.',
     };
   }