fix(cli): bd list --wisp-type cannot match a row — register the plane knob it needs (#6098)

`bd list --wisp-type heartbeat` returns an empty listing for EVERY input, and
`bd list` exposes no flag that changes that.

ListRequest.WispType is a predicate, not a plane selector — its own doc says
so, and RunReaderListWispTypeNarrowsTheAdmittedPlaneRatherThanAdmittingIt pins
it. That contract is right and this does not touch it. The doc also names the
way out:

    The combination that answers with rows is IncludeEphemeral (or
    IncludeInfra) plus this, and it is lawful rather than refused.

`bd list` registers neither `--include-ephemeral` nor `--all-types`. So of the
two combinations the doc names, the CLI can express only IncludeInfra — which
admits the plane AND lifts the infra-type exclusions AND changes the template
treatment, three decisions a caller who wanted one classification did not ask
for. The narrow knob the doc names FIRST has no flag at all.

That is the whole defect: the API composes correctly, and the CLI is missing
the other half of the pair.

## What this does

1. Registers `--include-ephemeral` on `bd list`, wired to
   `ListRequest.IncludeEphemeral` — the plane knob alone, off by default, so
   the default listing is byte-identical.

2. Refuses `--wisp-type` when no plane is admitted, with the fix in the hint,
   instead of printing an empty listing.

The refusal is at the CLI layer ONLY. At the API layer the combination stays
lawful and still composes to an empty page: that is the pinned contract, and a
programmatic caller composing filters may legitimately land on it. A human
typing `--wisp-type heartbeat` cannot have meant "prove to me that durable rows
carry no classification", so the CLI is where the guess is safe to make.

An explicit `--type` is deliberately left alone: an infra type routes to the
plane by itself, so the request may well be satisfiable, and this layer cannot
tell which types those are without loading the workspace's infra vocabulary.
Refusing there would reject lawful, answerable requests.

## Verification

    --- PASS: TestListRegistersIncludeEphemeral
    --- PASS: TestGatherListInput_WispTypeWithoutAPlaneIsRefused
    --- PASS: TestGatherListInput_WispTypeWithAPlaneIsAccepted (3 subtests)
    --- PASS: TestGatherListInput_IncludeEphemeralReachesTheRequest

The pair discriminates rather than being trivially green: a guard that refused
every `--wisp-type` would pass the refusal test and fail all three acceptance
subtests, one per route that admits the plane.

`ok github.com/steveyegge/beads/cmd/bd`, `ok
github.com/steveyegge/beads/internal/workapi`, `go build ./...` and `go vet`
clean. `internal/workapi/list.go` and the golden corpus are untouched.

docs/CLI_REFERENCE.md is not regenerated here: the docs pipeline builds from
the release tag in docs/cli-docs.pin (v1.2.2), not from this checkout, so the
new flag appears at the next release bump.

Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6
This commit is contained in:
Karel Bourgois 2026-09-03 02:34:05 +02:00 • committed by GitHub
commit cbf84cb1c0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 161 additions and 0 deletions

View file

@ -470,6 +470,14 @@ func init() {
// Infra type filtering: exclude agent/role/message by default
listCmd.Flags().Bool("include-infra", false, "Include infrastructure beads (agent/role/message) in output")
// Ephemeral plane: the wisps table is suppressed by default. This is the
// PLANE knob on its own — ListRequest.IncludeEphemeral — as distinct from
// --include-infra, which admits the plane AND lifts the infra-type
// exclusions above. Without it the plane is reachable from the CLI only
// through --include-infra's wider bundle, which leaves --wisp-type below
// with no narrow way to match anything.
listCmd.Flags().Bool("include-ephemeral", false, "Include ephemeral wisp-plane rows in output (normally hidden)")
// Explicit type exclusion
listCmd.Flags().StringSlice("exclude-type", nil, "Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic)")

View file

@ -134,6 +134,7 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) {
in.IncludeTemplates, _ = cmd.Flags().GetBool("include-templates")
in.IncludeGates, _ = cmd.Flags().GetBool("include-gates")
in.IncludeInfra, _ = cmd.Flags().GetBool("include-infra")
in.IncludeEphemeral, _ = cmd.Flags().GetBool("include-ephemeral")
in.ExcludeTypes, _ = cmd.Flags().GetStringSlice("exclude-type")
in.ParentID, _ = cmd.Flags().GetString("parent")
@ -158,6 +159,28 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) {
return in, HandleError("invalid wisp-type %q (must be %s)", s, types.ValidWispTypeNames())
}
in.WispType = &wt
// wisp_type is a PREDICATE, not a plane selector (see
// issueops.ListRequest.WispType): it narrows whatever the rest of the
// request admitted. On a default listing that is the durable rows,
// which carry no classification — so this request cannot match a row
// for ANY input, and would report an empty listing rather than the
// unread plane that actually holds the answer.
//
// The request stays LAWFUL at the API layer, where composing to empty
// is the pinned contract. Refusing it belongs HERE, at the CLI, where
// the only thing a human can have meant is the combination that
// answers with rows.
//
// An explicit --type is left alone: an infra type routes to the plane
// by itself, so the request may be satisfiable and this cannot tell
// without the workspace's infra vocabulary, which this layer does not
// load.
if !in.IncludeEphemeral && !in.IncludeInfra && in.IssueType == "" {
return in, HandleErrorWithHint(
fmt.Sprintf("--wisp-type %s cannot match anything here: it filters the wisp_type column, and this listing admits only durable rows, which never carry one", s),
"add --include-ephemeral to admit the ephemeral plane (or --include-infra, which admits it as part of a wider bundle)")
}
}
in.DeferredFlag, _ = cmd.Flags().GetBool("deferred")

