gitnexus 1.6.9 → 1.6.10-aptos.0

package/hooks/claude/gitnexus-hook.cjs

@@ -349,6 +349,49 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
   });
 }
 
+/**
+ * Fallback augmentation for the #2396 path: when a GitNexus process holds the
+ * lbug DB write lock the CLI `augment` can't run, so point the agent at the MCP
+ * `query` tool instead. Phrased conditionally ("if the MCP tools are live") so it
+ * stays truthful on every owner path — a confirmed MCP owner, a `serve` owner, or
+ * a fail-closed probe where no server is actually confirmed. `pattern` is embedded
+ * verbatim; the caller (sendHookResponse) JSON-escapes it structurally.
+ */
+function buildMcpQueryHint(pattern) {
+  return (
+    `[GitNexus] Local augment is unavailable (the graph DB is held by another ` +
+    `GitNexus process). If the GitNexus MCP tools are live in this session, call ` +
+    `the GitNexus \`query\` MCP tool (e.g. mcp__gitnexus__query) with ` +
+    `search_query "${pattern}".`
+  );
+}
+
+/**
+ * #2396 throttle: emit the MCP-query hint at most once per repo per window, so an
+ * owner-locked session isn't nudged on every search. Window (ms) via
+ * GITNEXUS_MCP_HINT_THROTTLE_MS (default 10min; 0/invalid disables). Best-effort —
+ * any fs error falls back to emitting.
+ * ponytail: per-repo mtime marker, shared across concurrent sessions on the same
+ * repo; add per-session dedup only if that sharing becomes a problem.
+ */
+function shouldEmitMcpHint(gitNexusDir) {
+  const raw = process.env.GITNEXUS_MCP_HINT_THROTTLE_MS;
+  const windowMs = raw === undefined || raw === '' ? 600000 : Number(raw);
+  if (!Number.isFinite(windowMs) || windowMs <= 0) return true;
+  const marker = path.join(gitNexusDir, '.mcp-hint-shown');
+  try {
+    if (Date.now() - fs.statSync(marker).mtimeMs < windowMs) return false;
+  } catch {
+    /* marker missing/unreadable → emit */
+  }
+  try {
+    fs.writeFileSync(marker, '');
+  } catch {
+    /* best-effort; still emit */
+  }
+  return true;
+}
+
 /**
  * PreToolUse handler — augment searches with graph context.
  */
@@ -385,18 +428,25 @@ function handlePreToolUse(input) {
   let result = '';
   try {
     if (hasGitNexusServerOwner(gitNexusDir)) {
-      // Normal skip path: the MCP server owns the DB, so the CLI augment would
-      // contend on the lock. Stay silent for strict hook runners (issue #1913);
-      // surface the reason only when diagnostics are explicitly requested.
+      // #2396: the MCP server holds the DB write lock, so a competing CLI
+      // `augment` would only contend on it (LadybugDB is single-writer). But the
+      // session that triggered this hook has the GitNexus MCP tools live — route
+      // the augmentation to the agent via additionalContext instead of silently
+      // doing nothing. Mirror the skip reason to stderr only under GITNEXUS_DEBUG
+      // (strict-runner contract, #1913); the hint itself rides the sanctioned
+      // additionalContext stdout channel the successful augment already uses.
       if (isDebugEnabled()) {
         process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
       }
-      return;
-    }
-    const cliPath = resolveCliPath();
-    const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
-    if (!child.error && child.status === 0) {
-      result = extractAugmentContext(child.stderr || '');
+      if (shouldEmitMcpHint(gitNexusDir)) {
+        result = buildMcpQueryHint(pattern);
+      }
+    } else {
+      const cliPath = resolveCliPath();
+      const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
+      if (!child.error && child.status === 0) {
+        result = extractAugmentContext(child.stderr || '');
+      }
     }
   } catch {
     /* graceful failure */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9",
+  "version": "1.6.10-aptos.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -35,7 +35,12 @@
     "hooks",
     "scripts",
     "skills",
-    "vendor",
+    "vendor/leiden",
+    "vendor/tree-sitter-c",
+    "vendor/tree-sitter-dart",
+    "vendor/tree-sitter-kotlin",
+    "vendor/tree-sitter-proto",
+    "vendor/tree-sitter-swift",
     "web"
   ],
   "scripts": {
@@ -52,11 +57,11 @@
     "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",
-    "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js"
+    "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js",
+    "version": "node scripts/sync-plugin-manifests.mjs"
   },
   "dependencies": {
-    "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.18.0",
+    "@ladybugdb/core": "^0.18.3",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "busboy": "^1.6.0",
@@ -70,13 +75,12 @@
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
     "ignore": "^7.0.5",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.0.0",
     "jsonc-parser": "^3.3.1",
     "mnemonist": "^0.40.3",
     "node-addon-api": "^8.0.0",
     "node-gyp-build": "^4.8.0",
     "onnxruntime-common": "^1.26.0",
-    "onnxruntime-node": "^1.24.0",
     "pandemonium": "^2.4.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -93,18 +97,20 @@
     "tree-sitter-typescript": "^0.23.2",
     "uuid": "^14.0.0"
   },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^4.1.0",
+    "onnxruntime-node": "^1.24.0"
+  },
   "devDependencies": {
-    "@babel/generator": "^7.29.7",
-    "@babel/parser": "^7.29.7",
-    "@babel/traverse": "^7.29.7",
-    "@babel/types": "^7.29.7",
+    "@babel/generator": "^8.0.0",
+    "@babel/parser": "^8.0.0",
+    "@babel/traverse": "^8.0.0",
+    "@babel/types": "^8.0.0",
     "@types/busboy": "^1.5.4",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.6",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.6.0",
-    "@types/uuid": "^11.0.0",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.0.18",
     "gitnexus-shared": "file:../gitnexus-shared",
     "tsx": "^4.0.0",
@@ -117,6 +123,6 @@
     }
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": "^22.18.0 || >=24.11.0"
   }
 }

