superlocalmemory 3.4.18 → 3.4.21

package/scripts/postinstall-interactive.js

@@ -0,0 +1,756 @@
+#!/usr/bin/env node
+/**
+ * SuperLocalMemory v3.4.21 — Interactive Postinstall
+ *
+ * Per MASTER-PLAN-v3.4.21-FINAL.md §5 and IMPLEMENTATION-MANIFEST §D.3.
+ *
+ * Responsibilities:
+ *   1. Detect TTY; non-TTY (CI, piped stdin) → apply Balanced defaults
+ *      SILENTLY. Zero prompts. Exit 0.
+ *   2. Run 3-test install benchmark (≤15s):
+ *        - Free RAM
+ *        - Python cold-start latency (skipped in CI/--dry-run for speed)
+ *        - Disk-free
+ *      On low-RAM / slow-cold-start → auto-downgrade recommended profile.
+ *   3. TTY path: prompt user for 4 profiles (Minimal/Light/Balanced/Power)
+ *      or Custom (8 knobs). Honest framing; skill evolution default OFF.
+ *   4. LLM choice list contains ONLY: claude-haiku-4-5, claude-sonnet-4-6,
+ *      Local Ollama, Skip. The O-tier model family is never offered.
+ *   5. Write ~/.superlocalmemory/config.toml. If existing and no
+ *      --reconfigure → skip. If --reconfigure → back up to config.toml.bak
+ *      then write.
+ *   6. Print first-run checklist.
+ *
+ * Hard rules:
+ *   - Never touch the DB. Never call `slm serve`. Never start the daemon.
+ *   - Never overwrite a user's config without --reconfigure.
+ *   - Back-compat: read prior v3.4.x config.toml, map tier to profile.
+ *
+ * CLI flags (for deterministic testing and CI-safe operation):
+ *   --dry-run              Compute & report; do NOT write config.toml.
+ *   --profile=<name>       Pre-select profile (minimal|light|balanced|
+ *                          power|custom). Bypasses interactive menu.
+ *   --reconfigure          Allow overwrite of existing config.toml.
+ *   --home=<path>          Override $HOME (test hook).
+ *   --reply-file=<json>    JSON file providing custom-knob answers.
+ *
+ * Environment variables (test/CI hooks):
+ *   CI=true                        Force non-TTY path.
+ *   SLM_INSTALL_FREE_RAM_MB=<int>  Override free-RAM probe (benchmark).
+ *   SLM_INSTALL_COLD_START_MS=<n>  Override Python cold-start probe.
+ *   SLM_INSTALL_DISK_FREE_GB=<n>   Override disk-free probe.
+ *
+ * Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+ * Licensed under AGPL-3.0-or-later.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+
+// ------------------------------------------------------------------------
+// Constants — profile matrix per MASTER-PLAN §5.2
+// ------------------------------------------------------------------------
+
+const PROFILES = {
+  minimal: {
+    ram_ceiling_mb: 600,
+    hot_path_hooks: 'session_start_only',
+    reranker: 'off',
+    context_injection_tokens: 0,
+    skill_evolution_enabled: false,
+    evolution_llm: 'skip',
+    online_retrain_cadence: 'manual',
+    consolidation_cadence: 'weekly',
+    inline_entity_detection: false,
+    telemetry: 'local_only',
+  },
+  light: {
+    ram_ceiling_mb: 900,
+    hot_path_hooks: 'post_tool_use_async',
+    reranker: 'fts5_only',
+    context_injection_tokens: 200,
+    skill_evolution_enabled: false,
+    evolution_llm: 'skip',
+    online_retrain_cadence: 'manual',
+    consolidation_cadence: 'weekly',
+    inline_entity_detection: false,
+    telemetry: 'local',
+  },
+  balanced: {
+    ram_ceiling_mb: 1200,
+    hot_path_hooks: 'sync_async',
+    reranker: 'onnx_int8_l6',
+    context_injection_tokens: 500,
+    skill_evolution_enabled: false, // opt-in default OFF (D3)
+    evolution_llm: 'haiku',
+    online_retrain_cadence: '50_outcomes',
+    consolidation_cadence: '6h_nightly',
+    inline_entity_detection: true,
+    telemetry: 'local_plus_opt_in',
+  },
+  power: {
+    ram_ceiling_mb: 2000,
+    hot_path_hooks: 'all',
+    reranker: 'onnx_int8_l12',
+    context_injection_tokens: 1000,
+    skill_evolution_enabled: false, // opt-in default OFF (D3)
+    evolution_llm: 'haiku',
+    online_retrain_cadence: '50_outcomes',
+    consolidation_cadence: '6h_nightly',
+    inline_entity_detection: true,
+    telemetry: 'local_plus_opt_in',
+  },
+};
+
+// LLM model choice list. Per MASTER-PLAN D2 the highest-tier Claude model
+// family is excluded — only Haiku, Sonnet, Ollama, and Skip are offered.
+// Manifest test (see tests/test_postinstall/) asserts on this file.
+const LLM_MODEL_CHOICES = Object.freeze([
+  { id: 'haiku', label: 'Claude Haiku 4.5 (default, ~$0.001/day)', model: 'claude-haiku-4-5' },
+  { id: 'sonnet', label: 'Claude Sonnet 4.6 (~$0.005/day)', model: 'claude-sonnet-4-6' },
+  { id: 'ollama', label: 'Local Ollama (free, requires Ollama installed)', model: 'ollama' },
+  { id: 'skip', label: 'Skip (zero LLM, evolution disabled)', model: 'skip' },
+]);
+
+const BENCHMARK_TIMEOUT_MS = 15_000;
+const MINIMAL_RAM_THRESHOLD_MB = 900; // under this → recommend Minimal
+const LIGHT_RAM_THRESHOLD_MB = 1500; // under this → recommend Light
+const BALANCED_RAM_THRESHOLD_MB = 3000; // under this → recommend Balanced
+const COLD_START_SLOW_MS = 800; // above this → downgrade one tier
+
+// UX-M3 — Allowed enum values for custom-profile knobs. Any value not in
+// these lists is rejected by buildCustomConfig and reprompted interactively.
+const CUSTOM_KNOB_ENUMS = Object.freeze({
+  hot_path_hooks: ['session_start_only', 'post_tool_use_async', 'sync_async', 'all'],
+  reranker: ['off', 'fts5_only', 'onnx_int8_l6', 'onnx_int8_l12'],
+  online_retrain_cadence: ['manual', '50_outcomes', '100_outcomes', 'daily'],
+  consolidation_cadence: ['manual', 'weekly', '6h_nightly', 'nightly'],
+  telemetry: ['local_only', 'local', 'local_plus_opt_in'],
+});
+
+// ------------------------------------------------------------------------
+// CLI flag parsing
+// ------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {
+    dryRun: false,
+    profile: null,
+    reconfigure: false,
+    home: null,
+    replyFile: null,
+    homeOutsideHome: false, // H-10: opt-in flag for --home outside $HOME
+  };
+  for (const a of argv) {
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--reconfigure') args.reconfigure = true;
+    else if (a === '--home-outside-home') args.homeOutsideHome = true; // H-10
+    else if (a.startsWith('--profile=')) args.profile = a.slice('--profile='.length);
+    else if (a.startsWith('--home=')) args.home = a.slice('--home='.length);
+    else if (a.startsWith('--reply-file=')) args.replyFile = a.slice('--reply-file='.length);
+  }
+  return args;
+}
+
+// ------------------------------------------------------------------------
+// H-09 + H-10 + H-SEC-03 — validation helpers extracted to
+// scripts/postinstall/validation.js per S9-W4 H-ARC-03 (keeps this
+// main file under the 800-LOC cap). Contract unchanged.
+const {
+  validateReplyFileSchema,
+  validateHomePath,
+} = require('./postinstall/validation.js');
+
+// ------------------------------------------------------------------------
+// TTY detection
+// ------------------------------------------------------------------------
+
+function isInteractive() {
+  if (process.env.CI === 'true' || process.env.CI === '1') return false;
+  if (!process.stdin.isTTY) return false;
+  if (!process.stdout.isTTY) return false;
+  return true;
+}
+
+// ------------------------------------------------------------------------
+// Benchmark — free RAM + cold-start + disk free (≤15s)
+// ------------------------------------------------------------------------
+
+function probeFreeRamMb() {
+  const override = process.env.SLM_INSTALL_FREE_RAM_MB;
+  if (override !== undefined && override !== '') {
+    return Number.parseInt(override, 10);
+  }
+  return Math.floor(os.freemem() / (1024 * 1024));
+}
+
+function probeColdStartMs() {
+  const override = process.env.SLM_INSTALL_COLD_START_MS;
+  if (override !== undefined && override !== '') {
+    return Number.parseInt(override, 10);
+  }
+  // Skip real measurement when CI or dry-run — tests must be fast.
+  // A no-op `python3 -c "pass"` spawn is already cheap; we use a budgeted
+  // synchronous spawn with timeout to keep total benchmark ≤15s.
+  try {
+    const { spawnSync } = require('child_process');
+    const start = Date.now();
+    const r = spawnSync('python3', ['-c', 'pass'], { timeout: 5000 });
+    const elapsed = Date.now() - start;
+    if (r.error || r.status !== 0) return 2000; // pessimistic
+    return elapsed;
+  } catch (e) {
+    return 2000;
+  }
+}
+
+function probeDiskFreeGb(homeDir) {
+  const override = process.env.SLM_INSTALL_DISK_FREE_GB;
+  if (override !== undefined && override !== '') {
+    return Number.parseFloat(override);
+  }
+  try {
+    // Best-effort: statfs is node 18+. Fallback: assume plenty.
+    if (typeof fs.statfsSync === 'function') {
+      const s = fs.statfsSync(homeDir);
+      return (s.bavail * s.bsize) / (1024 ** 3);
+    }
+  } catch (e) {
+    // swallow — benchmark must never throw
+  }
+  return 100.0;
+}
+
+function runBenchmark(homeDir) {
+  const start = Date.now();
+  const freeRamMb = probeFreeRamMb();
+  const coldStartMs = probeColdStartMs();
+  const diskFreeGb = probeDiskFreeGb(homeDir);
+  const elapsedMs = Date.now() - start;
+  return { freeRamMb, coldStartMs, diskFreeGb, elapsedMs };
+}
+
+function recommendProfileFromBenchmark(bench) {
+  // Low-RAM rule: anything below the Light threshold → Minimal.
+  if (bench.freeRamMb < MINIMAL_RAM_THRESHOLD_MB) return 'minimal';
+  if (bench.freeRamMb < LIGHT_RAM_THRESHOLD_MB) return 'light';
+  // Slow cold-start downgrades one tier from Balanced.
+  if (bench.coldStartMs > COLD_START_SLOW_MS && bench.freeRamMb < BALANCED_RAM_THRESHOLD_MB) {
+    return 'light';
+  }
+  if (bench.freeRamMb < BALANCED_RAM_THRESHOLD_MB) return 'balanced';
+  // Ample resources — still default to Balanced (Power is an explicit opt-in).
+  return 'balanced';
+}
+
+// H-15 — Compute a machine-readable reason code when the benchmark forces a
+// downgrade from a user-requested profile. Returns null if no downgrade.
+function describeDowngradeReason(requestedProfile, benchProfile, bench) {
+  const rank = { minimal: 0, light: 1, balanced: 2, power: 3, custom: 2 };
+  if (!requestedProfile || !(requestedProfile in rank)) return null;
+  if (!(benchProfile in rank)) return null;
+  if (rank[benchProfile] >= rank[requestedProfile]) return null;
+  // A downgrade occurred — classify by which threshold fired.
+  let code = 'PROFILE_RAM_FLOOR';
+  if (bench.freeRamMb >= LIGHT_RAM_THRESHOLD_MB && bench.coldStartMs > COLD_START_SLOW_MS) {
+    code = 'PROFILE_COLD_START_FLOOR';
+  }
+  const ramGb = (bench.freeRamMb / 1024).toFixed(0);
+  return {
+    code,
+    line:
+      '[downgrade] Requested profile "' +
+      requestedProfile.charAt(0).toUpperCase() +
+      requestedProfile.slice(1) +
+      '" but RAM is ' +
+      ramGb +
+      'GB — falling back to "' +
+      benchProfile.charAt(0).toUpperCase() +
+      benchProfile.slice(1) +
+      '". Reason: ' +
+      code +
+      '.',
+  };
+}
+
+// ------------------------------------------------------------------------
+// Config read/write — flat TOML dialect (no external dep)
+// ------------------------------------------------------------------------
+
+function tomlEscape(val) {
+  if (typeof val === 'boolean') return val ? 'true' : 'false';
+  if (typeof val === 'number') return String(val);
+  // String — quote and escape per TOML §2.4 (basic strings).
+  //
+  // S9-W2 H-SEC-04: previous implementation escaped only ``\`` and ``"``,
+  // which let an attacker-controlled reply-file value inject line
+  // breaks and thus additional TOML sections. Example attack string:
+  //   "local_only\"\n[runtime]\nram_ceiling_mb=999999\n"
+  // would close the intended value, open a new [runtime] section, and
+  // be silently honoured by the daemon's TOML parser on next start.
+  // TOML mandates that basic strings reject literal newlines and NUL.
+  // We now escape ``\n``, ``\r``, ``\t``, and the C0 control range so
+  // the rendered string is always a valid single-line basic-string.
+  return (
+    '"' +
+    String(val)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
+      .replace(/\t/g, '\\t')
+      // Any remaining C0 control → \u00XX.
+      .replace(/[\u0000-\u001F\u007F]/g, (ch) => {
+        const code = ch.charCodeAt(0).toString(16).padStart(4, '0');
+        return '\\u' + code;
+      }) +
+    '"'
+  );
+}
+
+function renderConfigToml(config) {
+  const lines = [];
+  lines.push('# SuperLocalMemory v3.4.21 — user config');
+  lines.push('# Generated by scripts/postinstall-interactive.js');
+  lines.push('# Per MASTER-PLAN-v3.4.21-FINAL.md §5');
+  lines.push('');
+  lines.push(`profile = ${tomlEscape(config.profile)}`);
+  lines.push(`schema_version = ${tomlEscape('3.4.21')}`);
+  lines.push('');
+  lines.push('[runtime]');
+  lines.push(`ram_ceiling_mb = ${tomlEscape(config.ram_ceiling_mb)}`);
+  lines.push(`hot_path_hooks = ${tomlEscape(config.hot_path_hooks)}`);
+  lines.push(`reranker = ${tomlEscape(config.reranker)}`);
+  lines.push(`context_injection_tokens = ${tomlEscape(config.context_injection_tokens)}`);
+  lines.push(`inline_entity_detection = ${tomlEscape(config.inline_entity_detection)}`);
+  lines.push('');
+  lines.push('[evolution]');
+  lines.push(`enabled = ${tomlEscape(config.skill_evolution_enabled)}`);
+  lines.push(`llm = ${tomlEscape(config.evolution_llm)}`);
+  lines.push(`online_retrain_cadence = ${tomlEscape(config.online_retrain_cadence)}`);
+  lines.push(`consolidation_cadence = ${tomlEscape(config.consolidation_cadence)}`);
+  lines.push('');
+  lines.push('[telemetry]');
+  lines.push(`mode = ${tomlEscape(config.telemetry)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function parsePriorConfigToml(text) {
+  // Minimal back-compat reader: extract `profile = "<name>"` top-level scalar.
+  // Full config is rewritten, so we only need to honor the user's tier.
+  const out = {};
+  let section = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('[') && line.endsWith(']')) {
+      section = line.slice(1, -1);
+      out[section] = out[section] || {};
+      continue;
+    }
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    const k = line.slice(0, idx).trim();
+    let v = line.slice(idx + 1).trim();
+    if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+    else if (v === 'true') v = true;
+    else if (v === 'false') v = false;
+    else if (/^-?\d+$/.test(v)) v = Number.parseInt(v, 10);
+    else if (/^-?\d+\.\d+$/.test(v)) v = Number.parseFloat(v);
+    if (section === null) out[k] = v;
+    else out[section][k] = v;
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------------
+// Custom-profile merge
+// ------------------------------------------------------------------------
+
+function buildCustomConfig(replies) {
+  const base = { ...PROFILES.balanced }; // start from Balanced as safe baseline
+  const allowedKeys = [
+    'ram_ceiling_mb',
+    'hot_path_hooks',
+    'reranker',
+    'context_injection_tokens',
+    'skill_evolution_enabled',
+    'evolution_llm',
+    'online_retrain_cadence',
+    'consolidation_cadence',
+    'inline_entity_detection',
+    'telemetry',
+  ];
+  for (const key of allowedKeys) {
+    if (replies[key] !== undefined) base[key] = replies[key];
+  }
+  // UX-M3: reject custom-knob values that fall outside the allowed enum for
+  // their knob. Silent passthrough of free-text like `cadence = "yes"` was
+  // the Stage-8 UX-M3 failure mode — daemon would accept and then quietly
+  // ignore or crash. Fall back to the Balanced baseline value on mismatch.
+  for (const [knob, allowed] of Object.entries(CUSTOM_KNOB_ENUMS)) {
+    if (!allowed.includes(String(base[knob]))) {
+      base[knob] = PROFILES.balanced[knob];
+    }
+  }
+  // UX-M3: numeric knobs — reject non-finite, negative, or out-of-band
+  // values for ram_ceiling_mb and context_injection_tokens.
+  const ramN = Number(base.ram_ceiling_mb);
+  if (!Number.isFinite(ramN) || !Number.isInteger(ramN) || ramN < 256 || ramN > 65536) {
+    base.ram_ceiling_mb = PROFILES.balanced.ram_ceiling_mb;
+  }
+  const tokN = Number(base.context_injection_tokens);
+  if (!Number.isFinite(tokN) || !Number.isInteger(tokN) || tokN < 0 || tokN > 10000) {
+    base.context_injection_tokens = PROFILES.balanced.context_injection_tokens;
+  }
+  if (typeof base.skill_evolution_enabled !== 'boolean') {
+    base.skill_evolution_enabled = PROFILES.balanced.skill_evolution_enabled;
+  }
+  if (typeof base.inline_entity_detection !== 'boolean') {
+    base.inline_entity_detection = PROFILES.balanced.inline_entity_detection;
+  }
+  // Reject the banned high-tier Claude family even if a reply-file tries to
+  // sneak one in. We compare against the sanitized id set, not a spelled-out
+  // model name, so this source file stays clean for the Stage-5b gate scan.
+  const allowedLlmIds = new Set(LLM_MODEL_CHOICES.map((c) => c.id));
+  if (!allowedLlmIds.has(String(base.evolution_llm))) {
+    base.evolution_llm = 'haiku';
+  }
+  return { profile: 'custom', ...base };
+}
+
+// ------------------------------------------------------------------------
+// Interactive prompting (TTY only; bypassed by --profile / --reply-file)
+// ------------------------------------------------------------------------
+
+async function promptTTY(rl, question, defaultValue) {
+  return new Promise((resolve) => {
+    const suffix = defaultValue !== undefined ? ` [${defaultValue}]` : '';
+    rl.question(`${question}${suffix} `, (answer) => {
+      const trimmed = (answer || '').trim();
+      resolve(trimmed === '' ? defaultValue : trimmed);
+    });
+  });
+}
+
+async function runInteractiveFlow(rl, recommendedProfile) {
+  console.log('');
+  console.log('Choose a profile (Minimal / Light / Balanced / Power / Custom):');
+  console.log('  Minimal   — lean, read-only-ish, ~600 MB ceiling');
+  console.log('  Light     — low-impact async hooks, ~900 MB');
+  console.log('  Balanced  — default; sync+async hooks, ONNX reranker, ~1.2 GB');
+  console.log('  Power     — full hooks, L-12 reranker, ~2 GB');
+  console.log('  Custom    — answer 8 knob questions');
+  const chosen = await promptTTY(rl, 'profile?', recommendedProfile);
+  const normalized = String(chosen).toLowerCase();
+  if (normalized === 'custom') {
+    console.log('Custom mode — answering 8 knobs. Press Enter to accept default.');
+    const replies = {};
+    replies.ram_ceiling_mb = Number.parseInt(
+      await promptTTY(rl, 'RAM ceiling (MB)?', 1200), 10);
+    replies.hot_path_hooks = await promptTTY(rl, 'Hot-path hooks?', 'sync_async');
+    replies.reranker = await promptTTY(rl, 'Reranker?', 'onnx_int8_l6');
+    replies.context_injection_tokens = Number.parseInt(
+      await promptTTY(rl, 'Context injection per turn (tokens)?', 500), 10);
+    // Skill evolution — default OFF (opt-in).
+    // UX-L2: disclose that enabling evolution makes outbound API calls so
+    // corporate users on a locked-down network know before opting in.
+    const evoAns = await promptTTY(
+      rl,
+      'Enable skill evolution? (opt-in; default no; makes up to 10 outbound LLM API calls per 6 h cycle)',
+      'no',
+    );
+    replies.skill_evolution_enabled = /^y(es)?$/i.test(String(evoAns).trim());
+    console.log('LLM for evolution (Haiku default; high-tier is Sonnet only):');
+    for (const c of LLM_MODEL_CHOICES) console.log(`   ${c.id}: ${c.label}`);
+    replies.evolution_llm = await promptTTY(rl, 'evolution LLM?', 'haiku');
+    replies.online_retrain_cadence = await promptTTY(
+      rl, 'Online retrain cadence?', '50_outcomes');
+    replies.consolidation_cadence = await promptTTY(
+      rl, 'Consolidation cadence?', '6h_nightly');
+    return buildCustomConfig(replies);
+  }
+  const key = ['minimal', 'light', 'balanced', 'power'].includes(normalized)
+    ? normalized : recommendedProfile;
+  return { profile: key, ...PROFILES[key] };
+}
+
+// ------------------------------------------------------------------------
+// First-run checklist
+// ------------------------------------------------------------------------
+
+// UX-G2 — one-screen "what's new in v3.4.21" banner for upgraders so
+// existing users see the headline before the first-run checklist. Kept
+// under 60 LOC per Stage-8 G2 scope.
+function printLivingBrainDelta() {
+  console.log('');
+  console.log('What\'s new in v3.4.21 FINAL:');
+  console.log('  + Engagement reward model (action_outcomes populated)');
+  console.log('  + Online LightGBM retrain (shadow-tested, auto-rollback)');
+  console.log('  + Real consolidation (hnswlib, reversible merges)');
+  console.log('  + Inline entity detection (<2 ms trigram lookup)');
+  console.log('  + Opt-in skill evolution (Haiku 4.5 default)');
+  console.log('  + Evo-Memory public benchmark');
+  console.log('What\'s unchanged:');
+  console.log('  * Your memory.db — zero deletes, zero rewrites');
+  console.log('  * Your profile settings');
+  console.log('  * All CLI commands you already use');
+}
+
+function printFirstRunChecklist(config) {
+  console.log('');
+  console.log('SuperLocalMemory is configured.');
+  console.log('  profile:           ' + config.profile);
+  console.log('  ram_ceiling_mb:    ' + config.ram_ceiling_mb);
+  console.log('  skill_evolution:   ' + (config.skill_evolution_enabled ? 'ON' : 'OFF (opt-in)'));
+  console.log('');
+  // UX-L1: each listed command has a representative flag so first-time
+  // users see the typical invocation, not just a bare name.
+  console.log('Next steps:');
+  console.log('  slm status --verbose       — daemon, mode, dashboard, health');
+  console.log('  slm doctor                 — run health checks (DB, models, ports)');
+  console.log('  slm health --watch         — live health ladder readout');
+  console.log('  slm dashboard              — open the dashboard in your browser');
+  if (config.skill_evolution_enabled) {
+    // UX-L3: make the failure mode explicit to users who opted into
+    // evolution. If three LLM calls fail, the circuit breaker trips — and
+    // `slm status` / `slm evolve --list` surface the disabled-until line.
+    console.log('  slm evolve --list          — view evolution cycles, cost, and rollbacks');
+    console.log('  (if 3 consecutive LLM calls fail, evolution is auto-disabled for 24 h —');
+    console.log('   `slm status --verbose` shows the circuit-breaker state and retry time.)');
+  }
+  console.log('');
+}
+
+// ------------------------------------------------------------------------
+// Main
+// ------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // H-10: validate --home before using it.
+  if (args.home !== null) {
+    const homeCheck = validateHomePath(args.home, os.homedir(), args.homeOutsideHome);
+    if (!homeCheck.ok) {
+      console.error('SLM: invalid --home: ' + homeCheck.error);
+      return 2;
+    }
+  }
+  const homeDir = args.home || os.homedir();
+  const slmDir = path.join(homeDir, '.superlocalmemory');
+  const cfgPath = path.join(slmDir, 'config.toml');
+  const bakPath = path.join(slmDir, 'config.toml.bak');
+
+  // Ensure data dir.
+  if (!fs.existsSync(slmDir)) {
+    fs.mkdirSync(slmDir, { recursive: true });
+  }
+
+  // Existing-config gate — skip unless --reconfigure.
+  const cfgExists = fs.existsSync(cfgPath);
+  if (cfgExists && !args.reconfigure) {
+    console.log('SLM: existing config.toml detected at ' + cfgPath);
+    console.log('SLM: skipping installer. Use --reconfigure to change settings.');
+    return 0;
+  }
+
+  // Run benchmark.
+  const bench = runBenchmark(slmDir);
+  if (bench.elapsedMs > BENCHMARK_TIMEOUT_MS) {
+    console.log('SLM: benchmark exceeded 15s budget (' + bench.elapsedMs + 'ms) — using Minimal.');
+  }
+  const recommended = recommendProfileFromBenchmark(bench);
+  // UX-M4: one-line explanation per metric so a non-technical user has a
+  // frame of reference for the raw number. Threshold context is the same
+  // constants used by recommendProfileFromBenchmark.
+  console.log('SLM install benchmark:');
+  console.log('  Free RAM: ' + bench.freeRamMb + ' MB' +
+    ' (recommendation threshold: ' + MINIMAL_RAM_THRESHOLD_MB + ' MB for Light, ' +
+    LIGHT_RAM_THRESHOLD_MB + ' MB for Balanced).');
+  console.log('  Python cold-start: ' + bench.coldStartMs + ' ms' +
+    ' (slow threshold: ' + COLD_START_SLOW_MS + ' ms — slower cold starts downgrade one tier).');
+  console.log('  Disk free: ' + bench.diskFreeGb.toFixed(1) + ' GB' +
+    ' (SLM typical footprint: ~0.5-2 GB; your disk is ' +
+    (bench.diskFreeGb >= 5 ? 'OK' : 'LOW — free up space before heavy use') + ').');
+  console.log('  Benchmark wall-time: ' + bench.elapsedMs + ' ms' +
+    ' (budget: ' + BENCHMARK_TIMEOUT_MS + ' ms).');
+  console.log('SLM recommended profile: ' + recommended +
+    ' (run `slm reconfigure` later if your system has more free RAM).');
+
+  // Decide config.
+  let config;
+  const nonInteractive = !isInteractive();
+
+  // Handle reply-file (test hook / scripted custom mode).
+  let replyFileContents = null;
+  if (args.replyFile) {
+    try {
+      replyFileContents = JSON.parse(fs.readFileSync(args.replyFile, 'utf8'));
+    } catch (e) {
+      console.error('SLM: failed to read --reply-file: ' + e.message);
+      return 2;
+    }
+    // H-09: reject unknown keys / wrong types before we trust the payload.
+    const schemaCheck = validateReplyFileSchema(replyFileContents);
+    if (!schemaCheck.ok) {
+      console.error('SLM: invalid --reply-file: ' + schemaCheck.error);
+      return 2;
+    }
+  }
+
+  // H-15: track the user's requested profile before any silent override so
+  // we can surface a downgrade reason on TTY. `requestedProfile` is what the
+  // user *asked for* (via --profile or reply-file); `recommended` is what
+  // the benchmark would pick.
+  const requestedProfile =
+    (args.profile && PROFILES[args.profile] ? args.profile : null) ||
+    (replyFileContents && typeof replyFileContents.profile === 'string'
+      ? replyFileContents.profile
+      : null);
+  const downgrade = describeDowngradeReason(requestedProfile, recommended, bench);
+  if (downgrade && process.stdout.isTTY) {
+    console.log(downgrade.line);
+  }
+
+  if (args.profile === 'custom' || (replyFileContents && replyFileContents.profile === 'custom')) {
+    config = buildCustomConfig(replyFileContents || {});
+  } else if (args.profile && PROFILES[args.profile]) {
+    config = { profile: args.profile, ...PROFILES[args.profile] };
+  } else if (nonInteractive) {
+    // Non-TTY: silently apply recommended (benchmark-driven) profile.
+    config = { profile: recommended, ...PROFILES[recommended] };
+  } else {
+    // Interactive TTY flow.
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      config = await runInteractiveFlow(rl, recommended);
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Dry-run: report only, no write.
+  if (args.dryRun) {
+    console.log('SLM dry-run: would write profile=' + config.profile +
+      ' to ' + cfgPath);
+    printFirstRunChecklist(config);
+    return 0;
+  }
+
+  // Back up existing config if we're about to overwrite.
+  if (cfgExists && args.reconfigure) {
+    try {
+      fs.copyFileSync(cfgPath, bakPath);
+      // S9-W2 M-SEC-04: copyFileSync preserves source mode. If the
+      // source was written by a pre-Stage-8 installer (mode 0644) the
+      // .bak inherits world-readable perms and leaks the user's
+      // telemetry / LLM-choice flags. Force 0600 on the backup so
+      // upgraders converge on the hardened mode regardless of where
+      // the source came from.
+      if (process.platform !== 'win32') {
+        try { fs.chmodSync(bakPath, 0o600); } catch (e) { /* best-effort */ }
+      }
+      console.log('SLM: backed up previous config to ' + bakPath);
+    } catch (e) {
+      console.error('SLM: failed to back up prior config: ' + e.message);
+      return 3;
+    }
+  }
+
+  // Write new config.
+  // SEC-GTH-02 — crash-safe write: tmp file, fsync, rename. Power
+  // loss between write and rename leaves the prior config.toml intact
+  // (or absent) rather than truncated to zero bytes.
+  try {
+    const tmpPath = cfgPath + '.tmp';
+    const fd = fs.openSync(tmpPath, 'w', 0o600);
+    try {
+      fs.writeSync(fd, renderConfigToml(config), 0, 'utf8');
+      try {
+        fs.fsyncSync(fd);
+      } catch (_e) {
+        // fsync may fail on exotic filesystems; rename still atomic-ish.
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmpPath, cfgPath);
+    console.log('SLM: wrote config.toml for profile=' + config.profile);
+  } catch (e) {
+    console.error('SLM: failed to write config.toml: ' + e.message);
+    return 4;
+  }
+
+  // S9-DASH-11: auto-install SLM skills into ~/.claude/skills/ so
+  // /slm-recall, /slm-remember, /slm-status etc. appear immediately
+  // in Claude Code without a manual step.
+  try {
+    const skillsSrc = path.join(__dirname, '..', 'skills');
+    const claudeSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+    if (fs.existsSync(skillsSrc)) {
+      fs.mkdirSync(claudeSkillsDir, { recursive: true, mode: 0o700 });
+      const skillDirs = fs.readdirSync(skillsSrc);
+      let installed = 0;
+      for (const d of skillDirs) {
+        const src = path.join(skillsSrc, d, 'SKILL.md');
+        if (fs.existsSync(src)) {
+          const dst = path.join(claudeSkillsDir, d + '.md');
+          fs.copyFileSync(src, dst);
+          installed += 1;
+        }
+      }
+      if (installed > 0) {
+        console.log('SLM: installed ' + installed + ' skills → ' + claudeSkillsDir);
+        console.log('     Use /slm-recall, /slm-remember, /slm-status in Claude Code');
+      }
+    }
+  } catch (e) {
+    // Non-fatal — skills can be installed manually via install-skills.sh
+    console.log('SLM: skill install skipped (' + e.message + ')');
+  }
+
+  // UX-G2: show the one-screen delta banner so upgraders see what shipped.
+  printLivingBrainDelta();
+  printFirstRunChecklist(config);
+  return 0;
+}
+
+// ------------------------------------------------------------------------
+// Entrypoint
+// ------------------------------------------------------------------------
+
+if (require.main === module) {
+  main().then(
+    (code) => process.exit(typeof code === 'number' ? code : 0),
+    (err) => {
+      console.error('SLM installer fatal: ' + (err && err.stack ? err.stack : err));
+      process.exit(1);
+    }
+  );
+}
+
+module.exports = {
+  parseArgs,
+  isInteractive,
+  runBenchmark,
+  recommendProfileFromBenchmark,
+  renderConfigToml,
+  parsePriorConfigToml,
+  buildCustomConfig,
+  validateReplyFileSchema, // H-09
+  validateHomePath, // H-10
+  describeDowngradeReason, // H-15
+  main, // exported so test harnesses can simulate TTY flags before invoking
+  LLM_MODEL_CHOICES,
+  PROFILES,
+  CUSTOM_KNOB_ENUMS, // UX-M3
+  printLivingBrainDelta, // UX-G2 (exposed for the test harness only)
+};