nlm-memory 0.4.1 → 0.5.0

package/src/http/app.ts

@@ -139,12 +139,90 @@ function parseLimit(raw: string | undefined, fallback: number, max: number): num
   return Math.min(max, n);
 }
 
+// Accept Host headers that point to loopback, with or without the bound port.
+// Rejecting non-loopback Hosts closes the DNS-rebinding hole: a malicious
+// site can resolve attacker.com to 127.0.0.1 in the browser but cannot
+// forge a Host header browsers send automatically.
+export function isLoopbackHost(host: string | undefined, port: number): boolean {
+  if (!host) return false;
+  const lower = host.toLowerCase();
+  return (
+    lower === "localhost" ||
+    lower === `localhost:${port}` ||
+    lower === "127.0.0.1" ||
+    lower === `127.0.0.1:${port}` ||
+    lower === "[::1]" ||
+    lower === `[::1]:${port}`
+  );
+}
+
+// Browser Origin headers are set automatically and cannot be spoofed by
+// page-level JS. A request with a non-loopback Origin reaching loopback
+// means the user is on attacker.com — the page is trying to read our data.
+export function isLoopbackOrigin(origin: string | undefined, port: number): boolean {
+  if (!origin) return false;
+  const lower = origin.toLowerCase();
+  return (
+    lower === `http://localhost:${port}` ||
+    lower === `http://127.0.0.1:${port}` ||
+    lower === `http://[::1]:${port}`
+  );
+}
+
 const VALID_MODES: ReadonlyArray<RecallMode> = ["keyword", "semantic", "hybrid"];
 const VALID_KINDS: ReadonlyArray<RecallKindFilter> = ["decision", "open"];
 const VALID_FACT_KINDS: ReadonlyArray<FactKind> = ["decision", "open", "attribute"];
 
 export function createApp(deps: HttpDeps): Hono {
   const app = new Hono();
+  const boundPort = process.env["NLM_PORT"] ? Number.parseInt(process.env["NLM_PORT"], 10) : 3940;
+
+  // ── Local-only access middleware (defense in depth on top of 127.0.0.1 bind) ──
+  //
+  // Threat model: server binds to loopback so external network is blocked.
+  // What's left:
+  //   1. DNS rebinding from a malicious tab — Host check blocks it
+  //   2. Browser drive-by from a cross-origin tab — Origin check blocks it
+  //   3. Port forwarding (ssh -L, ngrok) reaching another machine — Bearer blocks it
+  //
+  // Applied to /api/* and /mcp. Static UI (/ui/*) and /api/health pass through
+  // the host check but skip Origin/Bearer so SPAs and liveness probes work.
+  // Skip entirely under Vitest — in-process app.request() calls have no real
+  // network surface and synthesize requests without a Host header.
+  const skipLocalGate = !!process.env["VITEST"] || process.env["NODE_ENV"] === "test";
+  app.use("/api/*", async (c, next) => {
+    if (skipLocalGate) return next();
+    const host = c.req.header("host");
+    if (!isLoopbackHost(host, boundPort)) {
+      return c.json({ error: "host header not allowed" }, 403);
+    }
+    if (c.req.path === "/api/health") {
+      return next();
+    }
+    const origin = c.req.header("origin");
+    if (origin !== undefined) {
+      if (!isLoopbackOrigin(origin, boundPort)) {
+        return c.json({ error: "origin not allowed" }, 403);
+      }
+      // Loopback origin → same-origin UI request. Allow.
+      return next();
+    }
+    // No Origin → not a browser fetch. Require Bearer if a token is configured.
+    const token = process.env["NLM_MCP_TOKEN"];
+    if (!token) {
+      // No token configured → local-only daemon with loopback Host already verified.
+      // Acceptable for single-user dev installs; production users should set the token.
+      return next();
+    }
+    const auth = c.req.header("authorization") ?? "";
+    const match = /^Bearer\s+(\S+)$/i.exec(auth);
+    const given = Buffer.from(match?.[1] ?? "", "utf8");
+    const want = Buffer.from(token, "utf8");
+    if (!match || given.length !== want.length || !timingSafeEqual(given, want)) {
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    return next();
+  });
 
   app.get("/api/health", (c) =>
     c.json({ status: "ok", service: "nlm-memory", version: "0.2.0-dev" }),

package/src/install/claude-code.ts

@@ -94,7 +94,7 @@ export function installClaudeCodeHooks(opts: HookInstallOptions): HookInstallRes
   const installed: HookSpec[] = [];
   for (const spec of opts.hooks) {
     try {
-      const command = opts.buildHookCommand(opts.nodeExecPath, spec.script, "shadow");
+      const command = opts.buildHookCommand(opts.nodeExecPath, spec.script, "live");
       opts.addHook(opts.settingsPath, command, spec.event);
       const smoke = opts.smokeTestHookCommand(command, opts.hookLogPath);
       if (!smoke.ok) {

package/src/install/cursor.ts

@@ -0,0 +1,68 @@
+/**
+ * `nlm connect cursor` / `nlm disconnect cursor` — registers or removes the
+ * Cursor adapter source in the NLM source registry.
+ *
+ * Unlike plugin-based runtimes (hermes-agent, codex), Cursor needs no file
+ * to be installed. NLM reads Cursor's existing state.vscdb directly. The
+ * connect operation only registers the source row so the daemon scans it.
+ */
+
+import { existsSync } from "node:fs";
+import { defaultDbPath } from "../core/adapters/cursor.js";
+import type { SourceRegistry } from "../core/sources/source-registry.js";
+
+export interface ConnectCursorOptions {
+  readonly dbPath?: string;
+  readonly dryRun?: boolean;
+}
+
+export interface ConnectCursorReport {
+  readonly adapterDbPath: string;
+  readonly adapterExists: boolean;
+  readonly action: "created" | "enabled" | "already-active" | "dry-run";
+}
+
+export interface DisconnectCursorReport {
+  readonly action: "disabled" | "not-found" | "dry-run";
+}
+
+export function connectCursor(
+  registry: SourceRegistry,
+  opts: ConnectCursorOptions = {},
+): ConnectCursorReport {
+  const adapterDbPath = opts.dbPath ?? defaultDbPath();
+  const adapterExists = existsSync(adapterDbPath);
+
+  if (opts.dryRun) {
+    return { adapterDbPath, adapterExists, action: "dry-run" };
+  }
+
+  const existing = registry.getByName("Cursor");
+  if (existing) {
+    if (existing.enabled && existing.pathOrUrl === adapterDbPath) {
+      return { adapterDbPath, adapterExists, action: "already-active" };
+    }
+    registry.update(existing.id, { enabled: true, pathOrUrl: adapterDbPath });
+    return { adapterDbPath, adapterExists, action: "enabled" };
+  }
+
+  registry.insert({
+    kind: "cursor",
+    name: "Cursor",
+    pathOrUrl: adapterDbPath,
+    runtimeLabel: "cursor/1.0",
+    enabled: adapterExists,
+  });
+  return { adapterDbPath, adapterExists, action: "created" };
+}
+
+export function disconnectCursor(
+  registry: SourceRegistry,
+  opts: { dryRun?: boolean } = {},
+): DisconnectCursorReport {
+  if (opts.dryRun) return { action: "dry-run" };
+  const existing = registry.getByName("Cursor");
+  if (!existing) return { action: "not-found" };
+  registry.update(existing.id, { enabled: false });
+  return { action: "disabled" };
+}

package/src/install/nlm-dir-perms.ts

@@ -0,0 +1,55 @@
+/**
+ * Idempotent permission hardening for ~/.nlm/.
+ *
+ * Recursively sets owner-only perms on the daemon's working directory:
+ *   directories → 0o700
+ *   files       → 0o600
+ *
+ * Run at every `nlm setup`, `nlm install`, and `nlm start` so installs
+ * predating v0.4.2 (when explicit chmod was added) self-heal on next
+ * launch. No-op on Windows — ACLs are the POSIX equivalent and out of
+ * scope here.
+ */
+
+import { chmodSync, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface PermsHardenResult {
+  readonly nlmDir: string;
+  readonly filesHardened: number;
+  readonly dirsHardened: number;
+  readonly skipped: number;
+}
+
+export function hardenNlmDirPermissions(
+  nlmDir: string = join(homedir(), ".nlm"),
+): PermsHardenResult {
+  const result = { nlmDir, filesHardened: 0, dirsHardened: 0, skipped: 0 };
+  if (process.platform === "win32") return result;
+  if (!existsSync(nlmDir)) return result;
+  walk(nlmDir, result);
+  return result;
+}
+
+interface MutableResult {
+  filesHardened: number;
+  dirsHardened: number;
+  skipped: number;
+}
+
+function walk(path: string, r: MutableResult): void {
+  try {
+    const s = statSync(path);
+    if (s.isDirectory()) {
+      chmodSync(path, 0o700);
+      r.dirsHardened += 1;
+      for (const name of readdirSync(path)) walk(join(path, name), r);
+    } else if (s.isFile()) {
+      chmodSync(path, 0o600);
+      r.filesHardened += 1;
+    }
+  } catch {
+    r.skipped += 1;
+  }
+}

package/src/install/ollama.ts

@@ -12,10 +12,11 @@
  *   Windows — winget install / detached spawn
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { spawnSync, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 
 export const EMBEDDING_MODEL = "nomic-embed-text";
 const OS = platform();
@@ -180,29 +181,104 @@ export function pullEmbeddingModel(): OllamaResult {
 
 export type ClassifierChoice = "deepseek" | "ollama-offline";
 
+export interface ClassifierConfigInput {
+  readonly choice: ClassifierChoice;
+  readonly model?: string;
+  readonly apiKey?: string;
+}
+
 /**
  * Write classifier config to ~/.nlm/.env. Merges into the existing file —
  * only the lines we manage are updated; anything the user added by hand stays.
+ *
+ * Manages three keys: DEEPSEEK_API_KEY, NLM_CLASSIFIER, NLM_CLASSIFIER_MODEL.
+ * Backwards-compatible: passing positional (choice, apiKey) still works.
  */
-export function writeClassifierConfig(choice: ClassifierChoice, apiKey?: string): void {
+export function writeClassifierConfig(
+  choiceOrInput: ClassifierChoice | ClassifierConfigInput,
+  apiKey?: string,
+): void {
+  const input: ClassifierConfigInput =
+    typeof choiceOrInput === "string"
+      ? { choice: choiceOrInput, ...(apiKey !== undefined ? { apiKey } : {}) }
+      : choiceOrInput;
+
   const envPath = join(homedir(), ".nlm", ".env");
-  mkdirSync(join(homedir(), ".nlm"), { recursive: true });
+  const nlmDir = join(homedir(), ".nlm");
+  mkdirSync(nlmDir, { recursive: true, mode: 0o700 });
+  chmodSync(nlmDir, 0o700);
 
   const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
   const kept = existing
     .split("\n")
-    .filter((l) => !l.startsWith("DEEPSEEK_API_KEY=") && !l.startsWith("NLM_CLASSIFIER="))
+    .filter(
+      (l) =>
+        !l.startsWith("DEEPSEEK_API_KEY=") &&
+        !l.startsWith("NLM_CLASSIFIER=") &&
+        !l.startsWith("NLM_CLASSIFIER_MODEL="),
+    )
     .join("\n")
     .replace(/\n{3,}/g, "\n\n")
     .trim();
 
   const additions: string[] = [];
-  if (choice === "deepseek" && apiKey) {
-    // Strip newlines that clipboard paste can introduce.
-    const sanitized = apiKey.replace(/[\r\n]/g, "").trim();
-    additions.push(`DEEPSEEK_API_KEY=${sanitized}`);
+  if (input.choice === "deepseek") {
+    additions.push("NLM_CLASSIFIER=deepseek");
+    if (input.apiKey) {
+      // Strip newlines that clipboard paste can introduce.
+      const sanitized = input.apiKey.replace(/[\r\n]/g, "").trim();
+      additions.push(`DEEPSEEK_API_KEY=${sanitized}`);
+    }
+  }
+  if (input.choice === "ollama-offline") additions.push("NLM_CLASSIFIER=ollama");
+  if (input.model) additions.push(`NLM_CLASSIFIER_MODEL=${input.model}`);
+
+  writeFileSync(envPath, [kept, ...additions].filter(Boolean).join("\n") + "\n", { mode: 0o600 });
+  chmodSync(envPath, 0o600);
+}
+
+const TOKEN_BYTES = 32;
+
+/**
+ * Generate and persist an NLM_MCP_TOKEN if one isn't already set. Returns
+ * the token that's active for this process. Called during setup and on
+ * `nlm start` so installs that pre-date token-gated /api/* still get
+ * Bearer-protected without operator intervention.
+ *
+ * Token is hex-encoded crypto.randomBytes — 64 chars, 256 bits of entropy.
+ */
+export function ensureMcpToken(): string {
+  const existing = process.env["NLM_MCP_TOKEN"];
+  if (existing) return existing;
+
+  const token = randomBytes(TOKEN_BYTES).toString("hex");
+
+  const envPath = join(homedir(), ".nlm", ".env");
+  const nlmDir = join(homedir(), ".nlm");
+  mkdirSync(nlmDir, { recursive: true, mode: 0o700 });
+  chmodSync(nlmDir, 0o700);
+
+  const fileExisting = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  // Idempotent re-read: another setup run could have written the token
+  // between our env check and now. Prefer the persisted value.
+  for (const line of fileExisting.split("\n")) {
+    if (line.startsWith("NLM_MCP_TOKEN=")) {
+      const persisted = line.slice("NLM_MCP_TOKEN=".length).trim();
+      if (persisted) {
+        process.env["NLM_MCP_TOKEN"] = persisted;
+        return persisted;
+      }
+    }
   }
-  if (choice === "ollama-offline") additions.push("NLM_CLASSIFIER=ollama");
 
-  writeFileSync(envPath, [kept, ...additions].filter(Boolean).join("\n") + "\n", "utf8");
+  const kept = fileExisting
+    .split("\n")
+    .filter((l) => !l.startsWith("NLM_MCP_TOKEN="))
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  writeFileSync(envPath, [kept, `NLM_MCP_TOKEN=${token}`].filter(Boolean).join("\n") + "\n", { mode: 0o600 });
+  chmodSync(envPath, 0o600);
+  process.env["NLM_MCP_TOKEN"] = token;
+  return token;
 }

package/src/install/setup.ts

@@ -13,7 +13,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import {
   cancel, confirm, intro, isCancel, log, multiselect, outro, password, select, spinner,
 } from "@clack/prompts";
@@ -26,6 +26,7 @@ import {
   type ClassifierChoice,
   EMBEDDING_MODEL,
   embeddingModelPresent,
+  ensureMcpToken,
   installOllama,
   ollamaBinaryAvailable,
   ollamaServerRunning,
@@ -35,6 +36,7 @@ import {
   writeClassifierConfig,
 } from "./ollama.js";
 import { installClaudeCodeHooks } from "./claude-code.js";
+import { hardenNlmDirPermissions } from "./nlm-dir-perms.js";
 
 const OS = platform();
 
@@ -47,6 +49,10 @@ export interface SetupOptions {
   readonly launchAgentLabel: string;
   readonly launchAgentPlist: string;
   readonly buildPlist: (nodeExec: string, binPath: string) => string;
+  readonly linuxSystemdUnitName: string;
+  readonly linuxSystemdUnitPath: string;
+  readonly buildSystemdUnit: (nodeExec: string, binPath: string) => string;
+  readonly linuxSystemdUserAvailable: () => boolean;
   readonly claudeSettingsPath: string;
   readonly allHooks: ReadonlyArray<{
     event: ClaudeHookEvent;
@@ -59,6 +65,30 @@ export interface SetupOptions {
   readonly smokeTestHookCommand: (command: string, logPath: string) => { ok: boolean; reason?: string; stderr?: string };
 }
 
+// Embedding-only tags shouldn't be offered as classifier models — they
+// can't run chat completions and the call would fail at first ingest.
+const EMBEDDING_MODEL_PREFIXES = ["nomic-embed", "mxbai-embed", "snowflake-arctic-embed", "bge-"] as const;
+
+async function fetchOllamaChatModels(timeoutMs = 5000): Promise<string[]> {
+  const baseUrl = process.env["NLM_OLLAMA_URL"] ?? "http://localhost:11434";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${baseUrl}/api/tags`, { signal: controller.signal });
+    if (!res.ok) return [];
+    const data = (await res.json()) as { models?: Array<{ name?: string }> };
+    return (data.models ?? [])
+      .map((m) => m.name)
+      .filter((n): n is string => typeof n === "string")
+      .filter((n) => !EMBEDDING_MODEL_PREFIXES.some((p) => n.startsWith(p)))
+      .sort();
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 type RuntimeId = "claude-code" | "codex" | "opencode" | "hermes" | "pi";
 
 interface RuntimeOption {
@@ -194,35 +224,88 @@ export async function runSetup(opts: SetupOptions): Promise<void> {
     log.success(`Ollama ready — ${EMBEDDING_MODEL} present`);
   }
 
-  // ── Step 3: classifier API key ────────────────────────────────────────
-  const wantKey = await confirm({ message: "Add a classifier API key? (enables accurate session tagging; DeepSeek is ~$0.002/session)" });
-  if (isCancel(wantKey)) { cancel("Setup cancelled."); process.exit(0); }
+  // ── Step 3: classifier (provider + model + key) ───────────────────────
+  const wantConfigure = await confirm({
+    message: "Configure the session classifier? (controls how new sessions are tagged)",
+  });
+  if (isCancel(wantConfigure)) { cancel("Setup cancelled."); process.exit(0); }
 
-  if (wantKey) {
+  if (wantConfigure) {
     const classifierChoice = await select<ClassifierChoice>({
-      message: "Which classifier?",
+      message: "Which classifier provider?",
       options: [
-        { value: "deepseek", label: "DeepSeek", hint: "recommended — fast, cheap, needs DEEPSEEK_API_KEY" },
-        { value: "ollama-offline", label: "Ollama (offline)", hint: "free, no API key, slower and less accurate" },
+        {
+          value: "deepseek",
+          label: "DeepSeek (cloud)",
+          hint: "fast, cheap (~$0.002/session). Transcripts are sent to api.deepseek.com.",
+        },
+        {
+          value: "ollama-offline",
+          label: "Ollama (local)",
+          hint: "private — runs on this machine via your local Ollama. Slower; needs a chat model pulled.",
+        },
       ],
     });
     if (isCancel(classifierChoice)) { cancel("Setup cancelled."); process.exit(0); }
 
     if (classifierChoice === "deepseek") {
+      log.info("Heads up: DeepSeek classification sends up to 30K chars of each session transcript to api.deepseek.com.");
+      log.info("  Anything in a transcript (pasted keys, client names, internal URLs) leaves this machine.");
+      log.info("  Pick Ollama (local) above if that's not acceptable.");
+
+      const model = await select<string>({
+        message: "Which DeepSeek model?",
+        options: [
+          { value: "deepseek-v4-flash", label: "deepseek-v4-flash", hint: "recommended — fast + cheap, ~$0.002/session" },
+          { value: "deepseek-v4-pro", label: "deepseek-v4-pro", hint: "higher quality, ~10× cost" },
+          { value: "deepseek-chat", label: "deepseek-chat", hint: "legacy chat model" },
+        ],
+      });
+      if (isCancel(model)) { cancel("Setup cancelled."); process.exit(0); }
+
       const key = await password({ message: "DeepSeek API key (get one at platform.deepseek.com):" });
       if (isCancel(key)) { cancel("Setup cancelled."); process.exit(0); }
-      if (key && (key as string).trim()) {
-        writeClassifierConfig("deepseek", (key as string).trim());
-        log.success("DeepSeek API key saved to ~/.nlm/.env");
+      const apiKey = key && (key as string).trim() ? (key as string).trim() : undefined;
+      writeClassifierConfig(apiKey !== undefined
+        ? { choice: "deepseek", model: model as string, apiKey }
+        : { choice: "deepseek", model: model as string });
+      if (apiKey) {
+        log.success(`DeepSeek (${model as string}) configured — credentials saved to ~/.nlm/.env`);
       } else {
-        log.warn("No key entered — set DEEPSEEK_API_KEY in ~/.nlm/.env later.");
+        log.warn(`DeepSeek (${model as string}) configured — set DEEPSEEK_API_KEY in ~/.nlm/.env before running.`);
       }
     } else {
-      writeClassifierConfig("ollama-offline");
-      log.success("Classifier set to Ollama offline (saved to ~/.nlm/.env)");
+      const ollamaModels = await fetchOllamaChatModels();
+      let modelValue = "phi4-mini:latest";
+      if (ollamaModels.length > 0) {
+        const model = await select<string>({
+          message: "Which Ollama chat model?",
+          options: ollamaModels.map((m) => ({
+            value: m,
+            label: m,
+            hint: m === "phi4-mini:latest" ? "recommended default — small, fast" : undefined,
+          })) as { value: string; label: string; hint?: string }[],
+        });
+        if (isCancel(model)) { cancel("Setup cancelled."); process.exit(0); }
+        modelValue = model as string;
+      } else {
+        log.warn("No Ollama chat models detected. Defaulting to phi4-mini:latest.");
+        log.warn("  Pull a model with: ollama pull phi4-mini  (or any chat model you prefer)");
+      }
+      writeClassifierConfig({ choice: "ollama-offline", model: modelValue });
+      log.success(`Ollama classifier (${modelValue}) saved to ~/.nlm/.env`);
     }
   }
 
+  // ── Step 3.5: HTTP API auth token ─────────────────────────────────────
+  // Generate a token if one isn't set so /api/* gets Bearer-protected for
+  // non-browser callers (curl, port-forwarded clients). The UI still works
+  // because browsers send Origin and we exempt loopback origins.
+  const token = ensureMcpToken();
+  if (token === process.env["NLM_MCP_TOKEN"] && token.length === 64) {
+    log.success("HTTP API auth token saved to ~/.nlm/.env (NLM_MCP_TOKEN)");
+  }
+
   // ── Step 4: migrations ────────────────────────────────────────────────
   const ms = spinner();
   ms.start("Running database migrations");
@@ -237,6 +320,14 @@ export async function runSetup(opts: SetupOptions): Promise<void> {
     process.exit(1);
   }
 
+  // ── Step 4.5: harden ~/.nlm permissions ────────────────────────────────
+  // Idempotent. Covers upgrade from pre-v0.4.2 installs where files were
+  // written without explicit chmod, leaving secrets world-readable.
+  const perms = hardenNlmDirPermissions();
+  if (perms.filesHardened + perms.dirsHardened > 0) {
+    log.success(`Hardened perms on ${perms.dirsHardened} dirs and ${perms.filesHardened} files in ${perms.nlmDir}`);
+  }
+
   // ── Step 5: daemon ────────────────────────────────────────────────────
   if (OS === "darwin") {
     const installDaemon = await confirm({ message: "Install macOS LaunchAgent (auto-start on login)?" });
@@ -262,9 +353,34 @@ export async function runSetup(opts: SetupOptions): Promise<void> {
       }
     }
   } else if (OS === "linux") {
-    log.info("Linux daemon: add `nlm start` to your init system to auto-start on boot.");
-    log.info("  systemd example:  sudo systemctl enable --now nlm  (after creating a unit file)");
-    log.info("  Quick start now:  nlm start &");
+    if (opts.linuxSystemdUserAvailable()) {
+      const installDaemon = await confirm({ message: "Install systemd user unit (auto-start on login)?" });
+      if (isCancel(installDaemon)) { cancel("Setup cancelled."); process.exit(0); }
+
+      if (installDaemon) {
+        const ds = spinner();
+        ds.start("Installing systemd user unit");
+        try {
+          mkdirSync(dirname(opts.linuxSystemdUnitPath), { recursive: true });
+          mkdirSync(join(homedir(), ".nlm", "logs"), { recursive: true });
+          writeFileSync(opts.linuxSystemdUnitPath, opts.buildSystemdUnit(opts.nodeExecPath, opts.nlmBinPath), "utf8");
+          execFileSync("systemctl", ["--user", "daemon-reload"]);
+          execFileSync("systemctl", ["--user", "enable", "--now", opts.linuxSystemdUnitName]);
+          ds.stop("systemd user unit installed — daemon running");
+          log.info(`  Status:  systemctl --user status ${opts.linuxSystemdUnitName}`);
+          log.info("  Headless? Run `sudo loginctl enable-linger $USER` so the daemon survives logout.");
+        } catch (e) {
+          ds.stop("systemd install failed");
+          log.error(`${e instanceof Error ? e.message : String(e)}`);
+          log.warn("Run `nlm install` manually later, or start now with: nlm start &");
+        }
+      }
+    } else {
+      log.info("systemd user instance not available (no XDG_RUNTIME_DIR or `systemctl --user`).");
+      log.info("  Common on headless servers — start manually with: nlm start &");
+      log.info("  Or enable lingering, then re-run `nlm install`:");
+      log.info("    sudo loginctl enable-linger $USER");
+    }
   } else if (OS === "win32") {
     log.info("Windows daemon: run `nlm start` at login via Task Scheduler.");
     log.info("  Or start manually: nlm start");
@@ -352,6 +468,11 @@ export async function runSetup(opts: SetupOptions): Promise<void> {
       case "pi":
         log.success("pi.dev: session scanning enabled (passive — no extra config needed)");
         break;
+
+      default: {
+        const _: never = id;
+        log.warn(`Unknown runtime: ${_ as string} — skipping.`);
+      }
     }
   }
 

package/src/install/windsurf.ts

@@ -0,0 +1,68 @@
+/**
+ * `nlm connect windsurf` / `nlm disconnect windsurf` — registers or removes the
+ * Windsurf adapter source in the NLM source registry.
+ *
+ * NLM reads Windsurf's existing workspace SQLite DBs directly from the User
+ * directory. The connect operation only registers the source row so the daemon
+ * scans it.
+ */
+
+import { existsSync } from "node:fs";
+import { defaultUserDir } from "../core/adapters/windsurf.js";
+import type { SourceRegistry } from "../core/sources/source-registry.js";
+
+export interface ConnectWindsurfOptions {
+  readonly userDir?: string;
+  readonly dryRun?: boolean;
+}
+
+export interface ConnectWindsurfReport {
+  readonly userDir: string;
+  readonly dirExists: boolean;
+  readonly action: "created" | "enabled" | "already-active" | "dry-run";
+}
+
+export interface DisconnectWindsurfReport {
+  readonly action: "disabled" | "not-found" | "dry-run";
+}
+
+export function connectWindsurf(
+  registry: SourceRegistry,
+  opts: ConnectWindsurfOptions = {},
+): ConnectWindsurfReport {
+  const userDir = opts.userDir ?? defaultUserDir();
+  const dirExists = existsSync(userDir);
+
+  if (opts.dryRun) {
+    return { userDir, dirExists, action: "dry-run" };
+  }
+
+  const existing = registry.getByName("Windsurf");
+  if (existing) {
+    if (existing.enabled && existing.pathOrUrl === userDir) {
+      return { userDir, dirExists, action: "already-active" };
+    }
+    registry.update(existing.id, { enabled: true, pathOrUrl: userDir });
+    return { userDir, dirExists, action: "enabled" };
+  }
+
+  registry.insert({
+    kind: "windsurf",
+    name: "Windsurf",
+    pathOrUrl: userDir,
+    runtimeLabel: "windsurf/1.0",
+    enabled: dirExists,
+  });
+  return { userDir, dirExists, action: "created" };
+}
+
+export function disconnectWindsurf(
+  registry: SourceRegistry,
+  opts: { dryRun?: boolean } = {},
+): DisconnectWindsurfReport {
+  if (opts.dryRun) return { action: "dry-run" };
+  const existing = registry.getByName("Windsurf");
+  if (!existing) return { action: "not-found" };
+  registry.update(existing.id, { enabled: false });
+  return { action: "disabled" };
+}

package/src/shared/types.ts

@@ -31,6 +31,10 @@ export interface Session {
   readonly entities: ReadonlyArray<string>;
   readonly decisions: ReadonlyArray<string>;
   readonly open: ReadonlyArray<string>;
+  /** IDs of sessions this session supersedes (newer → older). Populated by getById; absent on bulk reads. */
+  readonly supersedes?: ReadonlyArray<string>;
+  /** ID of the session that superseded this one, if any. Populated by getById; absent on bulk reads. */
+  readonly supersededBy?: string | null;
 }
 
 export type RecallMode = "keyword" | "semantic" | "hybrid";