package/scripts/cross-platform-tests.ts

@@ -30,8 +30,16 @@ const PLATFORM_LOGIC = [
   'test/unit/setup-jsonc.test.ts',
   'test/unit/setup-codex.test.ts',
   'test/unit/setup-antigravity.test.ts',
+  'test/integration/setup-uninstall-roundtrip.test.ts',
   'test/unit/resolve-invocation.test.ts',
+  // CLI-spawn entry-point resolution; its path-separator assertion (cli[/\\]index)
+  // must exercise the Windows backslash branch, so run it on the OS matrix (#2394).
+  'test/unit/cli-entry.test.ts',
   'test/unit/platform-capabilities.test.ts',
+  // getconf page-size probe: explicit process.platform gate (win32 short-circuit)
+  // plus a live-probe test whose only real non-4K coverage is macos-arm64's
+  // 16 KiB pages — the exact hardware class #1231 targets (#2424 review).
+  'test/unit/lbug-config-pagesize.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
   'test/unit/lbug-pool-fts-load.test.ts',
   'test/unit/repo-manager.test.ts',
@@ -42,12 +50,38 @@ const PLATFORM_LOGIC = [
   'test/unit/cursor-hook.test.ts',
   'test/unit/sidecar-recovery.test.ts',
   'test/unit/pool-wal-recovery.test.ts',
+  'test/unit/lbug-adapter-wal-schema.test.ts',
   'test/unit/detect-changes-worktree.test.ts',
   'test/unit/eval-server-bind-restriction.test.ts',
   'test/unit/ignore-service.test.ts',
   'test/unit/group/bridge-db.test.ts',
   'test/unit/group/bridge-db-edge.test.ts',
   'test/unit/onnxruntime-node-resolver.test.ts',
+  // Windows cmd.exe arg-quoting + compose-and-spawn for the npm install (#2372):
+  // the quoting rules and win32 single-string spawn shape are OS-sensitive, so
+  // exercise them on real windows-latest. The spawn-shape/path tests force their
+  // platform branch and derive expected paths via the real fns, so they pass on
+  // any host (see the platform stubs + resolve() in the test file).
+  'test/unit/embedding-runtime-install.test.ts',
+  // Real-spawn arg-delivery round-trip: proves the install spawn delivers args
+  // to the child intact on each platform — win32 via the cmd.exe -> .cmd %* ->
+  // node chain (real cmd.exe, not just our model), macos/linux via the no-shell
+  // array form. Runs on every platform (the ubuntu suite covers Linux; this
+  // registration adds windows + macos).
+  'test/unit/embedding-install-arg-delivery.test.ts',
+  // Lazy MoveFlow install coordinates, PowerShell invocation data, archive
+  // streaming, and filesystem leases all vary across operating systems.
+  'test/unit/move/install-move-flow.test.ts',
+  // Structural FTS-extension classifier against REAL binaries (#2374): on this
+  // matrix `process.execPath` / `lbugjs.node` are a real PE (windows) and Mach-O
+  // (macos), so the header parsing is proven on genuine binaries, not synthetic
+  // buffers (the ubuntu suite covers the ELF path).
+  'test/integration/extension-binary-real.test.ts',
+  // Server repo resolver branches on path shape (path.isAbsolute, backslash
+  // detection) and canonicalizePath/realpathSync, all of which differ between
+  // POSIX and Windows — the fail-closed path-claim semantics must hold on the
+  // real windows-latest path implementation (#2419/#2420).
+  'test/unit/server-api-repo-resolution.test.ts',
 ];
 
 // Native LadybugDB integration tests — exercise the @ladybugdb/core
@@ -64,6 +98,9 @@ const LBUG_NATIVE = [
   'test/integration/lbug-orphan-sidecar-recovery.test.ts',
   'test/integration/lbug-readonly-init.test.ts',
   'test/integration/lbug-non-ascii-path.test.ts',
+  // Shared Move/non-Move rows must retain their schema defaults through the
+  // real native database on every supported desktop platform.
+  'test/integration/move-mixed-language-roundtrip.test.ts',
   // Cross-repo trace e2e: builds two real lbug indexes + a real bridge and
   // opens them through the pool adapter (native addon + bridge file locking).
   // Windows is skipped in-file (describeReopen) due to the bridge reopen lock.
@@ -77,6 +114,21 @@ const LBUG_NATIVE = [
   'test/integration/analyze-wal-checkpoint-failure.test.ts',
   'test/integration/fts-stemmer-sweep.test.ts',
   'test/integration/lbug-multiwriter-deadlock.test.ts',
+  // #2409 batched incremental writeback: chunked IN-list DETACH DELETEs +
+  // backslash quote escaping against the REAL native engine — the failing
+  // environment for #2409 was Windows, so the write pattern must be proven
+  // on the windows-latest native addon, not just Ubuntu.
+  'test/integration/lbug-delete-nodes-for-files.test.ts',
+  // #2409 defect 2: dirty-flag recovery parks lbug.wal/.shadow (rename next
+  // to a live native DB, rm-then-rename over an existing parked copy) before
+  // any open — rename semantics are exactly what differs on Windows.
+  'test/unit/incremental-dirty-recovery.test.ts',
+  // #2623: the incremental writeback must load VECTOR before the CodeEmbedding
+  // join-delete, and the blocked path must escalate instead of crashing. The
+  // win32 VECTOR gate was removed in the same PR, so this ordering must be
+  // proven on the windows-latest native addon, not just Ubuntu. Budget: ~25s
+  // on Linux → expect ~2min on the slowest Windows shard.
+  'test/unit/incremental-vector-extension-ordering.test.ts',
 ];
 
 // Process spawning and CLI tests — exercise child_process with real
@@ -87,6 +139,10 @@ const SPAWN_CLI = [
   'test/integration/cli-limit-e2e.test.ts',
   'test/integration/hooks-e2e.test.ts',
   'test/integration/skills-e2e.test.ts',
+  // Spawns the real CLI across hermetic HOME/USERPROFILE homes to exercise the
+  // FTS extension lifecycle — the #2374 bug was Windows-reported, so this must
+  // run on the Windows/macOS matrix, not just the Ubuntu full suite.
+  'test/integration/fts-extension-e2e.test.ts',
   'test/integration/server-http-startup.test.ts',
   'test/integration/mcp/server-startup.test.ts',
   'test/integration/analyze-heap-oom-e2e.test.ts',

package/scripts/ensure-fts.ts

@@ -0,0 +1,43 @@
+/**
+ * Install the LadybugDB FTS and VECTOR extensions into the shared home (~/.lbdb)
+ * up front, so every test in a sharded CI run finds them regardless of shard.
+ *
+ * FTS-dependent tests split two ways: the LOAD-path gate (skipUnlessFtsAvailable)
+ * self-installs on miss, but the FILE-path gate (requireFtsResourceOrSkip, e.g.
+ * extension-binary-real.test.ts) resolves the extension path at module load and
+ * cannot self-install. Sharding (and the balancing sequencer) can drop such a
+ * test into a shard with no installer sibling — this step removes that ordering
+ * dependency by installing FTS once before vitest starts. `auto` is LOAD-first,
+ * so a cache-warmed extension costs no network.
+ *
+ * Best-effort: exits 0 on failure (offline etc.) — the per-test gates still
+ * hard-fail under GITNEXUS_REQUIRE_FTS=1 if FTS is genuinely unavailable, which
+ * is where the loud signal belongs.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  initLbug,
+  loadFTSExtension,
+  loadVectorExtension,
+  closeLbug,
+} from '../src/core/lbug/lbug-adapter.js';
+
+const dir = mkdtempSync(join(tmpdir(), 'gn-ensure-fts-'));
+try {
+  await initLbug(join(dir, 'ensure-fts.lbug'));
+  const ok = await loadFTSExtension(undefined, { policy: 'auto' });
+  console.log(ok ? 'FTS extension ready.' : 'FTS extension unavailable (continuing).');
+  // VECTOR rides the same pre-install (#2623): the win32 gate is gone, so the
+  // vector suites genuinely run on Windows/macOS — installing once here means
+  // every sharded test process LOADs from ~/.lbdb instead of racing its own
+  // out-of-process INSTALL (bounded 15s each when the server is unreachable).
+  const vec = await loadVectorExtension(undefined, { policy: 'auto' });
+  console.log(vec ? 'VECTOR extension ready.' : 'VECTOR extension unavailable (continuing).');
+} catch (err) {
+  console.warn(`ensure-fts: skipped (${err instanceof Error ? err.message : String(err)})`);
+} finally {
+  await closeLbug();
+  rmSync(dir, { recursive: true, force: true });
+}

package/scripts/install-duckdb-extension.mjs

@@ -3,9 +3,41 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+// Positive on-disk-corruption signatures. `FORCE INSTALL` re-downloads even when
+// a file is already present; we only want that when the LOAD error proves the
+// existing file is bad (truncated/wrong-platform, #2374). For everything else —
+// a missing file (plain INSTALL downloads it), or a permanent non-file failure a
+// re-download can never fix (missing runtime dep: "cannot open shared object") —
+// plain INSTALL avoids re-downloading ~2 MB on every analyze run forever.
+// Exported so a parity test keeps this byte-identical to the copy in
+// src/core/lbug/extension-load-error.ts (this `.mjs` cannot import that `.ts`), #2383 F5b.
+export const FILE_CORRUPTION_SIGNATURES = [
+  /invalid elf/i,
+  /file too short/i,
+  /not a valid/i,
+  /bad magic/i,
+  /wrong architecture/i,
+  /mach-o/i,
+  /truncat/i,
+];
+
+/**
+ * Decide the install verb from the LOAD error that triggered this install.
+ * `FORCE INSTALL` only when the error positively indicates file-level breakage;
+ * otherwise plain `INSTALL` (missing file, missing-dependency dlopen failure,
+ * or unknown/absent error).
+ */
+export function chooseInstallVerb(loadError) {
+  if (loadError && FILE_CORRUPTION_SIGNATURES.some((re) => re.test(loadError))) {
+    return 'FORCE INSTALL';
+  }
+  return 'INSTALL';
+}
+
 function parseLbugMaxDbSize(raw) {
   const parsed = raw ? Number(raw) : NaN;
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -14,28 +46,54 @@ function parseLbugMaxDbSize(raw) {
   return Math.floor(parsed);
 }
 
-async function installDuckDbExtension(extensionName, verifyOnly = false) {
-  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
-    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
-  }
-
-  const require = createRequire(import.meta.url);
-  const lbugModule = require('@ladybugdb/core');
-  const lbug = lbugModule.default ?? lbugModule;
+function resolveMaxDbSize() {
   // argv[3] is the optional positional size; ignore it when it is actually a
   // flag token (e.g. `--verify-only`) and fall back to the env default.
   const sizeArg =
     process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : undefined;
-  const lbugMaxDbSize = parseLbugMaxDbSize(sizeArg ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE);
+  return parseLbugMaxDbSize(sizeArg ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE);
+}
+
+/** Open a scratch LadybugDB and return its connection plus a disposer. */
+async function defaultConnect(lbugMaxDbSize) {
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
   const dbPath = path.join(tmpDir, 'install.lbug');
-  let db;
-  let conn;
+  const db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
+  const conn = new lbug.Connection(db);
+  return {
+    conn,
+    dispose: async () => {
+      await conn.close().catch(() => {});
+      await db.close().catch(() => {});
+      await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * Install (or verify) an optional LadybugDB extension in this short-lived process.
+ *
+ * @param {string} extensionName
+ * @param {object} [options]
+ * @param {boolean} [options.verifyOnly] LOAD-only Docker build gate — no install.
+ * @param {string} [options.loadError] The parent's LOAD failure; selects the verb.
+ * @param {(size: number) => Promise<{conn: {query: (sql: string) => Promise<unknown>}, dispose: () => Promise<void>}>} [options.connect]
+ *        Connection factory; injectable for offline unit tests.
+ */
+export async function installDuckDbExtension(extensionName, options = {}) {
+  const { verifyOnly = false, loadError, connect } = options;
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const makeConnection = connect ?? (() => defaultConnect(resolveMaxDbSize()));
+  const { conn, dispose } = await makeConnection();
 
   try {
-    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
-    conn = new lbug.Connection(db);
     if (verifyOnly) {
       // Prove a previously-baked extension is resolvable by a FRESH process
       // under the current HOME (the runtime `LOAD EXTENSION` path) — no INSTALL,
@@ -46,19 +104,22 @@ async function installDuckDbExtension(extensionName, verifyOnly = false) {
         `[install-ext] LOAD-only verify OK for '${extensionName}' (HOME=${process.env.HOME})`,
       );
     } else {
-      await conn.query(`INSTALL ${extensionName}`);
+      // Plain INSTALL is a no-op when the file already exists; escalate to FORCE
+      // only when the LOAD error proves the on-disk file is broken (#2374).
+      await conn.query(`${chooseInstallVerb(loadError)} ${extensionName}`);
     }
   } finally {
-    if (conn) await conn.close().catch(() => {});
-    if (db) await db.close().catch(() => {});
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    await dispose();
   }
 }
 
-installDuckDbExtension(
-  process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME,
-  process.argv.includes('--verify-only'),
-).catch((err) => {
-  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
-  process.exitCode = 1;
-});
+// Only run when executed directly — imported (e.g. by unit tests) it stays inert.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME, {
+    verifyOnly: process.argv.includes('--verify-only'),
+    loadError: process.env.GITNEXUS_LBUG_EXTENSION_LOAD_ERROR,
+  }).catch((err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exitCode = 1;
+  });
+}

package/scripts/run-cross-platform.ts

@@ -14,6 +14,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { ALL_CROSS_PLATFORM } from './cross-platform-tests.js';
+import { parseShardArg } from './shard-arg.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -27,18 +28,72 @@ if (missing.length > 0) {
   process.exit(1);
 }
 
-console.log(`Running ${ALL_CROSS_PLATFORM.length} platform-sensitive tests...\n`);
+// Optional sharding (CI): `--shard=<i>/<n>` splits the fixed file list across
+// parallel matrix shards so each runner processes ~1/n of it. Passed straight
+// through to vitest, which partitions the *given* files deterministically. The
+// Windows runner is ~5x slower than macOS/Linux on this spawn-heavy suite (~50
+// CLI/worker process spawns), so a single shard was creeping past the watchdog
+// below; sharding keeps each runner well under it (see ci-tests.yml matrix).
+// Fail loud on a malformed --shard arg (mirrors the missing-files check above):
+// a silently-dropped shard flag would run the full unsharded suite and re-trip
+// the watchdog. Kept outside the execFileSync try/catch below so the message
+// isn't swallowed by that catch's watchdog-only branch.
+let shardArg: string | undefined;
+try {
+  shardArg = parseShardArg(process.argv.slice(2));
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+
+// Per-shard watchdog, default 15 min. Sharding splits the file list by COUNT, not
+// runtime, so the heaviest spawn suites can cluster on one shard — what this
+// bounds is the *busiest* shard, not an even 1/n of wall-clock. The busiest
+// Windows shard has grown to the default (14m57s on the v1.6.10-rc.19 green
+// run, one observed timeout since — #2449), so CI raises the budget to 20
+// minutes via GITNEXUS_CROSS_PLATFORM_TIMEOUT_MINUTES; the default stays 15
+// for local runs.
+const DEFAULT_TIMEOUT_MIN = 15;
+const timeoutMinutes = Number.parseInt(
+  process.env.GITNEXUS_CROSS_PLATFORM_TIMEOUT_MINUTES ?? String(DEFAULT_TIMEOUT_MIN),
+  10,
+);
+const timeoutMs =
+  Number.isFinite(timeoutMinutes) && timeoutMinutes > 0
+    ? timeoutMinutes * 60 * 1000
+    : DEFAULT_TIMEOUT_MIN * 60 * 1000;
+
+console.log(
+  `Running ${ALL_CROSS_PLATFORM.length} platform-sensitive tests` +
+    `${shardArg ? ` (${shardArg.replace('--shard=', 'shard ')})` : ''}...\n`,
+);
 
+const startedAt = Date.now();
 try {
-  execFileSync('npx', ['vitest', 'run', ...ALL_CROSS_PLATFORM], {
+  execFileSync('npx', ['vitest', 'run', ...ALL_CROSS_PLATFORM, ...(shardArg ? [shardArg] : [])], {
     cwd: ROOT,
     stdio: 'inherit',
-    timeout: 15 * 60 * 1000,
+    timeout: timeoutMs,
     shell: true,
   });
-} catch (err: any) {
-  if (err.killed || err.signal) {
-    console.error('vitest timed out after 15 minutes');
+} catch (err) {
+  // execFileSync sets `killed`/`signal` when the watchdog above kills vitest.
+  const e = err as {
+    killed?: boolean;
+    signal?: NodeJS.Signals | null;
+    status?: number | null;
+    code?: string;
+  };
+  if (e.killed || e.signal) {
+    console.error(`vitest timed out after ${Math.round(timeoutMs / 60_000)} minutes`);
   }
+  // #2449: Windows shards have died with a bare `status: null`, empty stderr
+  // and nothing to triage from. Always leave the child's exit facts behind.
+  const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
+  console.error(
+    `vitest exited abnormally: status=${e.status ?? 'null'} signal=${e.signal ?? 'none'} ` +
+      `killed=${e.killed === true} spawnCode=${e.code ?? 'none'} elapsed=${elapsedSec}s ` +
+      `budget=${Math.round(timeoutMs / 60_000)}min`,
+  );
   process.exit(1);
 }

package/scripts/shard-arg.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolves the optional `--shard=<index>/<total>` argument for
+ * `run-cross-platform.ts`.
+ *
+ * Extracted as a pure, side-effect-free function so the branch logic is
+ * unit-testable without the script's top-level `execFileSync` (see
+ * `test/unit/shard-arg.test.ts`). Mirrors the `computeSpawnPrefix` extraction
+ * pattern in `test/helpers/cli-entry.ts`.
+ */
+
+const SHARD_RE = /^--shard=\d+\/\d+$/;
+
+/**
+ * Returns the matched `--shard=<index>/<total>` token (e.g. `--shard=1/3`) to
+ * pass straight through to vitest, or `undefined` when no shard arg is present.
+ *
+ * Fails loud on a shard-shaped-but-malformed arg (e.g. `--shard=1`, `--shard`,
+ * `--shard=abc`): a silently-ignored malformed arg would drop the shard flag and
+ * run the full unsharded ~50-spawn suite, re-arming the Windows watchdog timeout
+ * with no signal. Only `--shard` / `--shard=…` args are inspected, so unrelated
+ * flags (including a hypothetical `--shardx=…`) pass through untouched.
+ */
+export function parseShardArg(argv: string[]): string | undefined {
+  const shardArgs = argv.filter((a) => a === '--shard' || a.startsWith('--shard='));
+  const malformed = shardArgs.find((a) => !SHARD_RE.test(a));
+  if (malformed !== undefined) {
+    throw new Error(`Malformed --shard arg '${malformed}' — expected --shard=<index>/<total>`);
+  }
+  return shardArgs[0];
+}