fix(prime): report when the memory plane could not be read (#6011)

`bd prime` failed silent by design when storage was down: a broken or
unreachable store made formatMemoriesForPrime return "", so the memory
section was simply omitted. An agent that woke with zero recall produced
output identical to a workspace that has no memories — same text, same
exit 0 — and an operator running a fleet had no instrument that could
tell the two apart (gh#5877).

Prime already had the right precedent for this: a deadline opening the
store renders a visible "Skipped: timed out ..." banner rather than going
quiet. This extends that treatment to the three sibling failures that
still returned "" — store open failure, the Memories() accessor, and the
List() call — via a shared formatPrimeMemoryUnavailable helper carrying
the same section shape:

  Skipped: beads storage unavailable (<error>) — persistent memories were
  NOT injected this session. Run `bd doctor`; ...

The proxied-server route shares the helper, so the two routes cannot
drift. The quoted error is reduced to its first line, whitespace
collapsed and capped at 160 runes: storage errors carry multi-line hints
and prime is injected into a context window.

Two cases stay silent, deliberately. A healthy store with zero memories
renders nothing, so fresh workspaces get no noise. And a directory with
no workspace at all has nothing to inject and nothing wrong with it —
telling those apart needed a typed error, so ensureStoreActiveWithContext
now wraps ErrNoBeadsDatabase (message unchanged) and both prime routes
match on it with errors.Is instead of on prose.

Exit codes are unchanged; prime still never fails a session-start hook.

Tests changed:

- prime_proxied_integration_test.go's "degrades_silently_when_plane_
  unavailable" asserted the empty-memories fallback for a corrupted
  proxied sidecar; that assertion IS the bug. Renamed to
  "reports_when_plane_unavailable" and it now asserts the banner and the
  absence of "No memories stored" (still cgo + shared-proxied-server
  gated, so not run here).
- stubPrimeStoreUnavailable, the helper eight prime tests use to detach
  from an ambient workspace, now reports ErrNoBeadsDatabase. Any other
  error would render the new banner into all of their output, and
  whether it did would depend on the runner's ancestor directories.
This commit is contained in:
Bee 2026-08-27 06:46:56 -07:00 • committed by GitHub
commit 67e9f2ab6c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 252 additions and 24 deletions

View file

@ -173,6 +173,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- **`bd prime` says when it could NOT read the memory plane**
([#5877](https://github.com/gastownhall/beads/issues/5877)). A broken or
unreachable store made prime omit the memory section entirely, so a session
that woke with zero recall looked exactly like a workspace that simply has no
memories — same output, same exit 0, no way for a fleet operator to tell them
apart. Prime still never fails a session-start hook, but a memory read it
cannot serve now renders `Skipped: beads storage unavailable (<error>) —
persistent memories were NOT injected this session`, alongside the timeout
banner that already existed for a deadline. Both the classic and the
proxied-server route share the banner. A workspace-less directory, and a
healthy store with no memories, stay silent as before.
- **Incremental auto-export now actually takes the incremental path**
([#5806](https://github.com/gastownhall/beads/pull/5806)). Change detection
compared `GetStateHash()` values — a hash of the entire database plus

View file

@ -2,11 +2,18 @@ package main
import (
"context"
"errors"
"fmt"
"github.com/steveyegge/beads/internal/beads"
)
// ErrNoBeadsDatabase reports that no beads workspace could be resolved at all,
// as distinct from a workspace whose storage failed to open. Callers that must
// tell "nothing here" apart from "the store is broken" — `bd prime`'s memory
// injection, for one — match on it with errors.Is rather than on the message.
var ErrNoBeadsDatabase = errors.New("no beads database found")
// ensureDirectMode makes sure the CLI is operating in direct-storage mode.
func ensureDirectMode(_ string) error {
return ensureStoreActive()
@ -33,8 +40,8 @@ func ensureStoreActiveWithContext(ctx context.Context) error {
// Find the .beads directory
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return fmt.Errorf("no beads database found.\n" +
"Hint: run 'bd init' to create a database in the current directory")
return fmt.Errorf("%w.\n"+
"Hint: run 'bd init' to create a database in the current directory", ErrNoBeadsDatabase)
}
// Use the factory to create the appropriate backend

View file

@ -423,9 +423,13 @@ func outputMemoriesOnlyContext(w io.Writer) error {
}
// formatMemoriesForPrime reads the memory plane through memoryops.Memories and
// formats it for injection. Returns empty string if no memories or if the plane
// is unavailable — prime degrades silently rather than failing a session-start
// hook, which is prime's presentation policy and not the role's.
// formats it for injection. Prime still never fails a session-start hook over
// the memory plane — but "degrade" is not "go quiet": a plane that could not be
// read renders the unavailable banner (or the timeout banner on a deadline), so
// an operator can tell "this workspace has no memories" from "this agent woke
// with no recall because the store is down" (gh#5877). Only two cases stay
// silent: no workspace at all (nothing to inject), and a healthy store with
// zero memories (a fresh workspace must not be given noise).
func formatMemoriesForPrime(compact bool) string {
// bd-mm8wf: in a proxied-server workspace the memory read must ride the
// proxied plane (UOW provider), never ensureStoreActiveForPrime — the
@ -449,19 +453,22 @@ func formatMemoriesForPrime(compact bool) string {
if errors.Is(err, context.DeadlineExceeded) {
return formatPrimeMemoryTimeout(compact, timeout)
}
return "" // Silently skip — store unavailable
if errors.Is(err, ErrNoBeadsDatabase) {
return "" // No workspace here — genuinely nothing to inject.
}
return formatPrimeMemoryUnavailable(compact, err)
}
}
if store == nil {
return ""
return formatPrimeMemoryUnavailable(compact, errors.New("storage reported ready but no store is active"))
}
memories, err := store.Memories()
if err != nil {
return ""
return formatPrimeMemoryUnavailable(compact, err)
}
result, err := memories.List(context.Background(), memoryops.ListRequest{})
if err != nil {
return ""
return formatPrimeMemoryUnavailable(compact, err)
}
return renderPrimeMemoryPlane(result.Memories, compact)
}
@ -603,6 +610,51 @@ func formatPrimeMemoryTimeout(compact bool, timeout time.Duration) string {
return "\n## Persistent Memories\n\n" + msg + "\n"
}
// formatPrimeMemoryUnavailable renders the memory section when the plane could
// not be read at all — store open failed, the memory accessor errored, or the
// list call errored. It is the non-deadline sibling of
// formatPrimeMemoryTimeout and carries the same section shape, and it is shared
// by the classic and proxied routes so the two cannot drift.
//
// The wording is deliberately blunt about what did NOT happen: before this,
// prime omitted the section entirely on these failures, so a fleet operator
// could not distinguish an agent that has no memories from an agent whose
// memory plane is down — every instrument read healthy while agents woke with
// zero recall (gh#5877).
func formatPrimeMemoryUnavailable(compact bool, err error) string {
msg := fmt.Sprintf("Skipped: beads storage unavailable (%s) — persistent memories were NOT injected this session. Run `bd doctor`; if the store is a Dolt server, check it is running and reachable.", primeErrorSummary(err))
if compact {
return "\n## Memories\n- " + msg + "\n"
}
return "\n## Persistent Memories\n\n" + msg + "\n"
}
// primeMemoryErrorMaxLen caps the error text quoted in the unavailable banner.
const primeMemoryErrorMaxLen = 160
// primeErrorSummary reduces an error to one short single-line phrase fit for a
// prime section. Storage errors routinely carry multi-line hints and stack-ish
// detail; prime is injected into an agent's context window, so it quotes the
// first line only, whitespace-collapsed and length-capped. `bd doctor` is where
// the full text belongs.
func primeErrorSummary(err error) string {
if err == nil {
return "unknown error"
}
line := err.Error()
if i := strings.IndexAny(line, "\r\n"); i >= 0 {
line = line[:i]
}
line = strings.Join(strings.Fields(line), " ")
if line == "" {
return "unknown error"
}
if runes := []rune(line); len(runes) > primeMemoryErrorMaxLen {
line = strings.TrimRight(string(runes[:primeMemoryErrorMaxLen]), " ") + "…"
}
return line
}
// outputMCPContext outputs minimal context for MCP users
func outputMCPContext(w io.Writer, stealthMode bool) error {
ephemeral := isEphemeralBranch()

View file

@ -82,7 +82,7 @@ func TestProxiedServerPrime(t *testing.T) {
}
})
t.Run("degrades_silently_when_plane_unavailable", func(t *testing.T) {
t.Run("reports_when_plane_unavailable", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "ppr4")
content := "this memory must not surface when the plane is down"
@ -90,8 +90,10 @@ func TestProxiedServerPrime(t *testing.T) {
// Corrupt the proxied-server sidecar: provider open now fails before
// touching any server, the deterministic stand-in for an unreachable
// plane. Prime must still exit 0 (silent-skip contract) with no
// memories and no direct-store fallback.
// plane. Prime must still exit 0 and must not fall back to a direct
// store — but it says so rather than rendering as an empty memory set
// (gh#5877), which is what made a downed plane indistinguishable from
// a workspace that simply has no memories.
sidecar := configfile.ProxiedServerClientInfoPath(p.beadsDir)
if err := os.WriteFile(sidecar, []byte("not json{"), 0o644); err != nil {
t.Fatalf("corrupting sidecar %s: %v", sidecar, err)
@ -101,8 +103,11 @@ func TestProxiedServerPrime(t *testing.T) {
if strings.Contains(out, content) || strings.Contains(out, "plane-down") {
t.Errorf("expected memory to be skipped when the proxied plane is unavailable, got: %s", out)
}
if !strings.Contains(out, "No memories stored") {
t.Errorf("expected the empty-memories fallback on silent skip, got: %s", out)
if !strings.Contains(out, "beads storage unavailable") || !strings.Contains(out, "were NOT injected this session") {
t.Errorf("expected the storage-unavailable banner when the proxied plane is down, got: %s", out)
}
if strings.Contains(out, "No memories stored") {
t.Errorf("an unreachable plane must not render as an empty memory set, got: %s", out)
}
assertNoEmbeddedStore(t, p)
})

View file

@ -3,7 +3,6 @@ package main
import (
"context"
"errors"
"fmt"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/storage/uow"
@ -22,9 +21,10 @@ import (
// provider's own capability accessor, on a provider opened scoped to this read.
// It is the same call `bd memories` makes, which is what stopped prime from
// being a fifth front door with its own copy of the kv.memory. prefix rule.
// Prime's contract is preserved on every failure edge: silent skip when the
// plane is unavailable, the timeout banner on a deadline, and rendering through
// the same shared tail as the classic path.
// Prime's contract is preserved on every failure edge: the unavailable banner
// when the plane cannot be read, the timeout banner on a deadline, a silent
// skip only when there is no workspace at all, and rendering through the same
// shared tail as the classic path.
// primeProxiedProviderOpen opens the proxied-plane provider for prime's
// memory read; a var so unit tests can stub the plane. Production opens the
@ -35,9 +35,10 @@ var primeProxiedProviderOpen = func(ctx context.Context, beadsDir string) (uow.U
}
// formatMemoriesForPrimeProxied is the proxied-mode branch of
// formatMemoriesForPrime. Returns "" whenever the read cannot be served (no
// workspace, provider open failure, read failure): prime must degrade
// silently, never fail the session-start hook.
// formatMemoriesForPrime. It never fails the session-start hook, but a read it
// cannot serve — provider open failure, read failure — renders the same
// unavailable banner the classic route renders (gh#5877); only "no workspace"
// stays silent.
func formatMemoriesForPrimeProxied(compact bool) string {
timeout := primeStoreTimeout()
ctx := context.Background()
@ -51,7 +52,10 @@ func formatMemoriesForPrimeProxied(compact bool) string {
if errors.Is(err, context.DeadlineExceeded) || errors.Is(ctx.Err(), context.DeadlineExceeded) {
return formatPrimeMemoryTimeout(compact, timeout)
}
return "" // Silently skip — proxied plane unavailable
if errors.Is(err, ErrNoBeadsDatabase) {
return "" // No workspace here — genuinely nothing to inject.
}
return formatPrimeMemoryUnavailable(compact, err)
}
return renderPrimeMemoryPlane(plane, compact)
}
@ -67,7 +71,7 @@ func primeProxiedMemoryPlane(ctx context.Context) (map[string]string, error) {
if provider == nil {
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return nil, fmt.Errorf("no beads directory found")
return nil, ErrNoBeadsDatabase
}
p, err := primeProxiedProviderOpen(ctx, beadsDir)
if err != nil {

View file

@ -5,6 +5,7 @@ import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
@ -22,6 +23,12 @@ import (
// containing "git pull" fails the stealth-mode rejectText assertions. CI never
// sees the leak because its checkouts have no ancestor database.
//
// The stub reports ErrNoBeadsDatabase, i.e. "there is no workspace here" — the
// one memory-read failure prime still passes over in silence. Any other error
// would (correctly, since gh#5877) render the storage-unavailable banner into
// every one of these tests' output, and whether it did would depend on the
// runner's ancestor directories.
//
// Returns a function to restore the original store wiring.
// Usage:
//
@ -33,7 +40,7 @@ func stubPrimeStoreUnavailable() func() {
store = nil
storeActive = false
ensureStoreActiveForPrime = func(context.Context) error {
return errors.New("prime store stubbed out in test")
return fmt.Errorf("prime store stubbed out in test: %w", ErrNoBeadsDatabase)
}
return func() {
store = origStore
@ -448,6 +455,147 @@ func TestFormatMemoriesForPrimeTimesOutOpeningStore(t *testing.T) {
}
}
// stubPrimeStoreOpen points prime's lazy store open at the given error and
// clears the ambient store, so a test drives formatMemoriesForPrime through a
// chosen failure edge. proxiedServerMode is forced off so the classic route is
// the one under test regardless of ambient wiring.
func stubPrimeStoreOpen(t *testing.T, err error) {
t.Helper()
oldStore := store
oldStoreActive := storeActive
oldEnsure := ensureStoreActiveForPrime
oldProxied := proxiedServerMode
store = nil
storeActive = false
proxiedServerMode = false
ensureStoreActiveForPrime = func(context.Context) error { return err }
t.Cleanup(func() {
store = oldStore
storeActive = oldStoreActive
ensureStoreActiveForPrime = oldEnsure
proxiedServerMode = oldProxied
})
}
// TestFormatMemoriesForPrimeReportsUnavailableStore is the gh#5877 regression:
// a broken or unreachable store used to make prime omit the memory section
// entirely, so "no memories" and "memory plane down" produced identical output
// and an identical exit 0. The failure must now announce itself.
func TestFormatMemoriesForPrimeReportsUnavailableStore(t *testing.T) {
openErr := fmt.Errorf("failed to open database: dial tcp 127.0.0.1:3308: connect: connection refused\nHint: run bd doctor")
tests := []struct {
name string
compact bool
header string
}{
{name: "full", compact: false, header: "## Persistent Memories\n\nSkipped: beads storage unavailable ("},
{name: "compact", compact: true, header: "## Memories\n- Skipped: beads storage unavailable ("},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
stubPrimeStoreOpen(t, openErr)
out := formatMemoriesForPrime(tt.compact)
for _, want := range []string{tt.header, "connection refused", "were NOT injected this session", "bd doctor"} {
if !strings.Contains(out, want) {
t.Fatalf("prime memory output missing %q, got %q", want, out)
}
}
if strings.Contains(out, "Hint: run bd doctor") {
t.Fatalf("multi-line store error leaked past the first line into prime output: %q", out)
}
})
}
}
// A workspace-less directory is the one failure prime still swallows: there is
// nothing to inject and nothing is wrong, so a fresh checkout gets no banner.
func TestFormatMemoriesForPrimeStaysSilentWithoutWorkspace(t *testing.T) {
stubPrimeStoreOpen(t, fmt.Errorf("%w.\nHint: run 'bd init'", ErrNoBeadsDatabase))
for _, compact := range []bool{false, true} {
if out := formatMemoriesForPrime(compact); out != "" {
t.Fatalf("formatMemoriesForPrime(compact=%v) = %q, want silence when no workspace is resolved", compact, out)
}
}
}
func TestFormatPrimeMemoryUnavailable(t *testing.T) {
tests := []struct {
name string
compact bool
err error
want []string
reject []string
}{
{
name: "full shape",
compact: false,
err: errors.New("connection refused"),
want: []string{
"\n## Persistent Memories\n\nSkipped: beads storage unavailable (connection refused) — persistent memories were NOT injected this session.",
"if the store is a Dolt server, check it is running and reachable.",
},
},
{
name: "compact shape",
compact: true,
err: errors.New("connection refused"),
want: []string{"\n## Memories\n- Skipped: beads storage unavailable (connection refused) — persistent memories were NOT injected this session."},
reject: []string{"## Persistent Memories"},
},
{
name: "nil error still says injection did not run",
compact: false,
err: nil,
want: []string{"(unknown error)", "NOT injected"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
out := formatPrimeMemoryUnavailable(tt.compact, tt.err)
for _, want := range tt.want {
if !strings.Contains(out, want) {
t.Fatalf("banner missing %q, got %q", want, out)
}
}
for _, reject := range tt.reject {
if strings.Contains(out, reject) {
t.Fatalf("banner unexpectedly contains %q, got %q", reject, out)
}
}
if !strings.HasSuffix(out, "\n") {
t.Fatalf("banner must end in a newline so the next section starts cleanly, got %q", out)
}
})
}
}
func TestPrimeErrorSummary(t *testing.T) {
long := strings.Repeat("é", primeMemoryErrorMaxLen*2)
tests := []struct {
name string
err error
want string
}{
{name: "nil", err: nil, want: "unknown error"},
{name: "blank", err: errors.New(" \n "), want: "unknown error"},
{name: "single line", err: errors.New("connection refused"), want: "connection refused"},
{name: "first line only", err: errors.New("open failed: boom\nHint: run bd doctor\nmore detail"), want: "open failed: boom"},
{name: "whitespace collapsed", err: errors.New("open failed:\tboom"), want: "open failed: boom"},
{name: "capped", err: errors.New(long), want: strings.Repeat("é", primeMemoryErrorMaxLen) + "…"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := primeErrorSummary(tt.err); got != tt.want {
t.Fatalf("primeErrorSummary() = %q, want %q", got, tt.want)
}
})
}
}
func TestPrimeStoreTimeoutNonPositiveUsesDefault(t *testing.T) {
for _, value := range []string{"0", "0s", "-5s"} {
t.Run(value, func(t *testing.T) {