ai-lens 0.8.98 → 0.8.99

package/.commithash

@@ -1 +1 @@
-5d8b7f1
+b23bf01

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 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.99 — 2026-06-17
+- fix: Cursor hooks on Windows no longer flash a console window on every event. The flash was `node.exe` (a console app) allocating its own window when Cursor runs the hook; a new windowless launcher (`cursor-ai-lens-hook.ps1`) starts node with no window and forwards the event to it, so capture keeps working with no flash. Existing Cursor installs migrate automatically on the next `ai-lens init` / `/setup`. macOS/Linux and Claude Code are unchanged
+
 ## 0.8.98 — 2026-06-17
 - fix: Cursor hooks on Windows no longer use the `conhost.exe --headless` wrapper — it made Cursor report a "JSON Parse Error" on every hook (conhost emits terminal escape codes that Cursor tries to parse as the hook's output) and broke capture. Cursor returns to the plain working form; machines that briefly got the conhost'd Cursor hook are auto-downgraded on the next `ai-lens init`/`/setup`. Claude Code keeps the windowless wrapper (it tolerates the output). The minor Cursor console flash on Windows is upstream Cursor behaviour
 

package/cli/hooks.js

@@ -369,24 +369,35 @@ export function cursorCaptureCommand(opts = {}) {
   const { useTilde = false, customPath = null } = opts;
   const ctx = opts.ctx ?? resolveDefaultCtx();
   const platform = ctx.platform ?? process.platform;
-  // PowerShell doesn't expand ~ inside double-quoted strings — fall back to absolute.
-  const effectiveUseTilde = platform === 'win32' ? false : useTilde;
-  // Cursor on Windows runs hooks via PowerShell, so use the PS-compatible shell
-  // hint when building the underlying command (avoids the cmd.exe `call` prefix
-  // which PowerShell doesn't understand).
-  const shell = platform === 'win32' ? 'powershell' : null;
-  // NOTE: Cursor deliberately does NOT get the `conhost.exe --headless` windowless
-  // wrapper (unlike Claude Code). conhost runs a ConPTY and emits VT escape sequences
-  // (e.g. ESC[?9001h win32-input-mode) onto the hook's output stream, and Cursor
-  // parses a hook's stdout as JSON → "JSON Parse Error … is not valid JSON", which
-  // breaks the hook. Claude Code tolerates non-JSON hook stdout, so it keeps conhost.
-  // The residual Cursor console flash on Windows is upstream (how Cursor spawns the
-  // hook process) and is the lesser evil vs a broken hook. (ADR 0003 §3.2 deferred
-  // Cursor+conhost as unverified; verified incompatible — reverted here.)
-  const cmd = customPath != null
-    ? captureCommand({ rawPath: true, customPath, ctx, shell })
-    : captureCommand({ useTilde: effectiveUseTilde, ctx, shell });
-  return platform === 'win32' ? `& ${cmd}` : cmd;
+
+  if (platform === 'win32') {
+    // Windows: route node through the windowless launcher cursor-ai-lens-hook.ps1.
+    // Cursor spawns hooks via a hidden powershell and pipes the payload through the
+    // PS pipeline ($input); launching node.exe directly there pops a console window
+    // on every event (node is console-subsystem, parent powershell has no console).
+    // conhost.exe --headless hides the window but corrupts Cursor's JSON-parse of hook
+    // stdout with ConPTY VT codes (verified). The launcher starts node with
+    // CreateNoWindow=$true and forwards $input → node stdin: no window, clean stdout.
+    // Form: & "<...>/cursor-ai-lens-hook.ps1" "<absNode>" "<capture.js>"
+    const clientDir = (ctx.clientDir ?? CLIENT_INSTALL_DIR).replace(/\\/g, '/');
+    const nodeResolution = ctx.nodeResolution;
+    if (!nodeResolution || !nodeResolution.path) {
+      throw new Error('cursorCaptureCommand: nodeResolution is required');
+    }
+    const node = nodeResolution.path.replace(/\\/g, '/');
+    const capturePath = (customPath ?? `${clientDir}/capture.js`).replace(/\\/g, '/');
+    // The launcher ships next to capture.js (installed client dir, or the repo client
+    // dir for --use-repo-path) — derive its path from capturePath's directory.
+    const launcher = capturePath.replace(/[^/]*$/, 'cursor-ai-lens-hook.ps1');
+    const q = (s) => `"${s.replace(/"/g, '""')}"`;
+    return `& ${q(launcher)} ${q(node)} ${q(capturePath)}`;
+  }
+
+  // macOS / Linux: direct node, unchanged. (No console-window concept; conhost/launcher
+  // are Windows-only.)
+  return customPath != null
+    ? captureCommand({ rawPath: true, customPath, ctx })
+    : captureCommand({ useTilde, ctx });
 }
 
 // ---------------------------------------------------------------------------
@@ -401,7 +412,10 @@ export function cursorCaptureCommand(opts = {}) {
  * every hook with ERR_MODULE_NOT_FOUND on a missing sibling import.
  */
 export function listClientFiles(sourceDir = join(__dirname, '..', 'client')) {
-  return readdirSync(sourceDir).filter(f => f.endsWith('.js')).sort();
+  // .js — all client modules (sibling imports must all be present).
+  // .ps1 — the Windows windowless Cursor hook launcher (cursor-ai-lens-hook.ps1);
+  // a missing launcher would break every Cursor hook on Windows, so ship it too.
+  return readdirSync(sourceDir).filter(f => f.endsWith('.js') || f.endsWith('.ps1')).sort();
 }
 
 /**
@@ -796,6 +810,17 @@ export function _parseHookCommand(cmd) {
     return { kind: 'launcher', path: first, prefix, nodePrefix: null };
   }
 
+  // Windows windowless Cursor launcher: & "<...>/cursor-ai-lens-hook.ps1" "<node>" "<capture.js>".
+  // node is the SECOND token (the launcher's first arg); capture.js is the third.
+  if (first.endsWith('cursor-ai-lens-hook.ps1')) {
+    return {
+      kind: 'cursorWindowless',
+      path: first,
+      prefix,
+      nodePrefix: tokens.length >= 2 ? normalizePath(tokens[1]) : null,
+    };
+  }
+
   if (tokens.length >= 2) {
     const second = normalizePath(tokens[1]);
     if (second.endsWith('capture.js')) {
@@ -853,10 +878,14 @@ function normalizePath(p) {
 // still classifies run.* as ai-lens so `remove`/strip cleans up stale launchers.)
 export function isGuiSafeHookCommand(cmd) {
   if (!isAiLensCommand(cmd).isAiLens) return false;
-  // 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.
+  // GUI-safe when an ABSOLUTE node path is baked in — either the direct capture.js form
+  // (`<absNode> capture.js`) or the Windows windowless launcher form
+  // (`& "<...>/cursor-ai-lens-hook.ps1" "<absNode>" "<capture.js>"`), where node is the
+  // launcher's first arg. Bare `node` / `/usr/bin/env node` are NOT GUI-safe (depend on
+  // PATH, which GUI Cursor/Claude often lack). The old run.sh/run.cmd launcher is NOT
+  // recognised here (ADR 0003) — it stays `outdated` so init migrates it.
   const p = _parseHookCommand(cmd);
-  if (p.kind === 'captureJs' && p.nodePrefix) {
+  if ((p.kind === 'captureJs' || p.kind === 'cursorWindowless') && p.nodePrefix) {
     const np = p.nodePrefix;
     const isAbsolute = np.startsWith('/') || /^[a-zA-Z]:\//.test(np);
     const isEnvShim = np === '/usr/bin/env' || np.endsWith('/env');
@@ -1093,28 +1122,32 @@ function isCurrentAiLensHook(entry, expected, opts = {}) {
   // $CLAUDE_PROJECT_DIR/%CLAUDE_PROJECT_DIR% hook written for the OTHER OS won't
   // expand on this platform, so flag it outdated to let init rewrite it.
   //
-  // Windowless exception (same allowPlatformRewrite gate): flag a hook outdated when
-  // its stored `conhost.exe --headless` wrapper DISAGREES with the freshly regenerated
-  // `expected` command — in EITHER direction — so init re-syncs it:
-  //   - expected has conhost, stored doesn't → ADD it (Claude on conhost-capable
-  //     Windows that predates the windowless form);
-  //   - expected has NO conhost, stored DOES → REMOVE it (Cursor: conhost is
-  //     incompatible — its ConPTY VT output breaks Cursor's JSON parse of hook stdout
-  //     — so we downgrade machines that got the short-lived conhost'd Cursor form).
-  // We compare ONLY the windowless dimension (not the whole command), so legitimate
-  // path/node/install-mode variation never false-flags. `expected` already bakes in
-  // tool+platform+conhost-support (makeClaudeHookDefs passes windowless:true;
-  // makeCursorHookDefs and makeCodexHookDefs do NOT), so this self-scopes: Codex,
-  // Cursor, macOS, and old Windows produce a non-conhost `expected`, and only Claude
-  // on conhost-capable Windows produces a conhost `expected`. Committed (tracked)
-  // files are exempt via allowPlatformRewrite — they carry one OS-agnostic syntax
-  // and can't bake a Windows-only wrapper; the per-machine overlay provides it.
+  // Windows-wrapper exception (same allowPlatformRewrite gate): flag a hook outdated
+  // when its stored windowless wrapper DISAGREES with the freshly regenerated `expected`
+  // command, so init re-syncs it. We compare ONLY the wrapper kind — conhost vs the
+  // Cursor `cursor-ai-lens-hook.ps1` launcher vs plain — never the whole command, so
+  // legitimate path/node/install-mode variation never false-flags. `expected` already
+  // bakes in tool+platform: Claude on conhost-capable Windows → `conhost`; Cursor on
+  // Windows → `cursorPs1` (the windowless launcher; conhost corrupts Cursor's stdout
+  // JSON-parse); Codex, macOS, and old Windows → `plain`. So this self-scopes per tool:
+  //   - Claude: stored plain → outdated (add conhost); stored conhost → current.
+  //   - Cursor: stored plain/conhost → outdated (migrate to the .ps1 launcher); ps1 → current.
+  //   - Codex/macOS: expected plain, stored plain → current (untouched).
+  // Committed (tracked) files are exempt via allowPlatformRewrite — they carry one
+  // OS-agnostic syntax and can't bake a Windows-only wrapper; the per-machine overlay
+  // (or the local .cursor/hooks.json) provides it.
   const { platform = process.platform, allowPlatformRewrite = false } = opts;
   const expectedCmd = expected?.command ?? expected?.hooks?.[0]?.command ?? '';
-  const expectedWindowless = isConhostHeadlessCommand(expectedCmd);
+  const wrapperKind = (c) => {
+    const s = String(c || '');
+    if (isConhostHeadlessCommand(s)) return 'conhost';
+    if (/cursor-ai-lens-hook\.ps1/i.test(s)) return 'cursorPs1';
+    return 'plain';
+  };
+  const expectedWrapper = wrapperKind(expectedCmd);
   const ok = (cmd) => isAcceptableHookCommand(cmd)
     && !(allowPlatformRewrite && isWrongPlatformProjectDirCommand(cmd, platform))
-    && !(allowPlatformRewrite && expectedWindowless !== isConhostHeadlessCommand(cmd));
+    && !(allowPlatformRewrite && wrapperKind(cmd) !== expectedWrapper);
   // Flat format (Cursor): single command per entry.
   if (entry?.command != null) {
     return ok(entry.command);

package/cli/status.js

@@ -150,8 +150,28 @@ function validateHookCommandPaths(tool) {
 
   const issues = [];
   const launcherMatch = command.match(/["']([^"']*run\.(?:sh|cmd))["']|(\S*run\.(?:sh|cmd))/);
-
-  if (launcherMatch) {
+  const ps1Match = command.match(/["']([^"']*cursor-ai-lens-hook\.ps1)["']|(\S*cursor-ai-lens-hook\.ps1)/);
+
+  if (ps1Match) {
+    // Windows windowless Cursor launcher: & "<...>/cursor-ai-lens-hook.ps1" "<node>" "<capture.js>".
+    // Validate the launcher, the node arg (2nd token), and capture.js (3rd token) all exist.
+    const ps1Path = expandTilde(ps1Match[1] || ps1Match[2]);
+    if (!existsSync(ps1Path)) issues.push(`Cursor hook launcher not found at: ${ps1Path}`);
+    const capMatch = command.match(/["']([^"']*capture\.js)["']|(\S*capture\.js)/);
+    if (capMatch) {
+      const capturePath = expandTilde(capMatch[1] || capMatch[2]);
+      if (!existsSync(capturePath)) issues.push(`capture.js not found at: ${capturePath}`);
+    }
+    // node = the launcher's first argument (token right after the .ps1 path)
+    const nodeArg = command.replace(/^& /, '')
+      .match(/cursor-ai-lens-hook\.ps1["']?\s+(?:["']([^"']+)["']|(\S+))/);
+    if (nodeArg) {
+      const nodePath = expandTilde(nodeArg[1] || nodeArg[2]);
+      if (nodePath !== 'node' && !existsSync(nodePath)) {
+        issues.push(`node not found at: ${nodePath} — re-run \`ai-lens init\` to re-resolve node`);
+      }
+    }
+  } else if (launcherMatch) {
     // Launcher form (0.8.68+): one path, no separate node validation — the node binary
     // baked into the launcher is invoked from inside the script, not the hook command.
     const launcherPath = expandTilde(launcherMatch[1] || launcherMatch[2]);

package/client/cursor-ai-lens-hook.ps1

@@ -0,0 +1,32 @@
+# AI Lens — Cursor windowless hook launcher (Windows only).
+#
+# Why this exists: Cursor runs a hook by spawning a (hidden) powershell that pipes the
+# event payload through the PowerShell pipeline ($input) — e.g.
+#     Get-Content <tmp>.json -Raw | & { $input | & "<this.ps1>" "<node>" "<capture.js>" }
+# Launching node.exe directly there pops a console window on every event (node is a
+# console-subsystem binary and the parent powershell has no console). conhost.exe
+# --headless hides the window but emits ConPTY VT escape codes onto stdout, which Cursor
+# then fails to JSON-parse. This launcher instead starts node with CreateNoWindow=$true
+# (no window) while forwarding the payload to node's stdin — so capture still works and
+# nothing extra is written to stdout.
+#
+# Args: $args[0] = absolute node path, $args[1] = capture.js path.
+# Payload arrives on the PowerShell pipeline as $input (NOT [Console]::In, which is empty
+# here because the data is an in-process pipeline object, not the process's OS stdin).
+
+$ErrorActionPreference = 'Stop'
+$node = $args[0]
+$capture = $args[1]
+$payload = @($input) -join "`n"
+
+$psi = New-Object System.Diagnostics.ProcessStartInfo
+$psi.FileName = $node
+$psi.Arguments = '"' + $capture + '"'
+$psi.UseShellExecute = $false
+$psi.CreateNoWindow = $true
+$psi.RedirectStandardInput = $true
+
+$proc = [System.Diagnostics.Process]::Start($psi)
+$proc.StandardInput.Write($payload)
+$proc.StandardInput.Close()
+$proc.WaitForExit()

package/package.json

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