ai-lens 0.8.107 → 0.8.109

package/.commithash

@@ -1 +1 @@
-af32330
+99dee20

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.109 — 2026-06-22
+- fix: `init --yes` no longer captures every project or silently imports your local Claude history. It now scopes capture to the git root of the current folder (still `--projects all` for everything), and imports past history only when you pass `--import`.
+
+## 0.8.108 — 2026-06-22
+- feat: `ai-lens init --mcp-only` registers just the MCP server in Claude Code and Cursor — for when you only need to read sessions from Claude, not capture hooks. It skips hook setup, authentication, and history import. The MCP scope now mirrors how AI Lens is installed: a local/project install registers the MCP at project scope, a global install at user scope (local wins if both are present); pass `--mcp-scope` to override.
+- change: `init --project-hooks` now also registers the MCP at project scope (Claude `local` + the project `.cursor/mcp.json`) to match where it writes hooks, instead of always registering globally. Pass `--mcp-scope` to override.
+
 ## 0.8.107 — 2026-06-19
 - fix: Cyrillic / non-ASCII in Windows hook payloads is no longer corrupted (it was being dropped as malformed JSON). The windowless launcher now reads the payload as raw bytes straight off the process's stdin and never references PowerShell's `$input` — merely touching `$input` both pre-drains stdin and decodes it through the console's OEM codepage, mangling the UTF-8 BOM and every Cyrillic byte before forwarding. Byte-exact passthrough now; the 0.8.105 read still went through `$input` first. Cursor and Claude Code.
 - fix: the Windows hidden-sender launch now runs detached, so it isn't killed together with the hook's process tree before it finishes starting the sender — closing a rare window where an event could be dropped. The launcher is GUI-subsystem, so detached still adds no console window (no flash).

package/bin/ai-lens.js

