fix(doctor): skip shell assignments, probe hook documents before reading, fold Windows path case

- executedPath ignores leading NAME=value words before the command word
- readJson and the pinned static validator stat documents first so a FIFO
  at hooks/hooks.json or a manifest-declared hooks path cannot block Doctor
- AB7322 containment folds case on win32 (platform threaded from DoctorOptions)
- tests: assignment-prefixed duplicates/stale scripts, FIFO documents at both
  paths, mixed-case duplicate on win32 vs linux

Author: ScriptedAlchemy

docs/diagnostics.md

@@ -712,8 +712,8 @@ that registration statically and never writes `~/.cursor/hooks.json`.
 
 | Code | Severity | Meaning | Recovery |
 | --- | --- | --- | --- |
-| `AB7321` | info / error | Info: an installed `.cursor-plugin/plugin.json` plugin registers plugin-scoped hooks (events and command count listed) and the script each command executes — `${CURSOR_PLUGIN_ROOT}/…` or any relative path, including an interpreter's entry operand — exists under the plugin root (`hooks.state = registered`). Error: the declared hooks file is missing (`missing`), is not a `{ version, hooks: { <event>: [{ command }] } }` document, or an executed script is absent (`stale`). | Reinstall the plugin from a bundle whose emitted hooks document and scripts are intact. |
-| `AB7322` | warning | `~/.cursor/hooks.json` registers a command that points into an installed plugin directory (Cursor would deliver that hook twice), or the file is not a valid hooks document. | Remove the plugin-pointing entries or repair the file; manifest registration alone is sufficient. |
+| `AB7321` | info / error | Info: an installed `.cursor-plugin/plugin.json` plugin registers plugin-scoped hooks (events and command count listed) and the script each command executes — `${CURSOR_PLUGIN_ROOT}/…` or any relative path, including an interpreter's entry operand — exists under the plugin root (`hooks.state = registered`). Error: the declared hooks file is missing (`missing`), is not a regular file or not a `{ version, hooks: { <event>: [{ command }] } }` document, or an executed script is absent (`stale`). Documents and scripts are probed with `stat` before any read, so a FIFO cannot stall Doctor. | Reinstall the plugin from a bundle whose emitted hooks document and scripts are intact. |
+| `AB7322` | warning | `~/.cursor/hooks.json` registers a command whose executed file (after leading `NAME=value` assignments, `env`, and interpreter options) points into an installed plugin directory — compared on path-component boundaries, case-folded on Windows — so Cursor would deliver that hook twice; or the file is not a valid hooks document. | Remove the plugin-pointing entries or repair the file; manifest registration alone is sufficient. |
 | `AB7323` | info / warning / error | A staged marketplace repository under `~/.cursor/agent-bundle/marketplaces/<name>` (from `install cursor --mode marketplace`) is imported by Cursor (matching plugin under `~/.cursor/plugins/cache`; info, `registered`), still awaiting the Customize "Add Plugins from Local Repository" step (warning, `unregistered`), or incomplete (error, `corrupt`: manifests missing or failing the pinned schemas, no resolvable Git HEAD, HEAD naming a commit object that does not exist, or a working tree that differs from committed HEAD — verified read-only through `git cat-file -e` / `git --no-optional-locks status` when `git` is available). | Complete the Customize import, use `--mode local`, or remove the staged directory and rerun the installer. |
 
 The installer side reuses the `AB700x` codes: `AB7002` when `git` is missing

packages/agent-bundle/src/host-contracts/cursor-plugin-validation.ts

@@ -1,4 +1,4 @@
-import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 
 import { Ajv, type ErrorObject } from 'ajv/dist/ajv.js';
