Keep the store's one connection, delete the seam it cannot survive (V-642)

`SetMaxOpenConns(1)` under WAL gives up concurrent reads, and the task
asked whether that costs anything. Measured over a fixed two-second
window, a paced writer against a read loop, three runs per cap:
reads do not queue. Four connections buy 70µs at p50 on a turn that
spends 1.19s in the resident model, and write throughput more than
halves. A 19ms worst case also cannot be the source of the 2.7s router
figure, so that line of enquiry is closed.

What the cap cannot survive is a long-lived transaction. It holds the
only connection, so a second read never completes: two seconds and
`context deadline exceeded`, against 1ms at a cap of four.

`Store.DB` handed out exactly that transaction. It had been there since
the initial commit with no production caller, and its comment described
a loop that never materialised. Its one user was a test helper reading
`delivery_attempts` by raw SQL, which `ListDeliveryAttempts` has covered
since V-390. So the cap stays and the seam goes, and the hazard is gone
by construction rather than by documentation.

`internal/store/conncap_test.go` stays as the standing measurement,
skipped under -short. The comment at the cap and the one in
`internal/ipc/server.go` that leans on it now state the invariant and
cite the numbers.

Measurement: docs/evals/2026-08-07-store-connection-cap.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -53,7 +53,7 @@ CGO daemons (`mavend`, `mavsttd`, `mavttsd`, `mavenclient`) need the vendored to
 and libs wired through the Makefile — **do not** call `go build` on them bare, use `make`:
 
 ```sh
-make build          # all 9 binaries
+make build          # all 11 binaries
 make build-web      # single daemon (pure-Go ones: web/waked/poll/caldav build without CGO)
 make test           # go test -race across ./internal/... ./cmd/... with CGO env set
 ```
