ai-lens 0.8.68 → 0.8.70

package/.commithash

@@ -1 +1 @@
-72eb1f0
+0912a07

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.70 — 2026-05-28
+- diag: `sender-spawn-failed`, `codex-watcher-spawn-failed` and `queue-write-failed` entries in the capture log now record the OS `error.code` (e.g. EMFILE, EACCES). `ai-lens status` surfaces a per-category code breakdown so these failures can be diagnosed centrally instead of guessing from a bare count. The raw error message (which may contain local paths) stays on your machine — only the short code travels in the status report.
+
+## 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`.

package/cli/hooks.js

@@ -242,8 +242,20 @@ export function launcherFilename(platform = process.platform) {
 
 /**
  * Write a per-machine launcher script with the resolved node path baked in.
- * The launcher uses dirname-of-script to find capture.js, so it's independent
- * of HOME / USERPROFILE / cwd at execution time.
+ *
+ * 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
@@ -256,7 +268,13 @@ export function writeLauncher({ clientDir = CLIENT_INSTALL_DIR, nodePath, platfo
 
   if (platform === 'win32') {
     const escaped = nodePath.replace(/"/g, '""');
-    const content = `@echo off\r\n"${escaped}" "%~dp0capture.js" %*\r\n`;
+    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;
@@ -265,8 +283,14 @@ export function writeLauncher({ clientDir = CLIENT_INSTALL_DIR, nodePath, platfo
   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`;
+    + `exec ${escaped} "$DIR/capture.js"\n`;
   const target = join(clientDir, 'run.sh');
   writeFileSync(target, content);
   try { chmodSync(target, 0o755); } catch { /* best effort */ }

package/cli/init.js

@@ -20,8 +20,9 @@ import {
   getClaudeCodeHookDefsWithPath, getCursorHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
   checkHooksDisabled, enableHooks,
-  findStableNodePath, isVersionPinnedNodePath,
+  findStableNodePath, isVersionPinnedNodePath, writeLauncher,
 } from './hooks.js';
+import { mkdirSync } from 'node:fs';
 import { scanNestedClaudeProjects, summarizeNestedProjects } from './scan.js';
 
 function ask(question) {
@@ -351,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');
@@ -359,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`);
         }
       }
@@ -387,11 +391,17 @@ export default async function init() {
   //
   // --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 (willWriteHooks) {
+  if (willInstallLauncher) {
     nodeResolution = findStableNodePath();
     if (!nodeResolution) {
       error('Could not find any node binary on this system.');
@@ -406,7 +416,9 @@ export default async function init() {
     } else {
       detail(`  Resolved node: ${nodeResolution.path} (${nodeResolution.source})`);
     }
-    ctx = { nodeResolution, platform: process.platform, clientDir: join(homedir(), '.ai-lens', 'client') };
+    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.
@@ -545,9 +557,8 @@ 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).
-  // Launcher (run.sh / run.cmd) is written only when we will actually wire up hooks
-  // — --no-hooks installs leave it out (and don't require a resolved node 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 {
@@ -564,6 +575,21 @@ export default async function init() {
       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).');
   }

package/cli/status.js

@@ -725,8 +725,13 @@ function checkCaptureLog() {
     return { ok: false, summary: `error reading log: ${err.message}`, detail: `Error: ${err.message}` };
   }
 
-  // Count entries by category (reason for drops, msg for errors)
+  // Count entries by category (reason for drops, msg for errors). For error
+  // entries that carry an `error.code` (spawn/queue failures), also tally the
+  // code distribution per category so it reaches the server via client_reports
+  // — the count alone can't tell EMFILE from EACCES from ENOENT. The raw
+  // error.message strings stay local (may contain paths); only the code travels.
   const counts = {};
+  const codesByCategory = {};
   let lastTs = null;
   let hasErrors = false;
   for (const line of lines) {
@@ -734,24 +739,38 @@ function checkCaptureLog() {
       const entry = JSON.parse(line);
       const category = entry.reason || entry.msg || 'unknown';
       counts[category] = (counts[category] || 0) + 1;
+      if (entry.code) {
+        (codesByCategory[category] ??= {});
+        codesByCategory[category][entry.code] = (codesByCategory[category][entry.code] || 0) + 1;
+      }
       lastTs = entry.ts;
       if (entry.msg) hasErrors = true;
     } catch { /* non-JSON line */ }
   }
 
   const total = lines.length;
-  const breakdown = Object.entries(counts).map(([r, n]) => `${r}: ${n}`).join(', ');
+  const breakdown = Object.entries(counts).map(([r, n]) => {
+    const codes = codesByCategory[r];
+    if (!codes) return `${r}: ${n}`;
+    const codeStr = Object.entries(codes).map(([c, cn]) => `${c}: ${cn}`).join(', ');
+    return `${r}: ${n} [${codeStr}]`;
+  }).join(', ');
 
   let summary = `${total} entries`;
   if (breakdown) summary += ` (${breakdown})`;
   if (lastTs) summary += `, last ${relativeTime(lastTs)}`;
 
+  // Include a compact code-distribution block in detail too — survives even if
+  // the "last 10 entries" happen to be benign project_filter lines.
+  const codeLines = Object.entries(codesByCategory)
+    .map(([cat, codes]) => `  ${cat}: ${Object.entries(codes).map(([c, n]) => `${c}=${n}`).join(', ')}`);
+  const codeBlock = codeLines.length ? `\n\nError codes by category:\n${codeLines.join('\n')}` : '';
   const last10 = lines.slice(-10);
 
   return {
     ok: !hasErrors,
     summary,
-    detail: `Log: ${CAPTURE_LOG_PATH}\nTotal: ${total}\n\nLast 10 entries:\n${last10.join('\n')}`,
+    detail: `Log: ${CAPTURE_LOG_PATH}\nTotal: ${total}${codeBlock}\n\nLast 10 entries:\n${last10.join('\n')}`,
   };
 }
 

package/client/capture.js

@@ -1263,7 +1263,7 @@ async function main() {
       writeToSpool(ev);
       if (ev === primary) primaryWritten = true;
     } catch (err) {
-      captureLog({ msg: 'queue-write-failed', error: err.message, type: ev.type, session_id: ev.session_id });
+      captureLog({ msg: 'queue-write-failed', error: err.message, code: err.code, type: ev.type, session_id: ev.session_id });
       // If the primary failed, propagate the failure so the hook exits non-zero
       // (and dedup is NOT committed). If a per-call event failed, log and keep
       // going — losing one TokenUsage row is better than dropping the whole
@@ -1312,14 +1312,14 @@ async function main() {
   try {
     trySpawnSender();
   } catch (err) {
-    captureLog({ msg: 'sender-spawn-failed', error: err.message });
+    captureLog({ msg: 'sender-spawn-failed', error: err.message, code: err.code });
     // event is queued — sender will be spawned on next capture
   }
 
   try {
     trySpawnCodexWatcher({ replayExisting: shouldReplayCodexHistory(primary) });
   } catch (err) {
-    captureLog({ msg: 'codex-watcher-spawn-failed', error: err.message });
+    captureLog({ msg: 'codex-watcher-spawn-failed', error: err.message, code: err.code });
   }
 }
 

package/package.json

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