ai-lens 0.8.67 → 0.8.69

package/.commithash

@@ -1 +1 @@
-cf6dbc7
+fe949b0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.69 — 2026-05-27
+- feat: per-machine launcher (`~/.ai-lens/client/run.sh` / `run.cmd`) now also accepts an optional script path as its first argument. With no args it still execs the sibling `capture.js` (default install), but `~/.ai-lens/client/run.sh path/to/some/capture.js` execs that script with the launcher's resolved node — letting bootstrap-style workflows (e.g. meta-cursor) route through the launcher for proper node resolution while keeping `capture.js` under git in the workspace repo.
+- feat: new `--install-launcher` flag for `init`. Forces launcher installation even when `--no-hooks` is set, so the meta-cursor setup skill can wire up `~/.ai-lens/client/run.sh` without touching the static hook templates in the workspace repo.
+
+## 0.8.68 — 2026-05-27
+- fix: hooks now resolve node from nvm, asdf, fnm, volta and n in addition to Homebrew. Previously `init` fell back to `/usr/bin/env node`, which made GUI Cursor on macOS silently lose every event because launchd's minimal PATH doesn't include node. Affected users with custom node installs (e.g. `/Users/<you>/node/bin/node`) saw hundreds of dropped events with no visible error.
+- feat: `init` now installs a per-machine launcher (`~/.ai-lens/client/run.sh` on macOS/Linux, `run.cmd` on Windows) with the resolved node path baked in. Hook commands invoke the launcher directly, so they no longer depend on the GUI app's PATH and survive `brew upgrade node`.
+- fix: `init` now fails loudly if no node binary can be resolved, and warns when the only available node path is version-pinned (e.g. `/opt/homebrew/Cellar/node/24.10.0/bin/node`) and will break on upgrade.
+
 ## 0.8.67 — 2026-05-26
 - fix: sessions launched from a subdirectory of a repo (e.g. `cd scripts/asr-worker && claude`) now attribute to the repo root instead of the subdirectory. Previously the dashboard showed deep subfolders as if they were the project — a session that ran 74 events inside `meetings-lens/scripts/asr-worker` and 7 at the repo root was attributed to `asr-worker`. SessionStart cwd is now walked up to the nearest `.git` like file-path refinement already did.
 

package/cli/hooks.js

