Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 6 additions & 9 deletions cmd/corral/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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:]) {
Expand Down
68 changes: 68 additions & 0 deletions cmd/corral/mcp_findings.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ package main

import (
"context"
"errors"
"fmt"
"io"
"sort"
Expand Down Expand Up @@ -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{
Expand Down
174 changes: 174 additions & 0 deletions cmd/corral/mcp_store_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
Loading
Loading