diff --git a/CHANGELOG.md b/CHANGELOG.md index 760bf860..cc15612d 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 diff --git a/cmd/corral/main.go b/cmd/corral/main.go index f9768119..a346b8df 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 c949638e..416eb5bc 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 00000000..0adfdbbe --- /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 00000000..4e12a4a0 --- /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 83dbc0b0..10949434 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 8a9cdef8..87ec3e3f 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()