@nxuss/lemma 1.22.0 → 1.23.0

package/README.md

@@ -52,6 +52,23 @@ lemma start     # gateway + dashboard on http://localhost:8081
   real usage (`hits`), explicit negative feedback (`downvote_memory`), and `cognitive_map` domain
   tags; a passing `test_oracle` run over an uncommitted diff auto-captures itself; two memories
   about the same symbol that disagree on outcome are flagged, not silently both suggested.
+  Every hit explains itself (`whyShown` ranking signals + cited `evidence` files/symbols), and
+  every reuse books its savings onto the memory itself — `brain_stats` names which memories
+  actually pay for the Brain (`totalTokensSaved`, top savers).
+- **A memory that maintains itself** — `brain_upkeep` revalidates the most-reused memories,
+  surfaces exact duplicates and merge candidates, dead weight, and savings in one read-only
+  pass, each finding with its fix. `brain_merge` folds near-duplicate fragments into one
+  canonical entry (fragments survive as evidence-carrying claims). `forget_memory` moves to a
+  trash (`brain_trash`: list/restore/purge) instead of destroying, automatic snapshots roll
+  back every forget/import/clear/merge, and `brain_import dryRun:true` previews a bundle —
+  counts plus opposite-outcome conflicts — before a byte is written. Session onboarding
+  re-checks freshness of the memories it lists, so a day-one answer never starts stale.
+- **Integrity and encryption at rest** — the corpus carries a sha256 sidecar with `.prev`
+  backup rotation: a half-written or rotted file serves its intact lines, falls back to the
+  backup on total loss, and quarantines (never deletes) the bad bytes, with the incident
+  surfaced in `brain_stats`. `LEMMA_BRAIN_ENCRYPT=1` (or `LEMMA_BRAIN_KEY`) stores the
+  corpus AES-256-GCM encrypted under a local 0600 key; secrets never reach disk at all —
+  scrub-on-store redacts credentials one-way before indexing or persisting.
 - **Verifiable caching, not marketing numbers** — `state_hash_cache` only hits when the files an
   answer depends on are byte-identical; `token_receipt` gives a real per-session breakdown of how
   each answer was produced instead of an invented "% saved."
@@ -66,7 +83,7 @@ lemma start     # gateway + dashboard on http://localhost:8081
   compiler-verified AST location instead of asking the model to output a full-file rewrite.
 - **Infrastructure Command Center** — 22 free tools for Jenkins, OKD/OpenShift, and Terraform:
   discover, connect, deploy, diagnose, and detect drift, all via MCP.
-- **Scoped tool surface** — of the 98 registered tools, only the ones your project shows evidence
+- **Scoped tool surface** — of the 108 registered tools, only the ones your project shows evidence
   of needing are advertised to the model each turn; the rest stay one `lemma_toolbox` call away.
 
 See [`CHANGELOG.md`](CHANGELOG.md) for the full, per-version history.
@@ -75,13 +92,14 @@ See [`CHANGELOG.md`](CHANGELOG.md) for the full, per-version history.
 
 ## 💎 Free vs Pro
 
-48 of the 98 registered tools work with no license; 50 require Pro. Enforced by one allowlist in
-code (`FREE_TOOLS` in `src/mcp/tools.ts`), not by narrative. A session without a license doesn't
-even advertise the Pro tools — they stay registered and discoverable via `lemma_toolbox`.
+58 of the 108 registered tools work with no license; 50 require Pro. Enforced by one allowlist in
+code (`FREE_TOOLS` in `src/mcp/tools.ts`, including all 22 infrastructure tools), not by narrative.
+A session without a license doesn't even advertise the Pro tools — they stay registered and
+discoverable via `lemma_toolbox`.
 
-| | Free (48) | Pro (50) |
+| | Free (58) | Pro (50) |
 | :--- | :--- | :--- |
