fix(windows): pass windowsHide:true to every child_process spawn-family call (#1794)

* fix(hooks): pass windowsHide:true to every spawnSync to suppress flashing console windows on Windows

On Windows, every PostToolUse and Stop event from Claude Code (and
the Cursor integration variant) cold-spawns ``node`` / ``npx.cmd`` /
``git`` / ``lsof`` through ``child_process.spawnSync``. Without
``windowsHide: true`` in the options, Node's child_process module
asks ``CreateProcess`` to use ``STARTF_USESHOWWINDOW`` with
``SW_SHOWDEFAULT``, and a black console window flashes onto the
user's desktop for the duration of the call. Under active
editor / agent use this means a near-continuous stream of pop-up
windows — unusable in practice (reported live on a Windows 11
workstation running the gitnexus Claude plugin against an active
project; the flashes stack on the taskbar and steal focus from the
editor).

The Node fix is one option flag per spawnSync:

    spawnSync(cmd, args, {
        encoding: 'utf-8',
        timeout,
        cwd,
        stdio: ['pipe', 'pipe', 'pipe'],
        windowsHide: true,            // <-- new
    });

``windowsHide`` is a no-op on macOS/Linux (Node docs: "Hide the
subprocess console window that would normally be created on Windows
systems"), so the patch is platform-neutral and zero-risk on the
other two majors.

This commit touches every ``spawnSync`` call in the three sources
that ship the hook layer:

* gitnexus/hooks/claude/gitnexus-hook.cjs            (4 sites)
* gitnexus/hooks/claude/hook-db-lock-probe.cjs       (3 sites)
* gitnexus-claude-plugin/hooks/gitnexus-hook.js      (6 sites)
* gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs (3 sites)
* gitnexus-cursor-integration/hooks/gitnexus-hook.cjs (3 sites)

Total: 19 spawn sites guarded. ``hook-lock.cjs`` / ``hook-lock.js``
don't spawn subprocesses; nothing else in the hooks/ dirs touches
``child_process``.

Verified on Windows 10 22H2 / Node 22.21 / gitnexus 1.6.5 by
installing the locally-built tarball and running an active Claude
Code session against a large mixed-language repo — no console
window appears for any hook fire (pre-fix: ~2-3 visible flashes per
edit). No behavioural change on Linux/macOS hosts.

* test(hooks): regression — every hook spawnSync paired with windowsHide:true

Source-level assertion that every ``spawnSync`` invocation in the
hook layer has a matching ``windowsHide: true`` in its options
object. Without the flag, Node's child_process module asks
CreateProcess to use STARTF_USESHOWWINDOW with SW_SHOWDEFAULT and
a black console window flashes onto the user's desktop for the
duration of each call — see the parent fix commit.

The check is source-level rather than behavioural because:

* the flag's effect is observable only on Windows;
* GitHub Actions runs vitest on Linux for the hook tests;
* regressing this is easy (every new spawnSync site has to remember
  to add the flag), and a runtime check on a Windows-only CI leg
  would still let a PR land on the main branch first.

Counts spawnSync occurrences and windowsHide:true occurrences per
file (in code, ignoring comments) and asserts equality. Five files
covered:

* gitnexus/hooks/claude/gitnexus-hook.cjs
* gitnexus/hooks/claude/hook-db-lock-probe.cjs
* gitnexus-claude-plugin/hooks/gitnexus-hook.js
* gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs
* gitnexus-cursor-integration/hooks/gitnexus-hook.cjs

Adding a new hook file requires updating the HOOK_FILES tuple. A
sanity assertion ``spawnCount > 0`` catches accidental deletion of
all spawn calls in a future refactor (would otherwise silently make
the count-equality assertion trivially true).

Sits next to the existing "no shell: true" and ".cmd extension"
regression tests in test/unit/hooks.test.ts — same shape, same
spirit.

* fix(src): extend windowsHide:true to every spawn-family call in cli/core/mcp/server

Companion to the hook-layer fix in this branch's first commit. The
same Windows console-window flash bug applies to every
``spawn`` / ``spawnSync`` / ``execFile`` / ``execFileSync`` /
``execFileAsync`` / ``execSync`` call in the source tree — not just
the hooks. The MCP local backend
(``src/mcp/local/local-backend.ts``) and the ``gitnexus serve`` git
helpers (``src/server/git-clone.ts``) are particularly bad because
they run from daemonized processes that have no parent console; the
spawned child auto-allocates one and it pops onto the user's
desktop. The CLI sites are less visible (the user is at a terminal
with an existing console; ``stdio: 'inherit'`` shares it) but the
flag is harmless there — windowsHide only suppresses NEW console
allocation, an inherited parent console is untouched. The visible
output of ``gitnexus analyze`` and friends is preserved verbatim.

The pre-existing fix at ``src/core/lbug/extension-loader.ts:96``
established the convention in this codebase. This commit applies it
uniformly.

Sites covered (21 new):

| File | Sites |
|---|---|
| src/cli/analyze.ts           | 1 |
| src/cli/setup.ts             | 2 |
| src/cli/wiki.ts              | 3 |
| src/core/embeddings/embedder.ts | 1 |
| src/core/git-staleness.ts    | 3 |
| src/core/run-analyze.ts      | 1 |
| src/core/wiki/cursor-client.ts | 2 |
| src/core/wiki/generator.ts   | 3 |
| src/mcp/local/local-backend.ts | 2 |
| src/server/git-clone.ts      | 2 |
| src/core/lbug/extension-loader.ts | (already had it, untouched) |

Combined with the 19 hook sites from the first commit + the 1
pre-existing extension-loader site, the codebase now has uniform
``windowsHide: true`` on every spawn-family call.

Behavioural notes:

* ``windowsHide`` is documented by Node as a no-op on POSIX —
  Linux/macOS hosts see byte-identical behaviour.
* ``stdio: 'inherit'`` callers (e.g. ``cli/wiki.ts:522`` opens the
  editor in the user's terminal) keep their interactive UX. The
  child inherits the parent's stdio handles; no new console is
  allocated; the flag has nothing to hide.
* Piped callers (``stdio: ['pipe',…]``) continue to deliver every
  byte of stdout/stderr back to the parent for the parent to log
  / process / re-print. No output is swallowed.
* ``execSync`` / ``execFileSync`` callers that previously had no
  ``stdio`` option (e.g. ``generator.ts:887`` ``execSync('git
  rev-parse HEAD', { cwd })``) keep their default pipe semantics
  (``.toString()`` still works) — windowsHide is added alongside
  the existing ``cwd`` option.

Verified on Windows 10 22H2 / Node 22.21 by installing the locally
built tarball and exercising:

* MCP detect_changes via the local backend → no flash.
* gitnexus serve → no flash on git clone/clone-pull.
* gitnexus analyze interactively → output appears in terminal as
  before, no extra window.

* test(windowsHide): extend regression to every spawn-family call in src/

Companion to the src/ patch. The hooks.test.ts regression now
covers 16 files (5 hooks + 11 source files), and asserts the
invariant for every spawn-family function — not just spawnSync.

Changes:

* Generalise countSpawnCalls() to also count spawn, execFile,
  execFileSync, execFileAsync, execSync (the entire spawn-family
  surface of child_process). Skip method calls (e.g. RegExp.exec)
  via a negative-lookbehind on ``.``.
* Add SRC_FILES table with all 11 source-tree files that import
  spawn-family functions from child_process.
* Loop over [...HOOK_FILES, ...SRC_FILES] so a regression in any
  file fails the same test name.
* Tighten the assertion to ``hideCount >= spawnCount`` rather
  than strict equality, because some sites (e.g. setup.ts:534
  using execFileAsync via shell:true on Windows) may legitimately
  add windowsHide to nested option objects in future refactors.
* Sanity gate ``spawnCount > 0`` per file catches a refactor
  that deletes all spawn calls (would otherwise make the
  assertion trivially true).

Manually exercised against the patched repo:
  16 files, 28 total spawn-family calls, 28 windowsHide:true.
  All pass.

The convention to keep this list in sync: every new file in
gitnexus/src/ that imports from 'child_process' must be added to
the SRC_FILES tuple. The cost is one line per file; the benefit
is the next contributor never has to think about windowsHide
again — the test will catch a miss before merge.

* style: prettier --write on storage/git.ts + hooks.test.ts

CI quality / format job flagged two formatting issues in the
merge-resolution commit: a long single-line options object in
storage/git.ts and similar in hooks.test.ts. prettier --write
fixes both with the project's standard wrap-and-trailing-comma
style. No semantic change.

* test(git): include windowsHide in toHaveBeenCalledWith assertion

The merge-resolution commit added windowsHide:true to the
'git rev-parse --is-inside-work-tree' execSync call in
src/storage/git.ts, but the matching strict-shape assertion in
git.test.ts:31-34 still expected the pre-patch two-key options
object {cwd, stdio}. vitest's toHaveBeenCalledWith does a deep
structural match, so the extra third key flipped the assertion
to fail.

Add windowsHide: true to the expected shape. Only this one
assertion is strict; the two siblings ('passes the correct cwd'
and the no-cwd-arg case) use expect.objectContaining and
expect.any(String) and remain green without modification.

* test(setup-codex): include windowsHide in execFile shape assertions

Same root cause as the git.test.ts fix on this branch: the windowsHide
patch added windowsHide:true to the execFile() options in
src/cli/setup.ts, but three strict-shape toHaveBeenCalledWith
assertions in setup-codex.test.ts still expected the pre-patch
{shell:true} / {shell:false} two-key options. vitest does a deep
structural match, so the extra key flipped the assertions to fail
on every CI matrix leg (ubuntu coverage + macos + windows).

Adding windowsHide:true alongside the existing 'shell' key in
all three sites.

* ci: retrigger checks

go-parity failed on a flaky onnxruntime-node postinstall network timeout
(AggregateError [ETIMEDOUT] in node ./script/install), which cascaded into
the CI Gate. No code change — empty commit to re-run the pipeline.

* fix(test): strengthen windowsHide regression assertions (PR #1794 review)

- Replace toBeGreaterThanOrEqual with exact toBe per DoD §2.7
- Remove unused `m` variable in countSpawnCalls (CodeQL finding)
- Add windowsHide: true to runGit test helper for consistency

---------

Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: ManniX-ITA <35522085+ManniX-ITA@users.noreply.github.com>
Co-authored-by: Test <test@example.com>

gitnexus-claude-plugin/hooks/gitnexus-hook.js

@@ -77,6 +77,7 @@ function findCanonicalRepoRoot(cwd) {
       timeout: 2000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     if (result.error || result.status !== 0) return null;
     const commonDir = (result.stdout || '').trim();
@@ -200,6 +201,7 @@ function runGitNexusCli(args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
 
@@ -210,6 +212,7 @@ function runGitNexusCli(args, cwd, timeout) {
       encoding: 'utf-8',
       timeout: 3000,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     useDirectBinary = which.status === 0;
   } catch {
@@ -222,6 +225,7 @@ function runGitNexusCli(args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
   // npx fallback needs shell on Windows since npx is a .cmd script
@@ -230,6 +234,7 @@ function runGitNexusCli(args, cwd, timeout) {
     timeout: timeout + 5000,
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 }
 
@@ -318,6 +323,7 @@ function handlePostToolUse(input) {
       timeout: 3000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     currentHead = (headResult.stdout || '').trim();
   } catch {

gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs

@@ -109,6 +109,7 @@ function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
       encoding: 'utf-8',
       timeout: 6000,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
       env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
     },
   );
@@ -192,6 +193,7 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
     encoding: 'utf-8',
     timeout: 1000,
     stdio: ['ignore', 'pipe', 'ignore'],
+    windowsHide: true,
   });
   if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
 
@@ -203,6 +205,7 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
       encoding: 'utf-8',
       timeout: 500,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     });
     if (ps.error) {
       if (ps.error.code === 'ETIMEDOUT') return true;

gitnexus-cursor-integration/hooks/gitnexus-hook.cjs

@@ -58,6 +58,7 @@ function findCanonicalRepoRoot(cwd) {
       timeout: 2000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     if (result.error || result.status !== 0) return null;
     const commonDir = (result.stdout || '').trim();
@@ -201,6 +202,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
   return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
@@ -208,6 +210,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
     timeout: timeout + 5000,
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 }
 

gitnexus/hooks/claude/gitnexus-hook.cjs

@@ -77,6 +77,7 @@ function findCanonicalRepoRoot(cwd) {
       timeout: 2000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     if (result.error || result.status !== 0) return null;
     const commonDir = (result.stdout || '').trim();
@@ -218,6 +219,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
   // On Windows, invoke npx.cmd directly (no shell needed)
@@ -226,6 +228,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
     timeout: timeout + 5000,
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 }
 
@@ -315,6 +318,7 @@ function handlePostToolUse(input) {
       timeout: 3000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     currentHead = (headResult.stdout || '').trim();
   } catch {

gitnexus/hooks/claude/hook-db-lock-probe.cjs

@@ -109,6 +109,7 @@ function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
       encoding: 'utf-8',
       timeout: 6000,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
       env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
     },
   );
@@ -192,6 +193,7 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
     encoding: 'utf-8',
     timeout: 1000,
     stdio: ['ignore', 'pipe', 'ignore'],
+    windowsHide: true,
   });
   if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
 
@@ -203,6 +205,7 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
       encoding: 'utf-8',
       timeout: 500,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     });
     if (ps.error) {
       if (ps.error.code === 'ETIMEDOUT') return true;

gitnexus/src/cli/analyze.ts

@@ -312,6 +312,7 @@ const runRespawnedAnalyze = (
 
     const child = spawn(process.execPath, [...args], {
       stdio: ['inherit', 'pipe', 'pipe'],
+      windowsHide: true,
       env,
     });
 

gitnexus/src/cli/setup.ts

@@ -54,6 +54,7 @@ function resolveGitnexusBin(): string | null {
       encoding: 'utf-8',
       timeout: 5000,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     });
     const lines = output
       .split('\n')
@@ -532,6 +533,7 @@ async function setupCodex(result: SetupResult): Promise<void> {
     const entry = getMcpEntry();
     await execFileAsync('codex', ['mcp', 'add', 'gitnexus', '--', entry.command, ...entry.args], {
       shell: process.platform === 'win32',
+      windowsHide: true,
     });
     result.configured.push('Codex');
     return;

gitnexus/src/cli/wiki.ts

@@ -519,7 +519,7 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
         console.log('  Save and close the editor when done.\n');
 
         try {
-          execFileSync(editor, [treeFile], { stdio: 'inherit' });
+          execFileSync(editor, [treeFile], { stdio: 'inherit', windowsHide: true });
         } catch {
           console.log(`  Could not open editor. Please edit manually:\n  ${treeFile}\n`);
           console.log('  Then run `gitnexus wiki` to continue.\n');
@@ -655,7 +655,7 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
 
 function hasGhCLI(): boolean {
   try {
-    execSync('gh --version', { stdio: 'ignore' });
+    execSync('gh --version', { stdio: 'ignore', windowsHide: true });
     return true;
   } catch {
     return false;
@@ -699,7 +699,7 @@ function publishGist(htmlPath: string): { url: string; rawUrl: string } | null {
     const output = execFileSync(
       'gh',
       ['gist', 'create', htmlPath, '--desc', 'Repository Wiki — generated by GitNexus', '--public'],
-      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true },
     ).trim();
 
     // `gh gist create` prints the gist URL as a line in the output. Find the

gitnexus/src/core/embeddings/embedder.ts

@@ -78,7 +78,11 @@ function isCudaAvailable(): boolean {
   // Primary: query the dynamic linker cache — covers all architectures,
   // distro layouts, and custom install paths registered with ldconfig
   try {
-    const out = execFileSync('ldconfig', ['-p'], { timeout: 3000, encoding: 'utf-8' });
+    const out = execFileSync('ldconfig', ['-p'], {
+      timeout: 3000,
+      encoding: 'utf-8',
+      windowsHide: true,
+    });
     if (out.includes('libcublasLt.so.12')) return true;
   } catch {
     // ldconfig not available (e.g. non-standard container)

gitnexus/src/core/git-staleness.ts

@@ -26,6 +26,7 @@ export function checkStaleness(repoPath: string, lastCommit: string): StalenessI
       cwd: repoPath,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     }).trim();
 
     const commitsBehind = parseInt(result, 10) || 0;
@@ -59,6 +60,7 @@ export async function checkStalenessAsync(
     const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
       cwd: repoPath,
       encoding: 'utf-8',
+      windowsHide: true,
     });
 
     const commitsBehind = parseInt(stdout.trim(), 10) || 0;
@@ -90,6 +92,7 @@ function commitsAheadOfIndexed(siblingPath: string, indexedCommit: string): numb
       cwd: siblingPath,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     }).trim();
     return parseInt(result, 10) || 0;
   } catch {

gitnexus/src/core/run-analyze.ts

@@ -332,6 +332,7 @@ export async function runFullAnalysis(
             {
               cwd: repoPath,
               stdio: ['ignore', 'pipe', 'ignore'],
+              windowsHide: true,
               encoding: 'utf8',
             },
           );

gitnexus/src/core/wiki/cursor-client.ts

@@ -36,7 +36,7 @@ let cachedCursorBin: string | null | undefined;
 export function detectCursorCLI(): string | null {
   if (cachedCursorBin !== undefined) return cachedCursorBin;
   try {
-    execSync('agent --version', { stdio: 'ignore' });
+    execSync('agent --version', { stdio: 'ignore', windowsHide: true });
     cachedCursorBin = 'agent';
   } catch {
     cachedCursorBin = null;
@@ -109,6 +109,7 @@ export async function callCursorLLM(
     const child = spawn(cursorBin, args, {
       cwd: config.workingDirectory || process.cwd(),
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
       env: {
         ...process.env,
         // Ensure non-interactive mode

gitnexus/src/core/wiki/generator.ts

@@ -884,7 +884,12 @@ export class WikiGenerator {
 
   private getCurrentCommit(): string {
     try {
-      return execSync('git rev-parse HEAD', { cwd: this.repoPath }).toString().trim();
+      return execSync('git rev-parse HEAD', {
+        cwd: this.repoPath,
+        windowsHide: true,
+      })
+        .toString()
+        .trim();
     } catch {
       return '';
     }
@@ -899,6 +904,7 @@ export class WikiGenerator {
       execFileSync('git', ['merge-base', '--is-ancestor', fromCommit, toCommit], {
         cwd: this.repoPath,
         stdio: 'ignore',
+        windowsHide: true,
       });
       return true;
     } catch {
@@ -916,6 +922,7 @@ export class WikiGenerator {
     try {
       const output = execFileSync('git', ['diff', `${fromCommit}..${toCommit}`, '--name-only'], {
         cwd: this.repoPath,
+        windowsHide: true,
       })
         .toString()
         .trim();

gitnexus/src/mcp/local/local-backend.ts

@@ -2404,6 +2404,7 @@ export class LocalBackend {
         cwd: diffCwd,
         encoding: 'utf-8',
         maxBuffer: 256 * 1024 * 1024,
+        windowsHide: true,
       });
     } catch (err: any) {
       return { error: `Git diff failed: ${err.message}` };
@@ -2680,6 +2681,7 @@ export class LocalBackend {
         timeout: 5000,
         // Avoid ENOBUFS on large repos: rg -l can list many files.
         maxBuffer: 256 * 1024 * 1024,
+        windowsHide: true,
       });
       const files = output
         .trim()

gitnexus/src/server/git-clone.ts

@@ -304,6 +304,7 @@ export function getRemoteOriginUrl(cwd: string): Promise<string | null> {
     const proc = spawn('git', ['config', '--get', 'remote.origin.url'], {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
       env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
     });
     let stdout = '';
@@ -427,6 +428,7 @@ function runGit(args: string[], cwd?: string): Promise<void> {
     const proc = spawn('git', args, {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
       env: {
         ...process.env,
         // Prevent git from prompting for credentials (hangs the process)

gitnexus/src/storage/git.ts

@@ -6,7 +6,11 @@ import path from 'path';
 
 export const isGitRepo = (repoPath: string): boolean => {
   try {
-    execSync('git rev-parse --is-inside-work-tree', { cwd: repoPath, stdio: 'ignore' });
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: repoPath,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
     return true;
   } catch {
     return false;
@@ -23,6 +27,7 @@ export const getCurrentCommit = (repoPath: string): string => {
       // "fatal: not a git repository" to stderr, which leaks to the user's
       // terminal even though the error is caught here (#1172).
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     })
       .toString()
       .trim();
@@ -60,6 +65,7 @@ export const getRemoteUrl = (repoPath: string): string | undefined => {
     raw = execSync('git config --get remote.origin.url', {
       cwd: repoPath,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     })
       .toString()
       .trim();
@@ -100,6 +106,7 @@ export const getGitRoot = (fromPath: string): string | null => {
       cwd: fromPath,
       // Suppress stderr -- see getCurrentCommit comment and #1172.
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     })
       .toString()
       .trim();
@@ -142,6 +149,7 @@ export const getCanonicalRepoRoot = (fromPath: string): string | null => {
     const commonDir = execSync('git rev-parse --path-format=absolute --git-common-dir', {
       cwd: fromPath,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     })
       .toString()
       .trim();
@@ -245,6 +253,7 @@ export const getRemoteOriginUrl = (repoPath: string): string | null => {
     const url = execSync('git config --get remote.origin.url', {
       cwd: repoPath,
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     })
       .toString()
       .trim();

gitnexus/test/unit/git.test.ts

@@ -31,6 +31,7 @@ describe('git utilities', () => {
       expect(mockExecSync).toHaveBeenCalledWith('git rev-parse --is-inside-work-tree', {
         cwd: '/project',
         stdio: 'ignore',
+        windowsHide: true,
       });
     });
 

gitnexus/test/unit/hooks.test.ts

@@ -94,6 +94,7 @@ function runGit(dir: string, args: string[]) {
     cwd: dir,
     encoding: 'utf-8',
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
   if (result.status !== 0) {
     const message = result.stderr || result.stdout || result.error?.message || 'unknown error';
@@ -220,6 +221,176 @@ describe('Shell injection regression', () => {
   }
 });
 
+// ─── Source code regression: windowsHide:true on every spawn-family call ───
+
+/**
+ * Every ``spawn`` / ``spawnSync`` / ``execFile`` / ``execFileSync`` /
+ * ``execFileAsync`` / ``execSync`` call in the hook layer **and the
+ * core/CLI/MCP/server source tree** must pass ``windowsHide: true``
+ * in its options object. Without it, Node's ``child_process`` module
+ * asks ``CreateProcess`` to use ``STARTF_USESHOWWINDOW`` with
+ * ``SW_SHOWDEFAULT`` and a black console window flashes onto the
+ * user's desktop for each call. Under active Claude Code / MCP /
+ * gitnexus-serve use that's a near-continuous stream of pop-ups —
+ * unusable in practice on Windows.
+ *
+ * ``windowsHide`` is a no-op on POSIX (silently dropped), so the
+ * flag is safe to require unconditionally. ``stdio: 'inherit'``
+ * callers (interactive editors etc.) are unaffected — windowsHide
+ * only suppresses NEW console allocation; an inherited parent
+ * console isn't touched.
+ *
+ * The check is source-level rather than behavioural because:
+ *   - the flag's effect is observable only on Windows;
+ *   - GitHub Actions runs vitest on Linux for these tests;
+ *   - regressing this is easy (every new spawn site has to remember
+ *     the flag), and a runtime check on a Windows-only CI leg would
+ *     still let a PR land on the main branch first.
+ *
+ * The pre-existing fix at ``src/core/lbug/extension-loader.ts:96``
+ * established the convention. This test enforces it everywhere.
+ */
+describe('windowsHide regression', () => {
+  // Hook-layer files. Adding a new hook file MUST be reflected here.
+  const HOOK_FILES: Array<readonly [string, string]> = [
+    ['gitnexus/hooks/claude/gitnexus-hook.cjs', CJS_HOOK],
+    [
+      'gitnexus/hooks/claude/hook-db-lock-probe.cjs',
+      path.resolve(__dirname, '..', '..', 'hooks', 'claude', 'hook-db-lock-probe.cjs'),
+    ],
+    ['gitnexus-claude-plugin/hooks/gitnexus-hook.js', PLUGIN_HOOK],
+    [
+      'gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs',
+      path.resolve(
+        __dirname,
+        '..',
+        '..',
+        '..',
+        'gitnexus-claude-plugin',
+        'hooks',
+        'hook-db-lock-probe.cjs',
+      ),
+    ],
+    [
+      'gitnexus-cursor-integration/hooks/gitnexus-hook.cjs',
+      path.resolve(
+        __dirname,
+        '..',
+        '..',
+        '..',
+        'gitnexus-cursor-integration',
+        'hooks',
+        'gitnexus-hook.cjs',
+      ),
+    ],
+  ];
+
+  // Source-tree files. Every file that imports a spawn-family
+  // function from ``child_process`` belongs here. Discovered via
+  //   grep -rn "from 'child_process'" -- gitnexus/src/
+  // plus the explicit ``await import('child_process')`` callers in
+  // local-backend.ts.
+  const SRC_FILES: Array<readonly [string, string]> = [
+    [
+      'gitnexus/src/cli/analyze.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'cli', 'analyze.ts'),
+    ],
+    ['gitnexus/src/cli/setup.ts', path.resolve(__dirname, '..', '..', 'src', 'cli', 'setup.ts')],
+    ['gitnexus/src/cli/wiki.ts', path.resolve(__dirname, '..', '..', 'src', 'cli', 'wiki.ts')],
+    [
+      'gitnexus/src/core/embeddings/embedder.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'embeddings', 'embedder.ts'),
+    ],
+    [
+      'gitnexus/src/core/git-staleness.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'git-staleness.ts'),
+    ],
+    [
+      'gitnexus/src/core/lbug/extension-loader.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'lbug', 'extension-loader.ts'),
+    ],
+    [
+      'gitnexus/src/core/run-analyze.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'run-analyze.ts'),
+    ],
+    [
+      'gitnexus/src/core/wiki/cursor-client.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'wiki', 'cursor-client.ts'),
+    ],
+    [
+      'gitnexus/src/core/wiki/generator.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'core', 'wiki', 'generator.ts'),
+    ],
+    [
+      'gitnexus/src/mcp/local/local-backend.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'mcp', 'local', 'local-backend.ts'),
+    ],
+    [
+      'gitnexus/src/server/git-clone.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'server', 'git-clone.ts'),
+    ],
+    // New post-upstream-merge (May 2026 sync):
+    [
+      'gitnexus/src/storage/git.ts',
+      path.resolve(__dirname, '..', '..', 'src', 'storage', 'git.ts'),
+    ],
+  ];
+
+  /**
+   * Strip pure-comment lines so prose mentions of ``spawn`` /
+   * ``exec`` don't inflate the call count.
+   */
+  function stripComments(source: string): string {
+    return source
+      .split('\n')
+      .filter((l) => {
+        const t = l.trim();
+        return !t.startsWith('//') && !t.startsWith('*') && !t.startsWith('/*');
+      })
+      .join('\n');
+  }
+
+  /**
+   * Count spawn-family invocations. The regex matches ``spawn(``,
+   * ``spawnSync(``, ``execFile(``, ``execFileSync(``,
+   * ``execFileAsync(``, ``execSync(`` as function calls — not
+   * destructures (``const { spawn } = ...``), not method calls
+   * (``.exec(``), not bare ``exec()`` (which collides with regex
+   * ``.exec()``; we explicitly drop it).
+   */
+  function countSpawnCalls(codeSource: string): number {
+    const re =
+      /(^|[^a-zA-Z0-9_$.])(spawn|spawnSync|execFile|execFileSync|execFileAsync|execSync)\s*\(/gm;
+    let count = 0;
+    while (re.exec(codeSource) !== null) {
+      count++;
+    }
+    return count;
+  }
+
+  for (const [label, file] of [...HOOK_FILES, ...SRC_FILES]) {
+    it(`${label}: every spawn-family options object contains windowsHide: true`, () => {
+      // The file must exist — silent-skip would mask a deletion.
+      expect(fs.existsSync(file)).toBe(true);
+      const source = fs.readFileSync(file, 'utf-8');
+      const codeSource = stripComments(source);
+
+      const spawnCount = countSpawnCalls(codeSource);
+      const hideCount = (codeSource.match(/windowsHide\s*:\s*true/g) ?? []).length;
+
+      // Sanity: catch a refactor that accidentally deletes every
+      // spawn call (which would otherwise make the equality below
+      // trivially true at 0 == 0).
+      expect(spawnCount).toBeGreaterThan(0);
+      // One windowsHide per spawn-family call. We don't try to
+      // match brace structure — a same-count proxy is sufficient
+      // because every spawn site in these files passes an options
+      // object literal (no helper indirection).
+      expect(hideCount).toBe(spawnCount);
+    });
+  }
+});
+
 // ─── Source code regression: .cmd extensions for Windows ─────────────
 
 describe('Windows .cmd extension handling', () => {

gitnexus/test/unit/setup-codex.test.ts

@@ -74,7 +74,7 @@ describe('setupCommand codex execution', () => {
     expect(execFileMock).toHaveBeenCalledWith(
       'codex',
       ['mcp', 'add', 'gitnexus', '--', 'cmd', '/c', 'npx', '-y', NPX_REF, 'mcp'],
-      { shell: true },
+      { shell: true, windowsHide: true },
       expect.any(Function),
     );
   });
@@ -89,7 +89,7 @@ describe('setupCommand codex execution', () => {
     expect(execFileMock).toHaveBeenCalledWith(
       'codex',
       ['mcp', 'add', 'gitnexus', '--', 'cmd', '/c', 'npx', '-y', NPX_REF, 'mcp'],
-      { shell: true },
+      { shell: true, windowsHide: true },
       expect.any(Function),
     );
   });
@@ -104,7 +104,7 @@ describe('setupCommand codex execution', () => {
     expect(execFileMock).toHaveBeenCalledWith(
       'codex',
       ['mcp', 'add', 'gitnexus', '--', 'npx', '-y', NPX_REF, 'mcp'],
-      { shell: false },
+      { shell: false, windowsHide: true },
       expect.any(Function),
     );