feat(mcp): brain_read + brain_edit, contained to the sync source (brain#4) (#96)

brain_read returns a note verbatim; brain_edit is str_replace with an
exactly-once match, operating on the tree brain-sync commits from.

An adversarial design review before implementation changed three things:

1. Governance files are not in the model-facing tool. Brain content is
   ingested from the outside world and reaches a model's context, and that
   model would hold the editor — one poisoned page could rewrite the
   CLAUDE.md a .dispatch-allow agent later loads as instructions. And
   brain-sync merges with --strategy-option=ours, so the live tree beats a
   human's corrective push on the conflicting lines. CLAUDE.md now goes
   through brain_edit_root: de-surfaced from tools/list and gated on the
   local static principal. The scopes are disjoint — the privileged door
   has the smaller reach.

2. Reads needed the same allowlist, and brain_get already lacked it: it
   returned verbatim session transcripts under archive/ by path. A test
   proved the exposure live before the fix.

3. Canonicalise before allowlisting — knowledge/../.git/hooks/post-commit
   would otherwise reach a hook that brain-sync executes in a pod holding
   the Gitea push credentials.

Plus overlapping match counting, UTF-8 validation both ways, refusal while
git is mid-operation, flock with the read inside the lock, atomic
same-dir rename, and reindex only when frontmatter is touched.

Refs brain#4.

Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/mcp/tools_notes_test.go

@@ -0,0 +1,127 @@
+// ingestion/internal/mcp/tools_notes_test.go
+package mcp_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/mcp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---- brain#4: brain_read / brain_edit through the JSON-RPC surface --------
+
+func newBrainRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, ".git"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki/homelab/facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki/homelab/facts/n.md"),
+		[]byte("---\ntitle: 'n'\n---\n\nalpha\nbeta\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "CLAUDE.md"), []byte("# rules\n"), 0o644))
+	return dir
+}
+
+func call(t *testing.T, srv *mcp.Server, name string, args map[string]any) map[string]any {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", body(t, map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": name, "arguments": args},
+	}))
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	return resp
+}
+
+func TestBrainReadAndEdit_RoundTripThroughJSONRPC(t *testing.T) {
+	// The Go functions are tested in internal/notes; this pins the transport,
+	// because a tool that works in-process and is unreachable over JSON-RPC
+	// is indistinguishable from a working one in a unit test.
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_read", map[string]any{"path": "wiki/homelab/facts/n.md"})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	resp = call(t, srv, "brain_edit", map[string]any{
+		"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	got, err := os.ReadFile(filepath.Join(dir, "wiki/homelab/facts/n.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "---\ntitle: 'n'\n---\n\nalpha\nBETA\n", string(got),
+		"only the matched bytes may change")
+}
+
+func TestBrainEdit_RefusesGovernanceFilesFromTheModelFacingTool(t *testing.T) {
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_edit", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error", "brain_edit must not reach CLAUDE.md")
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got))
+}
+
+func TestBrainEditRoot_RefusedWithoutTheLocalStaticPrincipal(t *testing.T) {
+	// No principal in context is the model-facing case (and the default in
+	// this test server): the privileged door must stay shut.
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error")
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got), "governance file must be untouched")
+}
+
+func TestBrainGet_CannotReachSessionTranscripts(t *testing.T) {
+	// Pre-existing hole, not introduced here: api.ReadNote resolves any
+	// brain-relative path and parseFrontmatter returns the WHOLE file as body
+	// when there is no frontmatter fence. archive/ holds verbatim Claude
+	// session transcripts (up to 500 KB) that BM25 never indexes, so they are
+	// invisible to search and trivially readable by path — and CLAUDE.md
+	// documents the layout.
+	dir := newBrainRepo(t)
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "archive/claude-sessions/koala"), 0o755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "archive/claude-sessions/koala/session-1.md"),
+		[]byte("verbatim transcript with tool output\n"), 0o644))
+
+	srv := mcp.NewServer(dir, nil, nil, nil)
+	resp := call(t, srv, "brain_get", map[string]any{"path": "archive/claude-sessions/koala/session-1.md"})
+
+	require.Contains(t, resp, "error", "brain_get must not read outside knowledge/ and wiki/")
+	assert.NotContains(t, string(mustJSON(t, resp)), "verbatim transcript")
+}
+
+func TestBrainGet_StillReadsNotes(t *testing.T) {
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_get", map[string]any{"path": "wiki/homelab/facts/n.md"})
+	assert.NotContains(t, resp, "error", "%v", resp["error"])
+}
+
+func mustJSON(t *testing.T, v any) []byte {
+	t.Helper()
+	b, err := json.Marshal(v)
+	require.NoError(t, err)
+	return b
+}