perf(ready): skip the countReadyWork request when bd ready --json prints no total (#7699)

* perf(ready): skip the countReadyWork request when bd ready --json prints no total

Over a remote backend, bd ready --json sent GET /v0/beads/ready and then,
whenever the page came back with has_more, GET /v0/beads/ready:count, only to
put "of N" into the stderr hint. Without BD_JSON_ENVELOPE nothing else prints
the total, so that second request (about 120 ms at a 52 ms RTT) bought a
number no caller reads.

On a remote backend without the envelope, bd ready --json now lists one row
past the limit and says whether more exist without saying how many, in the
wording the proxied route already uses. A local store keeps the in-band total
it takes in the page's own transaction, and the envelope keeps
pagination.total. A --max-rows cap at or below the limit keeps the counted
listing, so the extra row never trips the cap.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of gascity-agent
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(ready): say "1 ready issue", not "1 ready issues", in the no-total hint

Review follow-up. The hint the remote --json path shares with the proxied
route now agrees in number; both routes take it from readyHiddenHint, so
they stay one wording.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of gascity-agent
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-19 18:15:57 +00:00 • committed by GitHub
commit d097b6c8a4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 212 additions and 2 deletions

View file

@ -499,6 +499,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
- Over an HTTP workspace, `bd ready --json` without `BD_JSON_ENVELOPE` no
longer sends `GET /v0/beads/ready:count` after a page the limit cut short:
the total only went into the stderr hint. It lists one row past the limit
instead, and the hint says more issues matched without saying how many
(the wording the proxied-server route already uses). A local store, and the
envelope's `pagination.total`, keep the total.
- `bd` initializes its packages with `GOMAXPROCS` capped at 4 and hands it
back before `main` runs anything, so the garbage collections package
initialization triggers do not stop the world across every CPU of a large

View file

@ -53,6 +53,9 @@ func TestE2E_PerCommandRequestBudget(t *testing.T) {
args []string
}{
{"ready", 2, []string{"ready", "--json"}},
// The limit hides rows, and without BD_JSON_ENVELOPE nothing
// prints their count: one listing, no ready:count after it.
{"ready --limit 1", 2, []string{"ready", "--json", "--limit", "1"}},
{"list", 4, []string{"list", "--json"}},
{"show", 1, []string{"show", target, "--json"}},
{"create", 2, []string{"create", "budget created", "-t", "task", "--json"}},

View file

@ -1102,6 +1102,7 @@ go_test(
"ready_embedded_test.go",
"ready_explain_ids_test.go",
"ready_input_test.go",
"ready_json_no_total_test.go",
"ready_max_rows_proxied_test.go",
"ready_max_rows_test.go",
"ready_proxied_integration_test.go",

View file

@ -179,6 +179,9 @@ This is useful for agents executing molecules to see which steps can run next.`,
return nil
}
if jsonOutput && readyJSONPrintsNoTotal(activeStore) {
return runReadyJSONWithoutTotal(ctx, activeStore, filter)
}
if jsonOutput {
// The page and the size of the whole ready set come back from ONE
// read transaction: the total rides the page's own ID query, so a
@ -430,6 +433,65 @@ var blockedCmd = &cobra.Command{
},
}
// readyJSONPrintsNoTotal reports whether `bd ready --json` should skip sizing
// the whole ready set. Without BD_JSON_ENVELOPE the total only decorates the
// stderr hint. A local store takes it in the page's own transaction, so the
// hint keeps it there; a remote backend pays a second request
// (countReadyWork) for it, so the hint goes without.
func readyJSONPrintsNoTotal(activeStore storage.DoltStorage) bool {
return !jsonEnvelopeEnabled() && storeIsRemoteBackend(activeStore)
}
// runReadyJSONWithoutTotal lists one row past the limit, which says whether
// the limit hid anything: all the hint needs. A cap at or below the limit
// would count that extra row against it, so such a listing keeps the counted
// path and its refusal exactly as before.
func runReadyJSONWithoutTotal(ctx context.Context, activeStore storage.DoltStorage, filter types.WorkFilter) error {
limit := filter.Limit
var results []*types.IssueWithCounts
var total int
var err error
if limit > 0 && filter.MaxRows > 0 && filter.MaxRows <= limit {
results, total, err = activeStore.GetReadyWorkWithCountsAndTotal(ctx, filter)
} else {
if limit > 0 {
filter.Limit = limit + 1
}
results, err = activeStore.GetReadyWorkWithCounts(ctx, filter)
total = len(results)
}
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
truncated := limit > 0 && len(results) >= limit && total > limit
if len(results) > limit && limit > 0 {
results = results[:limit]
}
if results == nil {
results = []*types.IssueWithCounts{}
}
if err := outputJSON(results); err != nil {
return err
}
if truncated {
fmt.Fprintf(os.Stderr, "%s Use --limit 0 for all, or --limit N to raise the cap.\n", readyHiddenHint(len(results)))
}
return nil
}
// readyHiddenHint is the truncation hint for a page whose total is unknown:
// how many rows are shown, and that the limit hid more.
func readyHiddenHint(shown int) string {
noun := "issues"
if shown == 1 {
noun = "issue"
}
return fmt.Sprintf("Showing %d ready %s; more matched but were hidden by --limit.", shown, noun)
}
// readyTotal sizes the whole ready set for the request `bd ready` just listed
// a page of, through the store's own ReadyCounter accessor.
//

View file

@ -0,0 +1,138 @@
package main
import (
"context"
"encoding/json"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
)
// readyPageFake serves GetReadyWorkWithCounts from a fixed ready set and
// records the filters it was asked for. Its embedded DoltStorage is nil, so any
// other read panics and the test says so.
type readyPageFake struct {
storage.DoltStorage
ready []*types.IssueWithCounts
limits []int
totalCalls int
}
func (f *readyPageFake) IsRemoteBackendStore() bool { return true }
func (f *readyPageFake) GetReadyWorkWithCounts(_ context.Context, filter types.WorkFilter) ([]*types.IssueWithCounts, error) {
f.limits = append(f.limits, filter.Limit)
if filter.Limit > 0 && filter.Limit < len(f.ready) {
return f.ready[:filter.Limit], nil
}
return f.ready, nil
}
func (f *readyPageFake) GetReadyWorkWithCountsAndTotal(_ context.Context, filter types.WorkFilter) ([]*types.IssueWithCounts, int, error) {
f.totalCalls++
if filter.Limit > 0 && filter.Limit < len(f.ready) {
return f.ready[:filter.Limit], len(f.ready), nil
}
return f.ready, len(f.ready), nil
}
func readyRows(n int) []*types.IssueWithCounts {
rows := make([]*types.IssueWithCounts, n)
for i := range rows {
rows[i] = &types.IssueWithCounts{Issue: &types.Issue{ID: "bd-" + string(rune('a'+i)), Title: "t", Status: types.StatusOpen}}
}
return rows
}
func runReadyJSONWithoutTotalForTest(t *testing.T, s storage.DoltStorage, filter types.WorkFilter) ([]types.IssueWithCounts, string) {
t.Helper()
stdioMutex.Lock()
defer stdioMutex.Unlock()
var err error
stdout, stderr := captureStdio(t, func() {
err = runReadyJSONWithoutTotal(context.Background(), s, filter)
})
if err != nil {
t.Fatalf("runReadyJSONWithoutTotal: %v\nstderr: %s", err, stderr)
}
var rows []types.IssueWithCounts
if err := json.Unmarshal([]byte(stdout), &rows); err != nil {
t.Fatalf("stdout is not a JSON array: %v\n%s", err, stdout)
}
return rows, stderr
}
// TestReadyJSONOnARemoteBackendAsksForNoTotal pins `bd ready --json` against a
// remote backend with no envelope: one listing one row past the limit, never
// the counted listing (which costs a remote store a countReadyWork request),
// and a hint that says more exist without saying how many.
func TestReadyJSONOnARemoteBackendAsksForNoTotal(t *testing.T) {
t.Run("truncated", func(t *testing.T) {
s := &readyPageFake{ready: readyRows(5)}
rows, stderr := runReadyJSONWithoutTotalForTest(t, s, types.WorkFilter{Limit: 2})
if len(rows) != 2 {
t.Fatalf("printed %d rows, want the 2 the limit allows", len(rows))
}
if len(s.limits) != 1 || s.limits[0] != 3 || s.totalCalls != 0 {
t.Fatalf("listings asked for limits %v and %d counted listings, want one listing of 3 and none counted", s.limits, s.totalCalls)
}
if !strings.Contains(stderr, "Showing 2 ready issues; more matched but were hidden by --limit.") {
t.Fatalf("stderr = %q, want the truncation hint without a total", stderr)
}
})
t.Run("whole set", func(t *testing.T) {
s := &readyPageFake{ready: readyRows(2)}
rows, stderr := runReadyJSONWithoutTotalForTest(t, s, types.WorkFilter{Limit: 2})
if len(rows) != 2 || stderr != "" {
t.Fatalf("rows = %d, stderr = %q; want both rows and no hint", len(rows), stderr)
}
})
t.Run("unlimited", func(t *testing.T) {
s := &readyPageFake{ready: readyRows(3)}
rows, stderr := runReadyJSONWithoutTotalForTest(t, s, types.WorkFilter{})
if len(rows) != 3 || stderr != "" || len(s.limits) != 1 || s.limits[0] != 0 {
t.Fatalf("rows = %d, stderr = %q, limits = %v; want every row, no hint, one unlimited listing", len(rows), stderr, s.limits)
}
})
t.Run("cap at the limit keeps the counted listing", func(t *testing.T) {
s := &readyPageFake{ready: readyRows(5)}
rows, stderr := runReadyJSONWithoutTotalForTest(t, s, types.WorkFilter{Limit: 2, MaxRows: 2})
if len(rows) != 2 || s.totalCalls != 1 || len(s.limits) != 0 {
t.Fatalf("rows = %d, counted = %d, limits = %v; want the counted listing alone", len(rows), s.totalCalls, s.limits)
}
if !strings.Contains(stderr, "Showing 2 ready issues; more matched") {
t.Fatalf("stderr = %q, want the truncation hint without a total", stderr)
}
})
}
// TestReadyJSONPrintsNoTotalOnlyWithoutTheEnvelopeOnARemoteBackend pins when
// the total is skipped: the envelope prints it as pagination.total, and a local
// store takes it in the page's own transaction for the stderr hint.
func TestReadyJSONPrintsNoTotalOnlyWithoutTheEnvelopeOnARemoteBackend(t *testing.T) {
remote := &readyPageFake{}
local := &routingSettingsFake{}
t.Setenv("BD_JSON_ENVELOPE", "")
if !readyJSONPrintsNoTotal(remote) {
t.Error("remote backend without the envelope: want the total skipped")
}
if readyJSONPrintsNoTotal(local) {
t.Error("local store: want the total kept")
}
t.Setenv("BD_JSON_ENVELOPE", "1")
if readyJSONPrintsNoTotal(remote) {
t.Error("remote backend with the envelope: want the total kept for pagination.total")
}
}
func TestReadyHiddenHintAgreesInNumber(t *testing.T) {
if got := readyHiddenHint(1); got != "Showing 1 ready issue; more matched but were hidden by --limit." {
t.Errorf("readyHiddenHint(1) = %q", got)
}
if got := readyHiddenHint(2); got != "Showing 2 ready issues; more matched but were hidden by --limit." {
t.Errorf("readyHiddenHint(2) = %q", got)
}
}

View file

@ -124,7 +124,7 @@ func runReadyProxiedList(ctx context.Context, uw uow.UnitOfWork, in readyInput)
}
_ = outputJSONWithPagination(results, pag)
if truncated {
fmt.Fprintf(os.Stderr, "Showing %d ready issues; more matched but were hidden by --limit. Use --limit 0 for all, or --limit N to raise the cap.\n", len(results))
fmt.Fprintf(os.Stderr, "%s Use --limit 0 for all, or --limit N to raise the cap.\n", readyHiddenHint(len(results)))
}
return nil
}
@ -174,7 +174,7 @@ func runReadyProxiedList(ctx context.Context, uw uow.UnitOfWork, in readyInput)
}
if truncated {
fmt.Printf("%s\n\n", ui.RenderMuted(fmt.Sprintf("Showing %d ready issues; more matched but were hidden by --limit. Use --limit 0 for all, or --limit N to raise the cap.", len(issues))))
fmt.Printf("%s\n\n", ui.RenderMuted(readyHiddenHint(len(issues))+" Use --limit 0 for all, or --limit N to raise the cap."))
}
return nil
}