* fix(claude): skip augment hook when server owns db
* chore(autofix): apply prettier + eslint fixes via /autofix command
* fix(hooks): cross-platform DB lock probe for MCP owner guard
Extract hook-db-lock-probe.cjs with a single hasGitNexusDbLockedByGitNexusServer
entry point used by both Claude hooks:
- Linux: scan /proc/<pid>/fd via dev+inode (no lsof required), optional lsof
fallback; GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS caps scan time
- macOS and other Unix: trusted lsof + ps (absolute paths / env overrides)
- Windows: Restart Manager + Win32_Process via win-rm-list-json.ps1 and
GITNEXUS_HOOK_POWERSHELL_PATH
Update hooks.test.ts source coverage for the probe module.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Update gitnexus/hooks/claude/win-rm-list-json.ps1
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* Apply suggestion from @github-actions[bot]
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* fix(gitnexus): repair package.json JSON after malformed engines edit
Co-authored-by: Cursor <cursoragent@cursor.com>
* Update Node.js engine version requirement to 22.0.0
* Update Node.js engine version to >=22.0.0
* fix(hooks): address ce-code-review findings on PR #1493
P0:
- Replace malformed `RM_UNIQUE_PROCESS` block in
`gitnexus/hooks/claude/win-rm-list-json.ps1` (duplicate struct decl +
duplicate `ProcessStartTime` + unbalanced braces) with a single
well-formed `[StructLayout(LayoutKind.Sequential, Pack = 4)]` struct,
so PowerShell `Add-Type` actually compiles and the Windows DB-lock
probe stops fail-open on every machine.
- `gitnexus/src/cli/setup.ts` now copies `hook-db-lock-probe.cjs` and
`win-rm-list-json.ps1` into the user's `~/.claude/hooks/gitnexus/`
alongside `hook-lock.cjs`, preventing the `MODULE_NOT_FOUND` thrown
by `gitnexus-hook.cjs:18`'s top-level require on every fresh install.
`gitnexus/test/unit/setup.test.ts` extended to assert both new copy
destinations.
- Four fail-open hook tests (`ENOENT lsof`, `npx parent line`,
`non-GitNexus ps line`, `ps ENOENT`) now seed `createHookToolDir`
with a valid `[GitNexus]` stderr line so
`expect(parseHookOutput).not.toBeNull()` actually holds on CI.
P1:
- Plugin copy of `win-rm-list-json.ps1` gains `Pack = 4` so its CLR
struct matches the 12-byte native `RM_UNIQUE_PROCESS` layout
(multi-blocker `RmGetList` no longer reads mangled `dwProcessId`).
- `GITNEXUS_HOOK_CLI_PATH = ''` now falls through to the resolution
chain in `gitnexus-hook.cjs`, matching the plugin copy and removing
the twin-file divergence on empty-string envs.
- Lock-warning suppression test seeds `gitnexusMarkerPath` and asserts
the augment subprocess actually ran, plus `GITNEXUS_DEBUG=1`
preserves the full discarded prefix.
- MCP-owner skip branch in both hook copies now emits
`[GitNexus] augment skipped: MCP server owns DB` on stderr, so
agents can distinguish intentional skip from silent failure.
P2:
- `ps` loop in `hook-db-lock-probe.cjs` fails-closed on `ETIMEDOUT`
to mirror the `lsof` handling (symmetric subprocess-probe contract).
- `RmStartSession` return value captured in both `.ps1` copies; exits
early with `[]` on non-zero so subsequent RM API calls don't operate
on an invalid handle.
- Windows RM-list `.ps1` encoded cache distinguishes uninitialized
(`undefined`) from load-failed (`null`) with a one-shot
`GITNEXUS_DEBUG` warning instead of silently caching empty string.
- `createHookToolDir` helper accepts `lsofOutputLines` and
`psOutputByPid`; the multi-PID test uses them instead of duplicating
the fake-binary construction inline.
- All five skip-path tests now assert `result.status === 0` and the
new skip-signal stderr line.
- `AGENTS.md` documents the seven hook configuration env vars
(`GITNEXUS_HOOK_CLI_PATH`, `_LSOF_PATH`, `_PS_PATH`,
`_POWERSHELL_PATH`, `_LINUX_PROC_BUDGET_MS`, `_RM_TARGET`,
`GITNEXUS_DEBUG`).
- `GITNEXUS_DEBUG` path in `gitnexus-hook.cjs`/`.js` writes the full
discarded stderr prefix instead of a 180-char preview.
- Inline comment in `hook-db-lock-probe.cjs` explains the intentional
Windows ETIMEDOUT fail-closed semantics.
- Removed the unnecessary `as WriteFileOptions` cast and orphaned
`import type { WriteFileOptions }` in `hooks.test.ts`.
P3:
- `isGitNexusServerCommand` unexported from
`hook-db-lock-probe.cjs` (kept as private helper).
- Env-path overrides (`GITNEXUS_HOOK_CLI_PATH`,
`_POWERSHELL_PATH`, `_LSOF_PATH`, `_PS_PATH`) require
`fs.existsSync` before being returned, so typos / stale config fall
through to the standard resolution chain.
Misc:
- `gitnexus/package.json` engines.node back to `>=22.0.0` (matches
origin/main and the original PR reviewer's earlier request).
Twin-tree parity / CI sync mechanism tracked separately at
abhigyanpatwari/GitNexus#1591.
Test plan: vitest run test/unit/hooks.test.ts → 113 passed,
18 Unix-only skipped; setup.test.ts → 14 passed.
* chore(autofix): apply prettier + eslint fixes via /autofix command
* trigger
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
* feat:(wiki) added --timeout and --retries flags for large module pages to mitigate timeout aborts
* docs(wiki): document --timeout and --retries options
* docs(wiki): document --timeout and --retries in SKILL.md
---------
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
* fix(hooks): cap concurrent augment subprocesses to prevent runaway process spawn (#1486)
When Claude Code fires PreToolUse hooks for parallel Grep/Glob/Bash tool
calls, each invocation spawned its own `gitnexus augment` subprocess —
a Node + LadybugDB cold start that holds resources for several seconds.
Under heavy parallel search load (issue #1486: 180+ piled-up processes,
load avg > 100), these accumulated faster than they completed because
nothing capped concurrent in-flight augments.
Add a lockfile-based concurrency guard under `<.gitnexus>/.hook-locks/`:
each running hook claims a `<pid>.lock`, the guard counts live PIDs and
prunes stale entries (>30s mtime or pid no longer alive), and bails
silently when MAX_INFLIGHT (3) is reached. Augment is best-effort
enrichment — missing a few fires under burst load is preferable to
melting the system.
Applied to all three hook variants that spawn augment:
- gitnexus/hooks/claude/gitnexus-hook.cjs (npm-installed Claude hook)
- gitnexus-claude-plugin/hooks/gitnexus-hook.js (plugin Claude hook)
- gitnexus-cursor-integration/hooks/gitnexus-hook.cjs (Cursor hook)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(hooks): make augment concurrency cap a hard cap via atomic slot files
Address Claude's review of #1510. The original count-then-claim guard had
a TOCTOU window: N hooks could each read `active < MAX_INFLIGHT` between
readdirSync and the per-pid `wx` write and all proceed, briefly exceeding
the cap. The PR title's "cap" language overstated this.
Replace with fixed-name `slot-0.lock` ... `slot-N.lock` under `.hook-locks/`.
`O_CREAT|O_EXCL` on a fixed path is OS-atomic — exactly one process wins
each slot, so the cap is hard regardless of burst arrival timing. Each
slot file contains the owning PID so stale-takeover still works when a
hook crashes without releasing.
PID liveness is checked before age (Claude's Finding 3): a slow-but-alive
hook is never wrongly evicted. The 30s age window only kicks in to defend
against PID reuse on a long-abandoned slot, well above the 7s augment
timeout so a healthy run never hits it.
Also adds the missing concurrency-guard tests to cursor-hook.test.ts
(Claude's Finding 2): source-level wiring + dead-PID reclaim + 3-slots-full
bail. Previously only the CJS and Plugin variants had test coverage for
the guard; the Cursor variant was validated only by code inspection.
Tests: 5726 passing, +9 from baseline (1 hard-cap burst test + 4 source
regressions in hooks.test.ts; 3 source + 2 integration in cursor-hook.test.ts).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(hooks): inspect slot mtime + content via single fd (codeql TOCTOU)
CodeQL flagged the stale-takeover path in acquireHookSlot as a potential
filesystem race (js/file-system-race): statSync(slotPath) followed by
readFileSync(slotPath) gives a TOCTOU window where the file could be
swapped between the metadata check and the content read.
Replace the two separate path-based calls with a single openSync + fstatSync
+ readSync + closeSync sequence. Both mtime and owner PID now come from the
same file descriptor, so the operations are atomic on one inode. No
behavioral change beyond closing the race.
Applied to all three hook variants (CJS, Plugin, Cursor).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(hooks): distinguish EPERM from ESRCH in PID liveness check
Cursor Bugbot caught a contradiction with the stated design: the bare
`catch` after `process.kill(owner, 0)` was treating EPERM (process exists
but owned by another user) the same as ESRCH (process gone), which would
evict a live slot whenever the lock dir straddled user boundaries.
Inspect the error code: ESRCH → dead, evict; EPERM → still alive, keep
the slot; anything else → assume alive (be conservative under unexpected
failure rather than over-evict).
Applied to all three hook variants.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(hooks): fail closed when lock dir cannot be created
Previously the mkdirSync catch in acquireHookSlot returned `() => {}`
(a truthy no-op). The caller checks `if (!release) return;` to skip
augment when the guard can't be established — but a truthy no-op
slipped through that check and let augment spawn unguarded. On a
cross-user shared `.gitnexus/` or read-only filesystem, N concurrent
hooks would each take that branch and reintroduce the #1486 fan-out
the guard exists to prevent.
Return `null` instead so the caller's `if (!release) return;` skips
augment cleanly. Augment is best-effort enrichment — skipping it when
the guard fails is strictly safer than running unguarded.
Also clarify the stale-slot comment: PID-liveness wins for slots
younger than HOOK_LOCK_STALE_MS, but age is the final arbiter beyond
30s (PID-reuse defense). The previous wording said "PID-liveness wins
over age" without qualifying it, which contradicted the >30s branch.
Add source-level regression tests in hooks.test.ts and
cursor-hook.test.ts asserting acquireHookSlot returns null (not
() => {}) on lock-dir failure. Note in the Cursor test file that the
10-spawner burst test is not duplicated because the algorithm is
byte-for-byte identical to the CJS hook and already covered there.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(hooks): extract lock guard into helper modules
Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/04dd20c5-28fd-433a-83cf-ad83fd03fb32
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
* fix(hook): resolve canonical repo root + guard read-only FTS ensure (#1224)
Two bugs in the Claude Code hook + query layer integration:
1. `findGitNexusDir` (in `gitnexus/hooks/claude/gitnexus-hook.cjs` and
`gitnexus-claude-plugin/hooks/gitnexus-hook.js`) walked upward from
cwd looking for a non-registry `.gitnexus/`. In linked git worktrees
created via `git worktree add`, the canonical repo's `.gitnexus/`
never sits above the worktree path, so the walk silently fails and
neither augmentation nor staleness notifications fire.
Fix: keep the cwd-walk as the fast path, then fall back to
`git rev-parse --git-common-dir` to resolve the shared `.git/`
directory (which lives inside the canonical repo across all linked
worktrees) and walk up from its parent. Returns null cleanly when
`git` isn't on PATH or cwd isn't inside any working tree.
2. `ensureFTSIndex` in the LadybugDB adapter rethrew when the active
connection is read-only (e.g. the MCP query pool, which opens DBs
read-only by design). Defensive callers used to surface five
"Cannot execute write operations in a read-only database" warnings
per query.
Fix: extract `isReadOnlyDbError` (mirroring the existing
`isDbBusyError` discriminator) and have `ensureFTSIndex` catch the
read-only error, cache the key, and return silently. Index creation
is owned by `gitnexus analyze` on a writable connection — the
ensure call is safely a no-op on the read pool. Lock / busy /
"already exists" / schema errors continue to propagate.
Tests:
- `test/unit/hooks.test.ts`: new "Linked git worktree resolution"
block exercises both hooks against a real linked worktree to confirm
PostToolUse stale notifications fire, plus a negative case when the
canonical repo has no `.gitnexus/`.
- `test/unit/lbug-readonly-error.test.ts`: new file unit-tests the
`isReadOnlyDbError` discriminator (positive matches, case
insensitivity, non-Error inputs, and unrelated errors that must
still surface — lock contention, "already exists", schema misses).
- `test/integration/lbug-core-adapter.test.ts`: extends the existing
FTS coverage with an idempotency assertion for `ensureFTSIndex` to
pin the read-only guard's success-path contract.
Verified with `npx tsc --noEmit` and `vitest run` on the affected
files (hooks + readonly + lbug-core-adapter + bm25-search +
lbug-extension-loader + lbug-embedding-hashes — 136 tests pass).
Build: `npm run build` succeeds.
Closes#1224
* fix(local-backend): cover supported vector path
Add the supported-platform regression assertion for QUERY_VECTOR_INDEX and align the unsupported VECTOR diagnostic wording with platform policy.
Made-with: Cursor
---------
Co-authored-by: Gergo Magyar <gergomagyar@icloud.com>
* fix(hooks): ignore global registry during staleness checks
* test(hooks): cover indexed repos under global registry
---------
Co-authored-by: laplace young <yangqk12@whu.edu.cn>
* feat: configure prettier with pre-commit hook integration
Add prettier, lint-staged, and prettier-plugin-tailwindcss at the repo
root with husky pre-commit hook integration. Moves husky from
gitnexus/ to root package.json for reliable hook installation.
- Root package.json with prepare/format/format:check scripts
- .prettierrc with endOfLine:lf and tailwindStylesheet for TW v4
- .prettierignore excluding fixtures, vendor, generated, *.d.ts, *.md
- .gitattributes enforcing LF line endings for Windows consistency
- Pre-commit hook uses direct node_modules/.bin/ paths (no npx)
* style: apply prettier formatting to entire codebase
One-time bulk format. No logic changes.
Use .git-blame-ignore-revs to skip this commit in git blame.
* chore: add .git-blame-ignore-revs for prettier format commit
* perf: pre-commit hook runs only tests related to staged files
Use vitest --related to scope test execution to tests that import
the changed files, instead of running the full suite on every commit.
* perf: remove vitest from pre-commit hook, keep in CI only
Pre-commit now runs lint-staged + tsc only. Tests run in CI
(ci-tests.yml) where they belong — keeps commits fast.
* ci: add prettier format check to quality workflow
PRs will now fail if code isn't formatted with prettier.
* refactor: migrate from KuzuDB to LadybugDB v0.15
KuzuDB was archived (Apple acquisition, Oct 2025). LadybugDB is the
community fork with full API compatibility.
- Package swap: kuzu → @ladybugdb/core, kuzu-wasm → @ladybugdb/wasm-core
- Rename all internal paths: kuzu → lbug (adapters, schema, storage)
- Storage path: .gitnexus/kuzu → .gitnexus/lbug (with auto-cleanup)
- Add explicit VECTOR extension loading (required in v0.15)
- Update CI workflow, documentation, and all tests
- 1151 unit + 27 integration tests passing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address code review findings (P1-P3)
P1: Fix WASM adapter to use getAll() API, wire cleanupOldKuzuFiles
into analyze command, add symlink path traversal protection.
P2: Cache VECTOR extension load state, batch augmentation engine
queries (20→4), fix web getCopyQuery for multi-language tables,
fix stale KuzuDB references, correct brainstorm package names.
P3: Complete lbug-wasm.d.ts type declarations, batch semantic
search per-label, update stale BM25 comment.
* chore: remove outdated KuzuDB migration brainstorming document
* fix: load FTS extension in MCP pool adapter on init
The read-only pool adapter never loaded the FTS extension, so all
QUERY_FTS_INDEX calls failed silently. This broke search-pool and
augmentation integration tests, and caused empty results in the
web UI server mode.
* feat: implement shared Database caching and connection reference counting
* feat: enhance KuzuDB migration handling and status reporting
* fix: mock cleanupOldKuzuFiles in local backend callTool tests
* fix: update mock for cleanupOldKuzuFiles and adjust imports in callTool tests
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Adds PostToolUse hook that detects stale GitNexus index after git mutations (commit, merge, rebase, cherry-pick, pull) and notifies the agent to reindex. Uses lightweight staleness check (git rev-parse HEAD vs meta.json) instead of running gitnexus analyze synchronously, avoiding KuzuDB corruption and 120s blocks. Security and cross-platform hardening: remove shell:true from all spawnSync calls, use .cmd extensions on Windows, add path.isAbsolute(cwd) guards, fix setup.ts path escaping with JSON.stringify, use sendHookResponse() consistently. Includes 73 regression tests.
Skill descriptions were too tool-centric ("using knowledge graph", "blast
radius") which prevented Claude Code from matching them to user intent.
Rewritten to user-intent-driven format with "Use when..." phrasing and
example trigger phrases so Claude can semantically match user requests.
Updated across all 3 sources: gitnexus/skills/, gitnexus-claude-plugin/skills/,
.claude/skills/, and the ai-context.ts fallback generator.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix hook exit status check: || → && so failed augment errors
don't get injected into Claude's context as graph results
- Add exit status check to npx fallback (same bug)
- Update plugin version from 1.2.11 to 1.3.3 in both
marketplace.json and plugin.json
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Skill folder names determine invocation paths in Claude Code plugins
(e.g. plugin:gitnexus:gitnexus-cli). Generic names like "cli" or
"debugging" could collide with other plugins, so prefix them all with
gitnexus- for clarity.
Updated across plugin dirs, main package source files, ai-context.ts
generator, setup.ts installer, and all CLAUDE.md/AGENTS.md routing tables.
Skill names should match folder names since the plugin namespace
(gitnexus:) already provides context. Avoids redundant display like
gitnexus:gitnexus-cli → now gitnexus:cli.
Bundle MCP server config (.mcp.json), fix hook to use spawnSync with npx
fallback and read stderr (KuzuDB stdout workaround), wire plugin.json with
hooks/mcpServers paths, add guide skill with tools/resources/schema reference,
add AMP-compatible mcp.json to all skill dirs, and slim CLAUDE.md generator
by moving reference content into the guide skill.