@@ -64,81 +64,360 @@ export function saveLensConfig(config) {
  * Escape a string for safe embedding in a single-quoted shell context.
  * Standard POSIX approach: replace each ' with '\'' (end quote, escaped quote, start quote).
  */
-export function shellEscape(str) {
-  if (typeof str !== 'string') return process.platform === 'win32' ? '""' : "''";
-  // Windows cmd.exe: double-quote, escape inner double quotes by doubling them
-  if (process.platform === 'win32') return '"' + str.replace(/"/g, '""') + '"';
+export function shellEscape(str, platform = process.platform) {
+  if (typeof str !== 'string') return platform === 'win32' ? '""' : "''";
+  if (platform === 'win32') return '"' + str.replace(/"/g, '""') + '"';
   return "'" + str.replace(/'/g, "'\\''") + "'";
 }
 
-// Resolve a stable node path that survives version upgrades.
-// process.execPath often points to a versioned path (e.g. /opt/homebrew/Cellar/node/24.10.0/bin/node)
-// that breaks after `brew upgrade node`. We prefer symlinks that point to the current version.
-// We intentionally avoid `|| node` fallback — it was tried and reverted (1dfdd25) because
-// it masks capture failures (re-runs with empty stdin, exits 0).
-function findStableNodePath() {
-  // On Windows, Unix paths (/usr/bin/env, /opt/homebrew/...) don't exist.
-  // Claude Code executes hooks via cmd.exe / CreateProcess, so we need a
-  // native Windows path. process.execPath is the most reliable option.
-  if (process.platform === 'win32') return process.execPath;
+/**
+ * Lighter form of shellEscape: only wrap when the path actually needs it.
+ * Used by rawPath mode where Claude Code's settings.json schema expects
+ * unwrapped paths for the common case, but spaces / tabs still need quoting
+ * to keep /bin/sh, cmd.exe and PowerShell from splitting argv.
+ */
+function quoteIfHasSpaces(path, platform = process.platform) {
+  if (typeof path !== 'string') return shellEscape(path, platform);
+  if (!/[\s'"]/.test(path)) return path;
+  return shellEscape(path, platform);
+}
+
+// ---------------------------------------------------------------------------
+// Stable node-path resolution
+// ---------------------------------------------------------------------------
+
+// Markers that identify a node binary living inside a version-pinned directory
+// (managed by a version manager or Homebrew Cellar). Such paths break after
+// brew upgrade node / nvm install / asdf install / etc.
+const VERSION_PINNED_MARKERS = [
+  '/Cellar/',                  // Homebrew (e.g. /opt/homebrew/Cellar/node/24.10.0/bin/node)
+  '/.nvm/versions/',           // nvm (~/.nvm/versions/node/v22.1.0/bin/node)
+  '/.asdf/installs/',          // asdf (~/.asdf/installs/nodejs/22.1.0/bin/node)
+  '/.fnm/node-versions/',      // fnm (~/.fnm/node-versions/v22.1.0/installation/bin/node)
+  '/.volta/tools/image/',      // volta (~/.volta/tools/image/node/22.1.0/bin/node)
+  '/n/versions/',              // n   (~/n/versions/node/22.1.0/bin/node)
+];
+
+/**
+ * True if path is inside a version-pinned directory (will break on upgrade).
+ * The /node-v\d/ pattern matches segment-style names like /node-v22.1.0/, not stray
+ * substrings like /node-bin/.
+ */
+export function isVersionPinnedNodePath(path) {
+  if (!path || typeof path !== 'string') return false;
+  const p = path.replace(/\\/g, '/');
+  if (/\/node-v\d/.test(p)) return true;
+  for (const marker of VERSION_PINNED_MARKERS) {
+    if (p.includes(marker)) return true;
+  }
+  return false;
+}
+
+/**
+ * Inside `parentDir`, pick the most recent semver-named subdirectory (e.g. "v22.1.0").
+ * Returns the directory name or null if no semver-shaped subdirectory exists.
+ */
+function pickLatestSemverDir(parentDir) {
+  let entries;
+  try {
+    entries = readdirSync(parentDir);
+  } catch {
+    return null;
+  }
+  const parsed = entries
+    .map(name => {
+      const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(name);
+      if (!m) return null;
+      return { name, version: [Number(m[1]), Number(m[2]), Number(m[3])] };
+    })
+    .filter(Boolean);
+  if (parsed.length === 0) return null;
+  parsed.sort((a, b) => {
+    for (let i = 0; i < 3; i++) {
+      if (a.version[i] !== b.version[i]) return b.version[i] - a.version[i];
+    }
+    return 0;
+  });
+  return parsed[0].name;
+}
+
+const DEFAULT_FS = {
+  existsSync,
+  lstatSync,
+};
 
-  // If process.execPath is already a symlink (e.g. /usr/local/bin/node), use it directly
+/**
+ * Resolve a stable node binary path with metadata about whether it will
+ * survive `brew upgrade node` / version-manager updates.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]      — home directory (default: homedir())
+ * @param {string} [opts.execPath]  — node binary that ran us (default: process.execPath)
+ * @param {string} [opts.platform]  — 'darwin' | 'linux' | 'win32' (default: process.platform)
+ * @param {object} [opts.fs]        — { existsSync, lstatSync } overrides for tests
+ * @returns {{ path: string, stable: boolean, source: string } | null}
+ */
+export function findStableNodePath({
+  home = homedir(),
+  execPath = process.execPath,
+  platform = process.platform,
+  fs = DEFAULT_FS,
+} = {}) {
+  if (!execPath) return null;
+
+  // Windows: Unix candidates don't exist. process.execPath is the only meaningful
+  // value; we accept it whether or not it's "stable" because there's no better source.
+  if (platform === 'win32') {
+    return { path: execPath, stable: !isVersionPinnedNodePath(execPath), source: 'execPathStable' };
+  }
+
+  // 1. execPath itself if it's a symlink — it presumably points to current version.
   try {
-    if (lstatSync(process.execPath).isSymbolicLink()) return process.execPath;
-  } catch {}
+    if (fs.lstatSync(execPath).isSymbolicLink()) {
+      return { path: execPath, stable: true, source: 'symlink' };
+    }
+  } catch { /* ignore */ }
+
+  // 2. execPath as a stable absolute (not in a version-pinned dir).
+  if (!isVersionPinnedNodePath(execPath)) {
+    return { path: execPath, stable: true, source: 'execPathStable' };
+  }
 
-  // Try stable symlinks that survive version upgrades
-  const candidates = [
-    '/opt/homebrew/bin/node',    // Homebrew (macOS ARM)
-    '/usr/local/bin/node',       // Homebrew (macOS x86), manual installs
+  // 3. Homebrew symlinks (typically user-managed and current).
+  const homebrewCandidates = [
+    { path: '/opt/homebrew/bin/node', source: 'brew' },     // macOS ARM
+    { path: '/usr/local/bin/node',    source: 'brew' },     // macOS Intel, manual installs
   ];
-  for (const p of candidates) {
-    try {
-      if (existsSync(p)) return p;
-    } catch {}
+  for (const c of homebrewCandidates) {
+    try { if (fs.existsSync(c.path)) return { path: c.path, stable: true, source: c.source }; } catch {}
+  }
+
+  // 4. Version managers (each picks its current/latest version).
+  // Preferred over /usr/bin/node because distro-packaged node is often older than
+  // the version a developer actually uses via nvm/asdf/fnm/volta. Picking distro
+  // node can bake a stale runtime into the launcher and break capture.js.
+  const nvmDir = join(home, '.nvm', 'versions', 'node');
+  const nvmLatest = pickLatestSemverDir(nvmDir);
+  if (nvmLatest) {
+    const p = join(nvmDir, nvmLatest, 'bin', 'node');
+    try { if (fs.existsSync(p)) return { path: p, stable: true, source: 'nvm' }; } catch {}
+  }
+
+  const asdfDir = join(home, '.asdf', 'installs', 'nodejs');
+  const asdfLatest = pickLatestSemverDir(asdfDir);
+  if (asdfLatest) {
+    const p = join(asdfDir, asdfLatest, 'bin', 'node');
+    try { if (fs.existsSync(p)) return { path: p, stable: true, source: 'asdf' }; } catch {}
+  }
+
+  const fnmDefault = join(home, '.fnm', 'aliases', 'default', 'bin', 'node');
+  try { if (fs.existsSync(fnmDefault)) return { path: fnmDefault, stable: true, source: 'fnm' }; } catch {}
+
+  const voltaShim = join(home, '.volta', 'bin', 'node');
+  try { if (fs.existsSync(voltaShim)) return { path: voltaShim, stable: true, source: 'volta' }; } catch {}
+
+  const nCandidates = [join(home, 'n', 'bin', 'node'), '/usr/local/n/bin/node'];
+  for (const p of nCandidates) {
+    try { if (fs.existsSync(p)) return { path: p, stable: true, source: 'n' }; } catch {}
+  }
+
+  // 5. Distro-packaged /usr/bin/node — last system candidate before fallback.
+  try { if (fs.existsSync('/usr/bin/node')) return { path: '/usr/bin/node', stable: true, source: 'sysBin' }; } catch {}
+
+  // 6. Last resort: execPath as-is (version-pinned). Better than env-PATH lookup,
+  // but the caller should warn the user — this hook will break on upgrade.
+  return { path: execPath, stable: false, source: 'execPathFallback' };
+}
+
+// ---------------------------------------------------------------------------
+// Per-machine launcher (run.sh / run.cmd)
+// ---------------------------------------------------------------------------
+
+/**
+ * Filename of the launcher in the client directory.
+ */
+export function launcherFilename(platform = process.platform) {
+  return platform === 'win32' ? 'run.cmd' : 'run.sh';
+}
+
+/**
+ * Write a per-machine launcher script with the resolved node path baked in.
+ *
+ * The launcher acts as a node-resolution shim that supports two invocation modes:
+ *
+ *   1. No arguments — run the sibling capture.js (the default install flow where
+ *      both the launcher and capture.js live in ~/.ai-lens/client/).
+ *   2. Script path as $1 — run that script with the resolved node. This is the
+ *      repo-path mode (e.g. meta-cursor static hooks pointing at
+ *      `internal/analytics/ai-lens/client/capture.js`) where capture.js auto-
+ *      updates via `git pull` and only the node binary needs per-machine baking.
+ *
+ * In both cases the launcher is independent of HOME / USERPROFILE / cwd — for
+ * mode 1 the path is derived from `dirname $0`; for mode 2 it's whatever the
+ * caller passes through (typically a workspace-relative path that resolves
+ * against the cwd Cursor/Claude Code set when firing the hook).
+ *
+ * @param {object} opts
+ * @param {string} opts.clientDir — directory where the launcher (and capture.js) live
+ * @param {string} opts.nodePath  — absolute path to the node binary to bake in
+ * @param {string} [opts.platform]
+ */
+export function writeLauncher({ clientDir = CLIENT_INSTALL_DIR, nodePath, platform = process.platform } = {}) {
+  if (!nodePath) throw new Error('writeLauncher: nodePath is required');
+  if (!clientDir) throw new Error('writeLauncher: clientDir is required');
+
+  if (platform === 'win32') {
+    const escaped = nodePath.replace(/"/g, '""');
+    const content =
+      '@echo off\r\n'
+      + 'if "%~1"=="" goto default\r\n'
+      + `"${escaped}" %*\r\n`
+      + 'goto :eof\r\n'
+      + ':default\r\n'
+      + `"${escaped}" "%~dp0capture.js"\r\n`;
+    const target = join(clientDir, 'run.cmd');
+    writeFileSync(target, content);
+    return target;
   }
 
-  // Fallback: rely on PATH at hook execution time
-  return '/usr/bin/env node';
+  const escaped = shellEscape(nodePath, 'linux'); // POSIX single-quote escape
+  const content =
+    '#!/bin/sh\n'
+    + `# AI Lens per-machine launcher. Two modes:\n`
+    + `#   $0           → exec node on sibling capture.js (default install)\n`
+    + `#   $0 <script>  → exec node on <script> with remaining args (repo-path mode)\n`
+    + 'if [ $# -gt 0 ]; then\n'
+    + `  exec ${escaped} "$@"\n`
+    + 'fi\n'
+    + 'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\n'
+    + `exec ${escaped} "$DIR/capture.js"\n`;
+  const target = join(clientDir, 'run.sh');
+  writeFileSync(target, content);
+  try { chmodSync(target, 0o755); } catch { /* best effort */ }
+  return target;
+}
+
+// ---------------------------------------------------------------------------
+// Hook command construction
+// ---------------------------------------------------------------------------
+
+// Lazy default ctx for callers that don't pass one (legacy tests, TOOL_CONFIGS at
+// import-time). Resolver isn't called at module load — only when captureCommand runs.
+function resolveDefaultCtx() {
+  const nodeResolution = findStableNodePath();
+  return {
+    nodeResolution,
+    platform: process.platform,
+    clientDir: CLIENT_INSTALL_DIR,
+  };
 }
 
 /**
- * @param {boolean} [useTilde] - If true, use ~/.ai-lens/client/capture.js (for project-level hooks so path is portable).
- * @param {boolean} [rawPath] - If true, do not quote the path (for Claude Code config; path written without quotes).
- * @param {string} [customPath] - If set, use this path (e.g. REPO_CAPTURE_PATH for --use-repo-path); rawPath implied.
+ * Build the hook command string. By default the command is the per-machine
+ * launcher (run.sh / run.cmd) at clientDir; in `--use-repo-path` mode
+ * (customPath given) it falls back to the legacy `<node> <capture.js>` form
+ * because the launcher only lives in the installed client dir.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.useTilde]   — write ~/.ai-lens/client/... (portable path for project-hooks)
+ * @param {boolean} [opts.rawPath]    — don't quote the target (Claude Code config wants raw)
+ * @param {string}  [opts.customPath] — absolute repo-mode path to capture.js (--use-repo-path)
+ * @param {object}  [opts.ctx]        — { nodeResolution, platform, clientDir }; lazy-resolved if omitted
  */
-export function captureCommand(useTilde = false, rawPath = false, customPath = null) {
-  const nodePath = findStableNodePath();
-  const capturePath = customPath != null
-    ? customPath.replace(/\\/g, '/')
-    : useTilde
-      ? '~/.ai-lens/client/capture.js'
-      : CAPTURE_PATH.replace(/\\/g, '/');
-  const pathPart = (customPath != null || rawPath) ? capturePath : shellEscape(capturePath);
-  if (nodePath === '/usr/bin/env node') return `/usr/bin/env node ${pathPart}`;
-  // Claude Code on Windows executes hooks via cmd.exe. A quoted executable path
-  // at the start of the line (e.g. "C:/Program Files/node.exe" args) is not
-  // recognised as a command by cmd.exe. Use bare `node` for Claude Code hooks
-  // (rawPath=true) when the path contains spaces; Cursor hooks use PowerShell
-  // where quoting works fine.
-  if (process.platform === 'win32' && rawPath && nodePath.includes(' ')) {
-    return `node ${pathPart}`;
-  }
-  return `${shellEscape(nodePath.replace(/\\/g, '/'))} ${pathPart}`;
-}
-
-// Cursor on Windows executes hooks via PowerShell, which treats a quoted path like
-// "node.exe" as a string expression, not a command invocation. The & (call) operator
-// is required. Claude Code uses bash or cmd.exe where & is not needed (and breaks bash).
+export function captureCommand(opts = {}) {
+  // Backward-compat: old positional signature captureCommand(useTilde, rawPath, customPath)
+  if (typeof opts === 'boolean') {
+    opts = { useTilde: opts, rawPath: arguments[1], customPath: arguments[2] ?? null };
+  }
+  const { useTilde = false, rawPath = false, customPath = null, shell = null } = opts;
+  const ctx = opts.ctx ?? resolveDefaultCtx();
+  // Tolerate partial ctx (e.g. only nodeResolution supplied) by filling in module
+  // defaults — keeps callers from having to repeat platform/clientDir everywhere.
+  const platform = ctx.platform ?? process.platform;
+  const clientDir = ctx.clientDir ?? CLIENT_INSTALL_DIR;
+  const nodeResolution = ctx.nodeResolution;
+  const isWin = platform === 'win32';
+  // shell hint distinguishes cmd.exe (Claude Code) from PowerShell (Cursor) on
+  // Windows — the two need different escaping for paths with spaces.
+  const isPS = shell === 'powershell';
+
+  // --use-repo-path: legacy <node> <capture.js> form.
+  if (customPath != null) {
+    if (!nodeResolution || !nodeResolution.path) {
+      throw new Error('captureCommand: nodeResolution is required for --use-repo-path');
+    }
+    const capturePath = customPath.replace(/\\/g, '/');
+    // Even in rawPath mode (Claude Code "do not unconditionally wrap"), the script
+    // path MUST be quoted when it contains spaces — otherwise /bin/sh, cmd.exe and
+    // PowerShell all split it into separate argv tokens (e.g. `/Users/foo bar/...`).
+    // Use shell-appropriate quoting: double-quote on Windows (works for both
+    // cmd.exe and PowerShell), POSIX single-quote elsewhere.
+    const pathPart = rawPath
+      ? quoteIfHasSpaces(capturePath, platform)
+      : shellEscape(capturePath, platform);
+    const nodeNorm = nodeResolution.path.replace(/\\/g, '/');
+    if (isWin && rawPath && nodeNorm.includes(' ')) {
+      const quotedNode = `"${nodeNorm.replace(/"/g, '""')}"`;
+      // PowerShell (Cursor) handles a quoted first token natively — caller will
+      // prepend `& `, giving `& "<node>" <path>`.
+      if (isPS) return `${quotedNode} ${pathPart}`;
+      // cmd.exe (Claude Code) doesn't always treat a quoted first token as a
+      // command — `call` is the canonical workaround. Avoids the previous bare-
+      // `node` fallback that depended on PATH (C:\Program Files\nodejs\node.exe
+      // wouldn't be reachable from launchd-like environments).
+      return `call ${quotedNode} ${pathPart}`;
+    }
+    return `${shellEscape(nodeNorm, platform)} ${pathPart}`;
+  }
+
+  // Launcher form. Path inside the command — tilde for project-hooks portability on POSIX;
+  // absolute on Windows (PowerShell/cmd don't expand ~).
+  const filename = launcherFilename(platform);
+  let launcherPath;
+  if (useTilde && !isWin) {
+    launcherPath = `~/.ai-lens/client/${filename}`;
+  } else {
+    launcherPath = join(clientDir, filename).replace(/\\/g, '/');
+  }
+
+  // POSIX: quote the launcher path unless it's the unquoted tilde form (which must
+  // remain unquoted for shell tilde expansion). rawPath (Claude Code) leaves the
+  // tilde form bare too — Claude Code passes commands to /bin/sh which expands ~.
+  if (!isWin) {
+    if (useTilde) return launcherPath; // unquoted ~/path
+    return shellEscape(launcherPath, 'linux');
+  }
+
+  // Windows: cmd.exe (Claude Code, rawPath=true) needs `call "..."` when the
+  // launcher path contains spaces; otherwise plain quoted path works.
+  // PowerShell (Cursor) handles `"..."` via the & prefix (added by cursorCaptureCommand).
+  const quoted = `"${launcherPath.replace(/"/g, '""')}"`;
+  if (rawPath && launcherPath.includes(' ') && !isPS) {
+    return `call ${quoted}`;
+  }
+  return quoted;
+}
+
 /**
- * @param {boolean} [useTilde] - If true, use ~/.ai-lens/client/capture.js (for --project-hooks).
- * @param {string} [customPath] - If set, use this path (e.g. REPO_CAPTURE_PATH for --use-repo-path).
+ * Cursor wrapper: PowerShell needs `& "..."` (call operator) to invoke a quoted path.
  */
-export function cursorCaptureCommand(useTilde = false, customPath = null) {
-  // On Windows, PowerShell does not expand ~ inside quoted strings — use absolute path.
-  const effectiveUseTilde = process.platform === 'win32' ? false : useTilde;
-  const cmd = customPath != null ? captureCommand(false, true, customPath) : captureCommand(effectiveUseTilde);
-  return process.platform === 'win32' ? `& ${cmd}` : cmd;
+export function cursorCaptureCommand(opts = {}) {
+  if (typeof opts === 'boolean') {
+    opts = { useTilde: opts, customPath: arguments[1] ?? null };
+  }
+  const { useTilde = false, customPath = null } = opts;
+  const ctx = opts.ctx ?? resolveDefaultCtx();
+  const platform = ctx.platform ?? process.platform;
+  // PowerShell doesn't expand ~ inside double-quoted strings — fall back to absolute.
+  const effectiveUseTilde = platform === 'win32' ? false : useTilde;
+  // Cursor on Windows runs hooks via PowerShell, so use the PS-compatible shell
+  // hint when building the underlying command (avoids the cmd.exe `call` prefix
+  // which PowerShell doesn't understand).
+  const shell = platform === 'win32' ? 'powershell' : null;
+  const cmd = customPath != null
+    ? captureCommand({ useTilde: false, rawPath: true, customPath, ctx, shell })
+    : captureCommand({ useTilde: effectiveUseTilde, ctx, shell });
+  return platform === 'win32' ? `& ${cmd}` : cmd;
 }
 
 // ---------------------------------------------------------------------------
@@ -157,20 +436,47 @@ export function listClientFiles(sourceDir = join(__dirname, '..', 'client')) {
 }
 
 /**
- * Copy client/ files from the package source to ~/.ai-lens/client/.
- * Works from npx cache, global install, and local dev.
+ * Copy client/*.js to ~/.ai-lens/client/ and (optionally) write the launcher.
+ *
+ * Default behaviour matches a real install: writes the launcher so the hook
+ * command target (`run.sh` / `run.cmd`) is always present. Tests that don't
+ * want the launcher in their tmpdir can pass `writeLauncher: false`. If the
+ * caller passes `writeLauncher: true` without a `nodeResolution`, we resolve
+ * one lazily — same heuristic init.js uses — so a tests-style call like
+ * `installClientFiles()` (no args) restores a working install.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.sourceDir]
+ * @param {string} [opts.clientDir]
+ * @param {{ path: string, stable: boolean }} [opts.nodeResolution] — auto-resolved if absent when writeLauncher=true
+ * @param {string}  [opts.platform]
+ * @param {boolean} [opts.writeLauncher] — default true; pass false to skip launcher
  */
-export function installClientFiles() {
-  const sourceDir = join(__dirname, '..', 'client');
-  mkdirSync(CLIENT_INSTALL_DIR, { recursive: true });
+export function installClientFiles(opts = {}) {
+  const {
+    sourceDir = join(__dirname, '..', 'client'),
+    clientDir = CLIENT_INSTALL_DIR,
+    platform = process.platform,
+    writeLauncher: shouldWriteLauncher = true,
+  } = opts;
+  let { nodeResolution = null } = opts;
+
+  if (shouldWriteLauncher && (!nodeResolution || !nodeResolution.path)) {
+    nodeResolution = findStableNodePath();
+    if (!nodeResolution || !nodeResolution.path) {
+      throw new Error('installClientFiles: writeLauncher=true but no node binary could be resolved');
+    }
+  }
+
+  mkdirSync(clientDir, { recursive: true });
 
   for (const file of listClientFiles(sourceDir)) {
-    copyFileSync(join(sourceDir, file), join(CLIENT_INSTALL_DIR, file));
+    copyFileSync(join(sourceDir, file), join(clientDir, file));
   }
 
   // ESM needs package.json with "type": "module"
   writeFileSync(
-    join(CLIENT_INSTALL_DIR, 'package.json'),
+    join(clientDir, 'package.json'),
     '{"type":"module"}\n',
   );
 
@@ -178,9 +484,13 @@ export function installClientFiles() {
   // packageRoot lets sender.js find bin/ai-lens.js for background status reports.
   const { version, commit } = getVersionInfo();
   writeFileSync(
-    join(CLIENT_INSTALL_DIR, 'version.json'),
+    join(clientDir, 'version.json'),
     JSON.stringify({ version, commit, packageRoot: PKG_ROOT }) + '\n',
   );
+
+  if (shouldWriteLauncher) {
+    writeLauncher({ clientDir, nodePath: nodeResolution.path, platform });
+  }
 }
 
 /**
@@ -196,126 +506,143 @@ export function removeClientFiles() {
 // Hook definitions per tool
 // ---------------------------------------------------------------------------
 
-// Use tilde path (~/.ai-lens/...) so settings are portable (no absolute paths).
-const CLAUDE_CODE_HOOKS = {
-  SessionStart: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  SessionEnd: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  UserPromptSubmit: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  PreToolUse: () => ({ matcher: 'EnterPlanMode|ExitPlanMode', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  PostToolUse: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  PostToolUseFailure: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  Stop: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  PreCompact: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  SubagentStart: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
-  SubagentStop: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand(true, true) }] }),
+// Claude Code hook event names — used by both global (absolute path) and project (tilde) modes.
+const CLAUDE_HOOK_SPEC = {
+  SessionStart:       { matcher: '' },
+  SessionEnd:         { matcher: '' },
+  UserPromptSubmit:   { matcher: '' },
+  PreToolUse:         { matcher: 'EnterPlanMode|ExitPlanMode' },
+  PostToolUse:        { matcher: '' },
+  PostToolUseFailure: { matcher: '' },
+  Stop:               { matcher: '' },
+  PreCompact:         { matcher: '' },
+  SubagentStart:      { matcher: '' },
+  SubagentStop:       { matcher: '' },
 };
 
-// Use absolute path — Cursor does not expand ~ in hook commands (it passes the
-// literal string to Node, which resolves it relative to CWD).
-const CURSOR_HOOKS = {
-  sessionStart: () => ({ command: cursorCaptureCommand(false) }),
-  beforeSubmitPrompt: () => ({ command: cursorCaptureCommand(false) }),
-  postToolUse: () => ({ command: cursorCaptureCommand(false) }),
-  postToolUseFailure: () => ({ command: cursorCaptureCommand(false) }),
-  afterFileEdit: () => ({ command: cursorCaptureCommand(false) }),
-  afterShellExecution: () => ({ command: cursorCaptureCommand(false) }),
-  afterMCPExecution: () => ({ command: cursorCaptureCommand(false) }),
-  subagentStart: () => ({ command: cursorCaptureCommand(false) }),
-  subagentStop: () => ({ command: cursorCaptureCommand(false) }),
-  preCompact: () => ({ command: cursorCaptureCommand(false) }),
-  afterAgentResponse: () => ({ command: cursorCaptureCommand(false) }),
-  afterAgentThought: () => ({ command: cursorCaptureCommand(false) }),
-  stop: () => ({ command: cursorCaptureCommand(false) }),
-  sessionEnd: () => ({ command: cursorCaptureCommand(false) }),
-};
+const CURSOR_HOOK_NAMES = [
+  'sessionStart', 'beforeSubmitPrompt', 'postToolUse', 'postToolUseFailure',
+  'afterFileEdit', 'afterShellExecution', 'afterMCPExecution',
+  'subagentStart', 'subagentStop', 'preCompact',
+  'afterAgentResponse', 'afterAgentThought', 'stop', 'sessionEnd',
+];
 
-// Same as CURSOR_HOOKS but command uses ~/.ai-lens/... (for --project-hooks)
-const CURSOR_HOOKS_TILDE = Object.fromEntries(
-  Object.keys(CURSOR_HOOKS).map(k => [k, () => ({ command: cursorCaptureCommand(true) })]),
-);
-
-// Same as CLAUDE_CODE_HOOKS but command uses ~/.ai-lens/... (for --project-hooks), path without quotes
-const CLAUDE_CODE_HOOKS_TILDE = {};
-for (const [k, fn] of Object.entries(CLAUDE_CODE_HOOKS)) {
-  CLAUDE_CODE_HOOKS_TILDE[k] = () => {
-    const r = fn();
-    r.hooks[0].command = captureCommand(true, true);
-    return r;
+// Wrap captureCommand in a memoised getter so makeXxxHookDefs(null) does NOT
+// trigger node-path resolution at builder time — the first .hookDefs[name]()
+// call does it instead, and subsequent calls reuse the cached string.
+function memoizeCmd(produce) {
+  let cached;
+  let resolved = false;
+  return () => {
+    if (!resolved) { cached = produce(); resolved = true; }
+    return cached;
   };
 }
 
+/**
+ * Build Claude Code hookDefs bound to a ctx. Claude Code's settings.json is the
+ * user's shared config, so we always emit a tilde path for portability —
+ * `mode` is accepted for symmetry with the Cursor builder but does not change
+ * the path style.
+ *
+ * The captureCommand call is deferred until the first hookDef thunk runs, so
+ * importing this module (or building TOOL_CONFIGS with ctx=null) never
+ * probes node candidates by itself.
+ */
+export function makeClaudeHookDefs(ctx = null, _mode = 'global') {
+  const getCmd = memoizeCmd(() => captureCommand({ useTilde: true, rawPath: true, ctx }));
+  const defs = {};
+  for (const [name, spec] of Object.entries(CLAUDE_HOOK_SPEC)) {
+    defs[name] = () => ({ matcher: spec.matcher, hooks: [{ type: 'command', command: getCmd() }] });
+  }
+  return defs;
+}
+
+/**
+ * Build Cursor hookDefs bound to a ctx. mode: 'global' (default) | 'project'.
+ * Cursor does not expand ~ in hook commands, so global hooks bake the absolute
+ * client-dir path. Project-hooks use ~/.ai-lens/... for portability across
+ * teammates who clone the repo.
+ *
+ * captureCommand is deferred (see makeClaudeHookDefs).
+ */
+export function makeCursorHookDefs(ctx = null, mode = 'global') {
+  const useTilde = mode === 'project';
+  const getCmd = memoizeCmd(() => cursorCaptureCommand({ useTilde, ctx }));
+  const defs = {};
+  for (const name of CURSOR_HOOK_NAMES) {
+    defs[name] = () => ({ command: getCmd() });
+  }
+  return defs;
+}
+
 /**
  * Claude Code hook defs that point to a custom path (e.g. REPO_CAPTURE_PATH for --use-repo-path).
  * @param {string} capturePath - Absolute path to client/capture.js.
+ * @param {object} [ctx]
  */
-export function getClaudeCodeHookDefsWithPath(capturePath) {
-  const cmd = captureCommand(false, true, capturePath);
-  return {
-    SessionStart: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    SessionEnd: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    UserPromptSubmit: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    PreToolUse: () => ({ matcher: 'EnterPlanMode|ExitPlanMode', hooks: [{ type: 'command', command: cmd }] }),
-    PostToolUse: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    PostToolUseFailure: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    Stop: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    PreCompact: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    SubagentStart: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-    SubagentStop: () => ({ matcher: '', hooks: [{ type: 'command', command: cmd }] }),
-  };
+export function getClaudeCodeHookDefsWithPath(capturePath, ctx = null) {
+  const getCmd = memoizeCmd(() => captureCommand({ rawPath: true, customPath: capturePath, ctx }));
+  const defs = {};
+  for (const [name, spec] of Object.entries(CLAUDE_HOOK_SPEC)) {
+    defs[name] = () => ({ matcher: spec.matcher, hooks: [{ type: 'command', command: getCmd() }] });
+  }
+  return defs;
 }
 
 /**
  * Cursor hook defs that point to a custom path (e.g. REPO_CAPTURE_PATH for --use-repo-path).
  * @param {string} capturePath - Absolute path to client/capture.js.
+ * @param {object} [ctx]
  */
-export function getCursorHookDefsWithPath(capturePath) {
-  const command = cursorCaptureCommand(false, capturePath);
-  return {
-    sessionStart: () => ({ command }),
-    beforeSubmitPrompt: () => ({ command }),
-    postToolUse: () => ({ command }),
-    postToolUseFailure: () => ({ command }),
-    afterFileEdit: () => ({ command }),
-    afterShellExecution: () => ({ command }),
-    afterMCPExecution: () => ({ command }),
-    subagentStart: () => ({ command }),
-    subagentStop: () => ({ command }),
-    preCompact: () => ({ command }),
-    afterAgentResponse: () => ({ command }),
-    afterAgentThought: () => ({ command }),
-    stop: () => ({ command }),
-    sessionEnd: () => ({ command }),
-  };
+export function getCursorHookDefsWithPath(capturePath, ctx = null) {
+  const getCmd = memoizeCmd(() => cursorCaptureCommand({ customPath: capturePath, ctx }));
+  const defs = {};
+  for (const name of CURSOR_HOOK_NAMES) {
+    defs[name] = () => ({ command: getCmd() });
+  }
+  return defs;
 }
 
-export const TOOL_CONFIGS = [
-  {
-    name: 'Claude Code',
-    dirPath: join(homedir(), '.claude'),
-    configPath: join(homedir(), '.claude', 'settings.json'),
-    hookDefs: CLAUDE_CODE_HOOKS,
-    topLevelFields: {},
-    sharedConfig: true,
-    // Older init versions wrote hooks here — clean up on init/remove
-    legacyConfigPaths: [join(homedir(), '.claude', 'hooks.json')],
-  },
-  {
-    name: 'Cursor',
-    dirPath: join(homedir(), '.cursor'),
-    configPath: join(homedir(), '.cursor', 'hooks.json'),
-    hookDefs: CURSOR_HOOKS,
-    topLevelFields: { version: 1 },
-  },
-];
+/**
+ * Build the array of TOOL_CONFIGS (Claude Code + Cursor at user-global paths).
+ * Pass ctx for production use; omit for the legacy TOOL_CONFIGS export
+ * (hookDefs lazy-resolve node path at first call).
+ */
+export function makeToolConfigs(ctx = null) {
+  return [
+    {
+      name: 'Claude Code',
+      dirPath: join(homedir(), '.claude'),
+      configPath: join(homedir(), '.claude', 'settings.json'),
+      hookDefs: makeClaudeHookDefs(ctx, 'global'),
+      topLevelFields: {},
+      sharedConfig: true,
+      // Older init versions wrote hooks here — clean up on init/remove
+      legacyConfigPaths: [join(homedir(), '.claude', 'hooks.json')],
+    },
+    {
+      name: 'Cursor',
+      dirPath: join(homedir(), '.cursor'),
+      configPath: join(homedir(), '.cursor', 'hooks.json'),
+      hookDefs: makeCursorHookDefs(ctx, 'global'),
+      topLevelFields: { version: 1 },
+    },
+  ];
+}
+
+// Backward-compat: lazy-bound TOOL_CONFIGS so import doesn't trigger node resolution.
+export const TOOL_CONFIGS = makeToolConfigs();
 
 /**
  * Cursor tool config with hooks in project's .cursor/ instead of ~/.cursor/.
  * Use for init (--project-hooks) and remove (when project has .cursor/hooks.json).
  * @param {string} projectRoot - Absolute path to project root (e.g. process.cwd()).
  * @param {string} [label] - Display name (default: 'Cursor (project)').
+ * @param {object} [ctx]
  * @returns {{ name: string, dirPath: string, configPath: string, hookDefs: object, topLevelFields: object }}
  */
-export function getCursorToolConfig(projectRoot, label = 'Cursor (project)') {
+export function getCursorToolConfig(projectRoot, label = 'Cursor (project)', ctx = null) {
   const base = TOOL_CONFIGS.find(t => t.name === 'Cursor');
   if (!base) return null;
   return {
@@ -323,7 +650,7 @@ export function getCursorToolConfig(projectRoot, label = 'Cursor (project)') {
     name: label,
     dirPath: join(projectRoot, '.cursor'),
     configPath: join(projectRoot, '.cursor', 'hooks.json'),
-    hookDefs: CURSOR_HOOKS_TILDE,
+    hookDefs: makeCursorHookDefs(ctx, 'project'),
   };
 }
 
@@ -332,9 +659,10 @@ export function getCursorToolConfig(projectRoot, label = 'Cursor (project)') {
  * Use for init (--project-hooks) and remove (when project has .claude/settings.json with AI Lens).
  * @param {string} projectRoot - Absolute path to project root (e.g. process.cwd()).
  * @param {string} [label] - Display name (default: 'Claude Code (project)').
+ * @param {object} [ctx]
  * @returns {{ name: string, dirPath: string, configPath: string, hookDefs: object, topLevelFields: object, sharedConfig: boolean, legacyConfigPaths: array }}
  */
-export function getClaudeCodeToolConfig(projectRoot, label = 'Claude Code (project)') {
+export function getClaudeCodeToolConfig(projectRoot, label = 'Claude Code (project)', ctx = null) {
   const base = TOOL_CONFIGS.find(t => t.name === 'Claude Code');
   if (!base) return null;
   return {
@@ -342,7 +670,7 @@ export function getClaudeCodeToolConfig(projectRoot, label = 'Claude Code (proje
     name: label,
     dirPath: join(projectRoot, '.claude'),
     configPath: join(projectRoot, '.claude', 'settings.json'),
-    hookDefs: CLAUDE_CODE_HOOKS_TILDE,
+    hookDefs: makeClaudeHookDefs(ctx, 'project'),
     sharedConfig: false,
     legacyConfigPaths: [],
   };
@@ -352,62 +680,160 @@ export function getClaudeCodeToolConfig(projectRoot, label = 'Claude Code (proje
 // AI Lens hook detection
 // ---------------------------------------------------------------------------
 
-// Both ~/.ai-lens/client/capture.js and repo path (e.g. internal/analytics/ai-lens/client/capture.js) are valid.
-function isAiLensCapturePath(cmd) {
+// Recognises any AI Lens hook target: launcher (run.sh / run.cmd) or capture.js
+// (legacy install, repo-path mode). Returns { isAiLens, kind } where kind is
+// 'launcher' | 'captureJs' for matched commands.
+//
+// We deliberately require an `ai-lens/` segment so we never classify an unrelated
+// user hook like `node client/capture.js` as AI Lens (init/remove would otherwise
+// strip it). init.js is responsible for emitting paths that contain `ai-lens/`
+// in every install mode, including --use-repo-path --project-hooks.
+export function isAiLensCommand(cmd) {
   const n = (cmd || '').replace(/\\/g, '/');
-  return n.includes('.ai-lens/client/capture.js') || n.includes('ai-lens/client/capture.js');
+  if (n.includes('.ai-lens/client/run.sh') || n.includes('.ai-lens/client/run.cmd')) {
+    return { isAiLens: true, kind: 'launcher' };
+  }
+  if (n.includes('.ai-lens/client/capture.js') || n.includes('ai-lens/client/capture.js')) {
+    return { isAiLens: true, kind: 'captureJs' };
+  }
+  return { isAiLens: false, kind: null };
+}
+
+// Deprecated alias for back-compat with any external callers.
+export function isAiLensCapturePath(cmd) {
+  return isAiLensCommand(cmd).isAiLens;
 }
 
 export function isAiLensHook(entry) {
   // Flat format (Cursor): { command: "..." }
-  if (isAiLensCapturePath(entry?.command || '')) return true;
+  if (entry?.command != null && isAiLensCommand(entry.command).isAiLens) return true;
   // Nested format (Claude Code): { matcher, hooks: [{ command: "..." }] }
   if (Array.isArray(entry?.hooks)) {
-    return entry.hooks.some(h => isAiLensCapturePath(h?.command || ''));
+    return entry.hooks.some(h => isAiLensCommand(h?.command || '').isAiLens);
   }
   return false;
 }
 
+/**
+ * Parse a hook command into normalized parts. Only recognises the formats we emit:
+ *   <launcher-path>
+ *   <node-path> <capture.js-path>
+ *   & <launcher-path>          (Cursor / PowerShell)
+ *   call <launcher-path>       (Claude Code / cmd.exe with spaces)
+ *
+ * Returns { kind, path, prefix, nodePrefix } where:
+ *   kind: 'launcher' | 'captureJs' | 'unknown'
+ *   path: normalised target path (trailing capture.js / run.sh / run.cmd token)
+ *   prefix: 'none' | 'cursor-ps' (& ) | 'win-claude' (call )
+ *   nodePrefix: normalised node binary (captureJs only), or null
+ */
+export function _parseHookCommand(cmd) {
+  if (typeof cmd !== 'string' || cmd.length === 0) {
+    return { kind: 'unknown', path: null, prefix: 'none', nodePrefix: null };
+  }
+  let rest = cmd.trim();
+  let prefix = 'none';
+  if (rest.startsWith('& ')) {
+    prefix = 'cursor-ps';
+    rest = rest.slice(2).trim();
+  } else if (rest.toLowerCase().startsWith('call ')) {
+    prefix = 'win-claude';
+    rest = rest.slice(5).trim();
+  }
+
+  const tokens = tokenizeHookCommand(rest);
+  if (tokens.length === 0) {
+    return { kind: 'unknown', path: null, prefix, nodePrefix: null };
+  }
+  const first = normalizePath(tokens[0]);
+
+  if (first.endsWith('/run.sh') || first.endsWith('/run.cmd') || first.endsWith('run.sh') || first.endsWith('run.cmd')) {
+    return { kind: 'launcher', path: first, prefix, nodePrefix: null };
+  }
+
+  if (tokens.length >= 2) {
+    const second = normalizePath(tokens[1]);
+    if (second.endsWith('capture.js')) {
+      return { kind: 'captureJs', path: second, prefix, nodePrefix: first };
+    }
+  }
+
+  return { kind: 'unknown', path: null, prefix, nodePrefix: null };
+}
+
+// Narrow tokenizer: splits on spaces but respects matched single or double quotes.
+// Does NOT handle escapes — not needed for our emitted commands.
+function tokenizeHookCommand(s) {
+  const tokens = [];
+  let buf = '';
+  let quote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        buf += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ' ' || ch === '\t') {
+      if (buf.length > 0) {
+        tokens.push(buf);
+        buf = '';
+      }
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf.length > 0) tokens.push(buf);
+  return tokens;
+}
+
+function normalizePath(p) {
+  return (p || '').replace(/\\/g, '/');
+}
+
 function isCurrentAiLensHook(entry, expected) {
-  // Any valid AI Lens capture path is "current" (tilde or repo path from --use-repo-path).
-  const norm = s => (s || '').replace(/\\/g, '/');
-  // Flat format (Cursor)
+  // Flat format (Cursor): single command per entry.
   if (entry?.command != null) {
-    if (isAiLensCapturePath(entry.command)) {
-      const expectedCmd = expected?.command || '';
-      // On Windows, Cursor hooks require & prefix for PowerShell invocation.
-      // If expected has & but entry doesn't, treat as outdated so init updates it.
-      if (expectedCmd.startsWith('& ') && !entry.command.startsWith('& ')) return false;
-      // On Windows, tilde is not expanded in double-quoted strings by PowerShell.
-      // If entry uses ~/ but expected uses an absolute path, treat as outdated.
-      const entryHasTilde = entry.command.includes('~/.ai-lens/');
-      const expectedHasTilde = expectedCmd.includes('~/.ai-lens/');
-      if (entryHasTilde && !expectedHasTilde) return false;
-      return true;
-    }
-    if (norm(entry.command) === norm(expected?.command || expected?.hooks?.[0]?.command || '')) return true;
-    return false;
+    const expectedCmd = expected?.command || expected?.hooks?.[0]?.command || '';
+    return commandsMatch(entry.command, expectedCmd);
   }
-  // Nested format (Claude Code): valid path + matcher must match when expected has matcher
+  // Nested format (Claude Code): { matcher, hooks: [{ command }] }
   if (Array.isArray(entry?.hooks)) {
-    const hasValidPath = entry.hooks.some(h => isAiLensCapturePath(h?.command));
-    if (!hasValidPath && !entry.hooks.some(h => norm(h?.command) === norm(expected?.hooks?.[0]?.command || ''))) return false;
-    if (!hasValidPath) {
-      if (expected?.matcher !== undefined && entry.matcher !== expected.matcher) return false;
-      return true;
-    }
+    const expectedCmd = expected?.hooks?.[0]?.command || '';
     if (expected?.matcher !== undefined && entry.matcher !== expected.matcher) return false;
-    return true;
+    return entry.hooks.some(h => commandsMatch(h?.command || '', expectedCmd));
   }
   return false;
 }
 
+function commandsMatch(entryCmd, expectedCmd) {
+  const e = _parseHookCommand(entryCmd);
+  const x = _parseHookCommand(expectedCmd);
+  if (x.kind === 'unknown') {
+    // Best-effort fallback: literal compare after slash-normalisation.
+    return normalizePath(entryCmd) === normalizePath(expectedCmd);
+  }
+  if (e.kind !== x.kind) return false;
+  if (e.prefix !== x.prefix) return false;
+  if (e.path !== x.path) return false;
+  if (x.kind === 'captureJs' && e.nodePrefix !== x.nodePrefix) return false;
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Tool detection
 // ---------------------------------------------------------------------------
 
-export function detectInstalledTools() {
-  return TOOL_CONFIGS.filter(t => existsSync(t.dirPath));
+export function detectInstalledTools(ctx = null) {
+  const tools = ctx ? makeToolConfigs(ctx) : TOOL_CONFIGS;
+  return tools.filter(t => existsSync(t.dirPath));
 }
 
 // ---------------------------------------------------------------------------

package/cli/init.js

@@ -20,7 +20,9 @@ import {
   getClaudeCodeHookDefsWithPath, getCursorHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
   checkHooksDisabled, enableHooks,
+  findStableNodePath, isVersionPinnedNodePath, writeLauncher,
 } from './hooks.js';
+import { mkdirSync } from 'node:fs';
 import { scanNestedClaudeProjects, summarizeNestedProjects } from './scan.js';
 
 function ask(question) {
@@ -173,10 +175,10 @@ function getTrackedRoots(projects, fallbackRoot) {
   return projects.split(',').map(path => path.trim()).filter(Boolean);
 }
 
-function makeNestedClaudeTool(projectDir, capturePathInHooks) {
-  const tool = getClaudeCodeToolConfig(projectDir, `Claude Code (${projectDir})`);
+function makeNestedClaudeTool(projectDir, capturePathInHooks, ctx = null) {
+  const tool = getClaudeCodeToolConfig(projectDir, `Claude Code (${projectDir})`, ctx);
   if (capturePathInHooks) {
-    tool.hookDefs = getClaudeCodeHookDefsWithPath(capturePathInHooks);
+    tool.hookDefs = getClaudeCodeHookDefsWithPath(capturePathInHooks, ctx);
   }
   return tool;
 }
@@ -350,6 +352,9 @@ function getInitArgs() {
       case '--use-repo-path':
         flags.useRepoPath = true;
         break;
+      case '--install-launcher':
+        flags.installLauncher = true;
+        break;
       case '--mcp-scope':
         if (i + 1 < args.length) flags.mcpScope = args[++i];
         else process.stderr.write('Warning: --mcp-scope requires a value\n');
@@ -358,7 +363,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', 'mcp-scope'].includes(a)) {
+        } else if (['server', 'projects', 'yes', 'no-mcp', '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`);
         }
       }
@@ -379,15 +384,53 @@ export default async function init() {
   heading(`AI Lens — Init  v${version} (${commit})`);
   detail(`capture.js: ${CAPTURE_PATH}`);
 
-  // Detect installed tools
+  // 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
+  // without a discoverable node can still set up MCP / config.
+  //
+  // --project-hooks ALWAYS writes hooks regardless of whether ~/.cursor or
+  // ~/.claude exist globally — so willWriteHooks must consider it.
+  //
+  // --install-launcher (added 0.8.69) forces launcher installation even when
+  // --no-hooks. Used by bootstrap workflows like meta-cursor where static hook
+  // templates point at ~/.ai-lens/client/run.sh but init must NOT overwrite
+  // those templates with the dynamic hook form.
+  const globalTools = detectInstalledTools();
+  const willWriteHooks = !flags.noHooks && (globalTools.length > 0 || !!flags.projectHooks);
+  const willInstallLauncher = willWriteHooks || !!flags.installLauncher;
+  let nodeResolution = null;
+  let ctx = null;
+  if (willInstallLauncher) {
+    nodeResolution = findStableNodePath();
+    if (!nodeResolution) {
+      error('Could not find any node binary on this system.');
+      info('  Install node via nvm/asdf/fnm/volta or `brew install node`, then re-run init.');
+      process.exit(1);
+    }
+    if (!nodeResolution.stable) {
+      warn(`Resolved node at ${nodeResolution.path}, but this path is version-pinned and will break on upgrade.`);
+      info('  Install node via a managed tool (nvm/asdf/fnm/volta) or create a stable symlink:');
+      info('    sudo ln -s "$(which node)" /usr/local/bin/node');
+      info('  Then re-run init. (Continuing with the version-pinned path for now.)');
+    } else {
+      detail(`  Resolved node: ${nodeResolution.path} (${nodeResolution.source})`);
+    }
+    if (willWriteHooks) {
+      ctx = { nodeResolution, platform: process.platform, clientDir: join(homedir(), '.ai-lens', 'client') };
+    }
+  }
+
+  // Detect installed tools — re-detect with ctx now that it's available.
   heading('Detecting installed AI tools...');
-  let tools = detectInstalledTools();
+  let tools = detectInstalledTools(ctx);
 
-  // When --project-hooks: put Cursor and Claude Code hooks in project's .cursor/ and .claude/ instead of ~/
+  // When --project-hooks: put Cursor and Claude Code hooks in project's .cursor/ and .claude/ instead of ~/.
+  // Project tools are added unconditionally, so this path is exercised even when no global tools exist.
   if (flags.projectHooks) {
     const projectRoot = resolve(process.cwd());
-    const cursorProject = getCursorToolConfig(projectRoot);
-    const claudeProject = getClaudeCodeToolConfig(projectRoot);
+    const cursorProject = getCursorToolConfig(projectRoot, undefined, ctx);
+    const claudeProject = getClaudeCodeToolConfig(projectRoot, undefined, ctx);
     if (cursorProject) {
       tools = tools.filter(t => t.name !== 'Cursor');
       tools.push(cursorProject);
@@ -412,7 +455,19 @@ export default async function init() {
     if (flags.projectHooks) {
       const projectRoot = resolve(process.cwd());
       pathInHooks = relative(projectRoot, repoPathAbs).replace(/\\/g, '/');
-      info('  Project hooks will use relative path to capture.js (from project root).');
+      // From inside the ai-lens package itself, `relative()` produces a bare
+      // `client/capture.js` that doesn't contain `ai-lens/` — isAiLensCommand
+      // wouldn't recognise it, and using a generic match would risk classifying
+      // unrelated user hooks as AI Lens. Fall back to the tilde/absolute form
+      // so the emitted path always carries the `ai-lens/` identifier.
+      if (!/(?:^|\/)ai-lens\//.test(pathInHooks)) {
+        pathInHooks = repoPathAbs.startsWith(home)
+          ? ('~' + repoPathAbs.slice(home.length)).replace(/\\/g, '/')
+          : repoPathAbs.replace(/\\/g, '/');
+        info('  Project root is inside ai-lens itself — using portable path with ai-lens/ segment for hook recognition.');
+      } else {
+        info('  Project hooks will use relative path to capture.js (from project root).');
+      }
     } else {
       pathInHooks = repoPathAbs.startsWith(home)
         ? ('~' + repoPathAbs.slice(home.length)).replace(/\\/g, '/')
@@ -420,8 +475,8 @@ export default async function init() {
       info('  Hooks will point to capture.js in this package (portable path).');
     }
     for (const tool of tools) {
-      if (tool.name.startsWith('Claude Code')) tool.hookDefs = getClaudeCodeHookDefsWithPath(pathInHooks);
-      else if (tool.name.startsWith('Cursor')) tool.hookDefs = getCursorHookDefsWithPath(pathInHooks);
+      if (tool.name.startsWith('Claude Code')) tool.hookDefs = getClaudeCodeHookDefsWithPath(pathInHooks, ctx);
+      else if (tool.name.startsWith('Cursor')) tool.hookDefs = getCursorHookDefsWithPath(pathInHooks, ctx);
     }
   } else if (flags.projectHooks) {
     info('  Project hooks use path ~/.ai-lens/client/capture.js.');
@@ -502,16 +557,39 @@ export default async function init() {
   // Build new config in memory — saved after "Proceed?" confirmation
   const newConfig = { ...currentConfig, serverUrl, projects };
 
-  // Install client files to ~/.ai-lens/client/ (skip when --use-repo-path)
+  // Install client files to ~/.ai-lens/client/ (skip when --use-repo-path because
+  // capture.js comes from the monorepo / package source in that mode).
   if (!flags.useRepoPath) {
     heading('Installing client files...');
     try {
-      installClientFiles();
+      installClientFiles({
+        nodeResolution,
+        platform: process.platform,
+        writeLauncher: willWriteHooks,
+      });
       success('  Copied client files to ~/.ai-lens/client/');
+      if (willWriteHooks) {
+        detail('  Wrote per-machine launcher (run.sh / run.cmd).');
+      }
     } catch (err) {
       error(`  Failed to install client files: ${err.message}`);
       return;
     }
+  } else if (willInstallLauncher) {
+    // --use-repo-path with --install-launcher: keep capture.js out of the install
+    // dir (it lives in the monorepo, auto-updates via git pull) but still create
+    // the per-machine launcher so static hooks can route through it for proper
+    // node resolution. The meta-cursor bootstrap is the primary consumer.
+    heading('Installing launcher (--install-launcher) ...');
+    try {
+      const clientDir = join(homedir(), '.ai-lens', 'client');
+      mkdirSync(clientDir, { recursive: true });
+      writeLauncher({ clientDir, nodePath: nodeResolution.path, platform: process.platform });
+      success('  Wrote per-machine launcher to ~/.ai-lens/client/');
+    } catch (err) {
+      error(`  Failed to write launcher: ${err.message}`);
+      return;
+    }
   } else {
     detail('  Skipping client install (--use-repo-path: using package copy).');
   }
@@ -638,7 +716,7 @@ export default async function init() {
           const capturePathInHooks = flags.useRepoPath
             ? relative(result.projectDir, resolve(REPO_CAPTURE_PATH)).replace(/\\/g, '/')
             : null;
-          const tool = makeNestedClaudeTool(result.projectDir, capturePathInHooks);
+          const tool = makeNestedClaudeTool(result.projectDir, capturePathInHooks, ctx);
           tool.configPath = join(tool.dirPath, result.installTarget);
           return {
             tool,

package/cli/status.js

@@ -61,6 +61,13 @@ function relativeTime(dateStr) {
 // Individual checks — each returns { ok, summary, detail }
 // ---------------------------------------------------------------------------
 
+// Recognises both the legacy `<node> capture.js` form and the per-machine launcher
+// (run.sh / run.cmd) introduced in 0.8.68.
+function isAiLensCommandString(cmd) {
+  if (!cmd) return false;
+  return cmd.includes('capture.js') || cmd.includes('run.sh') || cmd.includes('run.cmd');
+}
+
 function extractHookCommand(tool) {
   try {
     const raw = readFileSync(tool.configPath, 'utf-8');
@@ -71,11 +78,11 @@ function extractHookCommand(tool) {
       if (!Array.isArray(entries)) continue;
       for (const entry of entries) {
         // Flat format (Cursor): { command: "..." }
-        if (entry?.command?.includes('capture.js')) return entry.command;
+        if (isAiLensCommandString(entry?.command)) return entry.command;
         // Nested format (Claude Code): { hooks: [{ command: "..." }] }
         if (Array.isArray(entry?.hooks)) {
           for (const h of entry.hooks) {
-            if (h?.command?.includes('capture.js')) return h.command;
+            if (isAiLensCommandString(h?.command)) return h.command;
           }
         }
       }
@@ -98,13 +105,19 @@ function expandTilde(pathStr) {
  * Returns { ok, summary, detail } for the status output.
  */
 function detectInstallMode(tools) {
-  const copyDir = join(homedir(), '.ai-lens', 'client') + '/';
+  // Normalise both sides to forward slashes before comparing — captureCommand
+  // always emits forward-slash paths into the hook command, but join() on
+  // Windows returns backslashes, so a raw startsWith() check would miss every
+  // copy-mode install on Windows and mis-label it as repo-path.
+  const copyDir = (join(homedir(), '.ai-lens', 'client') + '/').replace(/\\/g, '/');
   const paths = [];
   for (const tool of tools) {
     const cmd = extractHookCommand(tool);
     if (!cmd) continue;
-    const m = cmd.match(/["']([^"']*capture\.js)["']|(\S*capture\.js)/);
-    if (m) paths.push({ tool: tool.name, raw: m[1] || m[2], resolved: expandTilde(m[1] || m[2]) });
+    // Match either a launcher (run.sh / run.cmd) or a legacy capture.js path. The launcher
+    // always lives in the install dir, so it's by definition copy-mode.
+    const m = cmd.match(/["']([^"']*(?:capture\.js|run\.(?:sh|cmd)))["']|(\S*(?:capture\.js|run\.(?:sh|cmd)))/);
+    if (m) paths.push({ tool: tool.name, raw: m[1] || m[2], resolved: expandTilde(m[1] || m[2]).replace(/\\/g, '/') });
   }
   if (paths.length === 0) {
     return { ok: null, summary: 'unknown', detail: 'No hook commands found — cannot determine install mode' };
@@ -134,25 +147,32 @@ function validateHookCommandPaths(tool) {
   if (!command) return null;
 
   const issues = [];
-
-  // Extract capture.js path using 'capture.js' as anchor (expand ~ so existsSync works)
-  const captureMatch = command.match(/["']([^"']*capture\.js)["']|(\S*capture\.js)/);
-  if (captureMatch) {
-    const capturePath = expandTilde(captureMatch[1] || captureMatch[2]);
-    if (!existsSync(capturePath)) {
-      issues.push(`capture.js not found at: ${capturePath}`);
+  const launcherMatch = command.match(/["']([^"']*run\.(?:sh|cmd))["']|(\S*run\.(?:sh|cmd))/);
+
+  if (launcherMatch) {
+    // Launcher form (0.8.68+): one path, no separate node validation — the node binary
+    // baked into the launcher is invoked from inside the script, not the hook command.
+    const launcherPath = expandTilde(launcherMatch[1] || launcherMatch[2]);
+    if (!existsSync(launcherPath)) {
+      issues.push(`launcher not found at: ${launcherPath}`);
     }
-  }
-
-  // Extract node path (first token). Skip if /usr/bin/env node (node resolved via PATH)
-  // Strip "& " prefix (PowerShell call operator, added on Windows) before matching.
-  const cmdForNode = command.replace(/^& /, '');
-  if (!cmdForNode.startsWith('/usr/bin/env node')) {
-    const nodeMatch = cmdForNode.match(/^["']([^"']+)["']|^(\S+)/);
-    if (nodeMatch) {
-      const nodePath = expandTilde(nodeMatch[1] || nodeMatch[2]);
-      if (nodePath !== 'node' && !existsSync(nodePath)) {
-        issues.push(`node not found at: ${nodePath}`);
+  } else {
+    // Legacy `<node> capture.js` form.
+    const captureMatch = command.match(/["']([^"']*capture\.js)["']|(\S*capture\.js)/);
+    if (captureMatch) {
+      const capturePath = expandTilde(captureMatch[1] || captureMatch[2]);
+      if (!existsSync(capturePath)) {
+        issues.push(`capture.js not found at: ${capturePath}`);
+      }
+    }
+    const cmdForNode = command.replace(/^& /, '');
+    if (!cmdForNode.startsWith('/usr/bin/env node')) {
+      const nodeMatch = cmdForNode.match(/^["']([^"']+)["']|^(\S+)/);
+      if (nodeMatch) {
+        const nodePath = expandTilde(nodeMatch[1] || nodeMatch[2]);
+        if (nodePath !== 'node' && !existsSync(nodePath)) {
+          issues.push(`node not found at: ${nodePath}`);
+        }
       }
     }
   }
@@ -345,8 +365,10 @@ function checkCaptureRun(installedTools) {
         const stderr = (guiResult.stderr || '').trim();
         guiDetail = guiOk ? 'exit 0' : `Exit code: ${guiResult.status}\nError: ${stderr || '(no stderr)'}`;
         if (!guiOk && stderr.includes('No such file or directory')) {
-          guiDetail += '\nHint: node is not in the system PATH. GUI apps (Cursor) cannot find it.\n'
-            + 'Fix: sudo ln -s $(which node) /usr/local/bin/node';
+          guiDetail += '\nHint: node is not in the system PATH for GUI apps (Cursor).\n'
+            + 'Fix: re-run `ai-lens init` — it installs a launcher that bakes in your node path.\n'
+            + 'If init still fails, install node via nvm/asdf/fnm/volta or symlink it:\n'
+            + '  sudo ln -s "$(which node)" /usr/local/bin/node';
         }
       } catch (err) {
         guiOk = false;

package/package.json

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