-| **Caching & memory** | `smarter_cache`, `state_hash_cache`, `token_receipt`, `search_memory`, `store_memory`, `downvote_memory`, `verify_memory`, `token_budget` | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` |
+| **Caching & memory** | `smarter_cache`, `state_hash_cache`, `token_receipt`, `search_memory`, `store_memory`, `downvote_memory`, `verify_memory`, `token_budget`, `brain_upkeep`, `brain_trash`, `brain_merge` | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` |
 | **Reading & context** | `read_workspace_file`, `scrub_privacy`, `import_tree_context`, `bulk_file_digest`, `auto_context_bundle`, `git_blame_heat`, `type_coverage_report` | `get_ast_hologram`, `smart_file_slice`, `get_symbol_surgical_context`, `diff_only` |
 | **Writing & workspace** | — | `write_workspace_file`, `apply_workspace_patch`, `multi_file_patch`, `search_workspace`, `run_workspace_command`, `validate_patch_sandbox`, `surgical_ast_insert` |
 | **Static analysis** | — | `entropy_score`, `coupling_radar`, `pattern_fossil`, `precrime_static`, `dead_export_necromancer`, `depgraph`, `refactor`, `ast_flow_visualizer`, `cognitive_map` |
@@ -96,7 +114,7 @@ Full per-tool listing: `lemma_toolbox { "action": "list" }`.
 
 ## 🎚️ Tool profiles
 
-Every advertised tool schema is re-sent on **every request** of the session — advertising all 97
+Every advertised tool schema is re-sent on **every request** of the session — advertising all 108
 costs ~11,600 tokens/turn. Lemma advertises a scoped surface instead: core tools always, situational
 groups (e.g. infrastructure) only when the repo shows evidence for them. Nothing is removed —
 everything stays registered and reachable via `lemma_toolbox`.
@@ -194,6 +212,14 @@ JS/TS, Python, Go, Rust, Ruby, JVM, `make`, git/gh, read-only shell utilities, a
 CLIs. Extend via `lemma.config.json` → `mcp.allowedCommandPrefixes`. See
 [`.env.security.example`](.env.security.example) for every security-related env var.
 
+**Brain at rest.** Secrets are redacted one-way before a memory is indexed or persisted
+(scrub-on-store, same patterns as the traffic firewall — the token map is discarded, there is
+no unmask step). `LEMMA_BRAIN_ENCRYPT=1` additionally stores the corpus AES-256-GCM encrypted
+under `<brainDir>/.brain.key` (0600, auto-generated); `LEMMA_BRAIN_KEY` (64 hex chars or base64
+of 32 bytes) overrides it for teams sharing one key. A malformed key fails loud at startup;
+a wrong key flows into the integrity fallback (backup → quarantine → fresh start), never an
+exception, never half a corpus.
+
 ---
 
 ## 🦜 SDK integrations & proxy mode

package/bin/init.js