@@ -224,6 +224,8 @@ const readDocuments = async (
     const file = join(pluginDirectory, contract.path);
     let source: string;
     try {
+      // `stat` first: `readFile` on a FIFO or device would block until a writer appears.
+      if (!(await stat(file)).isFile()) throw new Error(`${contract.path} is not a regular file`);
       source = await readFile(file, 'utf8');
     } catch (error) {
       if (isErrno(error, 'ENOENT')) {

packages/agent-bundle/src/install/cursor-hooks-registration.ts

@@ -155,11 +155,13 @@ const valueOptions = new Set([
 
 const powerShell = new Set(['powershell', 'pwsh']);
 
+const shellAssignment = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+
 /** `env [NAME=VALUE]... [OPTION]... COMMAND [ARG]...`: strips the assignments and options ahead of COMMAND. */
 const unwrapEnv = (operands: readonly string[]): readonly string[] | undefined => {
   for (let index = 0; index < operands.length; index += 1) {
     const token = operands[index] ?? '';
-    if (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(token)) continue;
+    if (shellAssignment.test(token)) continue;
     if (token === '-u' || token === '--unset' || token === '-C' || token === '--chdir') {
       index += 1;
       continue;
@@ -184,9 +186,11 @@ interface ExecutedPath {
  * (`node -e`, `sh -c`, `python -m`) or has no operand. Other arguments (`--output ./state/result.json`) are
  * runtime inputs/outputs, never the executed file.
  */
-const executedPath = (tokens: readonly string[]): ExecutedPath | undefined => {
+const executedPath = (words: readonly string[]): ExecutedPath | undefined => {
+  // Leading `NAME=value` words are shell assignments (`NODE_ENV=production node ./x.mjs`), not the command.
+  const tokens = words.slice(words.findIndex((word) => !shellAssignment.test(word)));
   const [executable, ...operands] = tokens;
-  if (executable === undefined) return undefined;
+  if (executable === undefined || shellAssignment.test(executable)) return undefined;
   // Interpreter basenames are matched case-insensitively (`PowerShell.EXE`, `Node.exe` on Windows).
   const interpreter = executable.replace(/^.*[\\/]/u, '').replace(/\.exe$/iu, '').toLowerCase();
   if (interpreter === 'env') {
@@ -261,18 +265,27 @@ const directory = async (path: string): Promise<boolean> => {
   }
 };
 
+/**
+ * Read a JSON document only after `stat` confirms a regular file: opening a FIFO (or a device) with `readFile`
+ * would block Doctor until a writer appears. Anything that is not a regular file reads as `invalid`.
+ */
 const readJson = async (path: string): Promise<{ readonly value?: unknown; readonly error?: 'missing' | 'invalid' }> => {
   try {
+    if (!(await stat(path)).isFile()) return { error: 'invalid' };
     return { value: JSON.parse(await readFile(path, 'utf8')) as unknown };
   } catch (error) {
     if (isErrno(error, 'ENOENT')) return { error: 'missing' };
     return { error: 'invalid' };
   }
 };
 
+/** Windows paths are case-insensitive, so containment checks there fold case (Cursor itself runs the same file). */
+const caseInsensitivePaths = process.platform === 'win32';
+
 const userHookDuplicates = async (
   home: string,
   pluginDirectory: string,
+  foldCase: boolean,
 ): Promise<{ readonly diagnostics: readonly Diagnostic[]; readonly duplicates: readonly string[] }> => {
   const userHooksPath = join(home, '.cursor', 'hooks.json');
   const document = await readJson(userHooksPath);
@@ -289,11 +302,15 @@ const userHookDuplicates = async (
       duplicates: Object.freeze([]),
     };
   }
+  const fold = (path: string): string => (foldCase ? path.toLowerCase() : path);
   const resolvedPlugin = resolve(pluginDirectory);
+  const foldedPlugin = fold(resolvedPlugin);
   // User hooks run from ~/.cursor (https://cursor.com/docs/hooks), so relative command tokens resolve there.
   const userHookCwd = join(home, '.cursor');
-  const insidePlugin = (candidate: string): boolean =>
-    candidate === resolvedPlugin || candidate.startsWith(`${resolvedPlugin}/`) || candidate.startsWith(`${resolvedPlugin}\\`);
+  const insidePlugin = (resolvedCandidate: string): boolean => {
+    const candidate = fold(resolvedCandidate);
+    return candidate === foldedPlugin || candidate.startsWith(`${foldedPlugin}/`) || candidate.startsWith(`${foldedPlugin}\\`);
+  };
   // Only the file the user hook executes counts: a plugin-local path passed as data (`--output
   // ./plugins/local/foo/state.json`) does not deliver that plugin's hook. `insidePlugin` matches on a path
   // component boundary so `plugins/local/foo` does not claim hooks aimed at `plugins/local/foo-tools`.
@@ -329,6 +346,7 @@ const userHookDuplicates = async (
 export const inspectCursorPluginHooks = async (
   pluginDirectory: string,
   home: string,
+  options: { readonly caseInsensitivePaths?: boolean } = {},
 ): Promise<{ readonly diagnostics: readonly Diagnostic[]; readonly registration: CursorHooksRegistration }> => {
   const none: CursorHooksRegistration = Object.freeze({ commands: 0, duplicates: Object.freeze([]), events: Object.freeze([]), state: 'none' });
   const manifest = await readJson(join(pluginDirectory, '.cursor-plugin/plugin.json'));
@@ -376,7 +394,7 @@ export const inspectCursorPluginHooks = async (
       if (!(await regularFile(script))) missingScripts.push(script);
     }
   }
-  const duplicates = await userHookDuplicates(home, pluginDirectory);
+  const duplicates = await userHookDuplicates(home, pluginDirectory, options.caseInsensitivePaths ?? caseInsensitivePaths);
   const registration: CursorHooksRegistration = Object.freeze({
     commands: parsed.commands.length,
     duplicates: duplicates.duplicates,

packages/agent-bundle/src/install/doctor.ts

@@ -608,6 +608,7 @@ const cursorInventory = async (
   home: string,
   available: boolean,
   git: CursorStagingGit,
+  platform: NodeJS.Platform,
 ): Promise<{ readonly diagnostics: readonly Diagnostic[]; readonly inventory: DoctorInventory }> => {
   if (!available) return { diagnostics: Object.freeze([]), inventory: freezeInventory('skipped') };
   const installRoot = join(home, '.cursor', 'plugins', 'local');
@@ -730,7 +731,7 @@ const cursorInventory = async (
     const durableState = await inspectDurableState(path, 'cursor');
     if (durableState !== undefined) diagnostics.push(...durableState.diagnostics);
     const hooks = manifest.manifest === cursorManifestCandidates[0]
-      ? await inspectCursorPluginHooks(path, home)
+      ? await inspectCursorPluginHooks(path, home, { caseInsensitivePaths: platform === 'win32' })
       : undefined;
     if (hooks !== undefined) diagnostics.push(...hooks.diagnostics);
     findings.push({
@@ -1409,7 +1410,7 @@ const doctorHost = async (
     : await probeBinary(host, home, run);
   const git = stagingGit(run);
   const inventoried = host === 'cursor'
-    ? await cursorInventory(home, probed.probe.status === 'available', git)
+    ? await cursorInventory(home, probed.probe.status === 'available', git, options.platform ?? process.platform)
     : unknownInventory(host);
   const diagnostics = [...probed.diagnostics, ...inventoried.diagnostics];
   let bundle: DoctorHostReport['bundle'];

packages/agent-bundle/tests/doctor.test.ts

@@ -1441,7 +1441,8 @@ const writeHookedCursorPlugin = async (pluginRoot: string, version = '1.2.3'): P
 it('proves plugin-scoped Cursor hook registration and flags stale, missing, and duplicate delivery', async () => {
   const fixture = await temporaryDoctor();
   const pluginRoot = join(fixture.home, '.cursor', 'plugins', 'local', 'hooked-fixture');
-  const doctor = () => runDoctor({ endpointDirectory: fixture.endpointDirectory, home: fixture.home, hosts: ['cursor'] });
+  const doctor = (options: { readonly platform?: NodeJS.Platform } = {}) =>
+    runDoctor({ ...options, endpointDirectory: fixture.endpointDirectory, home: fixture.home, hosts: ['cursor'] });
   const hookDiagnostics = (report: DoctorReport) => report.diagnostics.filter((entry) => entry.code === 'AB7321' || entry.code === 'AB7322');
   try {
     await writeHookedCursorPlugin(pluginRoot);
@@ -1523,6 +1524,24 @@ it('proves plugin-scoped Cursor hook registration and flags stale, missing, and
     expect(hostReport(await doctor(), 'cursor').inventory.findings[0]?.hooks).toMatchObject({
       duplicates: ['node .\\plugins\\local\\hooked-fixture\\hooks\\stop.mjs'],
     });
+    // A leading shell assignment is not the command word.
+    await writeJson(join(fixture.home, '.cursor', 'hooks.json'), {
+      hooks: { stop: [{ command: 'NODE_ENV=production node ./plugins/local/hooked-fixture/hooks/stop.mjs' }] },
+      version: 1,
+    });
+    expect(hostReport(await doctor(), 'cursor').inventory.findings[0]?.hooks).toMatchObject({
+      duplicates: ['NODE_ENV=production node ./plugins/local/hooked-fixture/hooks/stop.mjs'],
+    });
+    // On Windows the filesystem is case-insensitive, so a differently cased spelling still runs the plugin's file.
+    const upperCased = `node ${join(pluginRoot, 'hooks/before-tool.mjs').toUpperCase()}`;
+    await writeJson(join(fixture.home, '.cursor', 'hooks.json'), {
+      hooks: { preToolUse: [{ command: upperCased }] },
+      version: 1,
+    });
+    expect(hostReport(await doctor({ platform: 'win32' }), 'cursor').inventory.findings[0]?.hooks).toMatchObject({
+      duplicates: [upperCased],
+    });
+    expect(hostReport(await doctor({ platform: 'linux' }), 'cursor').inventory.findings[0]?.hooks).toMatchObject({ duplicates: [] });
     // A plugin-local path passed as data to an unrelated script is not duplicate delivery.
     await writeJson(join(fixture.home, '.cursor', 'hooks.json'), {
       hooks: { stop: [{ command: 'node ./hooks/audit.mjs --output ./plugins/local/hooked-fixture/state/result.json' }] },
@@ -1596,6 +1615,8 @@ it('proves plugin-scoped Cursor hook registration and flags stale, missing, and
       'pwsh -NoProfile -File hooks/gone.mjs',
       'PowerShell.EXE -NoProfile -EXECUTIONPOLICY Bypass -File hooks/gone.mjs',
       '/usr/bin/env node ./hooks/gone.mjs',
+      'NODE_ENV=production node hooks/gone.mjs',
+      'A=1 B=2 /usr/bin/env node ./hooks/gone.mjs',
       'bun run "${CURSOR_PLUGIN_ROOT}/hooks/gone.mjs"',
       'deno run -A ./hooks/gone.mjs',
       'env FOO=1 -u BAR node hooks/gone.mjs',
@@ -1638,6 +1659,31 @@ it('proves plugin-scoped Cursor hook registration and flags stale, missing, and
     expect(hostReport(missing, 'cursor').inventory.findings[0]?.hooks).toMatchObject({ commands: 0, events: [], state: 'missing' });
     expect(hookDiagnostics(missing)).toEqual([expect.objectContaining({ code: 'AB7321', severity: 'error' })]);
     expect(hookDiagnostics(missing)[0]?.message).toContain('is missing');
+
+    // A hooks document that is not a regular file (a FIFO would block `readFile` forever) is stale, not a hang —
+    // both at the pinned `hooks/hooks.json` path and at a manifest-declared custom path.
+    if (process.platform !== 'win32') {
+      const mkfifo = (path: string) => new Promise<void>((resolvePromise, reject) => {
+        const child = spawn('mkfifo', [path], { stdio: 'ignore' });
+        child.on('error', reject);
+        child.on('exit', (code) => (code === 0 ? resolvePromise() : reject(new Error(`mkfifo exited ${code}`))));
+      });
+      await mkfifo(join(pluginRoot, 'hooks', 'hooks.json'));
+      const fifo = await doctor();
+      expect(hostReport(fifo, 'cursor').inventory.findings[0]?.hooks).toMatchObject({ commands: 0, state: 'stale' });
+      expect(hookDiagnostics(fifo)).toEqual([expect.objectContaining({ code: 'AB7321', severity: 'error' })]);
+      await rm(join(pluginRoot, 'hooks', 'hooks.json'));
+      await writeJson(join(pluginRoot, '.cursor-plugin/plugin.json'), {
+        description: 'Hooked doctor fixture.',
+        hooks: 'custom-hooks.json',
+        name: 'hooked-fixture',
+        version: '1.2.3',
+      });
+      await mkfifo(join(pluginRoot, 'custom-hooks.json'));
+      const customFifo = await doctor();
+      expect(hostReport(customFifo, 'cursor').inventory.findings[0]?.hooks).toMatchObject({ commands: 0, state: 'stale' });
+      expect(hookDiagnostics(customFifo)).toEqual([expect.objectContaining({ code: 'AB7321', severity: 'error' })]);
+    }
   } finally {
     await fixture.cleanup();
   }