@zenithfoundry/slm-gate 1.2.1

package/dist/doctor.js

@@ -0,0 +1,338 @@
+/**
+ * Preflight Check (Doctor) Script
+ *
+ * Why it is written this way:
+ * 1. Fail-Fast Diagnostics: Instead of crashing deep within the application logic when a required
+ *    resource is missing (e.g., Ollama is down, port is bound), the `doctor` command acts as a
+ *    proactive health-check.
+ * 2. Actionable Feedback: Every check strictly reports a human-readable success/failure message
+ *    alongside an actionable `Fix` instruction.
+ * 3. Graceful Network Tolerance: It uses non-throwing network checks (catching fetch/net errors)
+ *    so the diagnostic tool itself doesn't crash if the environment is heavily misconfigured.
+ */
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG } from './config.js';
+import { detectHardware, recommendPreset, recommendNumCtx, getPresetRank, MIN_RAM_GB, modelsForRam, ramPresets } from './hardware.js';
+import { isPackageInstall } from './home-dir.js';
+import { getModelsFootprint } from './models/footprint.js';
+import { getProviderRegistry } from './pricing/providers.js';
+import { checkLocalModels } from './setup/local-models.js';
+import { cliCommand, GATE_LOG_FILE, isStoppedByUser, portOwner, probeGate } from './setup/model-gate.js';
+import { findStrandedServers } from './setup/parent-watch.js';
+import { toolSettings, UNROUTABLE_TOOLS } from './setup/tool-settings.js';
+import { listenOnThisComputer } from './utils/local-only.js';
+/**
+ * Checks whether slm-gate's HTTP server could start on a port, by making exactly the binds it makes
+ * (127.0.0.1 and ::1) and closing them again. A plain `listen(port)` would bind every interface, which
+ * macOS allows next to a server bound to 127.0.0.1 only, so a busy port would look free.
+ *
+ * @param port - The network port number to check (e.g., 8788).
+ * @returns A promise resolving to true if the port is free, false otherwise.
+ */
+async function checkPortFree(port) {
+    try {
+        const servers = await listenOnThisComputer({ handler: () => { }, port });
+        await Promise.all(servers.map(server => new Promise(resolve => server.close(resolve))));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Days without a model-gate event before doctor warns that per-prompt savings are not measured. */
+const MODEL_GATE_QUIET_DAYS = 7;
+/**
+ * The newest model-gate event in the ledger, benchmark runs excluded (they are not real traffic).
+ * Opens the ledger read-only: doctor must not create or migrate it, which getDb() would.
+ *
+ * @returns The event's timestamp, null when there is none, or the error that stopped the read.
+ */
+function lastModelGateEventTs() {
+    if (!fs.existsSync(CONFIG.LEDGER_PATH))
+        return { ts: null };
+    let db = null;
+    try {
+        db = new Database(CONFIG.LEDGER_PATH, { readonly: true });
+        const row = db.prepare("SELECT MAX(ts) AS ts FROM events WHERE layer = 'llm' AND (environment IS NULL OR environment != 'bench')").get();
+        return { ts: row.ts };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // A ledger that has never recorded an event has no table yet.
+        return /no such table/i.test(message) ? { ts: null } : { ts: null, error: message };
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * The Langfuse environments the gate's real traffic sits in: every environment in the ledger except
+ * the benchmark's, plus the one new events go to. History can sit apart from new traffic — events
+ * written before LANGFUSE_ENVIRONMENT defaulted to 'slm-gate' stay in 'default', because Langfuse
+ * never moves a score to a new environment.
+ */
+function dashboardEnvironments() {
+    const environments = new Set([CONFIG.LANGFUSE_ENVIRONMENT]);
+    if (!fs.existsSync(CONFIG.LEDGER_PATH))
+        return { environments: [...environments] };
+    let db = null;
+    try {
+        db = new Database(CONFIG.LEDGER_PATH, { readonly: true });
+        const rows = db.prepare("SELECT DISTINCT environment FROM events WHERE environment IS NOT NULL AND environment != 'bench'").all();
+        for (const row of rows)
+            environments.add(row.environment);
+        return { environments: [...environments].sort() };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return /no such table/i.test(message) ? { environments: [...environments] } : { environments: [...environments], error: message };
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Main execution flow for the doctor command.
+ * Sequentially tests critical dependencies: Hardware capabilities, Node version, Environment vars, Ollama and
+ * the configured local models, Downstream MCP config, Ledger write-permissions, and the model gate (running,
+ * or what holds its port). Then prints the setting that points each coding tool at the gate.
+ *
+ * This function will force a process.exit(1) if any issues are detected, preventing the application
+ * from starting in a broken state.
+ *
+ * @example
+ * // Usually invoked via CLI
+ * // $ node dist/cli.js doctor
+ * run().catch(err => console.error(err));
+ */
+async function run() {
+    console.log('=== SMALL-LANGUAGE-MODEL-GATE DOCTOR ===\n');
+    let issues = 0;
+    /**
+     * Helper to format and track the result of a single check.
+     */
+    function report(success, msg, fix) {
+        if (success) {
+            console.log(`✓ ${msg}`);
+        }
+        else {
+            console.log(`✗ ${msg}`);
+            if (fix)
+                console.log(`  Fix: ${fix}`);
+            issues++;
+        }
+    }
+    // 0. Hardware Check
+    const hw = detectHardware();
+    report(true, `Hardware: ${hw.totalRamGB}GB RAM, ${hw.arch}, ${hw.accelerator} accelerator${hw.unifiedMemory ? ' (Unified Memory)' : ''}`);
+    report(hw.totalRamGB >= MIN_RAM_GB, `At least ${MIN_RAM_GB} GB of RAM (found ${hw.totalRamGB} GB)`, `slm-gate needs ${MIN_RAM_GB} GB of RAM or more, to keep both local models loaded next to your other apps.`);
+    const recPreset = recommendPreset(hw.totalRamGB);
+    const recNumCtx = recommendNumCtx(hw.totalRamGB);
+    report(true, `Recommended settings: RAM_PRESET=${recPreset}, NUM_CTX=${recNumCtx}`);
+    // Compare the user's specifically configured models against the defaults for their preset
+    // This highlights potential mismatches where a user expects the performance of a preset but has overridden the models
+    const defaultModelsForPreset = ramPresets[CONFIG.RAM_PRESET] || ramPresets['custom'];
+    if (CONFIG.SLM_BRAIN_MODEL !== defaultModelsForPreset.brain || CONFIG.SLM_GATE_MODEL !== defaultModelsForPreset.gate) {
+        console.log(`  Note: Configured models (${CONFIG.SLM_BRAIN_MODEL} + ${CONFIG.SLM_GATE_MODEL}) differ from preset defaults (${defaultModelsForPreset.brain} + ${defaultModelsForPreset.gate})`);
+    }
+    let memoryWarning = false;
+    // Above 128 GB the recommendation is `custom`, and every preset fits.
+    const recRank = recPreset === 'custom' ? Infinity : getPresetRank(recPreset);
+    const curRank = getPresetRank(CONFIG.RAM_PRESET);
+    if (recRank < curRank) {
+        memoryWarning = true;
+    }
+    if (!memoryWarning && CONFIG.SLM_PROVIDER === 'ollama') {
+        try {
+            const footprint = await getModelsFootprint([CONFIG.SLM_BRAIN_MODEL, CONFIG.SLM_GATE_MODEL]);
+            const totalBytes = Object.values(footprint).reduce((a, b) => a + b, 0);
+            let totalGB = totalBytes / (1024 * 1024 * 1024);
+            // If footprint is 0 (Ollama down or models not pulled yet), estimate sizes from the model name's parameter count
+            if (totalGB === 0) {
+                // Heuristic: ~0.7GB per billion parameters (typical for 4-bit/5-bit quants)
+                const est = (m) => { const match = m.match(/(\d+(?:\.\d+)?)b/i); return match ? parseFloat(match[1]) * 0.7 : 0; };
+                totalGB = est(CONFIG.SLM_BRAIN_MODEL) + est(CONFIG.SLM_GATE_MODEL);
+            }
+            // Warn if the combined model sizes exceed 70% of total physical RAM
+            if (totalGB > hw.totalRamGB * 0.7) {
+                memoryWarning = true;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    // If a memory constraint is detected, actively intervene by writing a known-safe fallback configuration
+    // The system or user can then choose to load this fallback instead of crashing
+    if (memoryWarning) {
+        const fallbackModels = modelsForRam(hw.totalRamGB);
+        const fallbackConfig = {
+            RAM_PRESET: recPreset,
+            SLM_BRAIN_MODEL: fallbackModels.brain,
+            SLM_GATE_MODEL: fallbackModels.gate,
+            NUM_CTX: recNumCtx
+        };
+        const fallbackPath = path.join(CONFIG.HOME_DIR, '.slm-gate-fallback.json');
+        fs.writeFileSync(fallbackPath, JSON.stringify(fallbackConfig, null, 2));
+        report(false, `Memory constraint: Current models/preset likely exceed available memory (eviction/thrash risk).`, `A safe fallback config was written to .slm-gate-fallback.json`);
+    }
+    // 1. Node version check
+    // Node 22 is the floor set by package.json `engines`: better-sqlite3 >= 13 (N-API prebuilds)
+    // requires it, and it is the oldest release still receiving prebuilt binaries.
+    const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+    report(nodeMajor >= 22, `Node version ≥ 22 (found v${process.versions.node})`, 'Upgrade Node.js to v22 or later.');
+    // 2. .env presence and CONFIG parsing
+    // Validates that the configuration template has been implemented by the user.
+    const envPath = path.join(CONFIG.HOME_DIR, '.env');
+    const envExists = fs.existsSync(envPath);
+    report(envExists, '.env file is present', 'Copy .env.example to .env and configure it.');
+    report(true, 'Configuration parses successfully'); // If we reached here without throwing, CONFIG parsed correctly.
+    // 3. Ollama and the local models the settings name (the same check the MCP server runs at start-up).
+    if (CONFIG.SLM_PROVIDER === 'ollama') {
+        const models = await checkLocalModels();
+        for (const problem of models.problems)
+            report(false, problem.message, problem.fix);
+        if (models.problems.length === 0) {
+            report(true, `Ollama is running at ${CONFIG.OLLAMA_HOST} and has every local model the settings name`);
+        }
+    }
+    else {
+        report(true, `SLM_PROVIDER is openai; assuming SLM endpoint is reachable.`);
+    }
+    // No cloud key is checked: the model gate forwards each coding tool's own login. CLOUD_* is read only by
+    // the benchmark, the optional resolver cloud tier and an OpenAI-compatible SLM_PROVIDER.
+    // 6 & 7. Downstream MCP Configuration & TLS Adapter rules
+    // Ensures that if the user explicitly enabled the TLS adapter, the downstream MCP target is physically present on disk.
+    if (CONFIG.DOWNSTREAM_MCP) {
+        report(true, 'DOWNSTREAM_MCP is configured');
+        if (CONFIG.DOWNSTREAM_MCP.command) {
+            // For Stdio MCP servers, the first argument is conventionally the target script.
+            const cmdArgs = CONFIG.DOWNSTREAM_MCP.args || [];
+            const targetFile = cmdArgs[0];
+            if (targetFile) {
+                const resolvedTarget = path.resolve(targetFile);
+                const targetExists = fs.existsSync(resolvedTarget);
+                let fixMsg = `Ensure the file exists at ${resolvedTarget}`;
+                if (!targetExists && resolvedTarget.includes('tech-lead-stack') && resolvedTarget.includes('mcp-server.mjs')) {
+                    const tlsDir = resolvedTarget.split('/dist/')[0];
+                    fixMsg = `build it: cd ${tlsDir} && pnpm run mcp:build`;
+                }
+                report(targetExists, `DOWNSTREAM_MCP target file exists (${resolvedTarget})`, fixMsg);
+            }
+        }
+    }
+    else {
+        report(!CONFIG.TLS_ADAPTER, 'DOWNSTREAM_MCP is blank (standalone mode)', 'TLS_ADAPTER=on requires DOWNSTREAM_MCP to be set');
+    }
+    // 8. SQLite Ledger path & permissions
+    // MCP hosts (Claude Desktop among them) spawn the gate with a working directory that may not
+    // exist. A cwd-relative LEDGER_PATH therefore passes here — doctor runs from the repo — and
+    // ENOENTs inside the host, so only an absolute path is accepted.
+    if (!path.isAbsolute(CONFIG.LEDGER_PATH)) {
+        report(false, `Ledger path is a full path (${CONFIG.LEDGER_PATH})`, `Set LEDGER_PATH to a full path on this machine, e.g. ${path.join(CONFIG.OUTPUT_DIR, 'ledger.sqlite')} — or leave it blank to use that default.`);
+    }
+    else {
+        const ledgerDir = path.dirname(CONFIG.LEDGER_PATH);
+        try {
+            if (!fs.existsSync(ledgerDir)) {
+                fs.mkdirSync(ledgerDir, { recursive: true });
+            }
+            fs.accessSync(ledgerDir, fs.constants.W_OK);
+            report(true, `Ledger path is writable (${CONFIG.LEDGER_PATH})`);
+        }
+        catch (e) {
+            report(false, `Ledger path is not writable (${CONFIG.LEDGER_PATH})`, 'Fix permissions for the output directory.');
+        }
+    }
+    // 8b. Window budgets. Without one, that provider's cycle cards never fill in.
+    // A note, not a failure: the gate itself works fine without them.
+    const cycleCards = { claude: 'Claude', chatgpt: 'ChatGPT', gemini: 'Gemini' };
+    const registry = getProviderRegistry();
+    for (const [id, label] of Object.entries(cycleCards)) {
+        if (!registry[id]?.windowBudget) {
+            console.log(`  Note: ${id.toUpperCase()}_WINDOW_BUDGET is not set, so both "${label} Cycle" cards (Est. Seconds Saved / Est. Minutes Saved) will stay empty.`);
+        }
+    }
+    // 9. The model gate: every coding tool pointed at it fails while it is down, so this warns loudly.
+    const gatePort = CONFIG.MODEL_GATE_PORT;
+    const gateAddress = `http://localhost:${gatePort}`;
+    const toolsFail = `EVERY CODING TOOL POINTED AT ${gateAddress} CANNOT REACH ITS AI PROVIDER.`;
+    const [start, restart, doctor] = [cliCommand('start'), cliCommand('restart'), cliCommand('doctor')];
+    const repair = isPackageInstall(CONFIG.ROOT_DIR)
+        ? '`npm install -g @zenithfoundry/slm-gate@latest`'
+        : `\`cd ${CONFIG.ROOT_DIR} && pnpm install && pnpm run build\``;
+    const reinstall = `If it still does not start, see ${GATE_LOG_FILE}; a broken install is repaired with ${repair}, then \`${restart}\`.`;
+    const gate = await probeGate({ port: gatePort });
+    if (gate.kind === 'slm-gate') {
+        report(true, `Model gate is running on ${gateAddress} (pid ${gate.health.pid}, started ${gate.health.startedAt})`);
+        if (gate.stale) {
+            report(false, 'The running model gate is an older slm-gate build than the one installed', `\`${restart}\` when no coding tool is in the middle of an answer.`);
+        }
+    }
+    else if (gate.kind === 'other') {
+        const owner = portOwner(gatePort) ?? 'another program';
+        report(false, `MODEL GATE CANNOT RUN: port ${gatePort} is taken by ${owner}. ${toolsFail}`, `Either quit ${owner}, then run \`${start}\`. Or move the gate to a free port: set LLM_GATE_PORT=<new port> in ${path.join(CONFIG.HOME_DIR, '.env')}, run \`${restart}\`, then run \`${doctor}\` again, paste the new lines below into each coding tool and restart them.`);
+    }
+    else if (isStoppedByUser()) {
+        report(false, `MODEL GATE IS STOPPED (you ran \`slm-gate stop\`). ${toolsFail}`, `\`${start}\` (it also starts again by itself after a reboot). ${reinstall}`);
+    }
+    else {
+        const startsItself = CONFIG.LLM_GATE_AUTOSTART
+            ? `It starts by itself when a coding tool starts slm-gate's MCP server; to start it now run \`${start}\`.`
+            : `LLM_GATE_AUTOSTART is off, so nothing starts it for you: run \`${start}\`.`;
+        report(false, `MODEL GATE IS NOT RUNNING on ${gateAddress}. ${toolsFail}`, `${startsItself} ${reinstall}`);
+    }
+    if (CONFIG.MCP_GATE_TRANSPORT === 'http') {
+        const mcpPortFree = await checkPortFree(CONFIG.MCP_GATE_PORT);
+        report(mcpPortFree, `MCP_GATE_PORT (${CONFIG.MCP_GATE_PORT}) is free`, `Kill the process using port ${CONFIG.MCP_GATE_PORT}`);
+    }
+    // 9b. MCP servers whose coding tool went away. Current builds stop themselves; ones started by an
+    // older build cannot, and go on checking Ollama and showing notifications until the next reboot.
+    const stranded = findStrandedServers();
+    report(stranded.length === 0, 'No slm-gate MCP servers are left over from closed coding tools', `${stranded.length} slm-gate MCP server${stranded.length === 1 ? '' : 's'} still running with no coding tool attached (pid ${stranded.join(', ')}). ` +
+        `Each keeps checking Ollama and can show notifications from the build it was started with. Stop them with: kill ${stranded.join(' ')}`);
+    // 9c. Per-prompt savings (local answers, accuracy, window time per provider) are only measured on
+    // model-gate traffic. MCP tool calls alone keep the ledger busy while those cards stay empty, so the
+    // gap is called out here. A warning, not an issue: the gate itself works.
+    const lastModelGateEvent = lastModelGateEventTs();
+    if (lastModelGateEvent.error) {
+        console.log(`  Note: could not read the ledger to check for model-gate traffic: ${lastModelGateEvent.error}`);
+    }
+    else if (!lastModelGateEvent.ts || Date.now() - Date.parse(lastModelGateEvent.ts) > MODEL_GATE_QUIET_DAYS * 86_400_000) {
+        console.log(`⚠ No model request has gone through the model gate in the last ${MODEL_GATE_QUIET_DAYS} days (last: ${lastModelGateEvent.ts ?? 'never'}). ` +
+            'Per-prompt savings (local answers, SLM accuracy, window time saved) are not being measured; only MCP tool calls are reaching slm-gate.');
+        console.log(`  Fix: point a coding tool at ${gateAddress} with the settings printed below.`);
+    }
+    // 9d. Langfuse's dashboard shows one Env selection at a time; set to the wrong one it looks empty.
+    if (CONFIG.LANGFUSE_PUBLIC_KEY && CONFIG.LANGFUSE_SECRET_KEY && CONFIG.LANGFUSE_HOST) {
+        const dashboard = dashboardEnvironments();
+        if (dashboard.error)
+            console.log(`  Note: could not read the ledger's environments: ${dashboard.error}`);
+        console.log(`  Langfuse dashboard: set the Env selector to ${dashboard.environments.map(e => `"${e}"`).join(' and ')}` +
+            ` (new traffic goes to "${CONFIG.LANGFUSE_ENVIRONMENT}"; leave "bench" out unless you want benchmark runs).`);
+    }
+    // 10. The setting that sends each coding tool's model requests through the gate (on the current port).
+    console.log(`\n--- Coding tool settings: paste these to send a tool's model requests through ${gateAddress} ---`);
+    for (const setting of toolSettings(gatePort)) {
+        console.log(`\n${setting.tool}  (works with: ${setting.login})`);
+        for (const line of setting.lines)
+            console.log(`  ${line}`);
+    }
+    console.log('\nThese cannot send their model requests through the gate (slm-gate\'s MCP tools still work in them):');
+    for (const unroutable of UNROUTABLE_TOOLS)
+        console.log(`  ${unroutable.tool}: ${unroutable.reason}`);
+    console.log('\n=============================================');
+    if (issues === 0) {
+        console.log('READY');
+    }
+    else {
+        console.log(`${issues} issue(s) to fix`);
+        process.exit(1); // Fail the script execution so CI pipelines or scripts can catch it
+    }
+}
+run().catch(err => {
+    console.error('Doctor check failed unexpectedly:', err);
+    process.exit(1);
+});

package/dist/hardware.js

@@ -0,0 +1,126 @@
+import { execSync } from 'node:child_process';
+import os from 'node:os';
+/**
+ * Detects the host machine's hardware capabilities.
+ * Determines total RAM, OS platform, and available ML accelerators.
+ *
+ * @param mockOs - Optional mock OS module for unit testing.
+ * @returns {HardwareInfo} An object detailing the host's hardware profile.
+ *
+ * @example
+ * const hw = detectHardware();
+ * if (hw.accelerator === 'cuda') {
+ *   console.log('NVIDIA GPU detected!');
+ * }
+ */
+export function detectHardware(mockOs) {
+    const osModule = mockOs || os;
+    const totalRamGB = Math.round(osModule.totalmem() / (1024 * 1024 * 1024));
+    const arch = osModule.arch();
+    const platform = osModule.platform();
+    const isAppleSilicon = platform === 'darwin' && arch === 'arm64';
+    let accelerator = 'cpu';
+    // Apple Silicon inherently supports Metal
+    if (isAppleSilicon) {
+        accelerator = 'metal';
+    }
+    else {
+        // Attempt to detect NVIDIA GPUs by running nvidia-smi
+        try {
+            execSync('nvidia-smi', { stdio: 'ignore' });
+            accelerator = 'cuda';
+        }
+        catch {
+            // Ignore errors (e.g., command not found or no GPU), fallback to 'cpu' remains
+        }
+    }
+    // Apple Silicon uses a unified memory architecture where CPU and GPU share the same RAM pool
+    const unifiedMemory = isAppleSilicon;
+    return { totalRamGB, arch, platform, isAppleSilicon, accelerator, unifiedMemory };
+}
+/** slm-gate needs at least this much RAM: both local models, their context, and room for your other apps. */
+export const MIN_RAM_GB = 16;
+/**
+ * Recommends a RAM preset for a computer with MIN_RAM_GB of RAM or more. A size between two presets gets
+ * the smaller one (48–63 GB → ram-48). More than 128 GB gets `custom`: start from the 128 GB models
+ * (modelsForRam) and choose bigger ones yourself, e.g. with llmfit (https://github.com/AlexsJones/llmfit).
+ * `slm-gate init` and `slm-gate doctor` both use this.
+ *
+ * @param totalRamGB - The total physical RAM in gigabytes.
+ * @returns {string} The recommended RAM preset key (e.g., 'ram-16').
+ *
+ * @example
+ * const preset = recommendPreset(48);
+ * // returns 'ram-48'
+ */
+export function recommendPreset(totalRamGB) {
+    if (totalRamGB > 128)
+        return 'custom';
+    if (totalRamGB >= 128)
+        return 'ram-128';
+    if (totalRamGB >= 64)
+        return 'ram-64';
+    if (totalRamGB >= 48)
+        return 'ram-48';
+    if (totalRamGB >= 32)
+        return 'ram-32';
+    if (totalRamGB >= 24)
+        return 'ram-24';
+    return 'ram-16';
+}
+/**
+ * Recommends a safe context window size (NUM_CTX) based on available RAM.
+ * Ensures that there is enough memory to hold KV caches for both SLM models if running in dual-model mode.
+ *
+ * @param totalRamGB - The total physical RAM in gigabytes.
+ * @param dualModel - Whether the system is running both a brain and a gate model concurrently (defaults to true).
+ * @returns {number} The recommended NUM_CTX context length.
+ *
+ * @example
+ * const numCtx = recommendNumCtx(16);
+ * // returns 4096
+ */
+export function recommendNumCtx(totalRamGB, dualModel = true) {
+    return totalRamGB >= 24 ? 8192 : 4096;
+}
+/**
+ * Pre-defined model pairs tailored to different RAM tiers: the one table config.ts, doctor, init and
+ * `models:check` all read. Each preset specifies a 'brain' model (for complex reasoning) and a 'gate' model
+ * (for fast routing/classification); every name must exist in Ollama's library. `custom` is the pair used
+ * when RAM_PRESET=custom and no SLM_*_MODEL is set.
+ */
+export const ramPresets = {
+    'ram-16': { brain: 'qwen2.5-coder:3b', gate: 'qwen2.5-coder:0.5b' },
+    'ram-24': { brain: 'qwen3.5:4b', gate: 'qwen2.5-coder:3b' },
+    'ram-32': { brain: 'qwen2.5:7b', gate: 'qwen2.5-coder:3b' },
+    'ram-48': { brain: 'qwen3.5:9b', gate: 'qwen2.5-coder:3b' },
+    'ram-64': { brain: 'qwen3.5:9b', gate: 'qwen3.5:4b' },
+    'ram-128': { brain: 'qwen3:14b', gate: 'qwen3:8b' },
+    'custom': { brain: 'qwen3.5:4b', gate: 'qwen2.5-coder:3b' },
+};
+/**
+ * The models for a computer with this much RAM: its preset's pair, or above 128 GB (preset `custom`) the
+ * 128 GB pair, which certainly fits and is the starting point for choosing bigger models.
+ */
+export function modelsForRam(totalRamGB) {
+    const preset = recommendPreset(totalRamGB);
+    return ramPresets[preset === 'custom' ? 'ram-128' : preset];
+}
+/**
+ * Parses a RAM preset string to extract its numeric ranking/size in GB.
+ * This is used to logically compare if a user's configured preset is too demanding for their hardware.
+ *
+ * @param preset - The RAM preset string (e.g., 'ram-16' or 'custom').
+ * @returns {number} The numeric equivalent of the preset in GB.
+ *
+ * @example
+ * const rank = getPresetRank('ram-16');
+ * // returns 16
+ */
+export function getPresetRank(preset) {
+    const match = preset.match(/^ram-(\d+)$/);
+    if (match)
+        return parseInt(match[1], 10);
+    // `custom` without model names uses the custom pair (qwen3.5:4b + qwen2.5-coder:3b), a ram-24 class load
+    return 24;
+}

package/dist/home-dir.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Where an install keeps its settings and data: `.env`, and `output/` (the ledger, logs,
+ * markers and notices). Code and the shipped templates (`dist/`, `configs/`) stay in the install folder.
+ *
+ * - A git checkout keeps them in the checkout, as it always has.
+ * - An npm install lives inside `node_modules`, which every upgrade replaces, so it uses `~/.slm-gate`.
+ * - `SLM_GATE_HOME` overrides both. It says where `.env` is, so it comes from the environment (the shell,
+ *   or a coding tool's MCP env block), not from `.env`. It is not a configuration key, so the
+ *   automatically started model gate inherits it (src/setup/model-gate.ts `gateEnvironment`) and reads
+ *   the same `.env`.
+ *
+ * No side effects: cli.ts imports this without loading the configuration.
+ */
+import path from 'node:path';
+/**
+ * @param params.installDir The install folder, where `dist/` and `configs/` are
+ * @param params.env The process environment; only SLM_GATE_HOME is read, and blank counts as unset
+ * @param params.userHome The user's home folder
+ * @returns The absolute folder for `.env` and `output/`
+ * @throws When SLM_GATE_HOME is not an absolute path: coding tools start slm-gate from any folder, so a
+ *   relative one would point somewhere different each time
+ */
+export function resolveHomeDir(params) {
+    const explicit = params.env.SLM_GATE_HOME;
+    if (explicit) {
+        if (!path.isAbsolute(explicit)) {
+            throw new Error(`SLM_GATE_HOME must be an absolute path, because coding tools start slm-gate from any folder; got "${explicit}".`);
+        }
+        return path.resolve(explicit);
+    }
+    return isPackageInstall(params.installDir) ? path.join(params.userHome, '.slm-gate') : params.installDir;
+}
+/**
+ * @param installDir The install folder
+ * @returns True for a copy installed by npm (it lives inside node_modules), false for a git checkout
+ */
+export function isPackageInstall(installDir) {
+    return installDir.split(path.sep).includes('node_modules');
+}

package/dist/ledger/flush-lifecycle.js

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Langfuse flush lifecycle, shared by every long-lived gate process.
+ *
+ * Replaces the previous bare 5-minute `setInterval`. That design meant a gate which
+ * answered a few tool calls and exited inside one interval shipped nothing at all, and a
+ * backlog drained at only 50 events per 5 minutes — which is why the dashboard appeared
+ * empty and then jumped.
+ */
+import { LangfuseSink } from './index.js';
+/** Backstop poll. Short enough that data is reviewable almost immediately. */
+const INTERVAL_MS = 15_000;
+/**
+ * Wall-clock budget for the shutdown drain. MCP hosts send SIGTERM and then force-kill
+ * after a short grace period, so an unbounded network drain would just be killed mid-flight.
+ */
+const SHUTDOWN_BUDGET_MS = 4_000;
+/**
+ * Installs startup drain, periodic backstop, and a bounded shutdown drain.
+ *
+ * @param layer Log prefix identifying the calling gate (e.g. 'mcp-gate', 'llm-gate').
+ * @returns A `flushSoon` function callers may invoke after writing an event to ship it
+ *   near-immediately, debounced so a burst of events still results in one request.
+ */
+export function installLangfuseFlushLifecycle(layer) {
+    const flush = (why, options) => LangfuseSink.flushQueue(options).catch(err => console.error(`[${layer}] Langfuse flush error (${why}):`, err));
+    // Drain whatever a previous process left behind.
+    void flush('startup');
+    // unref() so this timer never keeps the process alive on its own.
+    setInterval(() => { void flush('interval'); }, INTERVAL_MS).unref();
+    let shuttingDown = false;
+    const drainAndExit = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await flush(signal, { deadlineMs: SHUTDOWN_BUDGET_MS });
+        process.exit(0);
+    };
+    process.once('SIGINT', () => void drainAndExit('SIGINT'));
+    process.once('SIGTERM', () => void drainAndExit('SIGTERM'));
+    let debounce = null;
+    return function flushSoon() {
+        if (debounce)
+            return;
+        debounce = setTimeout(() => {
+            debounce = null;
+            void flush('debounced');
+        }, 2_000);
+        debounce.unref();
+    };
+}