@@ -399,7 +399,7 @@ function configureClaudeCode() {
 // license tier (semantic cache vs. exact-match cache), which has nothing to do with
 // gateway credentials. The proxy (lemma-proxy.ts) never validates whatever token the
 // client sends anyway: it always signs upstream requests with its OWN server-side
-// ANTHROPIC_API_KEY (see installProxyDaemon). So ANTHROPIC_AUTH_TOKEN here is just a
+// ANTHROPIC_API_KEY (loaded from ~/.lemma-cache/env). So ANTHROPIC_AUTH_TOKEN here is just a
 // fixed local placeholder to satisfy Claude Code's "a token is present" check.
 function configureClaudeCodeGateway(anthropicApiKey) {
   if (!anthropicApiKey) {
@@ -795,20 +795,19 @@ function configureOpenCode() {
   return true;
 }
 
-function installProxyDaemon() {
+// Installs the cache-proxy daemon as a user-level launchd/systemd unit.
+// OPT-IN ONLY: `lemma init` never calls this without an explicit --daemon flag.
+// Secrets are never baked into the unit file: the daemon loads ~/.lemma-cache/env
+// at startup (see lemma-proxy.cjs loadEnvFile), where `lemma init` persists keys
+// with mode 0600 instead.
+function installProxyDaemon(homeDir = os.homedir()) {
   const isMac = process.platform === 'darwin';
   const isLinux = process.platform === 'linux';
 
-  // The full proxy server (lemma-proxy.ts) needs its own server-side credentials to sign
-  // upstream requests — it never trusts whatever token the calling client sends. A launchd/
-  // systemd service does not inherit the shell's exported env, so these must be baked into
-  // the unit definition at install time or the daemon silently falls back to local Ollama.
-  const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
-  const openaiApiKey = process.env.OPENAI_API_KEY || '';
   const proxyArgs = ['start', '--port', PORT, '--no-configure', '--no-clipboard'];
 
   if (isMac) {
-    const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const plistDir = path.join(homeDir, 'Library', 'LaunchAgents');
     ensureDir(plistDir);
     const plistPath = path.join(plistDir, 'com.lemma.cache-proxy.plist');
     const argEntries = proxyArgs.map((a) => `    <string>${a}</string>`).join('\n');
@@ -816,9 +815,7 @@ function installProxyDaemon() {
       `    <key>LEMMA_PROXY_PORT</key><string>${PORT}</string>`,
       `    <key>LEMMA_CACHE_DIR</key><string>${LEMMA_CACHE}</string>`,
       `    <key>LEMMA_DISABLE_CLIPBOARD</key><string>true</string>`,
-      anthropicApiKey ? `    <key>ANTHROPIC_API_KEY</key><string>${anthropicApiKey}</string>` : '',
-      openaiApiKey ? `    <key>OPENAI_API_KEY</key><string>${openaiApiKey}</string>` : '',
-    ].filter(Boolean).join('\n');
+    ].join('\n');
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -848,15 +845,13 @@ ${envEntries}
   }
 
   if (isLinux) {
-    const svcDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const svcDir = path.join(homeDir, '.config', 'systemd', 'user');
     ensureDir(svcDir);
     const envLines = [
       `Environment=LEMMA_PROXY_PORT=${PORT}`,
       `Environment=LEMMA_CACHE_DIR=${LEMMA_CACHE}`,
       `Environment=LEMMA_DISABLE_CLIPBOARD=true`,
-      anthropicApiKey ? `Environment=ANTHROPIC_API_KEY=${anthropicApiKey}` : '',
-      openaiApiKey ? `Environment=OPENAI_API_KEY=${openaiApiKey}` : '',
-    ].filter(Boolean).join('\n');
+    ].join('\n');
     const svc = `[Unit]
 Description=Lemma Cache Proxy
 After=network.target
@@ -879,6 +874,39 @@ WantedBy=default.target
   return false;
 }
 
+// Best-effort removal of a previously installed daemon unit. Plain `lemma init`
+// (no --daemon) calls this so a silent or legacy install can never linger behind:
+// the daemon only exists while the user explicitly asked for it.
+function removeProxyDaemon(homeDir = os.homedir()) {
+  if (process.platform === 'darwin') {
+    const plistPath = path.join(homeDir, 'Library', 'LaunchAgents', 'com.lemma.cache-proxy.plist');
+    if (!fs.existsSync(plistPath)) return false;
+    try { execSync('launchctl unload ' + plistPath, { stdio: 'ignore' }); } catch {}
+    try { fs.unlinkSync(plistPath); } catch {}
+    return !fs.existsSync(plistPath);
+  }
+  if (process.platform === 'linux') {
+    const svcPath = path.join(homeDir, '.config', 'systemd', 'user', 'lemma-cache-proxy.service');
+    if (!fs.existsSync(svcPath)) return false;
+    try { execSync('systemctl --user disable lemma-cache-proxy --now', { stdio: 'ignore' }); } catch {}
+    try { fs.unlinkSync(svcPath); } catch {}
+    return !fs.existsSync(svcPath);
+  }
+  return false;
+}
+
+// Global side effects stay opt-in: a plain `lemma init` only writes project-local
+// files + MCP registrations. --daemon installs the background proxy daemon,
+// --gateway reroutes the user's Claude Code model traffic through that proxy.
+function parseInitArgs(argv = process.argv) {
+  const args = argv.slice(2);
+  return {
+    showHelp: args.includes('--help') || args.includes('-h'),
+    wantDaemon: args.includes('--daemon'),
+    wantGateway: args.includes('--gateway'),
+  };
+}
+
 function applyEnvToCurrentProcess() {
   const proxyUrl = `http://localhost:${PORT}`;
   process.env.LEMMA_PROXY_PORT = PORT;
@@ -889,21 +917,29 @@ function applyEnvToCurrentProcess() {
   process.env.LITELLM_PROXY_BASE_URL = proxyUrl;
 }
 
-function createEnvFile() {
+// Upstream API keys live here (mode 0600) instead of inside the launchd/systemd
+// unit: the proxy daemon loads this file at startup (lemma-proxy.cjs loadEnvFile),
+// so a background service gets credentials without baking secrets into a unit file.
+function createEnvFile(envFile = ENV_FILE) {
   const proxyUrl = `http://localhost:${PORT}`;
+  const keyLines = [
+    process.env.ANTHROPIC_API_KEY ? `export ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}` : '',
+    process.env.OPENAI_API_KEY ? `export OPENAI_API_KEY=${process.env.OPENAI_API_KEY}` : '',
+  ].filter(Boolean).join('\n');
   const envContent = `# Lemma Cache Proxy — Auto-generated by \`lemma init\`
 # Source this file in your shell to route LLM traffic through the cache:
-#   source ${ENV_FILE}
+#   source ${envFile}
 export LEMMA_PROXY_PORT=${PORT}
 export LEMMA_CACHE_DIR=${LEMMA_CACHE}
 export OPENAI_BASE_URL=${proxyUrl}
 export OPENAI_API_BASE=${proxyUrl}
 export CODEX_BASE_URL=${proxyUrl}
 export LITELLM_PROXY_BASE_URL=${proxyUrl}
-`;
-  fs.writeFileSync(ENV_FILE, envContent, 'utf8');
+${keyLines ? keyLines + '\n' : ''}`;
+  fs.writeFileSync(envFile, envContent, 'utf8');
+  try { fs.chmodSync(envFile, 0o600); } catch {}
   applyEnvToCurrentProcess();
-  return ENV_FILE;
+  return envFile;
 }
 
 function setupShellIntegration() {
@@ -942,7 +978,26 @@ function setupShellIntegration() {
   return configured;
 }
 
-async function main() {
+async function main(argv = process.argv) {
+  const opts = parseInitArgs(argv);
+  if (opts.showHelp) {
+    process.stderr.write(`
+  Lemma Init — project setup (project-local files + MCP registrations only)
+
+  Usage: lemma init [--daemon] [--gateway]
+
+    --daemon    Install + start the background cache-proxy daemon
+                (launchd KeepAlive on macOS, systemd user unit on Linux).
+                Without it, no daemon is installed — and a previously installed
+                one is removed.
+    --gateway   Reroute this user's Claude Code model traffic through the proxy
+                (~/.claude/settings.json). Requires ANTHROPIC_API_KEY in env.
+                Without it, Claude Code keeps its own auth untouched.
+
+`);
+    return;
+  }
+
   process.stderr.write(`\n  ${BOLD}${CYAN}Lemma Init — Magic Setup${RESET}\n\n`);
 
   ensureDir(LEMMA_CACHE);
@@ -961,17 +1016,23 @@ async function main() {
   configureClaudeCode();
   ok('Claude Code / CLI configured (CLAUDE.md + .claude/settings.local.json)');
 
-  const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
-  const gatewayResult = configureClaudeCodeGateway(anthropicApiKey);
-  if (gatewayResult.activated) {
-    ok(`Claude Code gateway activated (~/.claude/settings.json → ANTHROPIC_BASE_URL=http://localhost:${PORT})`);
+  // --gateway is opt-in: flipping the user's global Claude Code auth without being
+  // asked is exactly how Pro subscribers end up billed as API usage.
+  if (!opts.wantGateway) {
+    skip('Claude Code gateway not requested — model traffic + auth untouched (MCP tools only). Re-run with --gateway to route it via the proxy.');
   } else {
-    warn('Claude Code gateway NOT activated — no ANTHROPIC_API_KEY in this environment.');
-    warn(`  Model traffic keeps going directly to Anthropic (subscription/OAuth or your own key, unchanged).`);
-    warn(`  Only Lemma's MCP tools are active for Claude Code — no cache savings on the model traffic itself.`);
-    warn(`  To enable it: export ANTHROPIC_API_KEY=sk-ant-... and re-run \`lemma init\`.`);
-    warn(`  This SWITCHES Claude Code off your subscription/OAuth session for LLM calls — they'll be`);
-    warn(`  signed by the proxy's own ANTHROPIC_API_KEY instead, and billed/rate-limited as API usage.`);
+    const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
+    const gatewayResult = configureClaudeCodeGateway(anthropicApiKey);
+    if (gatewayResult.activated) {
+      ok(`Claude Code gateway activated (~/.claude/settings.json → ANTHROPIC_BASE_URL=http://localhost:${PORT})`);
+    } else {
+      warn('Claude Code gateway NOT activated — no ANTHROPIC_API_KEY in this environment.');
+      warn(`  Model traffic keeps going directly to Anthropic (subscription/OAuth or your own key, unchanged).`);
+      warn(`  Only Lemma's MCP tools are active for Claude Code — no cache savings on the model traffic itself.`);
+      warn(`  To enable it: export ANTHROPIC_API_KEY=sk-ant-... and re-run \`lemma init --gateway\`.`);
+      warn(`  This SWITCHES Claude Code off your subscription/OAuth session for LLM calls — they'll be`);
+      warn(`  signed by the proxy's own ANTHROPIC_API_KEY instead, and billed/rate-limited as API usage.`);
+    }
   }
 
   updateAgentsMd();
@@ -1024,9 +1085,15 @@ async function main() {
   if (hasWindsurf) ok('Windsurf detected — env auto-configured');
   else skip('Windsurf not detected');
 
-  const daemonOk = installProxyDaemon();
-  if (daemonOk) ok('Cache proxy daemon installed & started (OpenAI + Anthropic /v1/messages, streaming)');
-  else warn('Could not install daemon — run `lemma proxy start` manually');
+  if (opts.wantDaemon) {
+    const daemonOk = installProxyDaemon();
+    if (daemonOk) ok('Cache proxy daemon installed & started (OpenAI + Anthropic /v1/messages, streaming)');
+    else warn('Could not install daemon — run `lemma proxy start` manually');
+  } else if (removeProxyDaemon()) {
+    ok('Removed previously installed proxy daemon (re-run with --daemon to restore it)');
+  } else {
+    skip('Proxy daemon not installed (opt-in via `lemma init --daemon`)');
+  }
 
   const envFile = createEnvFile();
   ok(`Env file created: ${envFile}`);
@@ -1037,7 +1104,11 @@ async function main() {
 
   process.stderr.write(`\n  ${BOLD}${GREEN}✓ Lemma init complete${RESET}\n`);
   process.stderr.write(`  ${DIM}──────────────────────────────────────${RESET}\n`);
-  process.stderr.write(`  ${GREEN}●${RESET} Cache proxy running on http://localhost:${PORT}\n`);
+  if (opts.wantDaemon) {
+    process.stderr.write(`  ${GREEN}●${RESET} Cache proxy running on http://localhost:${PORT}\n`);
+  } else {
+    process.stderr.write(`  ${DIM}○ Cache proxy daemon not installed (opt-in: \`lemma init --daemon\`)${RESET}\n`);
+  }
   process.stderr.write(`  ${GREEN}●${RESET} MCP server ready  ${DIM}(lemma mcp)${RESET}\n`);
   process.stderr.write(`  ${GREEN}●${RESET} Dashboard active  ${DIM}(lemma stats)${RESET}\n`);
   process.stderr.write(`  ${GREEN}●${RESET} New terminals: env vars auto-loaded\n`);
@@ -1057,4 +1128,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT };
+module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile };

package/dist/cjs/cli/lemma-proxy.d.ts

@@ -2,6 +2,8 @@
 export declare function startBackgroundClipboardWatcher(cliOpts?: {
     clipboard?: boolean;
 }): void;
+export declare const MAX_WORKSPACE_WATCHERS = 512;
+export declare function isUnsafeWatchRoot(dir: string): boolean;
 export declare function performAutoHeal(apply: boolean): Promise<{
     success: boolean;
     message: string;

package/dist/cjs/cli/lemma-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA0cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA4nED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA0cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AAqfD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AAyqDD,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8KhL"}

package/dist/cjs/cli/lemma-proxy.js

@@ -4,7 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WORKSPACE_WATCHERS = void 0;
 exports.startBackgroundClipboardWatcher = startBackgroundClipboardWatcher;
+exports.isUnsafeWatchRoot = isUnsafeWatchRoot;
 exports.performAutoHeal = performAutoHeal;
 const commander_1 = require("commander");
 const express_1 = __importDefault(require("express"));
@@ -960,6 +962,16 @@ class WriteQueue {
     }
 }
 const usageWriteQueue = new WriteQueue();
+// One fs.watch FD is opened per watched directory. Watching $HOME (the launchd
+// daemon's WorkingDirectory) or a filesystem root exhausts FDs (EMFILE), crashes
+// the process, and a KeepAlive supervisor turns that into an infinite
+// crash/relaunch loop — on macOS each relaunch re-triggers the TCC data-access
+// prompt. Refuse those roots outright.
+exports.MAX_WORKSPACE_WATCHERS = 512;
+function isUnsafeWatchRoot(dir) {
+    const resolved = path_1.default.resolve(dir);
+    return resolved === path_1.default.resolve(os_1.default.homedir()) || resolved === path_1.default.parse(resolved).root;
+}
 // ── Proxy Server class ─────────────────────────────────────────────────────────
 class LemmaServer {
     constructor(port, projectName, openBrowser = true) {
@@ -1648,12 +1660,28 @@ class LemmaServer {
     }
     startWorkspaceTimeWatcher() {
         const cwd = process.cwd();
+        if (isUnsafeWatchRoot(cwd)) {
+            console.log(`⏭️  [TimeTravel] Skipping workspace watcher: refusing to watch ${cwd} recursively (file-descriptor exhaustion risk). Start the proxy from a project directory instead.`);
+            return;
+        }
         const { watch } = require('fs');
         // Debounced capture function
         let debounceTimer = null;
         const pendingChanges = new Set();
+        // One FD per watched directory: cap it so giant trees degrade to a warning
+        // instead of an EMFILE crash (which a KeepAlive supervisor turns into a
+        // crash/relaunch loop).
+        let watchCount = 0;
+        let limitWarned = false;
         const ignoreDirs = ['node_modules', '.git', 'dist', 'chroma_data', '.lemma', 'dashboard', 'bin', 'sdks'];
         const watchDirRecursive = (dir) => {
+            if (watchCount >= exports.MAX_WORKSPACE_WATCHERS) {
+                if (!limitWarned) {
+                    limitWarned = true;
+                    console.log(`⚠️  [TimeTravel] Watcher limit (${exports.MAX_WORKSPACE_WATCHERS} dirs) reached at ${dir} — deeper directories won't trigger snapshots.`);
+                }
+                return;
+            }
             try {
                 const watcher = watch(dir, (eventType, filename) => {
                     if (!filename)
@@ -1675,6 +1703,19 @@ class LemmaServer {
                 // Prevent watcher from keeping process alive if in background
                 if (watcher.unref)
                     watcher.unref();
+                watchCount++;
+                // An async EMFILE/ENOSPC on a giant tree must never take down the server:
+                // contain it to a single warning and keep serving.
+                watcher.on('error', (err) => {
+                    if (!limitWarned) {
+                        limitWarned = true;
+                        console.log(`⚠️  [TimeTravel] Watcher error (${(err && err.code) || 'unknown'}) — snapshots degraded, server keeps running.`);
+                    }
+                    try {
+                        watcher.close();
+                    }
+                    catch { }
+                });
                 // Recursively watch subfolders
                 const files = fs_1.default.readdirSync(dir, { withFileTypes: true });
                 for (const file of files) {