From 244b496cf4a9b99346d469a5beab2460d6562619 Mon Sep 17 00:00:00 2001 From: Peter D Bethke Date: Thu, 12 Nov 2026 09:10:04 -0500 Subject: [PATCH 1/2] Open the findings store read-only, per call, in `corral mcp`, so a second 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 --- cmd/corral/main.go | 15 +-- cmd/corral/mcp_findings.go | 68 ++++++++++ cmd/corral/mcp_store_test.go | 174 ++++++++++++++++++++++++++ internal/criticscore/readonly_test.go | 128 +++++++++++++++++++ internal/criticscore/store.go | 69 +++++++++- internal/criticscore/store_test.go | 21 ++++ 6 files changed, 465 insertions(+), 10 deletions(-) create mode 100644 cmd/corral/mcp_store_test.go create mode 100644 internal/criticscore/readonly_test.go diff --git a/cmd/corral/main.go b/cmd/corral/main.go index f97681193..a346b8df3 100644 --- a/cmd/corral/main.go +++ b/cmd/corral/main.go @@ -536,19 +536,16 @@ func main() { } // Serve the findings to a coding agent over stdio, read-only, from the // same local store `certify --local` writes. See mcp_findings.go for - // why adjudication is deliberately absent from that surface. - criticPath, err := statedir.PathForWrite(statedir.CriticScoreDB) + // why adjudication is deliberately absent from that surface, and + // storeFindings for why the store is opened read-only per call rather + // than held: every agent session runs one of these at once. Path, not + // PathForWrite: a reader creates no directory. + criticPath, err := statedir.Path(statedir.CriticScoreDB) if err != nil { fmt.Fprintln(os.Stderr, "corral mcp:", err) os.Exit(1) } - cs, err := criticscore.Open(criticPath) - if err != nil { - fmt.Fprintf(os.Stderr, "corral mcp: opening the local findings store: %v\n", err) - os.Exit(1) - } - defer func() { _ = cs.Close() }() - os.Exit(runFindingsMCP(context.Background(), cs, os.Stderr)) + os.Exit(runFindingsMCP(context.Background(), storeFindings{path: criticPath}, os.Stderr)) case "criticscore": // -h must not open a store; see the scorecard case above. if verbWantsHelp(os.Args[2:]) { diff --git a/cmd/corral/mcp_findings.go b/cmd/corral/mcp_findings.go index c949638e0..416eb5bcc 100644 --- a/cmd/corral/mcp_findings.go +++ b/cmd/corral/mcp_findings.go @@ -4,6 +4,7 @@ package main import ( "context" + "errors" "fmt" "io" "sort" @@ -104,6 +105,73 @@ type findingReader interface { Get(ctx context.Context, id string) (criticscore.Finding, bool, error) } +// storeFindings is the findingReader `corral mcp` serves: the local findings +// store at path, opened READ-ONLY for each call and closed before the call +// returns. +// +// Why read-only: every coding-agent session on the machine spawns its own +// `corral mcp`. When this opened the store with criticscore.Open (read-write, +// plus CREATE TABLE and migrations), the first session held DuckDB's exclusive +// lock and every later session's server died at startup with "Conflicting lock +// is held" (observed 2026-11-12). Read-only opens share the file across +// processes. +// +// Why per call rather than once at startup: DuckDB does NOT let a read-only +// open share with a read-write one, in either direction. A server holding even +// a read-only handle for its whole life would keep `certify --local` from +// recording findings for as long as any agent session stays open. Opening per +// call narrows that to the milliseconds a query takes; the cost is one open +// per tool call, which an agent makes a handful of times. What remains: a call +// made while a run is writing the store fails, with busyWriter's explanation. +// +// A store that does not exist yet (nothing has run `certify --local` here) is +// read as zero findings and is NOT created: this is a reader, and the open +// below cannot create the file. The previous behaviour created both the state +// directory and an empty store at server start. +type storeFindings struct{ path string } + +// open returns nil, nil when there is no store yet. +func (s storeFindings) open() (*criticscore.Store, error) { + cs, err := criticscore.OpenReadOnly(s.path) + if errors.Is(err, criticscore.ErrNoStore) { + return nil, nil + } + if err != nil { + return nil, busyWriter(err) + } + return cs, nil +} + +func (s storeFindings) All(ctx context.Context) ([]criticscore.Finding, error) { + cs, err := s.open() + if cs == nil || err != nil { + return nil, err + } + defer func() { _ = cs.Close() }() + return cs.All(ctx) +} + +func (s storeFindings) Get(ctx context.Context, id string) (criticscore.Finding, bool, error) { + cs, err := s.open() + if cs == nil || err != nil { + return criticscore.Finding{}, false, err + } + defer func() { _ = cs.Close() }() + return cs.Get(ctx, id) +} + +// busyWriter says in plain words what DuckDB's lock error means here: some +// corral process has the store open read-write, which no read-only open can +// share. Any other error passes through unchanged. +func busyWriter(err error) error { + msg := err.Error() + if strings.Contains(msg, "Could not set lock") || strings.Contains(msg, "Conflicting lock") { + return fmt.Errorf("another corral process is writing the findings store (a running `certify --local`, or `corral criticscore confirm|refute`); "+ + "DuckDB lets no reader share the file with a writer, so retry when it finishes: %w", err) + } + return err +} + // registerFindingTools wires the read-only findings tools onto s. func registerFindingTools(s *mcp.Server, r findingReader) { mcp.AddTool(s, &mcp.Tool{ diff --git a/cmd/corral/mcp_store_test.go b/cmd/corral/mcp_store_test.go new file mode 100644 index 000000000..0adfdbbe2 --- /dev/null +++ b/cmd/corral/mcp_store_test.go @@ -0,0 +1,174 @@ +// SPDX-License-Identifier: Elastic-2.0 + +//go:build cgo && unix + +package main + +import ( + "bufio" + "context" + "io" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/pdbethke/corralai/internal/criticscore" +) + +// These drive the reader `corral mcp` actually serves (storeFindings) against +// a real DuckDB file, with the competing session in a SEPARATE process: +// DuckDB's lock is per process, so a second handle in this one would prove +// nothing. Observed 2026-11-12: every Claude Code session spawns its own +// `corral mcp`, the first held the store read-write, and every later one died +// at startup with "Conflicting lock is held". + +const mcpHoldEnv = "CORRAL_TEST_HOLD_FINDINGS" + +// TestHelperHoldFindingsStore is not a test: the parent re-execs the test +// binary into it so a DIFFERENT process holds the store, as another session's +// `corral mcp` ("ro") or a running `certify --local` ("rw") would. +func TestHelperHoldFindingsStore(t *testing.T) { + spec := os.Getenv(mcpHoldEnv) + if spec == "" { + t.Skip("helper process only") + } + mode, path, _ := strings.Cut(spec, ":") + open := criticscore.OpenReadOnly + if mode == "rw" { + open = criticscore.Open + } + s, err := open(path) + if err != nil { + t.Fatal(err) + } + _, _ = os.Stdout.WriteString("ready\n") + _, _ = io.ReadAll(os.Stdin) + _ = s.Close() +} + +// startFindingsHolder runs the helper holding path in mode. It returns a +// stop function; the holder is also stopped at cleanup. ok is false when the +// holder could NOT open the store (its output is in msg). +func startFindingsHolder(t *testing.T, mode, path string) (msg string, ok bool, stop func()) { + t.Helper() + cmd := exec.Command(os.Args[0], "-test.run=^TestHelperHoldFindingsStore$") // #nosec G204 -- re-exec of this test binary + cmd.Env = append(os.Environ(), mcpHoldEnv+"="+mode+":"+path) + stdin, err := cmd.StdinPipe() + if err != nil { + t.Fatal(err) + } + stdout, err := cmd.StdoutPipe() + if err != nil { + t.Fatal(err) + } + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + stopped := false + stop = func() { + if !stopped { + stopped = true + _ = stdin.Close() + _ = cmd.Wait() + } + } + t.Cleanup(stop) + line, _ := bufio.NewReader(stdout).ReadString('\n') + return line, strings.TrimSpace(line) == "ready", stop +} + +func seedFindingsStore(t *testing.T) string { + t.Helper() + path := filepath.Join(t.TempDir(), "cs.duckdb") + rw, err := criticscore.Open(path) + if err != nil { + t.Fatal(err) + } + if err := rw.Record(context.Background(), sampleFindings()); err != nil { + t.Fatal(err) + } + if err := rw.Close(); err != nil { + t.Fatal(err) + } + return path +} + +// Two sessions at once: another process already serves the store, and this +// session's reader still lists and gets findings. +func TestMCPStoreReadsWhileAnotherSessionHoldsIt(t *testing.T) { + path := seedFindingsStore(t) + if msg, ok, _ := startFindingsHolder(t, "ro", path); !ok { + t.Fatalf("holder could not open the store read-only: %q", msg) + } + r := storeFindings{path: path} + all, err := r.All(context.Background()) + if err != nil { + t.Fatalf("second session could not read while another held the store: %v", err) + } + if len(all) != len(sampleFindings()) { + t.Fatalf("read %d findings, want %d", len(all), len(sampleFindings())) + } + if _, ok, err := r.Get(context.Background(), "32:1"); err != nil || !ok { + t.Fatalf("get 32:1: ok=%v err=%v", ok, err) + } +} + +// An idle `corral mcp` must not keep a writer out: after a call returns, a +// separate process can open the store read-write, as `certify --local` must. +func TestMCPStoreHoldsNoLockBetweenCalls(t *testing.T) { + path := seedFindingsStore(t) + r := storeFindings{path: path} + if _, err := r.All(context.Background()); err != nil { + t.Fatal(err) + } + if msg, ok, _ := startFindingsHolder(t, "rw", path); !ok { + t.Fatalf("a writer could not open the store after an mcp call returned: %q", msg) + } +} + +// No store yet (no `certify --local` has run on this machine): the server +// answers with zero findings and does NOT create the file. +func TestMCPStoreMissingIsEmptyAndNotCreated(t *testing.T) { + path := filepath.Join(t.TempDir(), "state", "corralai_criticscore.duckdb") + r := storeFindings{path: path} + all, err := r.All(context.Background()) + if err != nil { + t.Fatalf("missing store should read as no findings, got %v", err) + } + if len(all) != 0 { + t.Fatalf("missing store returned %d findings", len(all)) + } + if _, ok, err := r.Get(context.Background(), "1:1"); err != nil || ok { + t.Fatalf("get on a missing store: ok=%v err=%v, want not found", ok, err) + } + if _, statErr := os.Stat(path); !os.IsNotExist(statErr) { + t.Fatalf("reading created %s (stat err %v)", path, statErr) + } + if _, statErr := os.Stat(filepath.Dir(path)); !os.IsNotExist(statErr) { + t.Fatalf("reading created the directory %s", filepath.Dir(path)) + } + out := callTool(t, r, "list_audit_findings", map[string]any{}) + if !strings.Contains(out, `"total":0`) { + t.Fatalf("list on a missing store = %s, want total 0", out) + } +} + +// While a writer holds the store, a call fails with an error that says why in +// plain words, rather than DuckDB's lock text alone. +func TestMCPStoreBusyWriterIsExplained(t *testing.T) { + path := seedFindingsStore(t) + msg, ok, stop := startFindingsHolder(t, "rw", path) + if !ok { + t.Fatalf("holder could not open the store read-write: %q", msg) + } + defer stop() + _, err := storeFindings{path: path}.All(context.Background()) + if err == nil { + t.Fatal("read succeeded while another process held the store read-write; DuckDB's limit changed — revisit criticscore.OpenReadOnly's comment") + } + if !strings.Contains(err.Error(), "writing the findings store") { + t.Fatalf("error does not explain the busy writer: %v", err) + } +} diff --git a/internal/criticscore/readonly_test.go b/internal/criticscore/readonly_test.go new file mode 100644 index 000000000..4e12a4a05 --- /dev/null +++ b/internal/criticscore/readonly_test.go @@ -0,0 +1,128 @@ +// SPDX-License-Identifier: Elastic-2.0 + +//go:build cgo && unix + +package criticscore_test + +import ( + "bufio" + "context" + "io" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/pdbethke/corralai/internal/criticscore" +) + +// holdEnv names the store, and the mode ("ro" or "rw"), a re-executed test +// binary should hold open. DuckDB's file lock is a per-PROCESS lock, so two +// handles inside one test process prove nothing about the defect this guards: +// every Claude Code session spawns its own `corral mcp`, and the second one +// failed with "Conflicting lock is held". The holder is a separate process +// for that reason. Same shape as statedir's TestHelperHoldDuckDB. +const holdEnv = "CRITICSCORE_TEST_HOLD" + +// TestHelperHoldCriticStore is not a test: the parent re-execs the test +// binary into it so a DIFFERENT process holds the store open. +func TestHelperHoldCriticStore(t *testing.T) { + spec := os.Getenv(holdEnv) + if spec == "" { + t.Skip("helper process only") + } + mode, path, _ := strings.Cut(spec, ":") + open := criticscore.OpenReadOnly + if mode == "rw" { + open = criticscore.Open + } + s, err := open(path) + if err != nil { + t.Fatal(err) + } + _, _ = os.Stdout.WriteString("ready\n") + _, _ = io.ReadAll(os.Stdin) + _ = s.Close() +} + +// holdStore starts a second process holding path open in mode and returns +// once it has. The holder exits at test cleanup. +func holdStore(t *testing.T, mode, path string) { + t.Helper() + cmd := exec.Command(os.Args[0], "-test.run=^TestHelperHoldCriticStore$") // #nosec G204 -- re-exec of this test binary + cmd.Env = append(os.Environ(), holdEnv+"="+mode+":"+path) + stdin, err := cmd.StdinPipe() + if err != nil { + t.Fatal(err) + } + stdout, err := cmd.StdoutPipe() + if err != nil { + t.Fatal(err) + } + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = stdin.Close(); _ = cmd.Wait() }) + line, _ := bufio.NewReader(stdout).ReadString('\n') + if strings.TrimSpace(line) != "ready" { + t.Fatalf("holder process could not open the store %s: %q", mode, line) + } +} + +// seededStore writes one finding through the read-write Open and closes it, +// as a finished `certify --local` leaves the store. +func seededStore(t *testing.T) string { + t.Helper() + path := filepath.Join(t.TempDir(), "cs.duckdb") + rw, err := criticscore.Open(path) + if err != nil { + t.Fatal(err) + } + if err := rw.Record(context.Background(), []criticscore.Finding{ + {ID: "1:1", RecordID: 1, Model: "m", Scope: "whole-test", Adjudication: "unadjudicated", Source: "auto"}, + }); err != nil { + t.Fatal(err) + } + if err := rw.Close(); err != nil { + t.Fatal(err) + } + return path +} + +// Two `corral mcp` sessions at once: one process holds the store read-only, +// and a second read-only open in another process succeeds and reads. +func TestOpenReadOnlySharesAcrossProcesses(t *testing.T) { + path := seededStore(t) + holdStore(t, "ro", path) + + ro, err := criticscore.OpenReadOnly(path) + if err != nil { + t.Fatalf("a second read-only open failed while another process held one: %v", err) + } + defer ro.Close() + all, err := ro.All(context.Background()) + if err != nil { + t.Fatal(err) + } + if len(all) != 1 || all[0].ID != "1:1" { + t.Fatalf("read-only handle read %+v, want the one recorded finding", all) + } +} + +// The limit OpenReadOnly's doc comment states, executed rather than asserted: +// a read-only open does NOT share with a concurrent read-write process. If a +// DuckDB upgrade lifts this, this test fails and the comment should change. +func TestOpenReadOnlyStillBlockedByAConcurrentWriter(t *testing.T) { + path := seededStore(t) + holdStore(t, "rw", path) + + ro, err := criticscore.OpenReadOnly(path) + if err == nil { + _ = ro.Close() + t.Fatal("read-only open succeeded while another process held the store read-write; update OpenReadOnly's doc comment") + } + if !strings.Contains(err.Error(), "lock") { + t.Fatalf("want DuckDB's lock conflict, got %v", err) + } +} diff --git a/internal/criticscore/store.go b/internal/criticscore/store.go index 83dbc0b05..109494346 100644 --- a/internal/criticscore/store.go +++ b/internal/criticscore/store.go @@ -13,10 +13,15 @@ package criticscore import ( "context" "database/sql" + "errors" "fmt" - "github.com/pdbethke/corralai/internal/seatrecord" + "io/fs" + "os" + "strings" "time" + "github.com/pdbethke/corralai/internal/seatrecord" + _ "github.com/marcboeker/go-duckdb/v2" ) @@ -75,6 +80,68 @@ func Open(dsn string) (*Store, error) { return &Store{db: db}, nil } +// ErrNoStore is OpenReadOnly's answer for a local store file that does not +// exist yet. It is a distinct error, not an empty Store, so the caller decides +// what "no findings recorded on this machine" means for its surface; a +// read-only open cannot create the file, and must not. +var ErrNoStore = errors.New("criticscore: no findings store yet") + +// OpenReadOnly opens an EXISTING store for reading only: DuckDB's +// access_mode=read_only, and none of Open's CREATE TABLE or migration DDL. It +// is the opener for readers that may run as many processes at once — `corral +// mcp` is spawned by every coding-agent session on the machine, and when it +// used Open the first session's server held DuckDB's exclusive read-write +// lock and every later one failed at startup with "Conflicting lock is held". +// +// The DuckDB limit, stated exactly: read-only opens share the file with each +// other across processes, but NOT with a concurrent read-write process. While +// `certify --local` (or `corral criticscore confirm|refute`) holds the store +// read-write, a read-only open still fails with the same lock error, and a +// running reader still blocks that writer from opening. Only reader-vs-reader +// contention is removed here. (cmd/corral/scorecard.go records the same +// limit for the bugcatch store.) +// +// Because no migration runs, a store last written by an older corral is read +// at its own schema; a query naming a column added since fails with DuckDB's +// error rather than silently migrating a file a reader was never meant to +// change. Opening it once read-write (any `certify --local`) brings it +// forward. +// +// A missing local file returns ErrNoStore without touching the filesystem. +// An `md:` DSN is passed through untouched apart from the access mode. +func OpenReadOnly(dsn string) (*Store, error) { + if local, ok := localPath(dsn); ok { + if _, err := os.Stat(local); errors.Is(err, fs.ErrNotExist) { + return nil, fmt.Errorf("%w at %s", ErrNoStore, local) + } + } + sep := "?" + if strings.Contains(dsn, "?") { + sep = "&" + } + db, err := sql.Open("duckdb", dsn+sep+"access_mode=read_only") + if err != nil { + return nil, fmt.Errorf("criticscore: open %q read-only: %w", dsn, err) + } + // sql.Open is lazy; ping so a lock conflict surfaces here, at open, with + // the path, rather than on the first query a client happens to send. + if err := db.Ping(); err != nil { + _ = db.Close() + return nil, fmt.Errorf("criticscore: open %q read-only: %w", dsn, err) + } + return &Store{db: db}, nil +} + +// localPath reports the filesystem path a DSN names, and false for one that +// names no local file (MotherDuck's md:, or an in-memory database). +func localPath(dsn string) (string, bool) { + p, _, _ := strings.Cut(dsn, "?") + if p == "" || p == ":memory:" || strings.HasPrefix(p, "md:") { + return "", false + } + return p, true +} + // migrateCriticFindings additively brings a ledger created before a schema // change up to the current column set, exactly as bugcatch does: probe // information_schema.columns for what already exists, add only what's diff --git a/internal/criticscore/store_test.go b/internal/criticscore/store_test.go index 8a9cdef81..87ec3e3f4 100644 --- a/internal/criticscore/store_test.go +++ b/internal/criticscore/store_test.go @@ -4,6 +4,8 @@ package criticscore_test import ( "context" + "errors" + "os" "path/filepath" "testing" @@ -20,6 +22,25 @@ func openTmp(t *testing.T) *criticscore.Store { return s } +// A read-only open must not run the schema DDL, and must not create a store +// that does not exist: `corral mcp` is a reader, and a reader that creates +// the file it was asked to read leaves state behind on every machine it is +// registered on. +func TestOpenReadOnlyDoesNotCreateAMissingStore(t *testing.T) { + path := filepath.Join(t.TempDir(), "absent.duckdb") + s, err := criticscore.OpenReadOnly(path) + if err == nil { + _ = s.Close() + t.Fatal("OpenReadOnly of a missing file succeeded; want ErrNoStore") + } + if !errors.Is(err, criticscore.ErrNoStore) { + t.Fatalf("want ErrNoStore, got %v", err) + } + if _, statErr := os.Stat(path); !os.IsNotExist(statErr) { + t.Fatalf("OpenReadOnly created %s (stat err %v)", path, statErr) + } +} + func TestRecordAndPrecision(t *testing.T) { s := openTmp(t) ctx := context.Background() From 15b3d9bcae36230c016818afed0b87b979ce6b63 Mon Sep 17 00:00:00 2001 From: Peter D Bethke Date: Thu, 19 Nov 2026 09:31:05 -0500 Subject: [PATCH 2/2] Say in the changelog what the read-only findings store changes for someone 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 --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 760bf8602..cc15612d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,15 @@ still move between minor versions. Entries describe what changed for someone *using* the tool. For the full commit history of any release, `git log v0.3.4..v0.3.5`. +## [Unreleased] + +### Fixed + +- **`corral mcp` starts in a second agent session.** The findings server opened the local findings store read-write and held it for as long as it ran. DuckDB allows one read-write process per file, so the first session's server locked the store: every later session's server failed at start-up with `Could not set lock on file`, and `certify --local` could not record findings while any agent session stayed open. The server now opens the store read-only for each tool call and closes it before answering, so an idle server holds no lock. + - *What still fails.* DuckDB does not let a reader share the file with a process that is writing it. A tool call made while `certify --local` or `corral criticscore confirm|refute` is writing fails, with an error that names the cause and says to retry. + - *No store yet.* The server no longer creates the state directory or an empty store at start-up. `list_audit_findings` answers `total: 0` and nothing is created. + - *A store written by an older corral* is read at its own schema, because a reader runs no migration; any `certify --local` brings it forward. + ## [v1.0.0-rc.35] — 2026-11-18 ### Fixed