ai-lens 0.8.97 → 0.8.99

package/.commithash

@@ -1 +1 @@
-13ab9a5
+b23bf01

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.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
+
 ## 0.8.97 — 2026-06-17
 - fix: `ai-lens init` no longer leaves an invalid `{ "version": 1 }` (no hooks) in `~/.cursor/hooks.json` when migrating to project hooks — Cursor flagged such a file as an error and stopped running ALL hooks, silently killing capture even when project hooks were correct. init now deletes the empty file, and repairs machines already left in this state on the next run
 

package/cli/hooks.js

@@ -369,20 +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;
-  // 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({ rawPath: true, customPath, windowless: true, ctx, shell })
-    : captureCommand({ useTilde: effectiveUseTilde, windowless: true, 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 });
 }
 
 // ---------------------------------------------------------------------------
@@ -397,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();
 }
 
 /**
@@ -792,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')) {
@@ -849,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');
@@ -1089,25 +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): when the freshly
-  // regenerated `expected` command carries the `conhost.exe --headless` wrapper
-  // (Cursor/Claude on conhost-capable Windows) but the stored command does NOT,
-  // flag it outdated so init upgrades it — otherwise a pre-conhost install stays
-  // `current` forever and keeps flashing a console window on every event. 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 (makeCursorHookDefs/makeClaudeHookDefs pass
-  // windowless:true; makeCodexHookDefs does not), so this self-scopes: Codex,
-  // macOS, and old Windows produce a non-conhost `expected` and never trip 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 provides the windowless path.
+  // 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.97",
+  "version": "0.8.99",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {