ai-lens 0.8.72 → 0.8.74

package/.commithash

@@ -1 +1 @@
-78b5c4c
+87a4956

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.74 — 2026-06-04
+- fix: committed Claude Code project hooks now resolve `capture.js` via `$CLAUDE_PROJECT_DIR`, so they fire from any working directory — no more `MODULE_NOT_FOUND` after the agent `cd`s into a subdirectory.
+- fix: `ai-lens status` and `ai-lens init --project-hooks` recognize the `$CLAUDE_PROJECT_DIR` hook form as current instead of flagging it outdated or overwriting it.
+
+## 0.8.73 — 2026-05-29
+- fix: spooling an event now retries the atomic `rename` in `~/.ai-lens/pending/` a few times with a short backoff before giving up. On Windows, antivirus/Defender or the search indexer transiently locks the temp file and the rename failed with EPERM, silently dropping that event (observed in prod via the 0.8.70 error-code instrumentation). POSIX is unaffected (its rename is atomic and never hits this).
+
 ## 0.8.72 — 2026-05-29
 - fix: `status` no longer reports hooks as "outdated" when they already capture reliably. A hook is now considered current if it's GUI-safe — either the per-machine launcher (`run.sh`/`run.cmd`, including the transitional `sh -c` wrapper) OR a `capture.js` command with an absolute node path baked in (e.g. `/opt/homebrew/bin/node`). Only PATH-dependent forms (bare `node`, `/usr/bin/env node`) — which break for GUI-launched Cursor/Claude on macOS — stay flagged outdated so `init` rewrites them.
 - fix: `ai-lens status --report` now prints the full status to the screen just like plain `ai-lens status`, in addition to sending the report to the server. Previously it ran silently. The only difference from plain status is that it POSTs the report instead of writing the local `~/ai-lens-status.txt` file.

package/README.md

@@ -308,6 +308,8 @@ npm run dev:dashboard  # Dashboard dev server
 
 Tests require PostgreSQL — set `DATABASE_URL` or use `docker compose up postgres -d` (test DB `ailens_test` is created automatically).
 
+Architecture decisions are recorded under [`docs/adr/`](docs/adr/) — e.g. [ADR 0001 — Canonical metric predicates](docs/adr/0001-canonical-metric-predicates.md).
+
 ## Deployment
 
 GitLab CI (`.gitlab-ci.yml`) on push to `main`:

package/cli/hooks.js