@@ -59,9 +59,10 @@ switch (command) {
     console.log('    --server URL    Server URL (default: saved or http://localhost:3000)');
     console.log('    --yes, -y       Non-interactive: accept all defaults, no prompts');
     console.log('    --projects LIST Comma-separated project paths to track');
-    console.log('    --no-hooks      Skip writing hooks and MCP (config + auth only)');
+    console.log('    --no-hooks      Skip writing hooks (config + auth + MCP only)');
     console.log('    --no-mcp        Skip MCP server registration');
-    console.log('    --mcp-scope S   MCP scope: user, local, or project (default: user)');
+    console.log('    --mcp-only      Register only the MCP server, mirroring your install scope (skip hooks/auth/import)');
+    console.log('    --mcp-scope S   MCP scope: user, local, or project (default: auto-detected from install scope, else user)');
     console.log('    --project-hooks Write Cursor/Claude hooks to project .cursor/ and .claude/ (not ~/.cursor)');
     console.log('    --use-repo-path Run capture.js from this package; skip copy to ~/.ai-lens/client/');
     console.log('  remove          Remove AI Lens hooks and client files');

package/cli/hooks.js

@@ -1190,6 +1190,50 @@ export function detectInstalledTools(ctx = null) {
   return tools.filter(t => existsSync(t.dirPath));
 }
 
+/**
+ * Detect whether AI Lens is installed at the PROJECT (local) or GLOBAL (user)
+ * level, by looking at where its hooks actually live. Used to mirror the install
+ * scope when registering the MCP server (`init --mcp-only`).
+ *
+ * "present" = a tool config whose hooks include an AI Lens entry, i.e.
+ * analyzeToolHooks(...).status is 'current' or 'outdated' (NOT 'fresh'/'absent').
+ *
+ * Project (local) takes priority over global when both are present.
+ *
+ * @param {string} projectRoot - Absolute path to inspect (e.g. process.cwd()).
+ * @returns {'project' | 'user' | null}
+ */
+export function detectAiLensInstallScope(projectRoot) {
+  // noBackup: this is read-only scope detection — never rename/back up a malformed
+  // file just to sniff its status (the project configs are sharedConfig:false, which
+  // would otherwise trigger a .bak rename of the user's settings.local.json).
+  const isPresent = (tool) => {
+    if (!tool) return false;
+    const status = analyzeToolHooks(tool, { noBackup: true }).status;
+    return status === 'current' || status === 'outdated';
+  };
+
+  // Project-level configs. Claude project hooks land in settings.local.json
+  // (per-machine, gitignored); the committed `--use-repo-path` form lands in
+  // settings.json — check BOTH so neither install style is missed.
+  const claudeProject = getClaudeCodeToolConfig(projectRoot);
+  const claudeProjectLocal = claudeProject
+    ? { ...claudeProject, configPath: claudeLocalSettingsPath(claudeProject) }
+    : null;
+  const projectTools = [
+    claudeProject,
+    claudeProjectLocal,
+    getCursorToolConfig(projectRoot),
+    getCodexToolConfig(projectRoot),
+  ];
+  if (projectTools.some(isPresent)) return 'project';
+
+  // Global (user-level) configs — ~/.claude, ~/.cursor, ~/.codex.
+  if (detectInstalledTools().some(isPresent)) return 'user';
+
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Analysis
 // ---------------------------------------------------------------------------
@@ -1215,8 +1259,10 @@ export function analyzeToolHooks(tool, opts = {}) {
   try {
     config = JSON.parse(raw);
   } catch (err) {
-    // For shared config files (settings.json), don't backup/rename — other tools depend on it
-    if (tool.sharedConfig) {
+    // For shared config files (settings.json), don't backup/rename — other tools depend on it.
+    // opts.noBackup lets read-only callers (e.g. install-scope detection) inspect status
+    // without mutating the user's file.
+    if (tool.sharedConfig || opts.noBackup) {
       return { status: 'malformed', error: err.message, disableAllHooks: false };
     }
     const bakPath = tool.configPath + '.bak';
@@ -1807,13 +1853,20 @@ function readJsonSafe(path) {
 
 /**
  * Add or update ai-lens MCP server in Cursor's mcp.json.
+ * @param {string} mcpUrl
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot] - When set, write the project-level
+ *   <projectRoot>/.cursor/mcp.json instead of the global ~/.cursor/mcp.json.
  */
-export function addCursorMcp(mcpUrl) {
-  const config = readJsonSafe(CURSOR_MCP_GLOBAL) || { mcpServers: {} };
+export function addCursorMcp(mcpUrl, { projectRoot } = {}) {
+  const target = projectRoot
+    ? join(projectRoot, '.cursor', 'mcp.json')
+    : CURSOR_MCP_GLOBAL;
+  const config = readJsonSafe(target) || { mcpServers: {} };
   if (!config.mcpServers) config.mcpServers = {};
   config.mcpServers['ai-lens'] = cursorMcpEntry(mcpUrl);
-  mkdirSync(dirname(CURSOR_MCP_GLOBAL), { recursive: true });
-  writeFileSync(CURSOR_MCP_GLOBAL, JSON.stringify(config, null, 2) + '\n');
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
 }
 
 /**

package/cli/init.js

@@ -20,9 +20,9 @@ import {
   getClaudeCodeHookDefsWithPath, getClaudeCodeHookDefsWithProjectDir, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
   checkHooksDisabled, enableHooks,
-  findStableNodePath,
+  findStableNodePath, detectAiLensInstallScope,
 } from './hooks.js';
-import { scanNestedClaudeProjects, summarizeNestedProjects } from './scan.js';
+import { scanNestedProjects, summarizeNestedProjects } from './scan.js';
 
 function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -35,6 +35,37 @@ function ask(question) {
   });
 }
 
+// Default `projects` scope for `init --yes` on a FRESH config: the git root of
+// cwd (the dev's work tree — the workspace when init is run there). Returns null
+// when cwd isn't inside a git repo (e.g. bot containers under /app) → capture-all,
+// which stays safe because the 90-day history import is separately gated to
+// opt-in (importMode).
+//
+// Uses the INNERMOST git root (`git rev-parse --show-toplevel`), NOT an outermost
+// walk-up: a `~/.git` dotfiles repo must never escalate the scope to $HOME (that
+// would re-introduce capture-all + a personal-history import). Without this,
+// `init --yes` left projects=null (= capture ALL).
+export function defaultProjectsScope(cwd = process.cwd()) {
+  try {
+    const root = execSync('git rev-parse --show-toplevel', {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return root || null;
+  } catch {
+    return null; // not a git repo (or git unavailable) → keep capture-all
+  }
+}
+
+// History-import decision for `init`. Opt-in by design: `--import` runs it,
+// interactive prompts, and `--yes` SKIPS (it used to auto-run, which silently
+// imported the full 90-day ~/.claude history including personal projects).
+// `--no-import` is handled earlier (skips outright before the preview).
+export function importMode(flags = {}) {
+  if (flags.importHistory) return 'run';   // explicit opt-in (highest priority)
+  if (flags.yes) return 'skip';            // non-interactive: never auto-import
+  return 'prompt';                         // interactive: ask
+}
+
 function getJson(url) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
@@ -193,6 +224,14 @@ function makeNestedClaudeTool(projectDir, capturePathInHooks, ctx = null) {
   return tool;
 }
 
+function makeNestedCodexTool(projectDir, capturePathInHooks, ctx = null) {
+  const tool = getCodexToolConfig(projectDir, `Codex (${projectDir})`, ctx);
+  if (capturePathInHooks) {
+    tool.hookDefs = getCodexHookDefsWithPath(capturePathInHooks, ctx);
+  }
+  return tool;
+}
+
 async function deviceCodeAuth(serverUrl) {
   // 1. Fetch Auth0 config from server
   let config;
@@ -353,6 +392,9 @@ function getInitArgs() {
       case '--no-mcp':
         flags.noMcp = true;
         break;
+      case '--mcp-only':
+        flags.mcpOnly = true;
+        break;
       case '--no-hooks':
         flags.noHooks = true;
         break;
@@ -379,7 +421,7 @@ function getInitArgs() {
         const a = args[i];
         if (a.startsWith('-')) {
           process.stderr.write(`Warning: unknown flag "${a}" — did you mean --${a.replace(/^-+/, '')}?\n`);
-        } else if (['server', 'projects', 'yes', 'no-mcp', 'no-hooks', 'project-hooks', 'use-repo-path', 'install-launcher', 'mcp-scope'].includes(a)) {
+        } else if (['server', 'projects', 'yes', 'no-mcp', 'mcp-only', 'no-hooks', 'project-hooks', 'use-repo-path', 'install-launcher', 'mcp-scope'].includes(a)) {
           process.stderr.write(`Warning: unexpected argument "${a}" — did you mean --${a}?\n`);
         }
       }
@@ -389,6 +431,138 @@ function getInitArgs() {
   return flags;
 }
 
+/**
+ * Resolve the server URL from --server flag / saved config / interactive prompt.
+ * Normalizes scheme + trailing slash and validates. Shared by the full init flow
+ * and the --mcp-only path.
+ */
+async function resolveServerUrl(flags, auto, currentConfig) {
+  const currentServer = currentConfig.serverUrl || 'http://localhost:3000';
+  let serverUrl;
+  if (flags.server) {
+    serverUrl = flags.server.replace(/\/+$/, '');
+  } else if (auto) {
+    serverUrl = currentServer;
+  } else {
+    const serverInput = await ask(`Server URL (Enter = ${currentServer}): `);
+    serverUrl = (serverInput || currentServer).replace(/\/+$/, '');
+  }
+  if (!/^https?:\/\//i.test(serverUrl)) serverUrl = `http://${serverUrl}`;
+  try { new URL(serverUrl); } catch { error(`Invalid server URL: ${serverUrl}`); process.exit(1); }
+  return serverUrl;
+}
+
+/**
+ * Register the AI Lens MCP server in Claude Code and/or Cursor (HTTP transport —
+ * auth via OAuth in browser, no token needed). Shared by the full init flow and
+ * the --mcp-only path.
+ *
+ * @param {string} serverUrl
+ * @param {object} opts
+ * @param {boolean} opts.auto - non-interactive (--yes)
+ * @param {string} [opts.mcpScope] - explicit --mcp-scope (user|local|project)
+ * @param {string} [opts.forcedScope] - pre-resolved Claude scope; skips the prompt
+ * @param {string} [opts.projectRoot] - project dir to use when the scope is local/project
+ */
+async function setupMcpServers(serverUrl, { auto, mcpScope, forcedScope = null, projectRoot = null }) {
+  const mcpUrl = `${serverUrl}/mcp`;
+
+  const claudeDir = join(homedir(), '.claude');
+  const hasClaudeDir = existsSync(claudeDir);
+  let hasClaudeCli = false;
+  try { execSync(process.platform === 'win32' ? 'where claude' : 'which claude', { stdio: 'ignore' }); hasClaudeCli = true; } catch {}
+
+  const cursorDir = join(homedir(), '.cursor');
+  const hasCursorDir = existsSync(cursorDir);
+
+  // A local/project scope targets the project .cursor/mcp.json; a user scope (or no
+  // project context) targets the global ~/.cursor/mcp.json. Owned here so the full
+  // init flow and --mcp-only map scope → Cursor target the same way.
+  const cursorRootFor = (scope) => ((scope === 'local' || scope === 'project') ? projectRoot : null);
+
+  // Resolve the Claude scope when it's known without prompting. null ⇒ ask
+  // interactively in the Claude block below, and the Cursor target then follows it.
+  let resolvedScope = forcedScope
+    || (mcpScope && ['local', 'project', 'user'].includes(mcpScope) ? mcpScope : null)
+    || (auto ? 'user' : null);
+
+  if (!hasClaudeDir && !hasCursorDir && !cursorRootFor(resolvedScope)) {
+    warn('  No MCP-capable tool found (~/.claude or ~/.cursor) — nothing to register.');
+    return;
+  }
+  if (hasClaudeDir && !hasClaudeCli) {
+    warn('  Claude Code detected but the `claude` CLI is not on PATH — skipping Claude MCP registration.');
+  }
+
+  // Claude Code MCP
+  if (hasClaudeDir && hasClaudeCli) {
+    heading('MCP Server — Claude Code');
+    let doSetup;
+    if (auto) {
+      doSetup = true;
+    } else {
+      const mcpAnswer = await ask('Set up AI Lens MCP server in Claude Code? [Y/n] ');
+      doSetup = !mcpAnswer || mcpAnswer.toLowerCase() === 'y';
+    }
+
+    if (doSetup) {
+      if (!resolvedScope) {
+        const scopeInput = await ask('  Scope — user, local, or project? (Enter = user): ');
+        resolvedScope = ['local', 'project', 'user'].includes(scopeInput) ? scopeInput : 'user';
+      }
+      const scope = resolvedScope;
+      try {
+        try { execSync('claude mcp remove ai-lens -s local', { stdio: 'ignore', shell: true }); } catch {}
+        try { execSync('claude mcp remove ai-lens -s project', { stdio: 'ignore', shell: true }); } catch {}
+        try { execSync('claude mcp remove ai-lens -s user', { stdio: 'ignore', shell: true }); } catch {}
+        cleanupEmptyMcpJson();
+        const escapedMcpUrl = process.platform === 'win32'
+          ? `"${mcpUrl.replace(/"/g, '""')}"`
+          : `'${mcpUrl.replace(/'/g, "'\\''")}'`;
+        execSync(
+          `claude mcp add --transport http ai-lens -s ${scope} ${escapedMcpUrl}`,
+          { stdio: 'inherit', shell: true },
+        );
+        success(`  MCP server registered in Claude Code (${scope})`);
+      } catch (err) {
+        error(`  Failed to register MCP server: ${err.message}`);
+      }
+    } else {
+      info('  Skipped');
+    }
+  }
+
+  // Cursor MCP. Mirror the resolved scope: project file for local/project, else global.
+  // Gate on a project target too, so a project-scoped install still registers even when
+  // the global ~/.cursor doesn't exist (fresh machine / CI / Cursor-only-in-project).
+  const cursorProjectRoot = cursorRootFor(resolvedScope);
+  if (hasCursorDir || cursorProjectRoot) {
+    heading('MCP Server — Cursor');
+    let doSetup;
+    if (auto) {
+      doSetup = true;
+    } else {
+      const cursorMcpAnswer = await ask('Set up AI Lens MCP server in Cursor? [Y/n] ');
+      doSetup = !cursorMcpAnswer || cursorMcpAnswer.toLowerCase() === 'y';
+    }
+
+    if (doSetup) {
+      try {
+        removeCursorMcp();
+        addCursorMcp(mcpUrl, { projectRoot: cursorProjectRoot });
+        const where = cursorProjectRoot
+          ? join(cursorProjectRoot, '.cursor', 'mcp.json')
+          : '~/.cursor/mcp.json';
+        success(`  MCP server registered in Cursor (${where})`);
+      } catch (err) {
+        error(`  Failed to register MCP server: ${err.message}`);
+      }
+    } else {
+      info('  Skipped');
+    }
+  }
+}
+
 export default async function init() {
   const flags = getInitArgs();
   const auto = flags.yes || false;
@@ -400,6 +574,50 @@ export default async function init() {
   heading(`AI Lens — Init  v${version} (${commit})`);
   detail(`capture.js: ${CAPTURE_PATH}`);
 
+  // --mcp-only: register ONLY the MCP server, mirroring the existing AI Lens
+  // install scope (local/project vs global/user). Skips hooks, auth, and import.
+  if (flags.mcpOnly) {
+    if (flags.noMcp) {
+      error('--mcp-only cannot be combined with --no-mcp.');
+      process.exit(1);
+    }
+    heading('Configuration');
+    const currentConfig = readLensConfig();
+    const serverUrl = await resolveServerUrl(flags, auto, currentConfig);
+    info(`  Server: ${serverUrl}`);
+
+    // Soft health check — don't block registration (the server may be briefly down),
+    // but warn so a typo'd URL doesn't silently register a dead MCP (verification is skipped).
+    try {
+      const health = await getJson(`${serverUrl}/api/health`);
+      if (health.status !== 'ok') warn(`  Server responded with unexpected status: ${JSON.stringify(health)}`);
+    } catch (err) {
+      warn(`  Server unreachable (${err.message}) — registering MCP anyway; double-check the URL.`);
+    }
+
+    // Persist the server URL so it sticks for later runs.
+    saveLensConfig({ ...currentConfig, serverUrl });
+
+    // Scope precedence: explicit --mcp-scope > --project-hooks > detected footprint > user.
+    const cwd = resolve(process.cwd());
+    let forcedScope;
+    if (flags.mcpScope && ['user', 'local', 'project'].includes(flags.mcpScope)) {
+      forcedScope = flags.mcpScope;
+    } else if (flags.projectHooks) {
+      forcedScope = 'local';
+    } else {
+      const detected = detectAiLensInstallScope(cwd); // 'project' | 'user' | null
+      forcedScope = detected === 'project' ? 'local' : 'user';
+    }
+    info(`  Install scope: ${forcedScope === 'user' ? 'global (user)' : 'local (project)'}`);
+
+    await setupMcpServers(serverUrl, { auto, forcedScope, projectRoot: cwd });
+
+    heading('Done');
+    info('  MCP-only setup complete — hooks, auth, and import were skipped.');
+    return;
+  }
+
   // Resolve a stable node binary path up-front. The same resolution is baked into
   // the per-machine launcher (run.sh / run.cmd) and into hook commands. We only
   // need it when hooks will actually be written; --no-hooks skips it so users
@@ -546,20 +764,7 @@ export default async function init() {
   const currentConfig = readLensConfig();
 
   // Server URL
-  const currentServer = currentConfig.serverUrl || 'http://localhost:3000';
-  let serverUrl;
-  if (flags.server) {
-    serverUrl = flags.server.replace(/\/+$/, '');
-  } else if (auto) {
-    serverUrl = currentServer;
-  } else {
-    const serverInput = await ask(
-      `Server URL (Enter = ${currentServer}): `,
-    );
-    serverUrl = (serverInput || currentServer).replace(/\/+$/, '');
-  }
-  if (!/^https?:\/\//i.test(serverUrl)) serverUrl = `http://${serverUrl}`;
-  try { new URL(serverUrl); } catch { error(`Invalid server URL: ${serverUrl}`); process.exit(1); }
+  const serverUrl = await resolveServerUrl(flags, auto, currentConfig);
   info(`  Server: ${serverUrl}`);
 
   // Project filter
@@ -569,7 +774,11 @@ export default async function init() {
   if (flags.projects) {
     projects = flags.projects;
   } else if (auto) {
-    projects = currentProjects || projectHooksDefault;
+    // Fresh config under --yes: default to the git root of cwd (the work tree),
+    // not null. null = capture ALL projects. Stays null only when cwd isn't a
+    // git repo (bots/containers) — safe because the import is separately gated.
+    // `--projects all` is the explicit opt-in for capture-everything.
+    projects = currentProjects || projectHooksDefault || defaultProjectsScope();
   } else {
     const projectsDefault = currentProjects || projectHooksDefault || 'all';
     const projectsInput = await ask(
@@ -756,34 +965,50 @@ export default async function init() {
 
     let nestedScan = [];
     let nestedPending = [];
+    let nestedCodexTrust = [];
     if (flags.projectHooks) {
       const trackedRoots = getTrackedRoots(newConfig.projects, resolve(process.cwd()));
-      nestedScan = scanNestedClaudeProjects(trackedRoots);
+      nestedScan = scanNestedProjects(trackedRoots);
 
       if (nestedScan.length > 0) {
-        heading('Nested Claude Code projects');
+        heading('Nested projects');
         for (const result of nestedScan) {
           const installNote = result.installTarget ? ` -> install in ${result.installTarget}` : '';
-          info(`  ${result.relativePath}: ${result.status}${installNote}`);
+          info(`  ${result.relativePath} (${result.tool}): ${result.status}${installNote}`);
         }
         const summary = summarizeNestedProjects(nestedScan);
-        detail(`Found ${summary.total} nested project(s), ${summary.unhooked} need attention.`);
+        detail(`Found ${summary.total} nested hook target(s), ${summary.unhooked} need attention.`);
         blank();
       }
 
       const nestedActionable = nestedScan.filter(result => result.installTarget);
+      nestedCodexTrust = nestedScan
+        .filter(result => result.tool === 'codex' && !result.installTarget)
+        .map(result => ({ tool: makeNestedCodexTool(result.projectDir, null, ctx) }));
       let shouldInstallNested = auto && nestedActionable.length > 0;
       if (!auto && nestedActionable.length > 0) {
-        const answer = await ask(`Install hooks in ${nestedActionable.length} nested Claude Code project(s)? [Y/n] `);
+        const answer = await ask(`Install hooks in ${nestedActionable.length} nested hook target(s)? [Y/n] `);
         shouldInstallNested = !answer || ['y', 'yes'].includes(answer.toLowerCase());
       }
 
       if (shouldInstallNested) {
         nestedPending = nestedActionable.map(result => {
-          const capturePathInHooks = flags.useRepoPath
-            ? relative(result.projectDir, resolve(REPO_CAPTURE_PATH)).replace(/\\/g, '/')
-            : null;
-          const tool = makeNestedClaudeTool(result.projectDir, capturePathInHooks, ctx);
+          let tool;
+          if (result.tool === 'codex') {
+            const capturePathInHooks = flags.useRepoPath
+              ? (() => {
+                const abs = resolve(REPO_CAPTURE_PATH);
+                const userHome = homedir();
+                return abs.startsWith(userHome) ? `~${abs.slice(userHome.length).replace(/\\/g, '/')}` : abs.replace(/\\/g, '/');
+              })()
+              : null;
+            tool = makeNestedCodexTool(result.projectDir, capturePathInHooks, ctx);
+          } else {
+            const capturePathInHooks = flags.useRepoPath
+              ? relative(result.projectDir, resolve(REPO_CAPTURE_PATH)).replace(/\\/g, '/')
+              : null;
+            tool = makeNestedClaudeTool(result.projectDir, capturePathInHooks, ctx);
+          }
           tool.configPath = join(tool.dirPath, result.installTarget);
           return {
             tool,
@@ -822,7 +1047,7 @@ export default async function init() {
       // Idempotent: re-run hook trust enrollment even when no hooks needed
       // rewriting. Without this, a previously-installed-but-untrusted Codex
       // hook stays inert until the next time hooks themselves change.
-      for (const { tool } of analyses) {
+      for (const { tool } of [...analyses, ...nestedCodexTrust]) {
         if (tool.name !== 'Codex' && !tool.name.startsWith('Codex')) continue;
         try {
           const r = enableCodexHookTrust(tool.configPath);
@@ -861,8 +1086,10 @@ export default async function init() {
 
       for (const { tool, analysis } of [...pending, ...nestedPending]) {
         try {
-          // Backup malformed shared configs (e.g. ~/.claude/settings.json) before overwriting
-          if (analysis.status === 'malformed' && tool.sharedConfig) {
+          // Backup malformed configs before overwriting. analyzeToolHooks already
+          // renames non-shared malformed files; nested scan is read-only, so it
+          // reaches this path and needs the backup here.
+          if (analysis.status === 'malformed' && existsSync(tool.configPath)) {
             try { copyFileSync(tool.configPath, tool.configPath + '.bak'); } catch { /* file may be gone */ }
           }
           const existingConfig = analysis.config || null;
@@ -882,7 +1109,7 @@ export default async function init() {
       // key, no `file:` prefix) — the same state the TUI "Trust all" flow writes,
       // but driven by AI Lens at install time. With it, `codex exec` fires hooks
       // with no interactive step.
-      for (const { tool } of [...pending, ...nestedPending]) {
+      for (const { tool } of [...pending, ...nestedPending, ...nestedCodexTrust]) {
         if (tool.name !== 'Codex' && !tool.name.startsWith('Codex')) continue;
         try {
           const r = enableCodexHookTrust(tool.configPath);
@@ -1074,81 +1301,17 @@ export default async function init() {
     } catch {}
   }
 
-  // MCP setup (HTTP transport — auth via OAuth in browser, no token needed)
+  // MCP setup (HTTP transport — auth via OAuth in browser, no token needed).
+  // --project-hooks installs hooks at project scope, so mirror that for the MCP:
+  // default the scope to local and target the project .cursor/mcp.json (an explicit
+  // --mcp-scope still wins; setupMcpServers maps scope → Cursor target).
   if (!flags.noMcp) {
-    const mcpUrl = `${serverUrl}/mcp`;
-
-    // Claude Code MCP
-    const claudeDir = join(homedir(), '.claude');
-    const hasClaudeDir = existsSync(claudeDir);
-    let hasClaudeCli = false;
-    try { execSync(process.platform === 'win32' ? 'where claude' : 'which claude', { stdio: 'ignore' }); hasClaudeCli = true; } catch {}
-
-    if (hasClaudeDir && hasClaudeCli) {
-      heading('MCP Server — Claude Code');
-      let doSetup;
-      if (auto) {
-        doSetup = true;
-      } else {
-        const mcpAnswer = await ask('Set up AI Lens MCP server in Claude Code? [Y/n] ');
-        doSetup = !mcpAnswer || mcpAnswer.toLowerCase() === 'y';
-      }
-
-      if (doSetup) {
-        let scope;
-        if (flags.mcpScope && ['local', 'project', 'user'].includes(flags.mcpScope)) {
-          scope = flags.mcpScope;
-        } else if (auto) {
-          scope = 'user';
-        } else {
-          const scopeInput = await ask('  Scope — user, local, or project? (Enter = user): ');
-          scope = ['local', 'project', 'user'].includes(scopeInput) ? scopeInput : 'user';
-        }
-        try {
-          try { execSync('claude mcp remove ai-lens -s local', { stdio: 'ignore', shell: true }); } catch {}
-          try { execSync('claude mcp remove ai-lens -s project', { stdio: 'ignore', shell: true }); } catch {}
-          try { execSync('claude mcp remove ai-lens -s user', { stdio: 'ignore', shell: true }); } catch {}
-          cleanupEmptyMcpJson();
-          const escapedMcpUrl = process.platform === 'win32'
-            ? `"${mcpUrl.replace(/"/g, '""')}"`
-            : `'${mcpUrl.replace(/'/g, "'\\''")}'`;
-          execSync(
-            `claude mcp add --transport http ai-lens -s ${scope} ${escapedMcpUrl}`,
-            { stdio: 'inherit', shell: true },
-          );
-          success(`  MCP server registered in Claude Code (${scope})`);
-        } catch (err) {
-          error(`  Failed to register MCP server: ${err.message}`);
-        }
-      } else {
-        info('  Skipped');
-      }
-    }
-
-    // Cursor MCP
-    const cursorDir = join(homedir(), '.cursor');
-    if (existsSync(cursorDir)) {
-      heading('MCP Server — Cursor');
-      let doSetup;
-      if (auto) {
-        doSetup = true;
-      } else {
-        const cursorMcpAnswer = await ask('Set up AI Lens MCP server in Cursor? [Y/n] ');
-        doSetup = !cursorMcpAnswer || cursorMcpAnswer.toLowerCase() === 'y';
-      }
-
-      if (doSetup) {
-        try {
-          removeCursorMcp();
-          addCursorMcp(mcpUrl);
-          success('  MCP server registered in Cursor (~/.cursor/mcp.json)');
-        } catch (err) {
-          error(`  Failed to register MCP server: ${err.message}`);
-        }
-      } else {
-        info('  Skipped');
-      }
-    }
+    await setupMcpServers(serverUrl, {
+      auto,
+      mcpScope: flags.mcpScope,
+      forcedScope: (flags.projectHooks && !flags.mcpScope) ? 'local' : null,
+      projectRoot: flags.projectHooks ? resolve(process.cwd()) : null,
+    });
   }
 
   // Quick verification
@@ -1278,7 +1441,8 @@ export default async function init() {
 
 /**
  * After a successful init, offer to import the developer's local Claude Code
- * history. `--no-import` skips; `--import` or `--yes` runs it without prompting;
+ * history. `--no-import` skips; `--import` runs it without prompting; `--yes`
+ * does NOT import (opt-in only — avoids silently pulling personal history);
  * otherwise asks interactively. No-op if there's no `~/.claude/projects`.
  */
 async function maybeOfferImportHistory(flags) {
@@ -1301,18 +1465,21 @@ async function maybeOfferImportHistory(flags) {
     ? `Found ${preview.count} Claude Code session${preview.count === 1 ? '' : 's'} from ${day(preview.earliest)} to ${day(preview.latest)} (last 90d).`
     : 'Local Claude Code history found.';
 
-  let run = flags.importHistory || flags.yes;
-  if (run) {
-    info(`  ${previewLine}`);
-  } else {
+  info(`  ${previewLine}`);
+  // History import is opt-IN (importMode): `--import` runs, interactive asks,
+  // `--yes` SKIPS. `--yes` used to auto-import (`|| flags.yes`), silently pulling
+  // the full 90-day ~/.claude history (incl. personal projects) on a fresh config.
+  const mode = importMode(flags);
+  let run = mode === 'run';
+  if (mode === 'prompt') {
     try {
-      const answer = (await ask(`${previewLine} Import now? (Y/n) `)).toLowerCase();
+      const answer = (await ask('  Import now? (Y/n) ')).toLowerCase();
       run = answer === '' || answer === 'y' || answer === 'yes';
     } catch { run = false; }
   }
   if (!run) {
     blank();
-    info('  Skipped import. Run `npx -y ai-lens import claude-code` anytime to bring it in.');
+    info('  Skipped local history import. Run `npx -y ai-lens import claude-code` (or pass `--import`) to bring it in.');
     return;
   }
 

package/cli/scan.js

@@ -78,40 +78,68 @@ function hasAnyNonAiLensHooks(config) {
   return collectHookEntries(config).some(entry => !isAiLensHook(entry));
 }
 
-function classifyProject(projectDir) {
-  const claudeDir = join(projectDir, '.claude');
-  const settingsPath = join(claudeDir, 'settings.json');
-  const settingsLocalPath = join(claudeDir, 'settings.local.json');
-  const settings = readJsonSafe(settingsPath);
-  const settingsLocal = readJsonSafe(settingsLocalPath);
-
-  if (settings === 'MALFORMED' || settingsLocal === 'MALFORMED') {
+function classifyHookProject({ tool, configs, installTarget, existingConfig, malformedInstallTarget = null }) {
+  if (configs.some(config => config === 'MALFORMED') || existingConfig === 'MALFORMED') {
     return {
+      tool,
       status: 'malformed',
-      installTarget: null,
+      installTarget: malformedInstallTarget,
       existingConfig: null,
     };
   }
 
-  if (hasAnyAiLensHook(settings) || hasAnyAiLensHook(settingsLocal)) {
+  if (configs.some(hasAnyAiLensHook) || hasAnyAiLensHook(existingConfig)) {
     return {
+      tool,
       status: 'installed',
       installTarget: null,
       existingConfig: null,
     };
   }
 
+  return {
+    tool,
+    status: configs.some(hasAnyNonAiLensHooks) || hasAnyNonAiLensHooks(existingConfig)
+      ? 'has non-ai-lens hooks'
+      : 'missing',
+    installTarget,
+    existingConfig,
+  };
+}
+
+function classifyClaudeProject(projectDir) {
+  const claudeDir = join(projectDir, '.claude');
+  const settingsPath = join(claudeDir, 'settings.json');
+  const settingsLocalPath = join(claudeDir, 'settings.local.json');
+  const settings = readJsonSafe(settingsPath);
+  const settingsLocal = readJsonSafe(settingsLocalPath);
+
   // AI Lens Claude hooks are per-machine / OS-specific (ADR 0003 — absolute node path,
   // conhost.exe on Windows). They must NEVER be written into a COMMITTED settings.json
   // (that re-introduces the cross-OS / cross-machine breakage MR !298 removed). Always
   // install into the gitignored, per-machine settings.local.json, which Claude Code
   // merges with settings.json at runtime — so a project's own non-ai-lens hooks in
   // settings.json keep working alongside.
-  return {
-    status: hasAnyNonAiLensHooks(settings) ? 'has non-ai-lens hooks' : 'missing',
+  return classifyHookProject({
+    tool: 'claude',
+    configs: [settings],
     installTarget: 'settings.local.json',
     existingConfig: settingsLocal,
-  };
+  });
+}
+
+function classifyCodexProject(projectDir) {
+  const codexDir = join(projectDir, '.codex');
+  const hooksPath = join(codexDir, 'hooks.json');
+  const hooks = readJsonSafe(hooksPath);
+
+  return classifyHookProject({
+    tool: 'codex',
+    configs: [],
+    installTarget: 'hooks.json',
+    malformedInstallTarget: 'hooks.json',
+    existingConfig: hooks,
+  });
 }
 
 function scanRoot(rootPath, options, results, seen) {
@@ -133,18 +161,40 @@ function scanRoot(rootPath, options, results, seen) {
       const childPath = join(currentDir, child.name);
       if (isIgnoredByGitignore(rules, childPath)) continue;
 
-      if (child.name === '.git' || child.name === '.claude') {
+      if (child.name === '.git' || child.name === '.claude' || child.name === '.codex') {
         const projectDir = resolve(currentDir);
         if (projectDir !== rootPath) {
           const depth = countDepth(rootPath, projectDir);
-          if (depth <= maxDepth && !seen.has(projectDir)) {
-            seen.add(projectDir);
-            results.push({
-              projectDir,
-              relativePath: relative(rootPath, projectDir).replace(/\\/g, '/'),
-              marker: child.name,
-              ...classifyProject(projectDir),
-            });
+          if (depth <= maxDepth) {
+            const projectKey = `${rootPath}:${projectDir}`;
+            if (!seen.has(projectKey)) {
+              seen.add(projectKey);
+              const base = {
+                projectDir,
+                relativePath: relative(rootPath, projectDir).replace(/\\/g, '/'),
+                marker: child.name,
+              };
+              // Classify by which markers ACTUALLY exist in the dir, not by which
+              // child readdir happened to yield first. readdirSync order is
+              // filesystem-dependent (unsorted), so gating Claude on
+              // `child.name !== '.codex'` dropped the Claude target whenever
+              // `.codex` was enumerated before `.git`/`.claude` in the same repo
+              // (latent on Linux; ANL-1126 review). Codex is offered for every
+              // project dir; Claude only for git/.claude repos (a .codex-only dir
+              // is not a Claude project).
+              const isClaudeProject = existsSync(join(projectDir, '.git'))
+                || existsSync(join(projectDir, '.claude'));
+              if (isClaudeProject) {
+                results.push({
+                  ...base,
+                  ...classifyClaudeProject(projectDir),
+                });
+              }
+              results.push({
+                ...base,
+                ...classifyCodexProject(projectDir),
+              });
+            }
           }
         }
         continue;
@@ -160,7 +210,7 @@ function scanRoot(rootPath, options, results, seen) {
   visit(rootPath);
 }
 
-export function scanNestedClaudeProjects(projectRoots, options = {}) {
+export function scanNestedProjects(projectRoots, options = {}) {
   const maxDepth = Number.isInteger(options.maxDepth) ? options.maxDepth : DEFAULT_MAX_DEPTH;
   const roots = (projectRoots || []).map(path => resolve(path));
   const results = [];
@@ -171,7 +221,15 @@ export function scanNestedClaudeProjects(projectRoots, options = {}) {
     scanRoot(rootPath, { maxDepth }, results, seen);
   }
 
-  return results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return results.sort((a, b) => (
+    a.relativePath.localeCompare(b.relativePath) || a.tool.localeCompare(b.tool)
+  ));
+}
+
+export function scanNestedClaudeProjects(projectRoots, options = {}) {
+  return scanNestedProjects(projectRoots, options)
+    .filter(result => result.tool === 'claude')
+    .map(({ tool, ...result }) => result);
 }
 
 export function summarizeNestedProjects(results) {

package/cli/status.js

@@ -11,7 +11,7 @@ import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConf
 import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, LAST_STATUS_REPORT_PATH, getGitIdentity, getMonitoredProjects } from '../client/config.js';
 import { isLockStale } from '../client/sender.js';
 import { initLogger, info, success, warn, error, heading, blank } from './logger.js';
-import { scanNestedClaudeProjects, summarizeNestedProjects } from './scan.js';
+import { scanNestedProjects, summarizeNestedProjects } from './scan.js';
 
 const INIT_LOG_PATH = join(DATA_DIR, 'init.log');
 
@@ -510,6 +510,16 @@ function checkGitIdentity() {
   return { ok: false, summary: 'not configured', detail: 'Git identity not configured (git config user.email)' };
 }
 
+// Server-driven update nudge ([0093]): the sender caches the server's verdict to
+// ~/.ai-lens/messages.json. Read-only here (no network); returns the outdated
+// message if the server says this client is behind the latest published version.
+function readOutdatedNudge() {
+  try {
+    const cache = JSON.parse(readFileSync(join(homedir(), '.ai-lens', 'messages.json'), 'utf-8'));
+    return (cache.messages || []).find(m => m && typeof m.id === 'string' && m.id.startsWith('outdated:')) || null;
+  } catch { return null; }
+}
+
 export function checkClientFiles(tools = []) {
   // In repo-path mode the hooks run capture.js straight from the repo, so the
   // ~/.ai-lens/client/ copy (if any) is an UNUSED leftover from a prior copy-mode
@@ -529,6 +539,10 @@ export function checkClientFiles(tools = []) {
     if (copyExists) {
       detail += `\n  Note: ~/.ai-lens/client/ exists but is UNUSED in repo-path mode (stale leftover from an old copy-install; safe to ignore).`;
     }
+    // Server nudge (if behind latest published): surface as an info line, but keep
+    // ok=true — a stale repo checkout is fixed by /sync, not a false ✗ here (Y4).
+    const repoNudge = readOutdatedNudge();
+    if (repoNudge) detail += `\n  ! ${repoNudge.text.split('\n').join('\n     ')}`;
     // Healthy as long as the hook-source version is readable. Don't compare against
     // the CLI: `ai-lens status` may run from a global npx CLI while the hooks point
     // at a checkout — that mismatch is expected, not an error. A stale repo checkout
@@ -557,9 +571,16 @@ export function checkClientFiles(tools = []) {
     const clientCommit = versionJson.commit || 'unknown';
     outdated = clientVersion !== cliVersion || clientCommit !== cliCommit;
     versionDetail = `\n  Client version: ${clientVersion} (${clientCommit})`;
+    const nudge = readOutdatedNudge();
     if (outdated) {
       versionDetail += `\n  CLI version:    ${cliVersion} (${cliCommit})`;
-      versionDetail += `\n  ! Client is outdated — run: npx -y ai-lens init --yes`;
+      if (!nudge) versionDetail += `\n  ! Client is outdated — run: npx -y ai-lens init --yes`;
+    }
+    // Server says behind latest published → copy-mode must re-init. Prefer the
+    // server's line (it carries the exact latest version + command).
+    if (nudge) {
+      versionDetail += `\n  ! ${nudge.text.split('\n').join('\n     ')}`;
+      outdated = true;
     }
   } catch {
     versionDetail = `\n  Client version: unknown (version.json not found — run: npx -y ai-lens init)`;
@@ -1564,7 +1585,7 @@ export default async function status({ report = false } = {}) {
 
   if (hasProjectHooks) {
     const nestedRoots = getMonitoredProjects() || [process.cwd()];
-    const nestedProjects = scanNestedClaudeProjects(nestedRoots);
+    const nestedProjects = scanNestedProjects(nestedRoots);
     const nestedSummary = summarizeNestedProjects(nestedProjects);
     const nestedUnhooked = nestedProjects.filter(result => result.status !== 'installed');
     printLine('Nested projects', {
@@ -1572,10 +1593,10 @@ export default async function status({ report = false } = {}) {
       summary: nestedSummary.total === 0
         ? 'none found'
         : nestedSummary.unhooked === 0
-          ? `${nestedSummary.total} nested project(s), all hooked`
-          : `${nestedSummary.unhooked} unhooked / ${nestedSummary.total} nested project(s)`,
+          ? `${nestedSummary.total} nested hook target(s), all hooked`
+          : `${nestedSummary.unhooked} unhooked / ${nestedSummary.total} nested hook target(s)`,
       detail: nestedUnhooked.length > 0
-        ? `nested_unhooked_projects:\n${nestedUnhooked.map(result => `- ${result.projectDir} (${result.status})`).join('\n')}`
+        ? `nested_unhooked_projects:\n${nestedUnhooked.map(result => `- ${result.projectDir} (${result.tool}: ${result.status})`).join('\n')}`
         : 'nested_unhooked_projects: none',
     });
   }

package/client/capture.js

@@ -29,6 +29,8 @@ import {
   getGitIdentity,
   getGitMetadata,
   getMonitoredProjects,
+  MESSAGES_PATH,
+  MESSAGES_SHOWN_PATH,
 } from './config.js';
 import { isLockStale, isSenderBackoffActive } from './sender.js';
 import { toNumberOrNull, buildTokenUsageRaw } from './token-usage.js';
@@ -1379,6 +1381,86 @@ export function trySpawnSender() {
 }
 
 
+// =============================================================================
+// Server-driven client messages ([0093]) — render on SessionStart
+// =============================================================================
+
+const MESSAGE_THROTTLE_MS = 24 * 60 * 60 * 1000; // show a given message ≤ once/day
+const MESSAGE_MAX_LEN = 2000;
+// Appended only for Cursor (additional_context → agent context) to raise the odds
+// the agent relays the nudge to the human. NOT added for Claude (direct banner).
+const CURSOR_RELAY_SUFFIX = '\n(Сообщи это пользователю в начале своего ответа.)';
+
+function readJsonFileSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
+}
+
+function sanitizeMessageText(s) {
+  if (typeof s !== 'string') return '';
+  // Strip control chars except newline/tab; cap length (defense-in-depth — the
+  // text is server-controlled and enters the tool's context).
+  let out = '';
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    if (c === 9 || c === 10 || (c >= 32 && c !== 127)) out += ch;
+    if (out.length >= MESSAGE_MAX_LEN) break;
+  }
+  return out.slice(0, MESSAGE_MAX_LEN);
+}
+
+/** First cache message whose id hasn't been shown within the throttle window. */
+function pickUnthrottledMessage(messages, shownMap, nowMs) {
+  for (const m of messages) {
+    if (!m || !m.id || typeof m.text !== 'string') continue;
+    const last = shownMap[m.id] ? Date.parse(shownMap[m.id]) : 0;
+    if (!Number.isFinite(last) || nowMs - last >= MESSAGE_THROTTLE_MS) return m;
+  }
+  return null;
+}
+
+/** Atomically record `id` as shown now, pruning ids no longer in the cache. */
+function markShown(id, validIds, nowIso) {
+  try {
+    const map = readJsonFileSafe(MESSAGES_SHOWN_PATH) || {};
+    const next = {};
+    for (const k of validIds) if (map[k]) next[k] = map[k];
+    next[id] = nowIso;
+    const tmp = MESSAGES_SHOWN_PATH + '.tmp.' + process.pid;
+    writeFileSync(tmp, JSON.stringify(next));
+    renameSync(tmp, MESSAGES_SHOWN_PATH);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * On SessionStart, render a cached server message into the tool's context via the
+ * one stdout write capture.js ever makes. Claude → `systemMessage` (banner);
+ * Cursor → `additional_context` (+ relay suffix). Codex/unknown → nothing.
+ * Identity-independent (reads only the local cache), throttled per id, and fully
+ * isolated: any failure is swallowed so it can never flip capture to exit≠0.
+ */
+export function maybeEmitSessionStartMessage(primary, { now = Date.now() } = {}) {
+  try {
+    if (!primary || primary.type !== 'SessionStart') return;
+    const source = primary.source;
+    if (source !== 'claude_code' && source !== 'cursor') return; // codex/unknown deferred
+    const cache = readJsonFileSafe(MESSAGES_PATH);
+    const messages = cache && Array.isArray(cache.messages) ? cache.messages : null;
+    if (!messages || messages.length === 0) return;
+    const shownMap = readJsonFileSafe(MESSAGES_SHOWN_PATH) || {};
+    const msg = pickUnthrottledMessage(messages, shownMap, now);
+    if (!msg) return;
+
+    const text = sanitizeMessageText(msg.text);
+    if (!text) return;
+    const out = source === 'claude_code'
+      ? { systemMessage: text }
+      : { additional_context: text + CURSOR_RELAY_SUFFIX };
+
+    process.stdout.write(JSON.stringify(out));
+    markShown(msg.id, messages.map(m => m && m.id).filter(Boolean), new Date(now).toISOString());
+  } catch { /* never break capture */ }
+}
+
 // =============================================================================
 // Main
 // =============================================================================
@@ -1435,6 +1517,12 @@ async function main() {
   // hook invocation on the same machine.
   const primary = events[0];
 
+  // Render a server-driven update nudge ([0093]) on SessionStart — BEFORE the
+  // project_filter / no_email / dedup gates below (those drop exactly the
+  // stale/unknown devs we want to reach). Identity-independent, reads only the
+  // local cache, never throws → can't flip this process to a non-zero exit.
+  maybeEmitSessionStartMessage(primary);
+
   // Filter by monitored projects (if configured) — based on the primary event.
   // If the primary is filtered out, drop the entire batch (the per-call events
   // share the same project_path).

package/client/config.js

@@ -24,6 +24,10 @@ export const LOG_PATH = join(DATA_DIR, 'sender.log');
 export const CAPTURE_LOG_PATH = join(DATA_DIR, 'capture.log');
 export const SENDER_BACKOFF_PATH = join(DATA_DIR, 'sender-backoff.json');
 export const LAST_STATUS_REPORT_PATH = join(DATA_DIR, 'last-status-report');
+// Server-driven client messages ([0093]): sender caches them here; capture.js
+// renders on SessionStart. `messages-shown` is the per-id throttle ledger.
+export const MESSAGES_PATH = join(DATA_DIR, 'messages.json');
+export const MESSAGES_SHOWN_PATH = join(DATA_DIR, 'messages-shown.json');
 export const LOG_MAX_AGE_DAYS = 30;
 const GIT_ROOT_CACHE = new Map();
 // Pipe stderr (instead of inheriting it) so that "fatal: not a git repository"
@@ -154,6 +158,24 @@ export function getClientVersion() {
   return { version: 'unknown', commit: 'unknown' };
 }
 
+/**
+ * Install mode of the RUNNING client — mirrors getClientVersion()'s three-way
+ * resolution so mode and version never disagree:
+ *   'copy'    — sibling version.json (copied into ~/.ai-lens/client/ by init)
+ *   'repo'    — running from the ai-lens package checkout (--use-repo-path / npx)
+ *   'unknown' — neither resolves
+ * Sent as X-Client-Mode so the server can return a mode-aware update nudge ([0093]).
+ */
+export function getClientMode() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  try { readFileSync(join(here, 'version.json'), 'utf-8'); return 'copy'; } catch { /* not a copy */ }
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(here, '..', 'package.json'), 'utf-8'));
+    if (pkg?.name === 'ai-lens' && pkg.version) return 'repo';
+  } catch { /* not a checkout */ }
+  return 'unknown';
+}
+
 export function getGitIdentity(cwd) {
   let email = null;
   let name = null;

package/client/sender.js

@@ -41,6 +41,8 @@ import {
   getServerUrl,
   getAuthToken,
   getClientVersion,
+  getClientMode,
+  MESSAGES_PATH,
   DEFAULT_SERVER_URL,
   log,
 } from './config.js';
@@ -627,12 +629,32 @@ export function isTransientFetchError(err) {
   return false;
 }
 
+/**
+ * Cache server-driven client messages ([0093]) for capture.js to render on
+ * SessionStart. `undefined` = no response parsed this run → leave cache as-is;
+ * `[]` = client is current → remove the cache (so a fixed client stops nudging);
+ * non-empty → atomic tmp+rename write. Best-effort: never break the flush.
+ */
+function cacheClientMessages(messages) {
+  if (!Array.isArray(messages)) return;
+  try {
+    if (messages.length === 0) {
+      try { unlinkSync(MESSAGES_PATH); } catch { /* already absent */ }
+      return;
+    }
+    const tmp = MESSAGES_PATH + '.tmp.' + process.pid;
+    writeFileSync(tmp, JSON.stringify({ updatedAt: new Date().toISOString(), messages }));
+    renameSync(tmp, MESSAGES_PATH);
+  } catch { /* best-effort */ }
+}
+
 function buildHeaders(identity, authToken) {
   const { version: clientVersion, commit: clientCommit } = getClientVersion();
   const headers = {
     'Content-Type':     'application/json',
     'Connection':       'close',
     'X-Client-Version': `${clientVersion}+${clientCommit}`,
+    'X-Client-Mode':    getClientMode(),
   };
   if (identity.email) headers['X-Developer-Git-Email'] = identity.email;
   if (identity.name)  headers['X-Developer-Name'] = encodeURIComponent(identity.name);
@@ -849,6 +871,7 @@ async function main() {
   }
 
   const sentEventIds = new Set();
+  let lastMessages; // server-driven client messages ([0093]) from the last ok POST
 
   try {
     for (const { identity, events: batch } of byDeveloper.values()) {
@@ -857,6 +880,7 @@ async function main() {
       for (const chunk of chunks) {
         const result = await postEvents(serverUrl, chunk, identity, hasAuthToken ? authToken : null, { lockPath });
         refreshLock(lockPath);
+        if (Array.isArray(result?.messages)) lastMessages = result.messages;
         totalReceived += (result?.received ?? 0);
         if ((result?.skipped ?? 0) > 0) {
           log({ msg: 'server-skipped', skipped: result.skipped, chunk_size: chunk.length, developer: identity.email });
@@ -869,6 +893,7 @@ async function main() {
       log({ msg: 'sent', events: totalReceived, chunks: chunks.length, developer: identity.email, projects, server: serverUrl });
     }
     clearSenderBackoff();
+    cacheClientMessages(lastMessages);
     commitQueue(sendingDir, acquiredFiles);
     trySpawnStatusReport();
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.107",
+  "version": "0.8.109",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {