Skip to content

corral mcp: open the findings store read-only, per call, so concurrent sessions can start - #521

Merged
pdbethke merged 3 commits into
mainfrom
fix/mcp-read-only-store
Nov 19, 2026
Merged

pdbethke merged 3 commits into
mainfrom
fix/mcp-read-only-store

Conversation

@pdbethke

Copy link
Copy Markdown
Owner

Defect, as observed (2026-11-12)

corral mcp is a read-only findings server, registered globally, so every Claude Code session spawns one. It opened the local DuckDB findings store with criticscore.Open: read-write, with CREATE TABLE and migrations, and it kept that handle open for the life of the server. DuckDB allows one read-write process per file. The first session's server therefore held an exclusive lock, and every later session's server failed at startup:

IO Error: Could not set lock on file ".../corralai_criticscore.duckdb": Conflicting lock is held in .../corral (PID n)

The same held handle also stopped certify --local from recording findings for as long as any agent session stayed open.

Fix

  • criticscore.OpenReadOnly(dsn) opens an existing store with DuckDB's access_mode=read_only. It runs no DDL and no migrations. It pings at open, so a lock conflict shows up there and not on the first query. If the local file is missing it returns criticscore.ErrNoStore and does not create the file. An md: DSN passes through with only the access mode added.
  • corral mcp now serves storeFindings{path}. That reader opens the store read-only for each tool call and closes it before returning, so an idle server holds no lock at all. The path comes from statedir.Path, not PathForWrite, because a reader should not create a directory.
    • Why open per call rather than once read-only: DuckDB does not let a read-only open share the file with a read-write one, in either direction. A server that held even a read-only handle would still block certify --local for the whole agent session. Opening per call costs one open for each tool call, and an agent makes only a handful.
  • Store does not exist yet: this behaviour changes. Before, the server created the state directory and an empty store at startup. Now it starts, answers list_audit_findings with total: 0, answers get_audit_finding with the existing "no finding" error, and creates neither the file nor its directory.
  • The mcp verb opens no other store. I grepped the case "mcp": path and mcp_findings.go, and criticscore is the only open.

The DuckDB limit, stated honestly

Read-only opens share the file with each other across processes. They do not share with a concurrent read-write process. A tool call made while certify --local (or corral criticscore confirm|refute) is writing the store fails. It now fails with an error that names the cause and says to retry, not with DuckDB's lock text alone. The limit is written in OpenReadOnly's doc comment, and a test executes it (TestOpenReadOnlyStillBlockedByAConcurrentWriter). If a DuckDB upgrade lifts the limit, that test fails, and the comment should then change.

A side effect: because no migration runs, a store last written by an older corral is read at its own schema. A query that names a newer column fails with DuckDB's error and does not migrate a file the reader was never meant to change. Any certify --local brings the store forward. This is documented on OpenReadOnly.

Tests (competing session in a SEPARATE process)

DuckDB's lock is per process, so the competing session runs in a separate process: the test binary re-execs itself as the holder, the same shape as statedir's TestHelperHoldDuckDB. These tests use the real opener against real DuckDB files, with no mocks.

  • internal/criticscore: two read-only opens across processes both succeed and read the data. Read-only is still blocked by a writer in another process. A missing store returns ErrNoStore and is not created.
  • cmd/corral (storeFindings, the reader the server actually serves):
    • It reads while another process holds the store.
    • After a call returns, another process can open the store read-write.
    • A missing store gives total: 0 through a real in-memory MCP client, and neither the file nor its directory is created.
    • While a writer holds the store, the call returns the plain-words error.

RED (the reader stub used criticscore.Open, and OpenReadOnly was stubbed to Open), which reproduces the production error exactly:

--- FAIL: TestOpenReadOnlySharesAcrossProcesses
    a second read-only open failed while another process held one: ... IO Error: Could not set lock on file ".../cs.duckdb": Conflicting lock is held in .../criticscore.test (PID 3105306)
--- FAIL: TestOpenReadOnlyDoesNotCreateAMissingStore
--- FAIL: TestMCPStoreReadsWhileAnotherSessionHoldsIt   (Conflicting lock is held)
--- FAIL: TestMCPStoreMissingIsEmptyAndNotCreated       (IO Error: Cannot open file ...)
--- FAIL: TestMCPStoreBusyWriterIsExplained

GREEN after the fix: all pass.

I also ran a smoke test against the real binary, using a temporary state dir over stdio JSON-RPC. With no store, list_audit_findings returned zero findings and the state dir was not created. With a seeded store, server A was held alive while server B started, and both returned the finding.

Gates

  • go build ./...: ok
  • go vet ./...: ok
  • gofmt -l ./cmd ./internal: prints nothing
  • go test ./... -count=1: green, 102 packages ok, 0 failures
  • bash scripts/check-licensing.sh: OK
  • bash scripts/gen-cli-docs.sh --check: OK. mcp -h text is unchanged.
  • bash scripts/check-security.sh: gofmt and gosec pass. govulncheck FAILS on GO-2026-6859, a Go 1.26.10 stdlib net/http issue fixed in 1.26.11. It has nothing to do with this change, and a separate PR bumps Go.
  • Printed-metrics gate: no new printing function. busyWriter returns an error and does not print.

🤖 Generated with Claude Code

pdbethke and others added 3 commits November 12, 2026 09:10
…cond agent session's server can start.

`corral mcp` is a read-only findings server that every Claude Code session
spawns, but it opened the local DuckDB store with criticscore.Open:
read-write, with CREATE TABLE and migrations, held for the server's whole
life. DuckDB allows one read-write process per file, so the first session's
server held an exclusive lock and every later session's server died at
startup with "IO Error: Could not set lock ... Conflicting lock is held"
(observed 2026-11-12). The same held handle kept `certify --local` from
recording findings for as long as any agent session stayed open.

criticscore.OpenReadOnly opens an existing store with access_mode=read_only
and runs no DDL; a missing local file returns ErrNoStore without creating
anything. `corral mcp` now opens through it for each tool call and closes
before returning, so readers share the file and an idle server holds no
lock at all. A missing store reads as zero findings and is not created
(the old path created the state directory and an empty store at start).

The DuckDB limit is not removed, only narrowed, and both tests and comments
say so: a read-only open cannot share with a concurrent read-write process
in either direction, so a tool call made while `certify --local` writes the
store fails, now with an error that says why. A test executes that limit so
a DuckDB upgrade that lifts it shows up as a failing test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…meone running corral mcp in more than one agent session, including the write that still blocks a read, because the fix changes start-up behaviour and had no entry.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@pdbethke
pdbethke merged commit 2d6f910 into main Nov 19, 2026
9 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 19, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant