ai-lens 0.8.92 → 0.8.94

package/.commithash

@@ -1 +1 @@
-2196993
+1b043cc

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.94 — 2026-06-16
+- feat: capture 8 more Claude Code events that were previously ignored — turn failures (session-limit / prompt-too-long / server-overload messages), notifications, permission requests, post-compact summaries, task created/completed, instructions loaded, and slash-command expansions. Re-run `ai-lens init` to install them; they're collected and forwarded only (no dashboard changes yet)
+
+## 0.8.93 — 2026-06-15
+- fix: on Windows, committed Claude Code project hooks no longer flash a console window that steals focus on every event — the hook command is wrapped in `conhost.exe --headless` (Windows 10 1809+), which runs capture with no visible window while still capturing every event. Older Windows builds and macOS/Linux are unchanged
+
 ## 0.8.92 — 2026-06-11
 - fix: when global `~/.claude` hooks are active, `ai-lens init` no longer also installs the `.claude/settings.local.json` platform overlay (and removes a previously-written one) — global hooks already capture every project, and registering both made every hook event fire capture twice
 - improve: `ai-lens status` shows committed other-OS project hooks as healthy ("capture covered by global hooks") when global hooks are doing the work, instead of a false warning

package/cli/hooks.js

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync, unlinkSync, chmodSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, release } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 
@@ -230,78 +230,31 @@ export function findStableNodePath({
   return { path: execPath, stable: false, source: 'execPathFallback' };
 }
 
+// ADR 0003 removed the per-machine launcher (run.sh / run.cmd). The absolute node
+// path is now baked straight into the hook command by captureCommand; there is no
+// launcher script. `isAiLensCommand` still recognises run.* so `remove`/migration
+// can clean up installs from before this change.
+
 // ---------------------------------------------------------------------------
-// Per-machine launcher (run.sh / run.cmd)
+// Hook command construction
 // ---------------------------------------------------------------------------
 
-/**
- * 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');
+// `conhost.exe --headless` runs a console program with no visible window — the
+// fix for Windows hooks flashing/stealing focus on every event (Claude Code spawns
+// the hook process without CREATE_NO_WINDOW; upstream anthropics/claude-code#61051).
+// Unlike wscript/`-WindowStyle Hidden`, it keeps stdin wired, so capture.js still
+// receives the hook payload. `--headless` requires the modern conhost shipped in
+// Windows 10 1809 (build 17763); on older builds the flag errors, so we gate on it
+// and fall back to the bare-node form (still flashes, but captures).
+const WIN_HEADLESS_MIN_BUILD = 17763;
 
-  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;
-  }
-
-  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;
+export function supportsConhostHeadless(osRelease = release()) {
+  // os.release() on Windows looks like '10.0.22631'. Build = the third segment.
+  const m = /^\d+\.\d+\.(\d+)/.exec(String(osRelease || ''));
+  if (!m) return false;
+  return Number(m[1]) >= WIN_HEADLESS_MIN_BUILD;
 }
 
-// ---------------------------------------------------------------------------
-// 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() {
@@ -310,6 +263,7 @@ function resolveDefaultCtx() {
     nodeResolution,
     platform: process.platform,
     clientDir: CLIENT_INSTALL_DIR,
+    conhost: process.platform === 'win32' && supportsConhostHeadless(),
   };
 }
 
@@ -332,7 +286,8 @@ 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, projectDirRelPath = null } = opts;
+  const { useTilde = false, rawPath = false, customPath = null, shell = null, projectDirRelPath = null, windowless = false } = opts;
+  void useTilde; // launcher form removed (ADR 0003); kept in the signature for back-compat, no effect
   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.
@@ -340,6 +295,11 @@ export function captureCommand(opts = {}) {
   const clientDir = ctx.clientDir ?? CLIENT_INSTALL_DIR;
   const nodeResolution = ctx.nodeResolution;
   const isWin = platform === 'win32';
+  // Windows-only windowless wrapper (see supportsConhostHeadless). Gated by the
+  // `windowless` opt so it's applied to CLAUDE forms only — Cursor/Codex never set it
+  // (no reported flash + unverified conhost+stdin for those tools; ADR 0003 §3.2).
+  // A build < 1809 falls back to the bare form. Never applied off Windows.
+  const conhost = isWin && windowless && (ctx.conhost ?? supportsConhostHeadless());
   // 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';
@@ -354,65 +314,49 @@ export function captureCommand(opts = {}) {
   // POSIX shells use $VAR.
   if (projectDirRelPath != null) {
     const rel = projectDirRelPath.replace(/\\/g, '/').replace(/^\.?\/+/, '');
+    if (conhost) {
+      // Windowless form. conhost is the launched image (no cmd.exe shell), so the
+      // path must use $CLAUDE_PROJECT_DIR — Claude Code substitutes that variable
+      // itself before exec on every OS (the %VAR% form would survive unexpanded
+      // since there's no shell to expand it). Verified on Windows 11 / cc 2.1.177.
+      return `conhost.exe --headless node "$CLAUDE_PROJECT_DIR/${rel}"`;
+    }
     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) {
-      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;
+  // Unified <node> <capture.js> form (ADR 0003 — replaces the run.sh/run.cmd launcher).
+  // capturePath = the repo capture.js (--use-repo-path, customPath given) OR the
+  // installed copy at <clientDir>/capture.js (default global install). The absolute
+  // node path is baked straight into the command — legal now that hooks are
+  // per-machine (no committed file to keep machine-agnostic).
+  if (!nodeResolution || !nodeResolution.path) {
+    throw new Error('captureCommand: nodeResolution is required');
+  }
+  const capturePath = (customPath ?? join(clientDir, 'capture.js')).replace(/\\/g, '/');
+  // The script path MUST be quoted when it contains spaces — otherwise /bin/sh,
+  // cmd.exe and PowerShell split it into argv tokens. Double-quote on Windows
+  // (works for cmd.exe + PowerShell), POSIX single-quote elsewhere.
+  const pathPart = rawPath
+    ? quoteIfHasSpaces(capturePath, platform)
+    : shellEscape(capturePath, platform);
+  const nodeNorm = nodeResolution.path.replace(/\\/g, '/');
+
+  // Windowless (Claude + Windows ≥ 1809): conhost.exe is the launched image and runs
+  // node directly, so it needs neither the cmd.exe `call` nor the PowerShell `&`
+  // wrapper. stdin is forwarded (verified). The node path is always double-quoted on
+  // Windows (it can contain spaces, e.g. C:/Program Files/nodejs/node.exe).
+  if (conhost) {
+    return `conhost.exe --headless "${nodeNorm.replace(/"/g, '""')}" ${pathPart}`;
+  }
+  if (isWin && rawPath && nodeNorm.includes(' ')) {
+    const quotedNode = `"${nodeNorm.replace(/"/g, '""')}"`;
+    // PowerShell (Cursor) handles a quoted first token natively — caller prepends `& `.
+    if (isPS) return `${quotedNode} ${pathPart}`;
+    // cmd.exe (Claude Code) needs `call` to run a quoted first token.
+    return `call ${quotedNode} ${pathPart}`;
+  }
+  return `${shellEscape(nodeNorm, platform)} ${pathPart}`;
 }
 
 /**
@@ -453,37 +397,20 @@ export function listClientFiles(sourceDir = join(__dirname, '..', 'client')) {
 }
 
 /**
- * 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.
+ * Copy client/*.js to ~/.ai-lens/client/ (default global install). No launcher is
+ * written any more (ADR 0003) — the hook command bakes the absolute node path itself,
+ * so installClientFiles no longer needs a node path. `writeLauncher` opt is accepted
+ * and ignored for back-compat with older callers/tests.
  *
  * @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(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 });
 
@@ -504,18 +431,15 @@ export function installClientFiles(opts = {}) {
     join(clientDir, 'version.json'),
     JSON.stringify({ version, commit, packageRoot: PKG_ROOT }) + '\n',
   );
-
-  if (shouldWriteLauncher) {
-    writeLauncher({ clientDir, nodePath: nodeResolution.path, platform });
-  }
 }
 
 /**
- * Remove installed client files from ~/.ai-lens/client/.
+ * Remove installed client files from the client dir (default ~/.ai-lens/client/).
+ * @param {string} [clientDir] — override for tests so they never rm the real install.
  */
-export function removeClientFiles() {
-  if (existsSync(CLIENT_INSTALL_DIR)) {
-    rmSync(CLIENT_INSTALL_DIR, { recursive: true, force: true });
+export function removeClientFiles(clientDir = CLIENT_INSTALL_DIR) {
+  if (existsSync(clientDir)) {
+    rmSync(clientDir, { recursive: true, force: true });
   }
 }
 
@@ -535,6 +459,18 @@ const CLAUDE_HOOK_SPEC = {
   PreCompact:         { matcher: '' },
   SubagentStart:      { matcher: '' },
   SubagentStop:       { matcher: '' },
+  // Observability events — captured + forwarded, not yet wired into analysis.
+  // All fire as Claude Code `command` hooks with an empty matcher (verified
+  // against live settings.json). Kept metric-neutral server-side via the
+  // exclusion sets in server/utils/event-types.js.
+  StopFailure:         { matcher: '' },
+  Notification:        { matcher: '' },
+  PermissionRequest:   { matcher: '' },
+  PostCompact:         { matcher: '' },
+  TaskCreated:         { matcher: '' },
+  TaskCompleted:       { matcher: '' },
+  InstructionsLoaded:  { matcher: '' },
+  UserPromptExpansion: { matcher: '' },
 };
 
 const CURSOR_HOOK_NAMES = [
@@ -579,7 +515,7 @@ function memoizeCmd(produce) {
  * probes node candidates by itself.
  */
 export function makeClaudeHookDefs(ctx = null, _mode = 'global') {
-  const getCmd = memoizeCmd(() => captureCommand({ useTilde: true, rawPath: true, ctx }));
+  const getCmd = memoizeCmd(() => captureCommand({ rawPath: true, windowless: true, ctx }));
   const defs = {};
   for (const [name, spec] of Object.entries(CLAUDE_HOOK_SPEC)) {
     defs[name] = () => ({ matcher: spec.matcher, hooks: [{ type: 'command', command: getCmd() }] });
@@ -627,7 +563,7 @@ export function makeCodexHookDefs(ctx = null, mode = 'global') {
  * @param {object} [ctx]
  */
 export function getClaudeCodeHookDefsWithPath(capturePath, ctx = null) {
-  const getCmd = memoizeCmd(() => captureCommand({ rawPath: true, customPath: capturePath, ctx }));
+  const getCmd = memoizeCmd(() => captureCommand({ rawPath: true, customPath: capturePath, windowless: true, ctx }));
   const defs = {};
   for (const [name, spec] of Object.entries(CLAUDE_HOOK_SPEC)) {
     defs[name] = () => ({ matcher: spec.matcher, hooks: [{ type: 'command', command: getCmd() }] });
@@ -647,7 +583,7 @@ export function getClaudeCodeHookDefsWithPath(capturePath, ctx = null) {
  * @param {object} [ctx]
  */
 export function getClaudeCodeHookDefsWithProjectDir(relPath, ctx = null) {
-  const getCmd = memoizeCmd(() => captureCommand({ projectDirRelPath: relPath, ctx }));
+  const getCmd = memoizeCmd(() => captureCommand({ projectDirRelPath: relPath, windowless: true, ctx }));
   const defs = {};
   for (const [name, spec] of Object.entries(CLAUDE_HOOK_SPEC)) {
     defs[name] = () => ({ matcher: spec.matcher, hooks: [{ type: 'command', command: getCmd() }] });
@@ -833,6 +769,14 @@ export function _parseHookCommand(cmd) {
     prefix = 'win-claude';
     rest = rest.slice(5).trim();
   }
+  // Windowless wrapper (Windows Claude, ADR 0003): conhost.exe --headless <node> <path>.
+  // Strip it like the other prefixes so the residue parses as the captureJs form and
+  // the existing absolute-node GUI-safe check applies unchanged.
+  const conhostMatch = rest.match(CONHOST_HEADLESS_PREFIX_RE);
+  if (conhostMatch) {
+    prefix = 'win-headless';
+    rest = rest.slice(conhostMatch[0].length).trim();
+  }
 
   const tokens = tokenizeHookCommand(rest);
   if (tokens.length === 0) {
@@ -892,18 +836,15 @@ function normalizePath(p) {
 }
 
 // A hook command is "GUI-safe" — i.e. survives a GUI app's minimal launchd PATH —
-// if it either routes through the per-machine launcher (run.sh / run.cmd, directly
-// OR via the transitional wrapper that execs it) OR runs capture.js with an
-// ABSOLUTE node path baked in. Bare `node` and `/usr/bin/env node` are NOT GUI-safe
-// (they depend on node being on PATH, which GUI Cursor/Claude often lack).
-//
-// Both GUI-safe forms capture events reliably, so init produces one of them and we
-// treat either as "current". Only the PATH-dependent forms get flagged outdated.
+// if it runs capture.js with an ABSOLUTE node path baked in (optionally behind the
+// conhost.exe --headless windowless wrapper, which _parseHookCommand strips). Bare
+// `node` and `/usr/bin/env node` are NOT GUI-safe (they depend on node being on PATH,
+// which GUI Cursor/Claude often lack). The old run.sh/run.cmd launcher is NO LONGER
+// recognised here (ADR 0003 removed it) — it is therefore reported `outdated`, so
+// `/setup` migrates an existing launcher install to the unified form. (`isAiLensCommand`
+// still classifies run.* as ai-lens so `remove`/strip cleans up stale launchers.)
 export function isGuiSafeHookCommand(cmd) {
   if (!isAiLensCommand(cmd).isAiLens) return false;
-  const n = (cmd || '').replace(/\\/g, '/');
-  // Launcher: direct path, or the transitional wrapper that execs run.sh/run.cmd.
-  if (n.includes('.ai-lens/client/run.sh') || n.includes('.ai-lens/client/run.cmd')) return true;
   // capture.js form: GUI-safe only when the node binary is an absolute path
   // (e.g. /opt/homebrew/bin/node), not bare `node` or an env shim.
   const p = _parseHookCommand(cmd);
@@ -945,10 +886,26 @@ function isAcceptableHookCommand(cmd) {
 export function isWrongPlatformProjectDirCommand(cmd, platform = process.platform) {
   if (!isClaudeProjectDirCommand(cmd)) return false;
   const n = (cmd || '').replace(/\\/g, '/');
+  // The conhost windowless form is unambiguously a Windows command (conhost.exe is
+  // Windows-only) and deliberately uses $CLAUDE_PROJECT_DIR — Claude Code substitutes
+  // that itself, so it expands on Windows too. It is therefore correct on win32 and
+  // wrong (won't run) anywhere else; the %VAR% rule below doesn't apply to it.
+  if (isConhostHeadlessCommand(n)) return platform !== 'win32';
   const correctVar = platform === 'win32' ? '%CLAUDE_PROJECT_DIR%' : '$CLAUDE_PROJECT_DIR';
   return !n.includes(correctVar);
 }
 
+// Leading `conhost.exe --headless ` windowless wrapper, with the trailing space so a
+// strip leaves the wrapped `<node> <path>` command. Single source of truth shared by
+// _parseHookCommand and status.js (avoids the regex drifting between the two).
+export const CONHOST_HEADLESS_PREFIX_RE = /^conhost(?:\.exe)?\s+--headless\s+/i;
+
+// `conhost.exe --headless …` windowless wrapper (Windows). Tolerates an optional
+// `.exe` and arbitrary spacing between the two tokens.
+export function isConhostHeadlessCommand(cmd) {
+  return /(^|[\\/\s])conhost(\.exe)?\s+--headless\b/i.test(String(cmd || '').replace(/\\/g, '/'));
+}
+
 // Whether a hook-config file is committed (tracked) in git. The anti-churn rule
 // (treat both $ and % CLAUDE_PROJECT_DIR forms as current) exists ONLY to keep a
 // COMMITTED cross-platform hook file from being flipped to one OS's syntax and

package/cli/init.js

@@ -20,9 +20,8 @@ import {
   getClaudeCodeHookDefsWithPath, getClaudeCodeHookDefsWithProjectDir, getCursorHookDefsWithPath, getCodexHookDefsWithPath,
   cleanupLegacyHooks, cleanupOppositeScope, cleanupEmptyMcpJson, addCursorMcp, removeCursorMcp,
   checkHooksDisabled, enableHooks,
-  findStableNodePath, isVersionPinnedNodePath, writeLauncher,
+  findStableNodePath,
 } from './hooks.js';
-import { mkdirSync } from 'node:fs';
 import { scanNestedClaudeProjects, summarizeNestedProjects } from './scan.js';
 
 function ask(question) {
@@ -360,7 +359,7 @@ function getInitArgs() {
         flags.useRepoPath = true;
         break;
       case '--install-launcher':
-        flags.installLauncher = true;
+        // ADR 0003 removed the launcher; flag accepted but inert (back-compat).
         break;
       case '--import':
         flags.importHistory = true;
@@ -405,16 +404,14 @@ 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 (willInstallLauncher) {
+  if (willWriteHooks) {
+    // The hook command bakes an absolute node path (ADR 0003 — no more launcher), so
+    // resolve a stable node binary up front. A version-pinned path still works but is
+    // warned about: it breaks on a node upgrade until the next /setup re-resolves it.
     nodeResolution = findStableNodePath();
     if (!nodeResolution) {
       error('Could not find any node binary on this system.');
@@ -429,9 +426,7 @@ export default async function init() {
     } else {
       detail(`  Resolved node: ${nodeResolution.path} (${nodeResolution.source})`);
     }
-    if (willWriteHooks) {
-      ctx = { nodeResolution, platform: process.platform, clientDir: join(homedir(), '.ai-lens', 'client') };
-    }
+    ctx = { nodeResolution, platform: process.platform, clientDir: join(homedir(), '.ai-lens', 'client') };
   }
 
   // Detect installed tools — re-detect with ctx now that it's available.
@@ -452,9 +447,17 @@ export default async function init() {
       info('  Cursor hooks will be written to this project (.cursor/hooks.json).');
     }
     if (claudeProject) {
+      // Б (HELP-1539): Claude Code project hooks go to the gitignored per-machine
+      // overlay (.claude/settings.local.json), NEVER the committed settings.json.
+      // A committed Claude Code hook carries one OS's form and is the recurring
+      // cross-OS bug source (flash on Windows / silently-never-fires on the other
+      // OS — HELP-1169, HELP-1539). The local layer lets each machine install its
+      // own OS-correct form (windowless conhost on Windows). Cursor/Codex keep their
+      // committed project files — they don't share the cross-OS-committed problem.
+      claudeProject.configPath = join(claudeProject.dirPath, 'settings.local.json');
       tools = tools.filter(t => t.name !== 'Claude Code');
       tools.push(claudeProject);
-      info('  Claude Code hooks will be written to this project (.claude/settings.json).');
+      info('  Claude Code hooks will be written per-machine to this project (.claude/settings.local.json, gitignored).');
     }
     if (codexProject) {
       tools = tools.filter(t => t.name !== 'Codex');
@@ -601,34 +604,12 @@ export default async function init() {
   if (!flags.useRepoPath) {
     heading('Installing client files...');
     try {
-      installClientFiles({
-        nodeResolution,
-        platform: process.platform,
-        writeLauncher: willWriteHooks,
-      });
+      installClientFiles({ platform: process.platform });
       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).');
   }
@@ -994,9 +975,11 @@ export default async function init() {
   // the hook silently never fires (cmd.exe vs sh; upstream anthropic/claude-code#24710
   // closed as not planned). When the committed form doesn't match this OS, mirror the
   // hooks into .claude/settings.local.json — Claude Code's per-machine layer
-  // (auto-gitignored, merged with settings.json at runtime). Runs regardless of
-  // --project-hooks: the committed file arrives with the clone, not via init.
-  if (!flags.noHooks) {
+  // (auto-gitignored, merged with settings.json at runtime). Only for the
+  // clone-with-committed-hooks case: under --project-hooks we already wrote the
+  // OS-correct form straight into settings.local.json above, so mirroring the
+  // committed file on top would be redundant (and racy against that write).
+  if (!flags.noHooks && !flags.projectHooks) {
     try {
       const overlayProjectRoot = resolve(process.cwd());
       const overlayClaudeTool = getClaudeCodeToolConfig(overlayProjectRoot, 'Claude Code (project)', ctx);

package/cli/scan.js

@@ -101,16 +101,14 @@ function classifyProject(projectDir) {
     };
   }
 
-  if (hasAnyNonAiLensHooks(settings)) {
-    return {
-      status: 'has non-ai-lens hooks',
-      installTarget: 'settings.json',
-      existingConfig: settings,
-    };
-  }
-
+  // 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: 'missing',
+    status: hasAnyNonAiLensHooks(settings) ? 'has non-ai-lens hooks' : 'missing',
     installTarget: 'settings.local.json',
     existingConfig: settingsLocal,
   };

package/cli/status.js

@@ -7,7 +7,7 @@ import tls from 'node:tls';
 
 import { TLS_TRUST_CODES, tlsCodeOf, tlsVerdictSummary, issuerName } from '../client/tls-trust.js';
 
-import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks, checkHooksDisabled, verifyCodexHookTrust, CAPTURE_PATH, TOOL_CONFIGS, isClaudeProjectDirCommand, analyzeClaudeLocalOverlay, extractProjectDirRelPath, globalClaudeHooksActive } from './hooks.js';
+import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks, checkHooksDisabled, verifyCodexHookTrust, CAPTURE_PATH, TOOL_CONFIGS, isClaudeProjectDirCommand, analyzeClaudeLocalOverlay, extractProjectDirRelPath, globalClaudeHooksActive, CONHOST_HEADLESS_PREFIX_RE } from './hooks.js';
 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';
@@ -167,13 +167,20 @@ function validateHookCommandPaths(tool) {
         issues.push(`capture.js not found at: ${capturePath}`);
       }
     }
-    const cmdForNode = command.replace(/^& /, '');
+    // Strip the Cursor PowerShell `& ` and the Windows windowless `conhost.exe
+    // --headless` wrappers so the FIRST remaining token is the real node binary —
+    // then flag a baked absolute node path that no longer exists (e.g. after a node
+    // upgrade moved a version-pinned path), so it surfaces instead of silently
+    // dropping events (ADR 0003 §6 / R3).
+    const cmdForNode = command
+      .replace(/^& /, '')
+      .replace(CONHOST_HEADLESS_PREFIX_RE, '');
     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}`);
+          issues.push(`node not found at: ${nodePath} — re-run \`ai-lens init\` to re-resolve node`);
         }
       }
     }

package/client/capture.js

@@ -99,6 +99,9 @@ export const TRUNCATION_LIMITS = {
   userPrompt: 1000,
   agentResponse: 1000,
   agentThought: 500,
+  // Compact summaries / task descriptions can run multiple KB — keep a
+  // generous prefix in `data`; the full text always survives in `raw`.
+  summary: 2000,
 };
 
 export function truncate(text, maxLen) {
@@ -684,6 +687,16 @@ const CLAUDE_CODE_TYPE_MAP = {
   PreCompact: 'PreCompact',
   SubagentStart: 'SubagentStart',
   SubagentStop: 'SubagentStop',
+  // Observability events — captured + forwarded, not yet wired into analysis.
+  // Kept metric-neutral server-side (server/utils/event-types.js exclusion sets).
+  StopFailure: 'StopFailure',
+  Notification: 'Notification',
+  PermissionRequest: 'PermissionRequest',
+  PostCompact: 'PostCompact',
+  TaskCreated: 'TaskCreated',
+  TaskCompleted: 'TaskCompleted',
+  InstructionsLoaded: 'InstructionsLoaded',
+  UserPromptExpansion: 'UserPromptExpansion',
 };
 
 // Tools that indicate plan mode transitions
@@ -795,6 +808,62 @@ function normalizeClaudeCode(event) {
         agent_type: event.agent_type || null,
       };
       break;
+    // --- Observability events (captured + forwarded, not yet analyzed) ------
+    case 'StopFailure':
+      // A turn that aborted (session limit / prompt-too-long / 5xx overload /
+      // rate limit). NOTE: deliberately does NOT read the transcript delta for
+      // TokenUsage (unlike Stop/SubagentStop below) — those tokens are picked
+      // up by the next Stop in the session via the persisted offset.
+      data = {
+        error: event.error ?? null,
+        last_assistant_message: truncate(event.last_assistant_message || '', TRUNCATION_LIMITS.userPrompt),
+      };
+      break;
+    case 'Notification':
+      data = {
+        notification_type: event.notification_type ?? null,
+        message: truncate(event.message || '', TRUNCATION_LIMITS.userPrompt),
+      };
+      break;
+    case 'PermissionRequest': {
+      const reqTool = event.tool_name || event.tool || 'unknown';
+      data = {
+        tool: reqTool,
+        input: truncateToolInput(event.tool_input || event.input, reqTool),
+        permission_mode: event.permission_mode ?? null,
+      };
+      break;
+    }
+    case 'PostCompact':
+      data = {
+        trigger: event.trigger ?? null,
+        compact_summary: truncate(event.compact_summary || '', TRUNCATION_LIMITS.summary),
+      };
+      break;
+    case 'TaskCreated':
+    case 'TaskCompleted':
+      data = {
+        task_id: event.task_id ?? null,
+        task_subject: truncate(event.task_subject || '', TRUNCATION_LIMITS.userPrompt),
+        task_description: truncate(event.task_description || '', TRUNCATION_LIMITS.summary),
+      };
+      break;
+    case 'InstructionsLoaded':
+      data = {
+        file_path: event.file_path ?? null,
+        memory_type: event.memory_type ?? null,
+        load_reason: event.load_reason ?? null,
+        trigger_file_path: event.trigger_file_path ?? null,
+      };
+      break;
+    case 'UserPromptExpansion':
+      data = {
+        expansion_type: event.expansion_type ?? null,
+        command_name: event.command_name ?? null,
+        command_source: event.command_source ?? null,
+        prompt: truncate(event.prompt || '', TRUNCATION_LIMITS.userPrompt),
+      };
+      break;
     default:
       data = { hook: hookType };
   }

package/package.json

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