@@ -82,13 +82,31 @@ Pure-Go packages (`router`, `memory`, `mavweb`, …) run under a plain `go test
 | `mavpoll` | Environment poller: netdata alarms, uptime-kuma, zenmoney, wireguard presence. Writes facts, sends nothing. Telegram is `internal/delivery/telegramsink`, not this. |
 | `mavcaldav` | CalDAV calendar sync. |
 | `mavmaild` | Mail reader (IMAP, read-only). Holds the IMAP password; core never sees it. |
+| `mavgpud` | GPU supervisor. **Runs on workpc, not homesrv** — own unit, `deploy/mavgpud.service`. Keeps llama-server loaded while the card is free (V-488). Maven never asks it for anything, it reads `/health` through `llm.Pair`. |
+| `mavupdate` | Not a daemon. Operator CLI a human runs on the box to deploy a new build. |
+
+Two more binaries have no Makefile target and are built with `go run` or `go build` when
+they are needed. Neither is deployed.
+
+| Binary | Role |
+|---|---|
+| `mavseal` | Recovery tool. Encrypts a live tmpfs working copy back to the ciphertext file when mavend was killed before `defer st.Close()` sealed it. |
+| `labelgen` | Runs the stage 0 grammars over utterances and prints JSONL, the training data for the routing heads (V-546). |
 
 Daemons are wired socket-to-socket, not linked. `internal/ipc` is the client/server wire
 protocol; the config in `deploy/mavend.json` (with `${VAR}` env expansion from gitignored
 `deploy/telegram.env`) sets socket paths, model paths, and the phraser/embedder blocks.
 
-**Seven of the nine run on homesrv. `mavwaked` and `mavenclient` do not, and that is the
-decision, not an oversight** (Vikunja #463, `docs/plans/17-where-the-voice-loop-runs.md`).
+**`docker-compose.yml` runs five: `mavend`, `mavsttd`, `mavttsd`, `mavweb`, `mavpoll`.**
+Count against compose, not against the table. Four of the nine daemons are absent, and each
+absence has a different reason.
+
+`mavmaild` is commented out in compose, with the reason written beside it: it needs a mail
+account and this box has none. `mavcaldav` appears nowhere at all, and unlike the other
+three that is an oversight rather than a decision (V-644).
+
+**`mavwaked` and `mavenclient` are absent by decision, not oversight** (Vikunja #463,
+`docs/plans/17-where-the-voice-loop-runs.md`).
 homesrv has a microphone — it is a laptop — but it is in the wrong room, so a wake-word
 daemon there listens to nobody. They belong on a client machine where the owner is standing.
 

cmd/mavend/boot.go

@@ -0,0 +1,120 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net"
+	"sync"
+	"time"
+
+	"github.com/kami/maven/internal/event"
+	"github.com/kami/maven/internal/ipc"
+	"github.com/kami/maven/internal/store"
+)
+
+// The two boot paths meet here. run() wires the daemon twice: once at boot
+// when a key is in the environment, and once inside UnlockFn after a passkey
+// assertion, minutes or days later. Listing the same wiring in both places is
+// what let them drift — seven workers started untracked on the unlock path and
+// two daemonAPI fields were never set there, silently, for as long as anyone
+// had been cold-starting (V-639).
+//
+// So both paths call newDaemonAPI and startBackground and nothing else. A
+// field or a worker added later reaches both paths or neither.
+
+// bootDeps is everything the two constructors below read. It is filled from
+// the same variables on both paths, by depsNow in run().
+type bootDeps struct {
+	coreFor    func() ipc.CoreAPI
+	tl         *tickLoop
+	evBus      *event.Bus
+	voiceW     *voiceWiring
+	st         *store.Store
+	factWorker *factEnrichmentWorker
+	evalWorker *memoryEvalWorker // nil ⇒ memory evaluation off (the default)
+	feedWkr    *feedWorker       // nil ⇒ no feed is read (the default)
+	crawlWkr   *crawlWorker      // nil ⇒ no page is watched (the default)
+}
+
+// newDaemonAPI builds the real CoreAPI, with every field set. The unlock path
+// used to leave nexus and getMCPServers nil, so after a cold start
+// ResolveEntity refused with a nexus block configured and /tools rendered
+// "not configured" with an mcp block configured. Empty is a wrong answer
+// there, not a degraded one.
+func newDaemonAPI(d bootDeps) *daemonAPI {
+	api := &daemonAPI{
+		CoreAPI:          d.coreFor(),
+		getTrace:         d.tl.trace,
+		getMorningStatus: func(ctx context.Context) []ipc.MorningRoutineStatus { return d.tl.morningStatus(ctx, time.Now()) },
+		getDayPlan:       func(ctx context.Context) ipc.DayPlan { return d.tl.dayPlan(ctx, time.Now()) },
+		getEvents:        intakeEventsFn(d.evBus),
+		getDecisions:     turnDecisionsFn(d.voiceW),
+		seedStore:        seedStoreIfAllowed(d.st),
+		nexus:            nexusOf(d.voiceW),
+	}
+	if d.voiceW != nil && d.voiceW.handler != nil {
+		api.chatFn = d.voiceW.handler.handleText
+		// And the reverse: the handler was wired with the bare store adapter,
+		// which cannot serve the day plan. See upgradeAPI.
+		d.voiceW.handler.upgradeAPI(api)
+	}
+	if d.voiceW != nil && d.voiceW.mcp != nil {
+		api.getMCPServers = d.voiceW.mcp.status
+	}
+	return api
+}
+
+// namedWorker is one long-running goroutine. The name exists so the set is
+// assertable from a test and readable in a log; nothing dispatches on it.
+type namedWorker struct {
+	name string
+	run  func(ctx context.Context)
+}
+
+// backgroundWorkers lists what this deployment runs. It is pure — it starts
+// nothing — so a test can compare the set the two paths would start without
+// standing a daemon up.
+func backgroundWorkers(d bootDeps) []namedWorker {
+	var ws []namedWorker
+	if d.voiceW != nil && d.voiceW.server != nil {
+		ws = append(ws, namedWorker{"voice", func(context.Context) {
+			if err := d.voiceW.server.Serve(); err != nil && !errors.Is(err, net.ErrClosed) {
+				log.Printf("voice serve: %v", err)
+			}
+		}})
+	}
+	ws = append(ws,
+		namedWorker{"tick", d.tl.run},
+		namedWorker{"fact-enrichment", d.factWorker.run},
+	)
+	if d.evalWorker != nil {
+		ws = append(ws, namedWorker{"memory-eval", d.evalWorker.run})
+	}
+	if d.feedWkr != nil {
+		ws = append(ws, namedWorker{"feed", d.feedWkr.run})
+	}
+	if d.crawlWkr != nil {
+		ws = append(ws, namedWorker{"crawl", d.crawlWkr.run})
+	}
+	if d.voiceW != nil && d.voiceW.mcp != nil {
+		ws = append(ws, namedWorker{"mcp", d.voiceW.mcp.run})
+	}
+	if d.voiceW != nil && d.voiceW.home != nil {
+		ws = append(ws, namedWorker{"home", d.voiceW.home.run})
+	}
+	return ws
+}
+
+// startBackground starts every worker through goWorker, so waitWorkers can
+// wait for it at shutdown. A worker started as a bare `go func()` is the
+// shutdown bug documented at the end of run(): run() never returns, the
+// deferred Close never seals the database, and the ciphertext goes stale.
+func startBackground(ctx context.Context, wg *sync.WaitGroup, d bootDeps) {
+	for _, w := range backgroundWorkers(d) {
+		goWorker(wg, func() { w.run(ctx) })
+	}
+	if d.voiceW != nil && d.voiceW.server != nil {
+		log.Printf("mavend: voice listening on %s", d.voiceW.server.Addr())
+	}
+}

cmd/mavend/boot_test.go

@@ -0,0 +1,96 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/kami/maven/internal/decision"
+	"github.com/kami/maven/internal/event"
+	"github.com/kami/maven/internal/ipc"
+	"github.com/kami/maven/internal/store"
+	"github.com/kami/maven/internal/voice"
+)
+
+// fullDeps — a deployment with every optional piece present. Nothing here is
+// run: newDaemonAPI takes method values and backgroundWorkers is pure, so
+// zero-value wirings are enough to say what WOULD be started.
+func fullDeps() bootDeps {
+	h := &reactiveHandler{
+		ecosystem: &ecosystemWiring{nexus: &nexusClient{}},
+		decisions: decision.NewRing(),
+	}
+	return bootDeps{
+		coreFor:    func() ipc.CoreAPI { return ipc.UnimplementedCoreAPI{} },
+		tl:         &tickLoop{},
+		evBus:      event.NewBus(4),
+		st:         &store.Store{},
+		factWorker: &factEnrichmentWorker{},
+		evalWorker: &memoryEvalWorker{},
+		feedWkr:    &feedWorker{},
+		crawlWkr:   &crawlWorker{},
+		voiceW: &voiceWiring{
+			server:  &voice.Server{},
+			handler: h,
+			mcp:     &mcpWiring{},
+			home:    &homeWiring{},
+		},
+	}
+}
+
+// The unlock path used to build its own daemonAPI literal and leave nexus and
+// getMCPServers nil (V-639). Both paths call newDaemonAPI now, so the drift
+// that can still happen is a field added to the struct and not to the
+// constructor. This catches that one, by name.
+func TestNewDaemonAPISetsEveryField(t *testing.T) {
+	prev := allowSeedOnStart
+	allowSeedOnStart = true
+	defer func() { allowSeedOnStart = prev }()
+
+	api := newDaemonAPI(fullDeps())
+	v := reflect.ValueOf(*api)
+	for i := range v.NumField() {
+		if v.Field(i).IsZero() {
+			t.Errorf("newDaemonAPI left %s unset — a fully wired deployment must fill every field", v.Type().Field(i).Name)
+		}
+	}
+}
+
+// The handler is wired with the bare store adapter and cannot serve the day
+// plan until upgradeAPI hands it the real one. The unlocked path did that and
+// the unlock path did it too; keep it a property of the constructor.
+func TestNewDaemonAPIUpgradesTheHandler(t *testing.T) {
+	d := fullDeps()
+	api := newDaemonAPI(d)
+	if d.voiceW.handler.api != ipc.CoreAPI(api) {
+		t.Fatal("newDaemonAPI did not hand the handler the API it built")
+	}
+}
+
+// Every worker the daemon runs goes through startBackground, so shutdown can
+// wait for it. The unlock path used to start seven of these as bare
+// `go func()` under a shadowed WaitGroup.
+func TestBackgroundWorkersFullSet(t *testing.T) {
+	want := []string{"voice", "tick", "fact-enrichment", "memory-eval", "feed", "crawl", "mcp", "home"}
+	var got []string
+	for _, w := range backgroundWorkers(fullDeps()) {
+		got = append(got, w.name)
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("workers = %v, want %v", got, want)
+	}
+}
+
+// A default box configures none of the optional blocks. Two workers always run
+// and the rest stay dark, rather than a nil run being scheduled.
+func TestBackgroundWorkersFloor(t *testing.T) {
+	d := fullDeps()
+	d.evalWorker, d.feedWkr, d.crawlWkr, d.voiceW = nil, nil, nil, nil
+	want := []string{"tick", "fact-enrichment"}
+	var got []string
+	for _, w := range backgroundWorkers(d) {
+		got = append(got, w.name)
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("workers = %v, want %v", got, want)
+	}
+}

cmd/mavend/factenrichment.go

@@ -37,8 +37,8 @@ type factEnrichmentWorker struct {
 	nextTry map[int64]time.Time // fact id → earliest retry
 }
 
-// enrichmentScanLimit bounds how deep a single tick (or status report) walks
-// the pending queue looking for facts whose backoff has elapsed. The queue is
+// enrichmentScanLimit bounds how deep a single tick walks the pending queue
+// looking for facts whose backoff has elapsed. The queue is
 // ordered by id, so without a scan the oldest facts hold every batch slot
 // whether or not they are eligible, and one permanently failing fact stalls
 // every younger one behind it.
@@ -75,8 +75,8 @@ func newFactEnrichmentWorker(st *store.Store, eco *ecosystemWiring, interval tim
 // has been down all day must be visible as a backlog, not as facts that
 // silently never got tagged.
 //
-// All three numbers describe the same set of rows, the first
-// enrichmentScanLimit pending facts. Counting Pending over a thousand rows
+// All three numbers describe the same set of rows, whatever is still pending
+// out of the first enrichmentScanLimit facts. Counting Pending over a thousand rows
 // while counting InBackoff over the twenty that reached the head of a batch
 // described two different populations under one struct.
 type enrichmentStatus struct {
@@ -86,13 +86,22 @@ type enrichmentStatus struct {
 	Scanned     int // rows the other three counts were taken over
 }
 
+// status reads the queue and counts over it. For a caller with no batch in
+// hand — anything asking the worker how it is doing from outside the tick.
 func (w *factEnrichmentWorker) status(ctx context.Context) enrichmentStatus {
-	var st enrichmentStatus
 	pending, err := w.store.PendingFactResolutions(ctx, enrichmentScanLimit)
 	if err != nil {
 		log.Printf("factenrichment: status: %v", err)
-		return st
+		return enrichmentStatus{}
 	}
+	return w.statusOf(pending)
+}
+
+// statusOf counts over a batch the caller already has. The batch is the query
+// the tick already ran, so reporting the backlog costs no second read of the
+// scan limit — up to a thousand rows, on a database that serialises them.
+func (w *factEnrichmentWorker) statusOf(pending []store.Fact) enrichmentStatus {
+	var st enrichmentStatus
 	st.Pending = len(pending)
 	st.Scanned = len(pending)
 	w.mu.Lock()
@@ -144,17 +153,24 @@ func (w *factEnrichmentWorker) tick(ctx context.Context) {
 	}
 	w.forgetDeparted(pending)
 	skipped, failed, attempted := 0, 0, 0
+	// A resolved fact leaves the pending queue, so the batch in hand overstates
+	// the backlog by however many succeeded. Drop them here rather than
+	// re-reading the queue to find out.
+	remaining := make([]store.Fact, 0, len(pending))
 	for _, f := range pending {
 		if attempted >= w.batch {
-			break
+			remaining = append(remaining, f)
+			continue
 		}
 		if !w.due(f.ID) {
 			skipped++
+			remaining = append(remaining, f)
 			continue
 		}
 		attempted++
 		if !w.resolveOne(ctx, f) {
 			failed++
+			remaining = append(remaining, f)
 		}
 	}
 	if failed > 0 {
@@ -164,7 +180,7 @@ func (w *factEnrichmentWorker) tick(ctx context.Context) {
 	// Report the backlog every tick, not only when something failed: the
 	// stalled state worth seeing is the one where nothing failed because
 	// nothing was attempted.
-	if st := w.status(ctx); st.Pending > 0 {
+	if st := w.statusOf(remaining); st.Pending > 0 {
 		log.Printf("factenrichment: %d facts pending entity resolution, %d in backoff, worst attempt %d (scanned %d)",
 			st.Pending, st.InBackoff, st.MaxAttempts, st.Scanned)
 	}

cmd/mavend/main.go

@@ -252,6 +252,23 @@ func run(args []string) error {
 	// envelope per successful intake write.
 	coreFor := func() ipc.CoreAPI { return newIntakeAPI(ipc.NewStoreAPI(st), evBus, time.Now) }
 
+	// depsNow reads whatever the current path has wired. Both boot paths build
+	// the CoreAPI and start the workers from this one value, so neither can
+	// hold a field the other misses. See cmd/mavend/boot.go.
+	depsNow := func() bootDeps {
+		return bootDeps{
+			coreFor:    coreFor,
+			tl:         tl,
+			evBus:      evBus,
+			voiceW:     voiceW,
+			st:         st,
+			factWorker: factWorker,
+			evalWorker: evalWorker,
+			feedWkr:    feedWkr,
+			crawlWkr:   crawlWkr,
+		}
+	}
+
 	if !locked {
 		rules = wireRules(cfg)
 		gatherer = wireGatherer(st, cfg, rules)
@@ -284,26 +301,7 @@ func run(args []string) error {
 		feedWkr = newFeedWorker(coreFor(), embedderOf(voiceW), cfg)
 		crawlWkr = newCrawlWorker(newCrawler(cfg), coreFor(), embedderOf(voiceW), cfg)
 
-		coreAPI = &daemonAPI{
-			CoreAPI:          coreFor(),
-			getTrace:         tl.trace,
-			getMorningStatus: func(ctx context.Context) []ipc.MorningRoutineStatus { return tl.morningStatus(ctx, time.Now()) },
-			getDayPlan:       func(ctx context.Context) ipc.DayPlan { return tl.dayPlan(ctx, time.Now()) },
-			getEvents:        intakeEventsFn(evBus),
-			getDecisions:     turnDecisionsFn(voiceW),
-			seedStore:        seedStoreIfAllowed(st),
-			nexus:            nexusOf(voiceW),
-		}
-		if voiceW != nil && voiceW.handler != nil {
-			api := coreAPI.(*daemonAPI)
-			api.chatFn = voiceW.handler.handleText
-			// And the reverse: the handler was wired with the bare store
-			// adapter, which cannot serve the day plan. See upgradeAPI.
-			voiceW.handler.upgradeAPI(api)
-		}
-		if voiceW != nil && voiceW.mcp != nil {
-			coreAPI.(*daemonAPI).getMCPServers = voiceW.mcp.status
-		}
+		coreAPI = newDaemonAPI(depsNow())
 	} else {
 		// locked mode: no real store yet, so there's no meaningful CoreAPI to
 		// serve. srv.Check below is the actual guard — every CoreAPI call is
@@ -497,19 +495,7 @@ func run(args []string) error {
 			crawlWkr = newCrawlWorker(newCrawler(cfg), coreFor(), embedderOf(voiceW), cfg)
 
 			// Swap the CoreAPI from the locked placeholder to the real store adapter.
-			newAPI := &daemonAPI{
-				CoreAPI:          coreFor(),
-				getTrace:         tl.trace,
-				getMorningStatus: func(ctx context.Context) []ipc.MorningRoutineStatus { return tl.morningStatus(ctx, time.Now()) },
-				getDayPlan:       func(ctx context.Context) ipc.DayPlan { return tl.dayPlan(ctx, time.Now()) },
-				getEvents:        intakeEventsFn(evBus),
-				getDecisions:     turnDecisionsFn(voiceW),
-				seedStore:        seedStoreIfAllowed(st),
-			}
-			if voiceW != nil && voiceW.handler != nil {
-				newAPI.chatFn = voiceW.handler.handleText
-				voiceW.handler.upgradeAPI(newAPI)
-			}
+			newAPI := newDaemonAPI(depsNow())
 			srv.SetAPI(newAPI)
 			srv.Check = (&auth.Gate{Enrollment: auth.NewFloorEnrollment(), Session: passkeySess}).Check
 			wireMailIntake(srv, st, phr, cfg, evBus)
@@ -524,59 +510,10 @@ func run(args []string) error {
 			// block, so no wire path takes a voiceprint on a default box.
 			wireSpeaker(srv, st, cfg)
 
-			// Start voice server.
-			if voiceW != nil {
-				var wg sync.WaitGroup
-				wg.Add(1)
-				go func() {
-					defer wg.Done()
-					if err := voiceW.server.Serve(); err != nil && !errors.Is(err, net.ErrClosed) {
-						log.Printf("voice serve: %v", err)
-					}
-				}()
-				log.Printf("mavend: voice listening on %s", voiceW.server.Addr())
-			}
-
-			// Start tick loop.
-			go func() {
-				tl.run(ctx)
-			}()
-
-			// Start fact-entity enrichment worker.
-			go func() {
-				factWorker.run(ctx)
-			}()
-
-			// Start background memory evaluation (nil unless configured).
-			if evalWorker != nil {
-				go func() {
-					evalWorker.run(ctx)
-				}()
-			}
-
-			// Start feed reading (nil unless configured).
-			if feedWkr != nil {
-				go func() {
-					feedWkr.run(ctx)
-				}()
-			}
-
-			// Start the watched-page crawls (nil unless configured).
-			if crawlWkr != nil {
-				go func() {
-					crawlWkr.run(ctx)
-				}()
-			}
-
-			// Keep MCP connections alive (nil unless configured).
-			if voiceW != nil && voiceW.mcp != nil {
-				go voiceW.mcp.run(ctx)
-			}
-
-			// Re-enumerate the house for new devices (nil unless configured).
-			if voiceW != nil && voiceW.home != nil {
-				go voiceW.home.run(ctx)
-			}
+			// The voice server and every background worker, on the outer wg
+			// so shutdown waits for them. This used to be nine bare
+			// `go func()` calls and a shadowed WaitGroup (V-639).
+			startBackground(ctx, &wg, depsNow())
 
 			dl.unlock(st)
 			log.Printf("mavend: unlocked via passkey assertion")
@@ -591,33 +528,8 @@ func run(args []string) error {
 	})
 	log.Printf("mavend: ipc listening on %s", srv.Path())
 
-	if !locked && voiceW != nil {
-		goWorker(&wg, func() {
-			if err := voiceW.server.Serve(); err != nil && !errors.Is(err, net.ErrClosed) {
-				log.Printf("voice serve: %v", err)
-			}
-		})
-		log.Printf("mavend: voice listening on %s", voiceW.server.Addr())
-	}
-
 	if !locked {
-		goWorker(&wg, func() { tl.run(ctx) })
-		goWorker(&wg, func() { factWorker.run(ctx) })
-		if evalWorker != nil {
-			goWorker(&wg, func() { evalWorker.run(ctx) })
-		}
-		if feedWkr != nil {
-			goWorker(&wg, func() { feedWkr.run(ctx) })
-		}
-		if crawlWkr != nil {
-			goWorker(&wg, func() { crawlWkr.run(ctx) })
-		}
-		if voiceW != nil && voiceW.mcp != nil {
-			goWorker(&wg, func() { voiceW.mcp.run(ctx) })
-		}
-		if voiceW != nil && voiceW.home != nil {
-			goWorker(&wg, func() { voiceW.home.run(ctx) })
-		}
+		startBackground(ctx, &wg, depsNow())
 	}
 
 	<-ctx.Done()

deploy/mavend.json

@@ -37,7 +37,15 @@
       "This needs a matching ufw rule or the container's SYN is dropped:",
       "  ufw allow from 192.168.240.0/20 to any port 10808 proto tcp"
     ],
-    "proxy": "socks5://192.168.240.1:10808"
+    "proxy": "socks5://192.168.240.1:10808",
+    "//intake": [
+      "Read the chat as well as write to it (V-637). The poller long-polls",
+      "getUpdates through the same relay and accepts chat_id as the only",
+      "sender. Deleting this key turns inbound off again.",
+      "chat_id must be numeric here or the daemon refuses to start: an inbound",
+      "update names its chat by number, so an @-name would match nothing."
+    ],
+    "intake": true
   },
 
   "//workstation": [

docs/evals/2026-08-07-store-connection-cap.md

@@ -0,0 +1,69 @@
+# Does one sqlite connection make reads queue? No (V-642)
+
+Measured 07-08-2026 at `7b507de`, on homesrv. The harness is
+`internal/store/conncap_test.go`. It stays in the repo, because this claim gets
+re-argued and the numbers should be re-runnable rather than quoted.
+
+`internal/store/store.go` opens the database with `SetMaxOpenConns(1)`, while
+`schema.sql` sets `journal_mode=WAL`. WAL exists to let readers run beside one
+writer, so the cap gives up the thing the journal mode was chosen for. The
+question was whether that costs anything.
+
+## What was measured
+
+A fixed two-second window. One writer calling `SetValue` paced at 2ms, and a
+reader loop calling `RecentFacts(50)` over 500 seeded rows as fast as it can.
+Same schema, same modernc driver, same machine, three runs per cap.
+
+The window is wall-clock rather than a read count on purpose. A first version ran
+a fixed 300 reads. That finished sooner at the higher cap, so it received fewer
+writes, and two runs that did different work cannot be compared.
+
+| cap | reads | writes | p50 | p95 | max |
+|---|---|---|---|---|---|
+| 1 | ~3050 | ~760 | 594µs | 900µs | 16-19ms |
+| 4 | ~3600 | ~340 | 525µs | 710µs | 1-2ms |
+
+## What it says
+
+**Reads do not queue behind writes.** Four connections buy about 70µs at p50. A
+turn spends 1.19s in the resident model. The tail does improve, from 19ms to 2ms,
+and 19ms is still not a figure anyone notices in a spoken reply.
+
+**Write throughput more than halves at the higher cap**, 760 writes against 340.
+inference, not measured directly: at one connection the reader and the writer take
+turns with no lock contention. At four the writer contends for the WAL write lock
+with a live reader. Whatever the mechanism, the trade runs the opposite way from
+the one the task expected.
+
+**The cap was not the source of the 2.7s router figure.** CLAUDE.md records that
+figure as contention rather than the model. This task was a candidate for where
+that contention came from. A 19ms worst case cannot produce it. That line of
+enquiry is closed.
+
+**One transaction is what the cap cannot survive.** With a read-only transaction
+open, a second read at cap 1 never completes. The harness gave it two seconds and
+got `context deadline exceeded`. The same read at cap 4 took 1ms. The transaction
+holds the only connection, so this is not a slow read, it is a stalled database.
+
+## What was done
+
+The cap stays at 1. The reason is now written where the cap is set, rather than
+inferred from a four-word comment.
+
+`Store.DB` was deleted. It handed out exactly the read-only transaction measured
+above. It had been there since the initial commit with no production caller, and
+its doc comment described a loop that never materialised. Its one user was a test
+helper reading `delivery_attempts` by raw SQL. `ListDeliveryAttempts` has covered
+that since V-390, and the helper now goes through the reader.
+
+So the hazard is gone by construction, not by documentation.
+`TestConnCap_ReadBlocksBehindOpenSnapshot` is the standing measurement of what
+re-adding the seam would cost.
+
+## Not answered
+
+Whether reads queue on the deployed box under real load, as opposed to a
+synthetic loop. The harness writes and reads one table. Digestion reads four and
+embeds while it does. The finding that closes this task is the transaction stall,
+which is structural and does not depend on load.

docs/plans/25-the-two-boot-paths.md

@@ -1,9 +1,26 @@
 # The two boot paths have drifted
 
-Last verified: 06-08-2026 @ 06c1cf2
+Last verified: 06-08-2026 @ 69d0f5e
 
 V-639. Reads with `docs/operations.md`.
 
+## What landed
+
+`cmd/mavend/boot.go`. `newDaemonAPI(deps)` builds the CoreAPI with every field
+set, and `startBackground(ctx, &wg, deps)` starts the voice server and every
+worker through `goWorker`. `backgroundWorkers(deps)` is the pure list behind it,
+so a test can compare the set without standing a daemon up. Both paths in
+`run()` now read `coreAPI = newDaemonAPI(depsNow())` and one
+`startBackground(...)`, where `depsNow` reads whatever the current path wired.
+
+The shadowed `wg` is gone. Four tests in `cmd/mavend/boot_test.go`. Every
+`daemonAPI` field is set on a fully wired deployment. The handler gets the API
+it was built with. The worker set is asserted by name, at the full set and at
+the floor.
+
+Still by hand: unlock a locked box by passkey, ask something that needs Nexus,
+and check `/tools` lists the MCP servers.
+
 ## What is wrong
 
 `run()` in `cmd/mavend/main.go` brings the daemon up two ways. A box with a key in the

internal/config/config.go

@@ -456,9 +456,30 @@ func (c *Config) validate() error {
 	if err := c.validateCapture(); err != nil {
 		return err
 	}
+	if err := c.validateTelegram(); err != nil {
+		return err
+	}
 	return nil
 }
 
+// validateTelegram refuses an intake half that cannot read the chat it is
+// pointed at. The push half accepts an @channelusername and the intake half
+// does not, so a box configured with both boots clean, keeps pushing, and
+// answers nothing — the failure is invisible from the chat. Same shape as
+// validateNetScan: fail the config rather than the turn.
+func (c *Config) validateTelegram() error {
+	if c.Telegram == nil || !c.Telegram.Intake {
+		return nil
+	}
+	// An unset ${TELEGRAM_*} expands to empty, and the daemon already reads an
+	// empty token or chat id as telegram not being wired at all. Validating a
+	// block that wires nothing would fail a box that merely has no bot.
+	if c.Telegram.BotToken == "" || c.Telegram.ChatID == "" {
+		return nil
+	}
+	return telegramsink.ValidateIntakeChatID(c.Telegram.ChatID)
+}
+
 // DBEncryptionKey resolves the at-rest encryption key: DBKeyEnv (if set) wins
 // over DBKeyB64. Returns (nil, nil) when neither is set — the caller then opens
 // a plaintext store. A configured-but-invalid key is an error (fail closed,

internal/config/config_test.go

@@ -466,3 +466,29 @@ func TestNormaliseKeepsExplicitWorkstationHealth(t *testing.T) {
 		t.Errorf("Health = %q, want %q", got, want)
 	}
 }
+
+func TestTelegramIntakeRefusesNamedChat(t *testing.T) {
+	// The push half accepts an @channelusername and the intake half cannot use
+	// one, so a box with both boots clean and answers nothing. Refuse the
+	// config instead.
+	p := writeConfig(t, `{"telegram":{"bot_token":"t","chat_id":"@maven","intake":true}}`)
+	if _, err := Load(p); err == nil {
+		t.Fatal("Load succeeded for intake with an @-name chat id; want error")
+	}
+}
+
+func TestTelegramNamedChatOKWithoutIntake(t *testing.T) {
+	// Push-only is what the @-name is for, so nothing changes for a box that
+	// never turned intake on.
+	p := writeConfig(t, `{"telegram":{"bot_token":"t","chat_id":"@maven"}}`)
+	if _, err := Load(p); err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+}
+
+func TestTelegramIntakeAcceptsNumericChat(t *testing.T) {
+	p := writeConfig(t, `{"telegram":{"bot_token":"t","chat_id":"-1001234567890","intake":true}}`)
+	if _, err := Load(p); err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+}

internal/delivery/durability_test.go

@@ -94,20 +94,22 @@ func openTestStore(t *testing.T) *store.Store {
 
 // attemptStatus reads one attempt row back. Returns ok=false when the row is
 // gone, which would itself be a broken promise (a dropped attempt).
+//
+// It goes through ListDeliveryAttempts rather than raw SQL. This helper used to
+// reach past the store into store.DB, which was the tell that the outbox was
+// write-only; the reader landed in V-390 and this caller was not moved over.
 func attemptStatus(t *testing.T, st *store.Store, id int64) (status string, completed bool, ok bool) {
 	t.Helper()
-	tx, err := st.DB(context.Background())
+	attempts, err := st.ListDeliveryAttempts(context.Background(), "", 200)
 	if err != nil {
-		t.Fatalf("read tx: %v", err)
+		t.Fatalf("ListDeliveryAttempts: %v", err)
 	}
-	defer func() { _ = tx.Rollback() }()
-	var completedTS *int64
-	err = tx.QueryRowContext(context.Background(),
-		`SELECT status, completed_ts FROM delivery_attempts WHERE id = ?`, id).Scan(&status, &completedTS)
-	if err != nil {
-		return "", false, false
+	for _, a := range attempts {
+		if a.ID == id {
+			return a.Status, a.HasComplete, true
+		}
 	}
-	return status, completedTS != nil, true
+	return "", false, false
 }
 
 // TestCrashBetweenBeginAndCompleteBecomesUnknown — simulate the crash window:

internal/delivery/telegramsink/intake.go

@@ -49,6 +49,24 @@ type Poller struct {
 	offset  int64
 }
 
+// ValidateIntakeChatID refuses a chat id the intake half cannot use. The push
+// half accepts @channelusername as a destination. The intake half cannot: an
+// inbound update names its chat by numeric id, so an @-name would match nothing
+// and the poller would read the chat and answer none of it. Config validation
+// calls this, so the box refuses to boot rather than running a dead reach —
+// NewPoller returning an error is too late, because the daemon is already up.
+func ValidateIntakeChatID(chatID string) error {
+	id := strings.TrimSpace(chatID)
+	if id == "" {
+		return errors.New("telegramsink: intake needs a chat id")
+	}
+	digits := strings.TrimPrefix(id, "-")
+	if digits == "" || strings.TrimLeft(digits, "0123456789") != "" {
+		return fmt.Errorf("telegramsink: intake needs the numeric chat id, not %s", chatID)
+	}
+	return nil
+}
+
 // NewPoller builds the intake half around an already-validated sink, so the
 // token, the base URL and the relay are resolved in one place. turn is
 // required; correct may be nil, and then the reply carries no buttons.
@@ -59,12 +77,8 @@ func NewPoller(s *Sink, turn Turn, correct Correct) (*Poller, error) {
 	if turn == nil {
 		return nil, errors.New("telegramsink: intake needs a turn handler")
 	}
-	// The push half accepts @channelusername as a destination. The intake half
-	// cannot: an inbound update names its chat by numeric id, so an @-name would
-	// match nothing and the poller would read the chat and answer none of it.
-	// Refusing here is the difference between a boot error and a dead reach.
-	if strings.HasPrefix(strings.TrimSpace(s.cfg.ChatID), "@") {
-		return nil, fmt.Errorf("telegramsink: intake needs the numeric chat id, not %s", s.cfg.ChatID)
+	if err := ValidateIntakeChatID(s.cfg.ChatID); err != nil {
+		return nil, err
 	}
 	// The sink's transport already carries the relay. Only the timeout differs,
 	// and it has to clear the long poll.
@@ -164,9 +178,10 @@ func (p *Poller) onMessage(ctx context.Context, m *message) {
 	}
 }
 
-// onCallback handles a tap on a correction button. Every path answers the
-// callback: telegram spins a clock on the button until it is answered, and an
-// unanswered tap reads as a gesture that was dropped.
+// onCallback handles a tap on a correction button. Every path from the owner
+// answers the callback: telegram spins a clock on the button until it is
+// answered, and an unanswered tap reads as a gesture that was dropped. A tap
+// from anyone else gets silence, the same as a message from a stranger.
 func (p *Poller) onCallback(ctx context.Context, cb *callbackQuery) {
 	if !p.fromOwner(cb.Message.Chat.idString()) {
 		return

internal/delivery/telegramsink/intake_test.go

@@ -199,3 +199,18 @@ func TestNewPollerNeedsATurn(t *testing.T) {
 		t.Error("built a poller with no sink to answer through")
 	}
 }
+
+// A chat id the intake half cannot match is refused before anything reads the
+// chat. Config validation calls the same check, so this is the boot error.
+func TestValidateIntakeChatID(t *testing.T) {
+	for _, ok := range []string{"123", "-1001234567890", " 42 "} {
+		if err := ValidateIntakeChatID(ok); err != nil {
+			t.Errorf("ValidateIntakeChatID(%q): %v", ok, err)
+		}
+	}
+	for _, bad := range []string{"", "@maven", "-", "12a", "1 2"} {
+		if err := ValidateIntakeChatID(bad); err == nil {
+			t.Errorf("ValidateIntakeChatID(%q) accepted; want error", bad)
+		}
+	}
+}

internal/ipc/server.go

@@ -17,9 +17,11 @@ import (
 // Server — the core side of the boundary. Listens on a unix domain socket,
 // accepts module connections, frames requests to a CoreAPI and responses back.
 // One Server per daemon process; concurrent connections are handled in their
-// own goroutine but share the single CoreAPI (and therefore the single store
-// writer — store is single-connection, SetMaxOpenConns(1), so serialization is
-// already guaranteed at the db; the Server adds no locking of its own).
+// own goroutine but share the single CoreAPI, and so the single store writer.
+// The store opens at SetMaxOpenConns(1), so serialisation is already guaranteed
+// at the database and the Server adds no locking of its own. That cap is an
+// invariant this comment depends on, measured and kept on 07-08-2026 (V-642,
+// docs/evals/2026-08-07-store-connection-cap.md).
 type Server struct {
 	api  atomic.Value // stores CoreAPI
 	path string

internal/store/conncap_test.go

@@ -0,0 +1,154 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"path/filepath"
+	"sort"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// conncap_test.go measures whether a read queues behind a write at
+// SetMaxOpenConns(1), which is what openAt sets (V-642). It is a measurement
+// harness, not an assertion: the numbers it prints are the evidence, and the
+// decision to move the cap or leave it belongs in docs/evals.
+//
+// Run it with -v, and note that it is skipped under -short because it spends
+// seconds on purpose.
+
+// openCapped opens a plaintext store at the given connection cap. In-package,
+// so it can reach the handle openAt caps at 1.
+func openCapped(t *testing.T, cap int) *Store {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "cap.db")
+	db, err := openAt(context.Background(), path)
+	if err != nil {
+		t.Fatalf("openAt: %v", err)
+	}
+	db.SetMaxOpenConns(cap)
+	s := &Store{db: db}
+	t.Cleanup(func() { _ = s.Close() })
+	return s
+}
+
+func percentile(d []time.Duration, p float64) time.Duration {
+	if len(d) == 0 {
+		return 0
+	}
+	i := int(float64(len(d)-1) * p)
+	return d[i]
+}
+
+// seedFacts writes n facts so a read has rows to decode.
+func seedFacts(t *testing.T, s *Store, n int) {
+	t.Helper()
+	ctx := context.Background()
+	now := time.Now().UTC()
+	for i := 0; i < n; i++ {
+		key := fmt.Sprintf("seed_%d", i)
+		if _, err := s.SetValue(ctx, KindSelf, key, "tap:test",
+			map[string]int{"ml": i}, now.Add(time.Duration(i)*time.Millisecond)); err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+}
+
+// measureReadsUnderWrites reports read latency percentiles while a writer
+// writes at a fixed pace. The pace matters: an unpaced writer completes a
+// different number of writes at each cap, because at a higher cap it competes
+// with the readers for the write lock instead of taking turns on one
+// connection. Two runs that did different work cannot be compared.
+// It runs for a fixed wall-clock window rather than a fixed read count, so the
+// paced writer does the same work at every cap. Tying the window to a read
+// count made the faster configuration receive fewer writes.
+func measureReadsUnderWrites(t *testing.T, s *Store, window, pace time.Duration) []time.Duration {
+	t.Helper()
+	ctx := context.Background()
+
+	var stop atomic.Bool
+	var writes atomic.Int64
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		now := time.Now().UTC()
+		for i := 0; !stop.Load(); i++ {
+			key := fmt.Sprintf("hot_%d", i%16)
+			if _, err := s.SetValue(ctx, KindSelf, key, "tap:test",
+				map[string]int{"n": i}, now.Add(time.Duration(i)*time.Millisecond)); err != nil {
+				t.Errorf("write: %v", err)
+				return
+			}
+			writes.Add(1)
+			time.Sleep(pace)
+		}
+	}()
+
+	var lat []time.Duration
+	deadline := time.Now().Add(window)
+	for time.Now().Before(deadline) {
+		start := time.Now()
+		if _, err := s.RecentFacts(ctx, 50); err != nil {
+			t.Fatalf("RecentFacts: %v", err)
+		}
+		lat = append(lat, time.Since(start))
+	}
+	stop.Store(true)
+	wg.Wait()
+	t.Logf("in %v: %d reads, %d writes", window, len(lat), writes.Load())
+
+	sort.Slice(lat, func(i, j int) bool { return lat[i] < lat[j] })
+	return lat
+}
+
+// TestConnCap_ReadLatencyUnderWrites is the V-642 measurement: read latency at
+// cap 1 against cap 4, same workload, same schema, same driver.
+func TestConnCap_ReadLatencyUnderWrites(t *testing.T) {
+	if testing.Short() {
+		t.Skip("measurement harness; runs for seconds")
+	}
+	for _, cap := range []int{1, 4} {
+		t.Run(fmt.Sprintf("cap=%d", cap), func(t *testing.T) {
+			s := openCapped(t, cap)
+			seedFacts(t, s, 500)
+			lat := measureReadsUnderWrites(t, s, 2*time.Second, 2*time.Millisecond)
+			t.Logf("cap=%d reads=%d p50=%v p95=%v max=%v",
+				cap, len(lat), percentile(lat, 0.50), percentile(lat, 0.95), lat[len(lat)-1])
+		})
+	}
+}
+
+// TestConnCap_ReadBlocksBehindOpenSnapshot is the sharper claim: at cap 1 an
+// open read-only transaction holds the only connection, so an unrelated read
+// cannot proceed until it commits. This is why the store exposes no way to
+// begin one — `Store.DB` used to, and was deleted in V-642 with no caller. The
+// test stays as the reason, so re-adding that seam fails a measurement rather
+// than shipping a stall.
+func TestConnCap_ReadBlocksBehindOpenSnapshot(t *testing.T) {
+	if testing.Short() {
+		t.Skip("measurement harness; waits on a timeout")
+	}
+	for _, cap := range []int{1, 4} {
+		t.Run(fmt.Sprintf("cap=%d", cap), func(t *testing.T) {
+			s := openCapped(t, cap)
+			seedFacts(t, s, 50)
+
+			tx, err := s.db.BeginTx(context.Background(), &sql.TxOptions{ReadOnly: true})
+			if err != nil {
+				t.Fatalf("BeginTx: %v", err)
+			}
+			defer func() { _ = tx.Rollback() }()
+
+			ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+			defer cancel()
+			start := time.Now()
+			_, err = s.RecentFacts(ctx, 10)
+			t.Logf("cap=%d read alongside an open snapshot: waited %v, err=%v",
+				cap, time.Since(start).Round(time.Millisecond), err)
+		})
+	}
+}

internal/store/store.go

@@ -95,7 +95,20 @@ func openAt(ctx context.Context, path string) (*sql.DB, error) {
 	if err != nil {
 		return nil, fmt.Errorf("open %s: %w", path, err)
 	}
-	// single writer expected; the daemon is the only process touching the db.
+	// One connection, so every statement is serialised at the database and no
+	// caller above needs a lock of its own. internal/ipc's Server relies on
+	// exactly this, which is why the cap is an invariant rather than a tuning
+	// knob: raising it moves the serialisation guarantee somewhere it is not
+	// written down.
+	//
+	// Measured on 07-08-2026 (V-642, docs/evals/2026-08-07-store-connection-cap.md).
+	// WAL exists to let readers run beside one writer, and the cap gives that
+	// up, but reads do not queue: p50 594µs against 525µs at a cap of four,
+	// while write throughput more than halves. The one thing the cap cannot
+	// survive is a long-lived transaction, which holds the only connection and
+	// stalls every read for its lifetime. So the store begins none, and
+	// TestConnCap_ReadBlocksBehindOpenSnapshot is the standing measurement of
+	// what re-adding one would cost.
 	db.SetMaxOpenConns(1)
 	if _, err := db.ExecContext(ctx, schemaSQL); err != nil {
 		if closeErr := db.Close(); closeErr != nil {
@@ -133,13 +146,6 @@ func (s *Store) Close() error {
 	return s.enc.closeAndSeal(s.db)
 }
 
-// DB exposes the underlying handle for internal read-only snapshots.
-// Used by the loop to take a consistent read under a single transaction.
-// Modules never receive this handle — core mediates.
-func (s *Store) DB(ctx context.Context) (*sql.Tx, error) {
-	return s.db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
-}
-
 var (
 	// ErrNoFact — no non-voided row exists for this key.
 	ErrNoFact = errors.New("store: no fact for key")