View file

@ -0,0 +1,130 @@
package main
import (
"strings"
"testing"
"github.com/spf13/cobra"
)
// newWispTypeInputCmd carries only the flags the --wisp-type reachability
// check reads. gatherListInput reads many others, but GetString / GetBool on
// an unregistered flag return zero values, so this stays minimal — the same
// shape as newListInputTestCmd.
func newWispTypeInputCmd() *cobra.Command {
cmd := &cobra.Command{Use: "list"}
f := cmd.Flags()
f.String("wisp-type", "", "")
f.Bool("include-ephemeral", false, "")
f.Bool("include-infra", false, "")
f.StringP("type", "t", "", "")
return cmd
}
// TestListRegistersIncludeEphemeral pins the flag the guard below points at.
//
// It is the load-bearing half of this change: ListRequest.IncludeEphemeral is
// the plane knob its own doc names as the combination that answers with rows,
// and `bd list` did not register a flag for it. Without this the advice the
// guard prints names a flag that does not exist, which is worse than the
// silence it replaces.
func TestListRegistersIncludeEphemeral(t *testing.T) {
if listCmd.Flags().Lookup("include-ephemeral") == nil {
t.Fatal("bd list must register --include-ephemeral: it is the only narrow way to admit the wisp plane, and --wisp-type's error message tells callers to use it")
}
}
// TestGatherListInput_WispTypeWithoutAPlaneIsRefused covers the request that
// cannot match a row for ANY input: wisp_type narrows whatever the rest of the
// request admitted, and a default listing admits only durable rows, which
// carry no classification.
//
// The API layer keeps composing this to an empty page — that is its pinned
// contract, and this does not touch it. The refusal is here, where the only
// thing a human can have meant is the combination that returns rows.
func TestGatherListInput_WispTypeWithoutAPlaneIsRefused(t *testing.T) {
defer func(prev bool) { jsonOutput = prev }(jsonOutput)
jsonOutput = false
cmd := newWispTypeInputCmd()
if err := cmd.Flags().Set("wisp-type", "heartbeat"); err != nil {
t.Fatalf("set wisp-type: %v", err)
}
var err error
stderr := captureStderr(t, func() { _, err = gatherListInput(cmd) })
if err == nil {
t.Fatal("--wisp-type with no plane knob cannot match any row and must be refused, got nil error")
}
// The message has to carry the way out, or it is just a different silence.
if !strings.Contains(stderr, "--include-ephemeral") {
t.Errorf("the refusal must name the flag that makes the request answerable; got:\n%s", stderr)
}
}
// TestGatherListInput_WispTypeWithAPlaneIsAccepted is the discriminating half:
// a guard that refused everything would pass the test above on its own. Each
// case here admits the plane by a different route, and all must survive.
func TestGatherListInput_WispTypeWithAPlaneIsAccepted(t *testing.T) {
defer func(prev bool) { jsonOutput = prev }(jsonOutput)
jsonOutput = false
for _, tc := range []struct {
name string
flag string
val string
}{
{"the narrow plane knob", "include-ephemeral", "true"},
{"the wider bundle that also admits it", "include-infra", "true"},
// An explicit type is left alone: an infra type routes to the plane by
// itself, and this layer cannot tell which types those are without the
// workspace's infra vocabulary. Refusing here would reject a lawful,
// answerable request.
{"an explicit type, which may itself be infra", "type", "agent"},
} {
t.Run(tc.name, func(t *testing.T) {
cmd := newWispTypeInputCmd()
if err := cmd.Flags().Set("wisp-type", "heartbeat"); err != nil {
t.Fatalf("set wisp-type: %v", err)
}
if err := cmd.Flags().Set(tc.flag, tc.val); err != nil {
t.Fatalf("set %s: %v", tc.flag, err)
}
in, err := gatherListInput(cmd)
if err != nil {
t.Fatalf("--wisp-type with --%s must be accepted, got: %v", tc.flag, err)
}
if in.WispType == nil || string(*in.WispType) != "heartbeat" {
t.Errorf("WispType must survive onto the request, got %v", in.WispType)
}
})
}
}
// TestGatherListInput_IncludeEphemeralReachesTheRequest confirms the new flag
// is wired through rather than merely registered — a flag that parses but is
// never read would leave the plane just as unreachable.
func TestGatherListInput_IncludeEphemeralReachesTheRequest(t *testing.T) {
defer func(prev bool) { jsonOutput = prev }(jsonOutput)
jsonOutput = false
cmd := newWispTypeInputCmd()
if err := cmd.Flags().Set("include-ephemeral", "true"); err != nil {
t.Fatalf("set include-ephemeral: %v", err)
}
in, err := gatherListInput(cmd)
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if !in.IncludeEphemeral {
t.Error("--include-ephemeral must set ListRequest.IncludeEphemeral, got false")
}
// And the default stays off, so the durable-only listing is unchanged.
bare, err := gatherListInput(newWispTypeInputCmd())
if err != nil {
t.Fatalf("gatherListInput (bare): %v", err)
}
if bare.IncludeEphemeral {
t.Error("IncludeEphemeral must default to false; the default listing is durable-only")
}
}