ai-lens 0.8.93 → 0.8.95

package/.commithash

@@ -1 +1 @@
-255d9a3
+defcd78

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.95 — 2026-06-17
+- fix: on Windows, Cursor hooks no longer flash a console window on every event (including new-session start) — the hook command is now wrapped in `conhost.exe --headless` (Windows 10 1809+), the same windowless form Claude Code hooks already use. Older Windows builds and macOS/Linux are unchanged. Re-run `ai-lens init` to apply
+- feat: `ai-lens init` now warns when the configured `projects` filter does not cover the workspace you're setting up — a stale filter silently drops all capture (hooks look configured but record nothing)
+- feat: the Claude Code history-import offer now previews how much there is to import ("Found N sessions from A to B") before asking, instead of a bare yes/no
+
+## 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
 

package/cli/hooks.js

@@ -230,73 +230,10 @@ export function findStableNodePath({
   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;
-  }
-
-  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;
-}
+// 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.
 
 // ---------------------------------------------------------------------------
 // Hook command construction
@@ -349,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.
@@ -357,9 +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). Resolved per-ctx
-  // so a build < 1809 falls back to the bare form. Never applied off Windows.
-  const conhost = isWin && (ctx.conhost ?? supportsConhostHeadless());
+  // 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';
@@ -385,61 +325,38 @@ export function captureCommand(opts = {}) {
     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}`;
 }
 
 /**
@@ -458,9 +375,13 @@ export function cursorCaptureCommand(opts = {}) {
   // hint when building the underlying command (avoids the cmd.exe `call` prefix
   // which PowerShell doesn't understand).
   const shell = platform === 'win32' ? 'powershell' : null;
+  // windowless: on Windows ≥1809 wrap node in `conhost.exe --headless` so Cursor
+  // doesn't flash a console window on every event (incl. session start). `& ` still
+  // works in front of conhost; the detector strips `& ` then the conhost prefix, so
+  // the form stays recognised as current (no churn). Mac/old-Windows: unchanged.
   const cmd = customPath != null
-    ? captureCommand({ useTilde: false, rawPath: true, customPath, ctx, shell })
-    : captureCommand({ useTilde: effectiveUseTilde, ctx, shell });
+    ? captureCommand({ rawPath: true, customPath, windowless: true, ctx, shell })
+    : captureCommand({ useTilde: effectiveUseTilde, windowless: true, ctx, shell });
   return platform === 'win32' ? `& ${cmd}` : cmd;
 }
 
@@ -480,37 +401,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 });
 
@@ -531,18 +435,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 });
   }
 }
 
@@ -562,6 +463,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 = [
@@ -606,7 +519,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() }] });
@@ -654,7 +567,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() }] });
@@ -674,7 +587,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() }] });
@@ -860,6 +773,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) {
@@ -919,18 +840,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);
@@ -981,6 +899,11 @@ export function isWrongPlatformProjectDirCommand(cmd, platform = process.platfor
   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) {

package/cli/import/claude-code.js

@@ -92,6 +92,31 @@ export function resolveCutoff({ days, since, from }, now = new Date()) {
   return new Date(now.getTime() - d * DAY_MS).toISOString();
 }
 
+/**
+ * Cheap preview for the init import offer — how many local transcripts (≈ sessions)
+ * fall within the window and their date span, by file mtime (no file reads). Lets
+ * init show "Found N sessions from A to B" before asking to import.
+ * @returns {{ count: number, earliest: string|null, latest: string|null }}
+ */
+export function previewClaudeCode({ days = 90, dir = PROJECTS_DIR } = {}, now = new Date()) {
+  if (!existsSync(dir)) return { count: 0, earliest: null, latest: null };
+  const cutoffMs = Date.parse(resolveCutoff({ days }, now));
+  let count = 0, min = Infinity, max = -Infinity;
+  for (const f of walkJsonl(dir)) {
+    let m;
+    try { m = statSync(f).mtimeMs; } catch { continue; }
+    if (m < cutoffMs) continue;
+    count++;
+    if (m < min) min = m;
+    if (m > max) max = m;
+  }
+  return {
+    count,
+    earliest: count ? new Date(min).toISOString() : null,
+    latest: count ? new Date(max).toISOString() : null,
+  };
+}
+
 /**
  * Resolve the INCLUSIVE lower bound from `--from` (or null when open-ended).
  * Unlike the file-level `cutoff` (which only decides whether to read a file),

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');
@@ -593,6 +596,27 @@ export default async function init() {
     info('  Tracking: all projects');
   }
 
+  // Loud guard: a narrow `projects` filter that does NOT cover this workspace silently
+  // drops ALL capture (project_filter) — hooks look configured but record nothing. This
+  // bites when init inherits a stale `projects` from an old config (a leftover test path).
+  // Warn against the cwd (the workspace init is being run from).
+  if (projects) {
+    const cwd = resolve(process.cwd());
+    const norm = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const cwdN = norm(cwd);
+    const covered = projects.split(',').map(norm).some(m => m && (cwdN === m || cwdN.startsWith(m + '/')));
+    if (!covered) {
+      blank();
+      warn(`  ⚠ Projects filter does not include this workspace — events from here will be DROPPED.`);
+      warn(`    filter: ${projects}`);
+      warn(`    here:   ${cwd}`);
+      info(`    Capture will look configured but record nothing. Fix: re-run with \`--projects all\``);
+      info(`    (track everything), or edit ~/.ai-lens/config.json and remove/adjust "projects".`);
+      info(`    (Ignore if you deliberately track only other paths.)`);
+      blank();
+    }
+  }
+
   // Build new config in memory — saved after "Proceed?" confirmation
   const newConfig = { ...currentConfig, serverUrl, projects };
 
@@ -601,34 +625,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 +996,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);
@@ -1273,10 +1277,28 @@ async function maybeOfferImportHistory(flags) {
   if (flags.noImport) return;
   if (!existsSync(join(homedir(), '.claude', 'projects'))) return;
 
+  // Preview so the offer isn't a blind yes/no: count of local transcripts (≈ sessions)
+  // and their date span within the 90d window (cheap mtime scan, no file reads).
+  let preview = null;
+  try {
+    const mod = await import('./import/claude-code.js');
+    if (mod.previewClaudeCode) preview = mod.previewClaudeCode({ days: 90 });
+  } catch { /* preview is best-effort */ }
+  if (preview && preview.count === 0) {
+    info('  No local Claude Code history in the last 90 days — nothing to import.');
+    return;
+  }
+  const day = (iso) => (iso || '').slice(0, 10);
+  const previewLine = preview
+    ? `Found ${preview.count} Claude Code session${preview.count === 1 ? '' : 's'} from ${day(preview.earliest)} to ${day(preview.latest)} (last 90d).`
+    : 'Local Claude Code history found.';
+
   let run = flags.importHistory || flags.yes;
-  if (!run) {
+  if (run) {
+    info(`  ${previewLine}`);
+  } else {
     try {
-      const answer = (await ask('Import your local Claude Code history now? (Y/n) ')).toLowerCase();
+      const answer = (await ask(`${previewLine} Import now? (Y/n) `)).toLowerCase();
       run = answer === '' || answer === 'y' || answer === 'yes';
     } catch { run = false; }
   }

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.93",
+  "version": "0.8.95",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {