serve and CLI commands cannot coexist — KuzuDB file lock prevents concurrent access

[ShunsukeHayashi]

Environment

• GitNexus version: 1.4.1 (Homebrew / npm global)
• Node.js version: v25.6.1
• OS: macOS (Darwin 25.2.0, ARM64)

Bug

When gitnexus serve is running (e.g. for the Web UI on port 4747), all CLI commands that access the KuzuDB database fail with a file lock error. This includes cypher, context, impact, query, and analyze.

Reproduction

# Terminal 1: Start server
gitnexus serve --port 4747

# Terminal 2: Try any CLI command
gitnexus cypher --repo MY_REPO "MATCH (c:Community) RETURN c.label LIMIT 1" 2>&1
# Error: IO exception: Could not set lock on file : /path/to/.gitnexus/kuzu
# See the docs: https://docs.kuzudb.com/concurrency for more information.

The same error occurs for context, query, impact, status, and analyze --force.

Expected behavior

Ideally, the serve process and CLI commands should be able to share read access to the database. KuzuDB supports concurrent read connections, so this may be solvable by using shared/read-only connections for CLI queries when the server holds the write lock.

Alternatively, the CLI could detect the lock and print a helpful message like:

Error: Database is locked by gitnexus serve (PID 12345).
Run `lsof -ti :4747 | xargs kill` to stop the server first.

Workaround

Kill the server before running CLI commands:

lsof -ti :4747 | xargs kill 2>/dev/null
sleep 2
gitnexus cypher --repo MY_REPO "..."

Impact

This is especially painful when:

1. The Web UI is being used for visual exploration while CLI is needed for scripting
2. The MCP server (gitnexus mcp) is running and CLI commands are attempted in parallel
3. Automated scripts (cron reindex, graph-meta updates) run while the server is active

Related issues: #285, #290 (concurrent query crashes)

[ShunsukeHayashi]

This issue may be resolved in v1.4.5 (LadybugDB migration).

The MCP backend (\src/mcp/core/lbug-adapter.ts) opens databases in read-only mode (line 186), which should allow concurrent access from both \serve\ and CLI tool commands.

The original KuzuDB adapter didn't have read-only support, causing the file lock conflicts described here.

If you're still seeing this on v1.4.5, please let us know — it might be a different code path that still opens with write access.

[ShunsukeHayashi]

Confirmed resolved in v1.4.6 (likely via the LadybugDB migration in v1.4.5 as mentioned above).

Tested concurrent access:

$ gitnexus --version
1.4.6

# Terminal 1: Start server
$ gitnexus serve --port 4848

# Terminal 2: CLI commands while serve is running
$ gitnexus status
# ✅ Works — no file lock error

$ gitnexus cypher --repo MY_REPO "MATCH (c:Community) RETURN c.label LIMIT 2"
# ✅ Works — returns JSON on stdout

$ gitnexus status  # while serve is active
# ✅ Works

All CLI commands (status, cypher, etc.) now coexist with serve without any Could not set lock on file errors.

The read-only mode in the LadybugDB adapter appears to have fully resolved this. Thank you!

This issue can be closed.