@@ -322,6 +322,8 @@ function resolveDefaultCtx() {
  * @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 {string}  [opts.projectDirRelPath] — capture.js path relative to the workspace root,
+ *   emitted as a Claude-Code-only `node "$CLAUDE_PROJECT_DIR/<rel>"` command (committed project hooks)
  * @param {object}  [opts.ctx]        — { nodeResolution, platform, clientDir }; lazy-resolved if omitted
  */
 export function captureCommand(opts = {}) {
@@ -329,7 +331,7 @@ export function captureCommand(opts = {}) {
   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 { useTilde = false, rawPath = false, customPath = null, shell = null, projectDirRelPath = 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.
@@ -341,6 +343,20 @@ export function captureCommand(opts = {}) {
   // Windows — the two need different escaping for paths with spaces.
   const isPS = shell === 'powershell';
 
+  // Claude Code committed project hooks: resolve capture.js via Claude Code's
+  // $CLAUDE_PROJECT_DIR (the workspace root, injected into the hook environment).
+  // Claude Code runs the command through a shell, so the var expands regardless of
+  // the agent's cwd — a path relative to cwd breaks the moment the agent cd's into a
+  // subdir/subrepo (MODULE_NOT_FOUND). Because this string is committed to the repo
+  // it must stay machine-agnostic: bare `node` + the env var, never an absolute node
+  // binary or /home/<user> path. Windows Claude Code shells via cmd.exe (%VAR%);
+  // POSIX shells use $VAR.
+  if (projectDirRelPath != null) {
+    const rel = projectDirRelPath.replace(/\\/g, '/').replace(/^\.?\/+/, '');
+    const dir = isWin ? '%CLAUDE_PROJECT_DIR%' : '$CLAUDE_PROJECT_DIR';
+    return `node "${dir}/${rel}"`;
+  }
+
   // --use-repo-path: legacy <node> <capture.js> form.
   if (customPath != null) {
     if (!nodeResolution || !nodeResolution.path) {
@@ -618,6 +634,26 @@ export function getClaudeCodeHookDefsWithPath(capturePath, ctx = null) {
   return defs;
 }
 
+/**
+ * Claude Code hook defs for committed PROJECT hooks (.claude/settings.json checked
+ * into the repo). Resolves capture.js via Claude Code's $CLAUDE_PROJECT_DIR so the
+ * hook fires from any cwd and the path stays machine-agnostic (no absolute node/path).
+ * This is the cwd-robust replacement for the `--use-repo-path --project-hooks` form,
+ * whose project-root-relative path broke when an agent cd'd into a subdir.
+ * @param {string} relPath - capture.js path relative to the workspace root
+ *   (e.g. internal/analytics/ai-lens/client/capture.js). Must contain an `ai-lens/`
+ *   segment so isAiLensCommand recognises it.
+ * @param {object} [ctx]
+ */
+export function getClaudeCodeHookDefsWithProjectDir(relPath, ctx = null) {
+  const getCmd = memoizeCmd(() => captureCommand({ projectDirRelPath: relPath, 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.
@@ -879,19 +915,39 @@ export function isGuiSafeHookCommand(cmd) {
   return false;
 }
 
+// A committed Claude Code PROJECT hook that resolves capture.js through Claude Code's
+// $CLAUDE_PROJECT_DIR ($VAR on POSIX, %VAR% on Windows). This form intentionally uses
+// bare `node` (it's checked into the repo and must work on every teammate's machine,
+// so it can't bake an absolute node path), and Claude Code guarantees the var points
+// at the workspace root regardless of cwd. The var is Claude-Code-specific and never
+// emitted for Cursor/Codex, so matching it here can't mis-accept another tool's hook.
+export function isClaudeProjectDirCommand(cmd) {
+  if (!isAiLensCommand(cmd).isAiLens) return false;
+  const n = (cmd || '').replace(/\\/g, '/');
+  return /\$CLAUDE_PROJECT_DIR|%CLAUDE_PROJECT_DIR%/.test(n)
+    && /ai-lens\/client\/capture\.js/.test(n);
+}
+
+// A hook command init/status should leave alone: either GUI-safe (launcher /
+// absolute-node capture.js) OR the committed Claude Code $CLAUDE_PROJECT_DIR form.
+function isAcceptableHookCommand(cmd) {
+  return isGuiSafeHookCommand(cmd) || isClaudeProjectDirCommand(cmd);
+}
+
 function isCurrentAiLensHook(entry, expected) {
-  // "Current" = a GUI-safe install (launcher OR absolute-node capture.js). We do
-  // NOT require an exact match against the expected command form — both valid
-  // install methods capture reliably, so neither should be reported outdated.
-  // Only PATH-dependent forms (bare `node`, `/usr/bin/env node`) are outdated.
+  // "Current" = a GUI-safe install (launcher OR absolute-node capture.js) OR a
+  // committed Claude Code $CLAUDE_PROJECT_DIR project hook. We do NOT require an exact
+  // match against the expected command form — every valid install method captures
+  // reliably, so none should be reported outdated. Only PATH-dependent forms
+  // (bare `node`, `/usr/bin/env node`) WITHOUT $CLAUDE_PROJECT_DIR are outdated.
   // Flat format (Cursor): single command per entry.
   if (entry?.command != null) {
-    return isGuiSafeHookCommand(entry.command);
+    return isAcceptableHookCommand(entry.command);
   }
   // Nested format (Claude Code / Codex): { matcher, hooks: [{ command }] }
   if (Array.isArray(entry?.hooks)) {
     if (expected?.matcher !== undefined && entry.matcher !== expected.matcher) return false;
-    return entry.hooks.some(h => isGuiSafeHookCommand(h?.command || ''));
+    return entry.hooks.some(h => isAcceptableHookCommand(h?.command || ''));
   }
   return false;
 }

package/cli/init.js

@@ -16,7 +16,7 @@ import {
   CAPTURE_PATH, REPO_CAPTURE_PATH, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig,
   analyzeToolHooks, buildMergedConfig, writeHooksConfig, describePlan, enableCodexHookTrust,
   installClientFiles, readLensConfig, saveLensConfig, getVersionInfo,
-  getClaudeCodeHookDefsWithPath, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
+  getClaudeCodeHookDefsWithPath, getClaudeCodeHookDefsWithProjectDir, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
   checkHooksDisabled, enableHooks,
   findStableNodePath, isVersionPinnedNodePath, writeLauncher,
@@ -177,7 +177,14 @@ function getTrackedRoots(projects, fallbackRoot) {
 function makeNestedClaudeTool(projectDir, capturePathInHooks, ctx = null) {
   const tool = getClaudeCodeToolConfig(projectDir, `Claude Code (${projectDir})`, ctx);
   if (capturePathInHooks) {
-    tool.hookDefs = getClaudeCodeHookDefsWithPath(capturePathInHooks, ctx);
+    // A relative path carrying the ai-lens/ segment is resolved via Claude Code's
+    // $CLAUDE_PROJECT_DIR (the nested project's own root) so the hook fires from any
+    // cwd. Absolute/tilde paths keep the legacy <node> <capture.js> form.
+    const rel = capturePathInHooks.replace(/\\/g, '/');
+    const isRelative = !rel.startsWith('/') && !rel.startsWith('~') && !/^[a-zA-Z]:\//.test(rel);
+    tool.hookDefs = (isRelative && /(?:^|\/)ai-lens\//.test(rel))
+      ? getClaudeCodeHookDefsWithProjectDir(rel, ctx)
+      : getClaudeCodeHookDefsWithPath(capturePathInHooks, ctx);
   }
   return tool;
 }
@@ -458,6 +465,10 @@ export default async function init() {
     const repoPathAbs = resolve(REPO_CAPTURE_PATH);
     const home = homedir();
     let pathInHooks;
+    // When set, Claude Code project hooks resolve capture.js via $CLAUDE_PROJECT_DIR
+    // (cwd-robust + machine-agnostic) instead of a cwd-relative path that breaks the
+    // moment an agent cd's into a subdir. Holds the workspace-root-relative path.
+    let claudeProjectDirRel = null;
     if (flags.projectHooks) {
       const projectRoot = resolve(process.cwd());
       pathInHooks = relative(projectRoot, repoPathAbs).replace(/\\/g, '/');
@@ -472,7 +483,10 @@ export default async function init() {
           : 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).');
+        // Relative path carries the ai-lens/ segment → Claude Code can resolve it via
+        // $CLAUDE_PROJECT_DIR. The plain relative path stays the form for Cursor/Codex.
+        claudeProjectDirRel = pathInHooks;
+        info('  Claude Code project hooks will resolve capture.js via $CLAUDE_PROJECT_DIR (cwd-independent).');
       }
     } else {
       pathInHooks = repoPathAbs.startsWith(home)
@@ -488,7 +502,11 @@ export default async function init() {
       ? ('~' + repoPathAbs.slice(home.length)).replace(/\\/g, '/')
       : repoPathAbs.replace(/\\/g, '/');
     for (const tool of tools) {
-      if (tool.name.startsWith('Claude Code')) tool.hookDefs = getClaudeCodeHookDefsWithPath(pathInHooks, ctx);
+      if (tool.name.startsWith('Claude Code')) {
+        tool.hookDefs = claudeProjectDirRel
+          ? getClaudeCodeHookDefsWithProjectDir(claudeProjectDirRel, ctx)
+          : getClaudeCodeHookDefsWithPath(pathInHooks, ctx);
+      }
       else if (tool.name.startsWith('Cursor')) tool.hookDefs = getCursorHookDefsWithPath(pathInHooks, ctx);
       else if (tool.name.startsWith('Codex')) tool.hookDefs = getCodexHookDefsWithPath(codexPathInHooks, ctx);
     }

package/client/capture.js

@@ -1182,6 +1182,32 @@ export function normalizeEvent(event) {
 // Queue + Sender Spawn
 // =============================================================================
 
+// Windows (Defender / other AV, search indexer, file-locks) transiently fails an
+// atomic rename with EPERM/EACCES/EBUSY while another process briefly holds the
+// .tmp or destination handle. The rename is our spool-write step, so a transient
+// failure would drop the event (observed in prod: queue-write-failed EPERM on
+// rename in ~/.ai-lens/pending). Retry a few times with a short synchronous
+// backoff before giving up. POSIX rename is atomic and never hits these, so this
+// is a no-op there. Non-transient errors (e.g. ENOENT) are re-thrown immediately.
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+export function renameSyncWithRetry(from, to, { attempts = 5, baseDelayMs = 20, renameFn = renameSync } = {}) {
+  for (let i = 1; ; i++) {
+    try {
+      renameFn(from, to);
+      return;
+    } catch (err) {
+      if (i >= attempts || !RENAME_RETRY_CODES.has(err?.code)) throw err;
+      // Synchronous backoff — capture.js runs in a one-shot hook context, no event loop to yield to.
+      try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, baseDelayMs * i);
+      } catch {
+        const end = Date.now() + baseDelayMs * i;
+        while (Date.now() < end) { /* spin fallback if Atomics unavailable */ }
+      }
+    }
+  }
+}
+
 export function writeToSpool(unified) {
   // Shallow copy before redaction — do not mutate the caller's object
   const toWrite = { ...unified };
@@ -1198,7 +1224,7 @@ export function writeToSpool(unified) {
   const tmpPath  = dstPath + '.tmp.' + process.pid;
   writeFileSync(tmpPath, JSON.stringify(toWrite));
   try {
-    renameSync(tmpPath, dstPath);
+    renameSyncWithRetry(tmpPath, dstPath);
   } catch (err) {
     // Clean up orphaned tmp file (e.g. antivirus/file-lock on Windows)
     try { unlinkSync(tmpPath); } catch {}

package/package.json

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